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>
This commit is contained in:
68
README.md
68
README.md
@@ -1,9 +1,11 @@
|
||||
# schulcloud-mcp
|
||||
|
||||
An MCP server that gives Claude read-only access to a
|
||||
[Schulcloud](https://github.com/hpi-schul-cloud) account — courses, boards,
|
||||
lessons, tasks — and reads the attached files, so you can ask about your
|
||||
coursework instead of downloading PDFs and uploading them by hand.
|
||||
Read-only access to a [Schulcloud](https://github.com/hpi-schul-cloud) account —
|
||||
courses, boards, lessons, tasks and files — for **Claude**, via MCP, and for
|
||||
**you**, via a CLI that mirrors your coursework to disk.
|
||||
|
||||
Both are front ends over one core library and one live Schulcloud session, kept
|
||||
alive on a Pi.
|
||||
|
||||
Built and verified against `schulcloud-thueringen.de` with a live student
|
||||
account. Everything in `docs/API.md` was confirmed against the running
|
||||
@@ -29,14 +31,29 @@ Thirteen tools, all read-only:
|
||||
| `get_task` | one task: description, due date, status, attachments |
|
||||
| `list_files` | files attached to any entity |
|
||||
| `download_file` | fetch a file and extract its text, or view an image |
|
||||
| `search` | keyword search across courses, boards, files and tasks |
|
||||
| `search` | keyword search across everything — **including the text inside PDFs and Office files** |
|
||||
| `refresh_index` | re-read Schulcloud now, per course or in full |
|
||||
| `what_changed` | what appeared, changed or vanished since a date |
|
||||
| `index_status` | how fresh the index is |
|
||||
| `list_news` | school and course announcements |
|
||||
| `api_get` | GET-only escape hatch for uncovered API surface |
|
||||
|
||||
`download_file` extracts text from **PDF, DOCX, XLSX, PPTX and OpenDocument**
|
||||
files and returns **images inline** for Claude to look at. Verified against
|
||||
real files in the account: a 93-file PDF corpus, DOCX, ODT and PPTX all
|
||||
extract correctly.
|
||||
files and returns **images inline** for Claude to look at. Image-only PDFs —
|
||||
scans with no text layer, which are common in this account — are reported as
|
||||
such rather than as an empty result.
|
||||
|
||||
## The CLI
|
||||
|
||||
```bash
|
||||
schulcloud login --server https://mcp.example.org --token <token>
|
||||
schulcloud sync --dry-run # see what would be mirrored
|
||||
schulcloud sync # mirror coursework to ~/Schulcloud
|
||||
schulcloud refresh --course <id>
|
||||
```
|
||||
|
||||
It talks only to the Pi and holds no Schulcloud credential — see
|
||||
[docs/CLI.md](docs/CLI.md).
|
||||
|
||||
## Quick start
|
||||
|
||||
@@ -73,9 +90,17 @@ connectors call it from Anthropic's cloud), so the fact that a leaked token
|
||||
cannot be used to *act* as the user is the main safety property. Adding one
|
||||
write tool would forfeit it.
|
||||
|
||||
**Stateless.** No database, despite one being available on the host. 26 courses
|
||||
is not a caching problem, and a cache would introduce staleness questions that
|
||||
live calls simply do not have.
|
||||
**An index, with an honest bypass.** Postgres holds crawl generations and a
|
||||
`german` + `pg_trgm` full-text index over extracted file text, so search covers
|
||||
the inside of PDFs rather than just their names. Every result states how fresh
|
||||
the index is, and `fresh=true` bypasses it for a live read — an agent should
|
||||
never be quietly misled by stale data. Without `DATABASE_URL` the server still
|
||||
works: search falls back to crawling live.
|
||||
|
||||
**Generations, not timestamps.** Sync cursors and change detection compare crawl
|
||||
generations by identity. Measured: the course-board endpoint returns *request
|
||||
time* as `updatedAt`, so a timestamp cursor would report everything as changed
|
||||
on every crawl — and could never detect deletions.
|
||||
|
||||
**Assembled, not raw.** `get_board` makes three kinds of upstream call and
|
||||
stitches the results — board skeleton, card bodies, and a files-storage lookup
|
||||
@@ -91,18 +116,23 @@ bypass, "what's new since…" — are sketched with their trade-offs in
|
||||
|
||||
```
|
||||
src/
|
||||
bin/ stdio and http entry points
|
||||
schulcloud/ API client, response types, board assembly
|
||||
tools/ one module per group of MCP tools
|
||||
http/ express app, bearer auth
|
||||
extract.ts document → text
|
||||
render.ts formatting helpers
|
||||
docs/ API findings, auth, deployment
|
||||
core/ client, types, board assembly, crawler, extraction, paths
|
||||
store/ Postgres: crawl generations, diffs, full-text search
|
||||
indexer/ crawl → persist → mirror bytes → extract text → index
|
||||
mcp/ MCP server and tools
|
||||
http/ express app, bearer auth, /api for the CLI
|
||||
cli/ CLI config, API client, sync engine
|
||||
bin/ http, stdio and cli entry points
|
||||
docs/ API findings, auth, deployment, CLI, roadmap
|
||||
deploy/ Caddyfile snippet
|
||||
scripts/ probe (verify against live) and smoke (end-to-end)
|
||||
scripts/ probe, smoke, session diagnostics
|
||||
vendor/ upstream clones, git-ignored, for reference only
|
||||
```
|
||||
|
||||
`core/` knows nothing about MCP, HTTP or the CLI: it holds the Schulcloud client,
|
||||
the traversal every feature needs, document extraction, and the path
|
||||
sanitisation that both the server's mirror and the CLI's sync depend on.
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
|
||||
Reference in New Issue
Block a user