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, and **the user's own lesson notes**, a
directory of Markdown files that is the only record of what was actually said in
the room. TypeScript, Node 22+, `@modelcontextprotocol/sdk`.

Three sources, and the distinction matters in every tool description: Schulcloud
has the material, WebUntis has the schedule and the class register, the notes
have what the teacher stressed. An answer that silently merges them is worse
than one that says which said what.

Three entry points over one core:
- `src/bin/http.ts` — Streamable HTTP + `/api` + `/app`, 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

```bash
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 `!reset`s 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 (index-backed) and without
(live-only). Without a WebUntis key the run asserts the `untis_*` tools are
*not* offered instead of exercising them, and the same holds for `NOTES_DIR` —
except that the smoke sets its own throwaway one, so the note tools are always
exercised and can never touch real notes. The degradation paths are supported
modes, not fallbacks nobody exercises.

The check counts are a tripwire, so re-measure them rather than trusting this
line after a change: **106/107 against the local instance** on 2026-09-19 (the
one failure is the H5P service, which that instance does not run). The live counts
are stale — they were last taken before the notes and class-register work, and
could not be retaken because the live session had lapsed. 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.
  - **`day-note.ts`** — a school day as a note: the timetable turned into one
    `##` heading per lesson. `lessonHeading` and `notes.ts`'s
    `subjectFromHeading` are a **loop** — the app writes the heading and the
    indexer reads the subject back out of it, so a change to either without the
    other files a day's notes under nothing. `test/day-note.test.ts` holds them
    to it.
  - **`notes.ts`** — the user's own lesson notes as a directory of Markdown
    files with a small frontmatter dialect. A note with `##` headings is a
    school day and is indexed **per lesson**, not whole: indexed whole, every
    hit would read "my note, Monday" and "what did we do in Deutsch" would match
    a note whose other five lessons were something else. The files are the truth and the
    index is a view of them, so `list_notes`/`get_note` read disk and answer
    before the first crawl and while Postgres is down. **The one thing anything
    here writes** — see Invariants. `docs/NOTES.md` is the guide.
  - **`untis-history.ts`** — the class register read backwards, which is what
    puts "what did we actually cover" into the search index. Its whole reason
    for existing is one API property: `getLessonTopic2017` answers per *series*,
    so a term costs one call per lesson series rather than one per period — see
    API gotchas.
  - `h5p.ts` — the quizzes on a board. One GET per element, parsed into
    questions and answers; board assembly attaches it like a pad, the crawl
    indexes its text, and `get_h5p` prints it.
  - `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.
- **`http/app-page.ts` + `http/app/`** — `/app`, the one surface meant for a
  person rather than a program: the day's notes and a settings page for the
  Schulcloud token. Served only when `WEB_PASSWORD` is set. Its assets are
  **files** under `src/http/app/`, copied to `dist/` by `scripts/copy-assets.mjs`
  and read relative to `import.meta.dirname` — real HTML, CSS and JS that an
  editor and a linter understand, which is also what the CSP requires, since it
  forbids inline script.
- **`http/web-auth.ts`** — the app's login, which is a different kind of
  credential from everything else here: a password a person types, not a token a
  program was configured with. scrypt at startup, a signed `HttpOnly` /
  `SameSite=Strict` session cookie, per-address rate limiting. The session key
  is **derived from the password**, so changing it logs every session out and
  there is no second secret to store. The cookie opens `/api` — a session *is*
  the user — and never `/mcp`. See Invariants.
- **`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.
  `untis_lesson_topics` takes **either** a `periodId` (one series) **or** a
  `subject` (a whole term, via `untis-history.ts`); neither and both are both
  refused, because guessing which was meant is worse than asking.
- **`mcp/tools/notes.ts`** — `list_notes`, `get_note` and `add_note`, registered
  **only** when `NOTES_DIR` is set, by the same rule as the `untis_*` tools.
- **`mcp/prompts.ts` takes a `Sources` flag** (`{ notes, untis }`) so a prompt
  never tells Claude to call a tool this deployment does not register. A prompt
  built with no sources names none of them — that is the default, and the safe
  one.
- **`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.

**The app's session opens `/api`, never `/mcp`, and the app is not served
without a password.** `WEB_PASSWORD` is the only credential here a human types,
so it is the only one that can be guessed: the rate limiter in `web-auth.ts` is
not decoration, and the scrypt cost that makes guessing expensive is itself a
denial-of-service vector without it. The password is hashed at startup and never
stored, compared or logged in the clear — it is a secret by the rule below, and
so is the session cookie. Unset means the app does not exist, the same rule the
`untis_*` and note tools follow: a login screen no password can open is worse
than no page, because it looks like a way in.

**The notes directory is the only thing anything here writes to.** That is not
an exception to the invariant above — it is a different store: the user's own
files, never Schulcloud and never WebUntis. It is bounded by the same two
functions as the file mirror, and for the same reason: `add_note`'s title and
subject arrive from a tool call, become path components through `safeComponent`,
and the result is checked by `resolveWithin`, so a note titled
`../../.ssh/authorized_keys` becomes a filename. `NOTES_READONLY` refuses writes
entirely. Do not widen this to anything outside `NOTES_DIR`, and do not take it
as precedent for a Schulcloud write tool — that decision is the one above, and
it has not changed.

**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`, `MCP_CONNECTOR_TOKEN` and `WEB_PASSWORD` 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 — a quiz is H5P.** There is no quiz module
  or endpoint upstream: interactive exercises are `h5p` elements carrying a
  `contentId`, or external (LTI) tools behind `contextExternalToolId`. Don't
  look for a quiz API; look for the H5P one.
- **One request holds a whole quiz**: `GET /api/v3/h5p-editor/params/{contentId}`
  returns the JSON the player is fed — every question, every option and which
  are correct — even though the player shows one question at a time. Nothing to
  step through, no page to scrape, and `play/{id}` is the same content plus 24 KB
  of scripts, so `params` is both cheaper and complete. The H5P service is not
  in `docs-json` and has no document of its own; `core/h5p.ts` interprets the
  payload, whose shape belongs to the H5P library the teacher used. Model a new
  library there rather than in a tool, and keep the generic harvest as the
  fallback — an exercise arriving as "0 questions" is the bug that path exists
  to prevent.
- **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.
- **`getLessonTopic2017` answers per *series*, not per period.** Its
  `previousTopics` are the lessons *before* the period you name, each carrying
  its own `periodId`, so a term is reconstructed by taking the distinct
  `lessonId`s in a range, asking about the **latest** period of each, and
  merging back by id — a few dozen calls for a school year. Asking about the
  earliest period of a series reaches none of its history. `core/untis-history.ts`.
- **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, and a note tool only when
   `config.notesDir` is set.
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 <code>:", 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),
`NOTES_DIR`, `UNTIS_HISTORY_DAYS` and `WEB_PASSWORD` (the app at `/app`);
docker-compose sets `STATE_DIR` and `NOTES_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.