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>
37 lines
1.1 KiB
TypeScript
37 lines
1.1 KiB
TypeScript
import assert from 'node:assert/strict';
|
|
import { afterEach, describe, it } from 'node:test';
|
|
import { loadConfig } from '../src/config.ts';
|
|
|
|
const SAVED = { ...process.env };
|
|
afterEach(() => {
|
|
process.env = { ...SAVED };
|
|
});
|
|
|
|
describe('loadConfig', () => {
|
|
it('requires the instance URL and token', () => {
|
|
delete process.env.TSC_URL;
|
|
process.env.TSC_JWT_COOKIE = 'x';
|
|
assert.throws(() => loadConfig(), /TSC_URL/);
|
|
});
|
|
|
|
it('strips trailing slashes so paths concatenate cleanly', () => {
|
|
process.env.TSC_URL = 'https://example.org///';
|
|
process.env.TSC_JWT_COOKIE = 'x';
|
|
assert.equal(loadConfig().baseUrl, 'https://example.org');
|
|
});
|
|
|
|
it('rejects a non-numeric port rather than silently defaulting', () => {
|
|
process.env.TSC_URL = 'https://example.org';
|
|
process.env.TSC_JWT_COOKIE = 'x';
|
|
process.env.PORT = 'not-a-number';
|
|
assert.throws(() => loadConfig(), /PORT/);
|
|
});
|
|
|
|
it('treats a blank auth token as absent', () => {
|
|
process.env.TSC_URL = 'https://example.org';
|
|
process.env.TSC_JWT_COOKIE = 'x';
|
|
process.env.MCP_AUTH_TOKEN = ' ';
|
|
assert.equal(loadConfig().authToken, undefined);
|
|
});
|
|
});
|