Files

MechaCat02 359c46afad Add the schulcloud CLI, and document the split

The CLI talks only to the Pi's /api surface and holds no Schulcloud
credential — only the same bearer token the Claude connector uses. That
is not layering for its own sake: a Schulcloud session dies after two
hours idle and a CLI process lives for seconds, so a CLI with its own
token would be dead most times you reached for it. Routing through the
Pi means one session, one keepalive, one monthly cookie paste.

sync is a one-way mirror, which follows from the data rather than from
scope-cutting: file records are immutable upstream, so there is no
versioning, no conflict resolution and no merge. State is keyed by file
record id with the path as derived output, so an upstream rename moves
the local file instead of duplicating it — verified against the live
server. Verification is size-only because the download endpoint exposes
no ETag and Schulcloud publishes no hash; size still catches the failure
that happens, a truncated download. Downloads land on a .part neighbour
and are renamed, so an interrupted run leaves no half-file that a later
run mistakes for complete. Deletions are reported but not propagated —
a teacher removing a worksheet is no reason to destroy the student's
copy — with --prune to opt in.

what_changed now clamps to the oldest stored generation instead of
refusing, and says it did: "what's new this week" is a reasonable
question to ask a two-day-old index.

Two build bugs caught by the checks rather than by luck: the smoke
harness constructed the app without services, so the index-backed tools
were never exercised; and the Docker build could not see
scripts/copy-assets.mjs, so the image would have shipped without
migrations and silently degraded to live-only.

67 unit tests (9 needing Postgres), smoke green both ways — 34 checks
with an index, 32 without, because graceful degradation is a supported
mode and not a fallback nobody runs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-12 21:26:33 +02:00

5.0 KiB

Raw Blame History

Extensions: built and possible

Items 1–3 are now implemented — see docs/CLI.md and the store/, indexer/ and cli/ modules. What remains below is the rationale (worth keeping) and the items still open.

Decisions already taken

Decision	Choice	Rejected
Endpoint auth	Static bearer token (`MCP_AUTH_TOKEN`, constant-time check)	OAuth 2.1; secret URL path
State	Stateless — every tool call hits the API live	Postgres cache; cache + full-text search
File delivery	Inline extracted text; images inline	Raw base64 only
If persistence is added	The Pi's existing PostgreSQL, with its own database and user	A dedicated container; SQLite

Two of the rejected options need no revisiting. OAuth 2.1 is disproportionate machinery for a single-user endpoint a bearer token already protects. "Raw bytes as well as extracted text" got built anyway — download_file takes raw: true.

1. Full-text search over file contents — BUILT

The gap: search covers course/board/card/lesson/task titles and text, and file names — never file contents. The 93 PDFs in this account are opaque to it. "Where does it explain the Caesar cipher?" only hits if those words are in a filename.

The cost: one search walks ~26 course pages, ~30 board skeletons plus card fetches, and ~150 per-element file listings — roughly 270 upstream requests, several seconds, every time.

Design sketch

Postgres tsvector + GIN. Use the german dictionary, so Verschlüsselung matches Verschlüsselungsverfahren; the default english config stems these wrongly.
Add pg_trgm alongside. German compounds defeat stemming — Datenschutzgrundverordnung will not match Datenschutz — and trigram similarity also absorbs typos.
Index: titles and text of courses, boards, cards, lessons, tasks; file names; and extracted file text.
Later, optionally: embeddings in pgvector, so "the thing about encryption" finds Verschlüsselung without sharing a word. Needs an embedding model in the loop, so it is a separate step, not part of this.

2. Cache, with bypass — BUILT (`search fresh=true`, `refresh_index`)

The split that makes staleness tolerable — index is discovery, live API is detail. Search the index to find where something is; always re-fetch it to read it. A stale index then costs a missed or spurious hit, never wrong content. That is a far better failure mode than a cache that can serve last week's homework list as current.

fresh: true on search (re-crawl the relevant course first) and on the detail tools.
State freshness in every cached result ("indexed 2h ago"), regardless of the flag — a bypass only helps if the agent knows it needs one.
Extracted file text is cacheable indefinitely. A fileRecord id maps to immutable bytes; an edit produces a new record. PDF parsing happens once, ever. Cheapest large win here, and free of staleness risk.
Sync: nightly full crawl (~270 requests, trivial) plus on-demand per course.

Consequence to weigh: coursework text would then live on the Pi at rest, outside Schulcloud. It does not weaken the read-only property, but it is new — consider disk encryption and whether it lands in a backup.

3. "What's new since …" — BUILT (`what_changed`)

Falls out of having an index with history: diff successive crawls to surface new boards, cards, files and tasks. Impossible today at any speed — the API has no changed-since filter anywhere. Arguably the most useful item on this list for a student, and nearly free once the sync job exists.

4. Still open

Video/audio transcription — this account has 5 MP4s and a WebM that are currently just "here is a file you cannot read".
MCP resources and prompts — expose courses/boards as attachable resources; canned prompts such as "summarise this week's homework".
Calendar — a separate schulcloud-calendar service, not part of the v3 API mapped in API.md.

5. Ruled out

Collaborative text editor contents. Confirmed unavailable: GET /api/v3/collaborative-text-editor/{parentType}/{parentId} returns a URL to the editor, never the document text.
OCR — partially wrong, revised. For reading, it remains unnecessary: images go to Claude inline and it reads them. For indexing it is a real gap. Measured after building the indexer: 3 of 4 sampled course PDFs have no embedded fonts at all — they are scans, so extraction legitimately yields nothing and they are unsearchable by content. extract.ts now reports these as image-only rather than as an empty result. Making them searchable would need OCR (or page rasterisation plus a vision pass), which is the largest remaining gap in search coverage.
Write tools (submitting homework, marking tasks done). Technically easy, but this forfeits the property that makes an internet-facing endpoint acceptable: that a leaked token cannot act as the user. A deliberate, separate decision — see the invariant in CLAUDE.md.

5.0 KiB Raw Blame History Unescape Escape