Schulcloud-MCP/CLAUDE.md

CLAUDE.md

Guidance for Claude Code when working in this repository.

What this is

Read-only access to a Schulcloud (HPI Schul-Cloud / Schulcloud-Verbund-Software) account: courses, column boards, lessons, tasks, files with text extraction, and a Postgres-backed full-text index — plus the timetable from WebUntis, which is a separate system and the only place this school publishes when a lesson happens, or that it was cancelled. TypeScript, Node 22+, @modelcontextprotocol/sdk.

Three entry points over one core:

• src/bin/http.ts — Streamable HTTP + /api, the deployed form, behind Caddy on a Pi.
• src/bin/stdio.ts — stdio, for local Claude Code / Desktop use.
• src/bin/cli.ts — the schulcloud CLI, which talks to the HTTP server, never to Schulcloud.

Commands

npm run build       # tsc → dist/ (also copies store/migrations/*.sql)
npm run dev         # watch mode, runs src/ directly via type stripping
npm test            # unit tests (node:test), no network
npm run typecheck
npm run probe       # verify token + API assumptions against the LIVE instance
npm run smoke       # full end-to-end: real server + real MCP client + real data
npm run keepalive-status   # is the deployed container holding its session?
npm run session-diagnose   # ~2.5h: measure what actually ends the session
npm run publish-image      # amd64 + arm64 image to registry.mc02.dev; clean tree only

docker-compose.override.yml is local-only and publishes the server on 127.0.0.1:8080 (or MCP_HOST_PORT) and Postgres on 127.0.0.1:55432; see docs/LOCAL.md. Compose merges it whenever COMPOSE_FILE is unset, so the Pi's .env sets COMPOSE_FILE=docker-compose.yml:deploy/docker-compose.pi.yml instead; docs/PI.md is the setup guide. The Pi never builds: that file runs registry.mc02.dev/schulcloud-mcp and !resets the build section, and npm run publish-image is how an image gets there — so a change reaches the Pi only once it is committed and published. When .env points at the live account, test against the local instance only through local-instance/scripts/mcp-env.sh: it pins its own database (schulcloud_local) and mirror, so fixtures cannot reach the live index.

probe and smoke hit the live Schulcloud and need a valid .env. Both are read-only with respect to Schulcloud. Run smoke after touching src/core/, src/mcp/ or src/http/ — the unit tests cover only pure functions.

Run smoke both ways: with DATABASE_URL set (89 checks, index-backed) and without (87 checks, live-only); without a WebUntis key both drop by 9, and the run then asserts the untis_* tools are not offered. The degradation paths are supported modes, not fallbacks nobody exercises. Every Schulcloud check fails with 401 when the live session has lapsed — check the container's keepalive log before suspecting code.

Store tests need a database and skip without one: TEST_DATABASE_URL=postgresql://… npm test. They use a real Postgres on purpose — the generation/diff semantics are entirely SQL, so a mock would test nothing. They TRUNCATE, and refuse to run unless the database name contains "test"; that guard exists because pointing them at the dev database once put fixtures into real data.

Architecture

