Document WebUntis

docs/API.md gains the findings: the endpoint and its required version
parameter, the one-time code and the two error codes worth naming, the Z that
means local time, a substitution being two periods, the unused exam module
that puts announced tests in the period notes, and a day without lessons that
is not a holiday. Those cost an afternoon of probing to learn and nothing
upstream states them.

docs/AUTH.md sets the key against the Schulcloud token it sits beside: no
password, nothing to keep alive, revocable on its own, and not read-only in
itself — which is why the allowlist exists. PI.md and DEPLOYMENT.md add the
four values, the container recreate a changed key needs, and the clock
requirement; the Pi's troubleshooting table gains both failure messages.

README and CLAUDE.md say what the server now is: Schulcloud for the material,
WebUntis for the day. Smoke is 89 checks with the index and a key, 87
live-only, 9 fewer without one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-09-17 20:43:24 +02:00
parent eaf9c7aa38
commit ccbf3ad3e9
8 changed files with 245 additions and 25 deletions

View File

@@ -196,6 +196,26 @@ claude mcp add --transport http --scope user schulcloud https://mcp.example.org/
schulcloud login --server https://mcp.example.org --token <MCP_AUTH_TOKEN>
```
## The WebUntis key
The timetable comes from WebUntis, which needs four values in `.env` —
`UNTIS_SERVER`, `UNTIS_SCHOOL`, `UNTIS_USER`, `UNTIS_SECRET` — all from WebUntis
→ Profil → Freigaben → Untis Mobile → QR-Code. With them the server offers the
`untis_*` tools and the `tagesvorbereitung` prompt; without them it does not,
and nothing else changes.
Operationally it is the easy credential: no password, it survives the container
being off, and it expires only when you generate a new key. Two consequences
for a deployment:
- **Recreate the container after changing it** (`docker compose up -d
--force-recreate schulcloud-mcp`) — `env_file` is read at creation, and unlike
the Schulcloud token there is no live swap, because there is no monthly chore
to spare anyone.
- **Keep the host's clock synchronised.** Requests are signed with a
time-based code; a drifting clock is refused with "invalid client time", which
the tools report in those words.
## Replacing the Schulcloud token
The token lasts 30 days at most and can only come from a browser login (see