Fabian Hamm
35125b7683
Read-only MCP server exposing a Schulcloud account to Claude: courses,
column boards, lessons, tasks, and file downloads with text extraction.
The API surface was verified against the live instance rather than
inferred from upstream source, which changed several design decisions:
- The `jwt` cookie works verbatim as `Authorization: Bearer` and lasts 30
days, so there is no cookie jar and no refresh-session timer.
- Course contents live at /api/v3/course-rooms/{courseId}/board; there is
no GET /api/v3/courses/{id}.
- Files are a separate service (/api/v3/file/*) with its own OpenAPI doc.
- Board file elements carry no file id; attachments are resolved by
listing files-storage with parentType=boardnodes and the element id.
Read-only by construction: every client method is a GET, including the
api_get escape hatch. The endpoint is internet-facing by necessity, so a
leaked token being unable to act as the user is the key safety property.
Deploys as a container behind the Pi's existing Caddy, guarded by a
constant-time bearer check. Stateless — no database.
Verified: 28 unit tests, plus a 30-check end-to-end run driving a real
MCP client over Streamable HTTP against the live account.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
45 lines
1.4 KiB
Caddyfile
45 lines
1.4 KiB
Caddyfile
# Add this to the Pi's existing Caddyfile.
|
|
#
|
|
# Caddy obtains and renews the certificate automatically, provided the VPS
|
|
# forwards ports 80 and 443 through to this Caddy and the DNS name resolves to
|
|
# the VPS's public address.
|
|
#
|
|
# The bearer-token check lives in the application, not here: Caddy would have
|
|
# to be reloaded to rotate the token, whereas the app reads it from the
|
|
# environment. Caddy's job is TLS, timeouts and keeping the container off the
|
|
# public interface.
|
|
|
|
mcp.example.org {
|
|
encode zstd gzip
|
|
|
|
# `schulcloud-mcp` is the Compose service name; Docker's embedded DNS
|
|
# resolves it on the shared network. No host port is published.
|
|
reverse_proxy schulcloud-mcp:8080 {
|
|
# MCP's Streamable HTTP transport keeps a server-sent-events channel
|
|
# open for server-initiated messages. Without flush_interval -1 Caddy
|
|
# buffers those, and the connector appears to hang.
|
|
flush_interval -1
|
|
|
|
# Long enough for a `search` call, which walks every course.
|
|
transport http {
|
|
read_timeout 300s
|
|
write_timeout 300s
|
|
}
|
|
}
|
|
|
|
header {
|
|
Strict-Transport-Security "max-age=31536000; includeSubDomains"
|
|
X-Content-Type-Options "nosniff"
|
|
Referrer-Policy "no-referrer"
|
|
-Server
|
|
}
|
|
|
|
log {
|
|
output file /var/log/caddy/schulcloud-mcp.log
|
|
format json
|
|
# Request URLs are not secrets here (the token is in a header, not the
|
|
# path), but the Authorization header must never be written to disk.
|
|
# Caddy does not log headers by default; do not add them.
|
|
}
|
|
}
|