bin/{http,stdio}.ts ─┬─ mcp/server.ts ── mcp/tools/*, mcp/{resources,prompts}.ts
                     └─ http/{server,api,auth}.ts        /mcp and /api
                          │
bin/cli.ts ──HTTP──────────┘   cli/{config,client,sync}.ts

           services.ts  (process-wide: client, Store, Indexer, UntisClient)
                │
   indexer/indexer.ts ── store/store.ts ── Postgres
                │
            core/{client,board,crawl,extract,text,paths,types}
            core/{untis,totp,dates}   ── WebUntis, a second upstream

• core/ knows nothing of MCP, HTTP or the CLI.
  • client.ts — every upstream call; GET-only except extendSession.
  • board.ts — a column board needs three kinds of call to reconstruct.
  • crawl.ts — the one traversal. Search, the indexer, the what-changed diff and the file mirror all need it; keep it here, not in a tool.
  • paths.ts — the security boundary for mirrored filenames. See Invariants.
  • legacy-files.ts — the file manager ("Dateien": Persönliche, Kurs-, Team-, Geteilte Dateien) as one path tree, parsed from the legacy client's pages. A separate store from files-storage; the fs_* tools and /api/fs sit on it.
  • session-token.ts — the Schulcloud token, replaceable at runtime: checked with GET /me (same userId), swapped into config.jwt, saved to STATE_DIR. Read config.jwt at the moment of use; never keep a copy.
  • untis.ts — WebUntis, the second upstream: the timetable with its cancellations and substitutions, class-register homework and lesson topics. Authenticates each request with a one-time code (totp.ts) over the key from Profil → Freigaben, so there is no session and no keepalive on this side. Resolves the payload's element ids to names and returns every day in a range, empty ones included. See Invariants for why the allowlist is there.
  • dates.ts — school days as YYYY-MM-DD in Europe/Berlin. The container runs UTC, so schoolToday() is not new Date(): at 00:30 in Erfurt the process clock still says yesterday, and a nightly briefing would prepare the wrong day.
• http/ — /mcp and /api take MCP_AUTH_TOKEN; /mcp alone also takes MCP_CONNECTOR_TOKEN, the request header claude.ai stores, which must never open /api. Besides those: the optional /<secret>/mcp for clients without headers (MCP_PATH_SECRET), and /token, a page that PUTs a fresh token to /api/token. docs/AUTH.md and docs/DEPLOYMENT.md say why each exists.
• store/ — crawl generations, identity diffs, german + pg_trgm FTS. Store.open returns undefined when Postgres is down; callers degrade.
• indexer/ — crawl → persist → mirror bytes → extract text → index. Coalesces concurrent refreshes; enforces a minimum interval. The crawl walks topic-attached tasks too, which the course page does not list: without that they are unsearchable and their grades invisible. INDEX_PERSONAL_FILES additionally indexes personal files and submitted/returned work, including grade comments — that is what makes "what got graded this week" answerable, at roughly three extra requests per task.
• mcp/tools/*.ts — tool descriptions are prompts: they are how Claude picks a tool, so they carry the German domain terms (Kurse, Themen, Aufgaben) and say when not to use the tool.
• mcp/tools/untis.ts — the untis_* tools, registered only when UNTIS_* is configured: a tool that can only fail is worse than a missing one. readTimetable is shared with the prompt, the way readCourse is.
• mcp/resources.ts, mcp/prompts.ts — courses and rooms as resources a person attaches, carrying exactly readCourse/readRoom, the functions behind get_course/get_room; and three prompts, the third being tagesvorbereitung, which attaches a day's timetable and is the point where the two systems meet. What people read in a picker (labels, prompt texts) is German; what the model reads stays English.
• context.ts — per-session state. Only /me is cached, because the school id is on every files-storage path and cannot change for a token.

Invariants

Everything that touches Schulcloud is read-only. Every client method is a GET except extendSession (the keepalive's refresh-session call, which touches only our own session and is not exposed as a tool, so no model-driven call can be a POST). api_get rejects non-/api/ paths and anything carrying a scheme or host. Against the legacy client, GET-only is not enough: GET /files/share/ mints a share token and GET /files/file?share= grants a permission, so getFileManagerPage allows only the listing routes, by pattern — widen that pattern only with a route you have read the handler of. A pre-signed download URL is fetched with no credentials: it names another host, and neither the bearer nor the jwt cookie may go with it. refresh_index and POST /api/refresh write only to the Pi's own index and mirror, and PUT /api/token only to the server's own token — every upstream call they make is still a GET.

WebUntis is read-only by allowlist, not by verb. Its API is JSON-RPC, so every call is a POST, reads included — "GET only" cannot carry over. Instead core/untis.ts holds READ_METHODS and assertReadMethod refuses anything else at the single choke point, which test/untis.test.ts asserts. This matters because the key is the mobile app's credential and can do what the app can: the live account's rights include W_OWN_ABSENCE, i.e. that key could report the user absent. Add a method only after reading what it does upstream, and never one whose name starts with submit, create, save or delete.

Filenames from Schulcloud are untrusted paths. Course titles, card titles and filenames are all user-supplied upstream, and both the server's mirror and the CLI's sync turn them into filesystem paths. Everything goes through core/paths.ts: safeComponent reduces one string to one safe component, and resolveWithin refuses anything that escapes the root. Do not bypass them with path.join, and keep the property that no .. survives anywhere in a component — it is what makes the invariant checkable. The endpoint is internet-facing by necessity, so "a leaked token cannot act as the user" is the property that makes that acceptable. Do not add a write tool without the user explicitly asking for one and understanding this.

Never log or echo secrets. TSC_JWT_COOKIE grants full read access to the account; MCP_AUTH_TOKEN and MCP_CONNECTOR_TOKEN guard the endpoint; UNTIS_SECRET authenticates as the user in WebUntis and outlives every other credential here, since it does not expire. None belongs in logs, error messages, or tool output. .env is git-ignored — keep it that way. Two more count as secrets: a token replaced at runtime (it lives only in STATE_DIR, mode 0600) and, when MCP_PATH_SECRET is set, request paths — so nothing may log a URL path, and config errors describe the rule, not the value.

Live behaviour beats upstream source. The clones in vendor/ track main and may be ahead of what is deployed. When they disagree with the instance, the instance is right. docs/API.md records which is which.

API gotchas

These cost real time to discover; docs/API.md has the full list with evidence.

• Course contents are at GET /api/v3/course-rooms/{courseId}/board. There is no GET /api/v3/courses/{id}, and :roomId there is the course id.
• Rooms ("Räume") are a separate space from courses, and the UI's naming is a trap: the sidebar's Kurse entry links to /rooms/courses-overview and lists courses; Räume links to /rooms and lists rooms. A /rooms/... url says nothing about which. list_rooms/get_room cover the latter; a room holds boards only — no lessons, no tasks. Empty is normal and is also what a revoked membership looks like.
• Room boards report isVisible, which the course-page projection does not, so a room's drafts can be named as drafts instead of being tried and 403ing.
• limit is rejected above 100 though the spec says 99. Page at 99; the client clamps and listAllCourses pages for you.
• There is no GET /tasks/{id}, and the task lists omit description — it only exists on the course page's task element. get_task does that join.
• GET /cards?ids= takes at most 20 ids (the qs arrayLimit default), and fails above that with a validation error that blames the ids rather than their number. MAX_IDS_PER_QUERY in core/client.ts. Any board over 20 cards is affected, which is common.
• Never swallow a per-item crawl error. Board failures used to be caught and dropped, so the index lost whole boards while the crawl reported success — which is how the 20-id limit went unnoticed. They go into Snapshot.failures.
• Record failures by kind, or transient ones become permanent. Every failed file used to be marked done, so a timeout was never retried. A download failure is now recorded with retry: true and the next crawl tries again; an extraction failure is final. Two causes found on the first full crawl of a real account: downloads bounded by the 30 s request timeout (11 MB scans cut off mid-transfer — downloads now time out on 30 s of silence), and PDF text containing NUL, which Postgres text refuses — stripped in recordFileText.
• A full crawl can outlast one HTTP request. The first one with the file manager took 14 minutes (every file downloaded once); Node's fetch abandons a response without headers after 5. POST /api/refresh takes wait: false and the CLI polls /api/status; refresh_index returns after 50 s and leaves the crawl running. Don't reintroduce a caller that waits on a full crawl inline.
• GET /lessons/{id}/tasks is a bare array whose items carry no id. Not the {data,total} envelope, and LessonLinkedTaskResponse has no id field at all. A topic-attached task is thus unidentifiable from the API and invisible in both task lists once past due — 18 of 60 tasks on the real account. core/lesson-page.ts scrapes the ids off the legacy topic page.
• Collaborative text editor (Etherpad) contents are reachable, in two hops. GET /api/v3/collaborative-text-editor/content-element/{id} returns the pad url and sets an Etherpad sessionID cookie; /etherpad/p/{id}/export/txt then returns the text. No Etherpad API key needed. core/etherpad.ts checks the url's host before sending the cookie to it.
• A draft board is listed on the course page but 403s when opened. Say "not published yet", not "no access".
• File records are mutable: PATCH /file/rename/{id} keeps the id and size, so the store's digest has to include the name.
• Submissions: only GET /submissions/status/task/{taskId} exists. No list, no fetch-by-id, and the payload has no submitted text, grade comment or graded-at. Don't imply absent feedback means none was given.
• /api/v1 is partly served, and it is production surface. Exactly three legacy routes survive in the deployment's own ingress table (dof_app_deploy/ansible/group_vars/all/x_ingress.yml): /api/v1/courses, /api/v1/users, /api/v1/classes. Everything else under /api/v1 is unrouted and 404s. They matter because v3 dropped things they still carry: courses has the description, teacherIds, userIds and times (the weekly timetable), and users/{id} is the only way to turn a user id into a name — submission submitters, file creatorId and course teacherIds are otherwise unreadable. Permission is per-account: a teacher may read their students, a student may read only themselves, so name resolution must degrade to "not visible to this account" rather than printing a bare id.
• The teacher's homework page is a different page from the student's. Its tabs are extended and submissions, not submission and feedback, and the grade lives in the grading form (name="grade", name="gradeComment", one block per submissionId) rather than in rendered prose. The student parser finds nothing on it, which is why a teacher account reported every graded submission as "neither a percentage nor feedback was found" while the data was plainly there. parseTeacherGrading handles that side.
• A grade is a percentage (Number 0-100) or absent; there is no text grade. Teachers commonly grade with gradeComment alone, so "graded by feedback" is a complete answer. formatGradeState in mcp/tools/submissions.ts owns that wording — don't reintroduce "no numeric grade recorded", which reads as a fault.
• Submitted text and grade comments are scraped, not fetched. No API exposes them; the legacy page GET /homework/{taskId} renders them, and it authenticates by jwt cookie, not bearer. core/homework-page.ts parses it on data-testid hooks and every field is optional — a markup change must degrade to "not found", never break get_task.
• files-storage listing ignores the parentType path segment — filter on each record's own parentType, or submission files get reported as grading files.
• Board file elements carry no file id. Files are found by listing files-storage with parentType: 'boardnodes' and the element id as parentId. Same for fileFolder and drawing.
• Files live in a separate service (/api/v3/file/*, repo file-storage) with its own OpenAPI document. It is not in the main docs-json.
• Legacy lesson responses return ids as {buffer:{data:[...]}}; use normalizeObjectId.
• updatedAt on the course-board projection is the request time, not a modification time — two reads seconds apart differ. Never build change detection on it; the store diffs crawl generations by identity instead. The dedicated endpoints (/boards/{id}, /cards, file records) are stable.
• Many course PDFs are image-only scans with no text layer (3 of 4 sampled), so extraction legitimately yields nothing. extract.ts detects this and says so; do not "fix" it by retrying. download_file then falls back to GET /file/preview/..., which renders the page as a picture Claude can read — the answer for a scan, though it still leaves the file unsearchable.
• The preview endpoint has two enums, and both 400 without saying so. width accepts only 50, 150 or 500 — a number outside that set is a validation error naming the value but not the permitted set. outputFormat accepts only image/webp; omitting it is worse than wrong, because the preview is then rendered in the source format and a PDF comes back as a PDF. The response also labels itself webp rather than image/webp, so the content type has to be normalised before anything will treat it as an image.
• A room's allowedOperations is an object, not a list. Every operation is present with a boolean; false means denied. Typing it as string[] type-checks and throws .some is not a function the moment anything reads it.
• Schulcloud has no quiz of its own. There is no quiz module or endpoint upstream: interactive exercises are H5P elements, whose contentId is the only handle onto the content, or external (LTI) tools behind contextExternalToolId. Say that rather than looking for a quiz API.
• The file manager is a third store, reachable only as HTML. Persönliche, Kurs-, Team- and Geteilte Dateien live in the legacy files collection, not in files-storage: list_files answers 0 for a course holding dozens of worksheets, and 21 of 26 live courses keep material there. Its Feathers service is not in the ingress, so listings are parsed from /files/{my,courses,teams,shared} pages and downloads go through GET /files/signedurl (JSON). Folders are addressed by id alone — /files/courses/{course}/{folder} at any depth. permittedDirectories returns every course with no folders (it queries refOwnerModel: 'courses', records say 'course'), and /files/search/ 504s, so walk listings. Course names contain /; resolve by joining segments. A listing page that does not parse must throw, never read as an empty folder — "0 files" is the bug this exists to fix. docs/API.md has the evidence.
• Teams cannot be read at any version. v3 exposes only GET /team/{teamId}/news; upstream main's teams controller is write-only (POST :teamId/create-room). /teams is the legacy client's HTML page, not an API. A team's files are reachable, through the file manager (/teams/<team>).
• exp (30 days) is not the session lifetime. The binding limit is a Valkey whitelist entry with a JWT_TIMEOUT_SECONDS TTL (7200s; live value at GET /api/v3/config/public) that every authenticated request re-sets. src/keepalive.ts holds it open — don't remove it. It cannot hold it across downtime: a host off for more than two hours loses the session (seen when a dev machine was off overnight), which is why the deployment is an always-on Pi and why a fresh token can be swapped in without a restart.
• A Schulportal tab left open revokes our token. The jwt cookie is the browser's session token, same jti. The front end runs a client-side timer (reset only on route change, never from the server TTL) and calls /logout?auto-logout=true ~2h after login, which issues POST /api/v3/logout and deletes the shared key. No keepalive can prevent it; the fix is to close the tab. This produced two false conclusions before being found — if a token dies ~2h after login, suspect an open tab first. docs/AUTH.md has the chain.

WebUntis has its own set; docs/API.md has them all, these are the ones that cost the most:

• jsonrpc_intern.do needs ?v=i3.2. Without it the call fails with -8998 wrapping a Java NullPointerException, which reads like a malformed body and is not. Errors also arrive with HTTP 200 and an error member, so check the body before the status.
• The one-time code travels as a string. One code in ten begins with a zero, and a JSON number drops it — a login that fails 10% of the time, which is the worst kind of failure to debug.
• startDateTime ends in Z and is local time. 2026-09-21T08:00Z is the 08:00 lesson in Erfurt. Never hand these to new Date; splitLocal takes the string apart. Every date the tools send is computed in Europe/Berlin (core/dates.ts), because the container is UTC.
• A substitution is two periods: the original with is: ["CANCELLED"] and the replacement beside it with is: ["IRREGULAR"]. A lesson is not "changed in place", so both have to be read, and orgId on an element exists as well.
• Announced tests live in text.info, not in the exam module — this school does not use it, so getExams2017 is always empty. That field is the most valuable thing in the payload.
• A day with no lessons is not a holiday. Vocational school weeks spent at the company simply have no periods, and holidays says nothing about them. Do not report "Ferien" for them; say there are no lessons.

Conventions

• Imports use .ts extensions; rewriteRelativeImportExtensions makes tsc emit .js. This lets node --watch src/bin/http.ts run the tree directly.
• No TypeScript parameter properties (constructor(private readonly x: T)). Node's type stripping rejects them, which breaks npm run dev and npm test. Declare the field and assign it in the constructor body instead.
• Tabs for indentation, single quotes, trailing commas.
• Comments explain why — an API quirk, a security property, a trade-off — not what the line does. Several such comments encode findings that are expensive to rediscover; do not strip them.
• Tool failures return isError: true with an actionable message via mcp/tools/result.ts. toToolError separates 401 (token expired — the user must act) from 403 (no access) from 404 (bad id) deliberately; keep that split.

Adding a tool

1. Add the client method in core/client.ts (GET only) — or, for the timetable side, in core/untis.ts, whose method name must go in READ_METHODS and must read.
2. Register the tool in the relevant mcp/tools/*.ts, with a description that says when to use it and when not to.
3. Format output as Markdown, keeping ids visible for follow-up calls.
4. If it reads the index, handle context.store === undefined with a message saying what is unavailable and what still works. A untis_* tool instead registers only when context.untis exists.
5. Add a check to scripts/smoke.mjs and run npm run smoke both ways.

Resources and prompts

Claude Code is the client these are tested in, and it shapes them. Read from its bundle (2.1.272), not its docs:

• A prompt command's arguments are split on whitespace, and extra words are dropped (zipObject(argNames, input.split(/\s+/))). A value of several words can only arrive joined, so argumentText turns _ back into spaces and reads - as "skipped"; course names match by fragments (resolveTarget). Any new free-text argument needs the same treatment.
• The @ autocomplete fuzzy-matches name but displays description, falling back to the name only when there is none — a description must carry the name.
• An @-mention resolves only URIs from resources/list; a template alone cannot be mentioned. McpServer returns every template's listing in one reply and ignores cursors, which suits a few dozen entries and not the file manager.
• Throw ProtocolError, not McpError: McpError prefixes its message with "MCP error :", the client prefixes it again, and people read both.
• A resource listing that fails yields no entries rather than an error: one refused kind would otherwise cost the whole reply.

Environment

.env holds TSC_URL, TSC_JWT_COOKIE, MCP_AUTH_TOKEN, and optionally MCP_CONNECTOR_TOKEN or MCP_PATH_SECRET, plus the four UNTIS_* values (all four or none — a half-filled block is a paste that went wrong, so it throws); docker-compose sets STATE_DIR. See .env.example for the full set and docs/AUTH.md for refreshing the JWT — schulcloud token set, no restart. npm run probe and schulcloud token report the clocks: days until hard expiry and the session budget.