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>
42 lines
1.2 KiB
Docker
42 lines
1.2 KiB
Docker
# syntax=docker/dockerfile:1
|
|
|
|
# Build stage: full dependency tree, compile TypeScript to dist/.
|
|
FROM node:22-alpine AS build
|
|
WORKDIR /app
|
|
COPY package.json package-lock.json ./
|
|
RUN npm ci
|
|
COPY tsconfig.json ./
|
|
COPY src ./src
|
|
RUN npm run build
|
|
|
|
# Prune to runtime dependencies only, in its own stage so the build tree
|
|
# (typescript, @types) never reaches the final image.
|
|
FROM node:22-alpine AS deps
|
|
WORKDIR /app
|
|
COPY package.json package-lock.json ./
|
|
RUN npm ci --omit=dev && npm cache clean --force
|
|
|
|
FROM node:22-alpine AS runtime
|
|
WORKDIR /app
|
|
ENV NODE_ENV=production
|
|
|
|
# Every extractor is pure JavaScript, so the runtime image needs no build
|
|
# toolchain — just a signal-forwarding init so SIGTERM reaches node.
|
|
RUN apk add --no-cache tini
|
|
|
|
COPY --from=deps /app/node_modules ./node_modules
|
|
COPY --from=build /app/dist ./dist
|
|
COPY package.json ./
|
|
|
|
# node:alpine ships an unprivileged `node` user; the process never writes to disk.
|
|
USER node
|
|
|
|
EXPOSE 8080
|
|
ENV PORT=8080 BIND_HOST=0.0.0.0
|
|
|
|
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
|
|
CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||8080)+'/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
|
|
|
|
ENTRYPOINT ["/sbin/tini", "--"]
|
|
CMD ["node", "dist/bin/http.js"]
|