MechaCat02
359c46afad
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>
99 lines
5.0 KiB
Markdown
99 lines
5.0 KiB
Markdown
# 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`.
|