Initial schulcloud-mcp server

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>

test/auth.test.ts

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { bearerAuth } from '../src/http/auth.ts';
+
+function run(headers: Record<string, string>): { status?: number; passed: boolean } {
+	const middleware = bearerAuth('correct-horse-battery-staple');
+	let status: number | undefined;
+	let passed = false;
+	const req = { get: (name: string) => headers[name.toLowerCase()] } as never;
+	const res = {
+		setHeader() {},
+		status(code: number) {
+			status = code;
+			return this;
+		},
+		json() {
+			return this;
+		},
+	} as never;
+	middleware(req, res, () => {
+		passed = true;
+	});
+	return { status, passed };
+}
+
+describe('bearerAuth', () => {
+	it('accepts the exact token', () => {
+		assert.equal(run({ authorization: 'Bearer correct-horse-battery-staple' }).passed, true);
+	});
+
+	it('accepts it via x-api-key, for connector UIs without an Authorization field', () => {
+		assert.equal(run({ 'x-api-key': 'correct-horse-battery-staple' }).passed, true);
+	});
+
+	it('is case-insensitive about the scheme but not the token', () => {
+		assert.equal(run({ authorization: 'bearer correct-horse-battery-staple' }).passed, true);
+		assert.equal(run({ authorization: 'Bearer CORRECT-HORSE-BATTERY-STAPLE' }).passed, false);
+	});
+
+	it('rejects a missing, empty, wrong or truncated token with 401', () => {
+		for (const headers of [
+			{},
+			{ authorization: '' },
+			{ authorization: 'Bearer ' },
+			{ authorization: 'Bearer wrong' },
+			{ authorization: 'Bearer correct-horse-battery-stapl' },
+			{ authorization: 'Bearer correct-horse-battery-staple-extra' },
+			{ authorization: 'Basic correct-horse-battery-staple' },
+		]) {
+			const result = run(headers as Record<string, string>);
+			assert.equal(result.passed, false, `should reject ${JSON.stringify(headers)}`);
+			assert.equal(result.status, 401);
+		}
+	});
+});

test/config.test.ts

@@ -0,0 +1,36 @@
+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);
+	});
+});

test/extract.test.ts

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { extractContent, formatBytes } from '../src/extract.ts';
+
+const MAX = 10_000;
+
+describe('extractContent', () => {
+	it('returns images inline as base64 without touching the bytes', async () => {
+		const png = Buffer.from('89504e470d0a1a0a', 'hex');
+		const result = await extractContent(png, 'image/png', 'a.png', MAX);
+		assert.equal(result.kind, 'image');
+		assert.equal(result.image?.base64, png.toString('base64'));
+		assert.equal(result.image?.mimeType, 'image/png');
+	});
+
+	it('reads plain text and normalises CRLF', async () => {
+		const result = await extractContent(Buffer.from('a\r\nb\r\n\r\n\r\n\r\nc'), 'text/plain', 'a.txt', MAX);
+		assert.equal(result.kind, 'text');
+		assert.equal(result.text, 'a\nb\n\nc');
+	});
+
+	it('recognises text even when the server mislabels it as octet-stream', async () => {
+		const result = await extractContent(Buffer.from('hello world'), 'application/octet-stream', 'note', MAX);
+		assert.equal(result.kind, 'text');
+		assert.equal(result.text, 'hello world');
+	});
+
+	it('reports binary content instead of emitting mojibake', async () => {
+		const bytes = Buffer.from([0x00, 0x01, 0x02, 0xff, 0xfe, 0x00]);
+		const result = await extractContent(bytes, 'application/octet-stream', 'blob.bin', MAX);
+		assert.equal(result.kind, 'binary');
+		assert.match(result.note, /no text extractor/);
+	});
+
+	it('truncates at the limit and says so', async () => {
+		const result = await extractContent(Buffer.from('x'.repeat(5000)), 'text/plain', 'a.txt', 100);
+		assert.equal(result.truncated, true);
+		assert.equal(result.text?.length, 100);
+		assert.match(result.note, /truncated to 100 characters \(of 5000\)/);
+	});
+
+	it('turns a parser failure into a note rather than throwing', async () => {
+		const result = await extractContent(Buffer.from('not really a pdf'), 'application/pdf', 'broken.pdf', MAX);
+		assert.equal(result.kind, 'binary');
+		assert.match(result.note, /Could not extract text|no text extractor/);
+	});
+});
+
+describe('formatBytes', () => {
+	it('scales units', () => {
+		assert.equal(formatBytes(512), '512 B');
+		assert.equal(formatBytes(2048), '2.0 KB');
+		assert.equal(formatBytes(5 * 1024 * 1024), '5.0 MB');
+	});
+});

test/render.test.ts

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { daysUntil, formatDate, htmlToText, joinSections, normalizeObjectId } from '../src/render.ts';
+
+describe('htmlToText', () => {
+	it('unwraps the CKEditor markup Schulcloud stores', () => {
+		assert.equal(htmlToText('<p>Hallo <strong>Welt</strong></p>'), 'Hallo Welt');
+	});
+
+	it('keeps the href when the link text differs from it', () => {
+		assert.equal(
+			htmlToText('<p><a href="https://example.org/x">Beispiel</a></p>'),
+			'Beispiel (https://example.org/x)',
+		);
+	});
+
+	it('does not duplicate a bare URL used as its own label', () => {
+		assert.equal(htmlToText('<a href="https://example.org">https://example.org</a>'), 'https://example.org');
+	});
+
+	it('renders list items as bullets and collapses blank runs', () => {
+		assert.equal(htmlToText('<ul><li>eins</li><li>zwei</li></ul>'), '- eins\n- zwei');
+	});
+
+	it('decodes entities, ampersand last so &amp;lt; stays literal', () => {
+		assert.equal(htmlToText('<p>a &amp;lt; b &lt; c &nbsp;d</p>'), 'a &lt; b < c  d');
+	});
+
+	it('returns an empty string for missing input', () => {
+		assert.equal(htmlToText(undefined), '');
+		assert.equal(htmlToText(null), '');
+	});
+});
+
+describe('formatDate', () => {
+	it('renders ISO timestamps as minute-precision UTC', () => {
+		assert.equal(formatDate('2026-08-17T08:00:00.000Z'), '2026-08-17 08:00');
+	});
+
+	it('passes through unparseable values rather than printing Invalid Date', () => {
+		assert.equal(formatDate('not a date'), 'not a date');
+	});
+
+	it('marks absent dates', () => {
+		assert.equal(formatDate(null), '—');
+	});
+});
+
+describe('daysUntil', () => {
+	it('is negative for past dates and undefined when unset', () => {
+		const yesterday = new Date(Date.now() - 86_400_000).toISOString();
+		assert.ok((daysUntil(yesterday) ?? 0) < 0);
+		assert.equal(daysUntil(undefined), undefined);
+	});
+});
+
+describe('joinSections', () => {
+	it('drops empty and falsy parts', () => {
+		assert.equal(joinSections(['a', '', undefined, false, '  ', 'b']), 'a\n\nb');
+	});
+});
+
+describe('normalizeObjectId', () => {
+	it('converts the buffer shape the legacy lesson API returns', () => {
+		const id = { buffer: { type: 'Buffer', data: [106, 130, 219, 101, 127, 25, 207, 115, 254, 60, 242, 13] } };
+		assert.equal(normalizeObjectId(id), '6a82db657f19cf73fe3cf20d');
+	});
+
+	it('passes plain strings through and gives up on anything else', () => {
+		assert.equal(normalizeObjectId('abc'), 'abc');
+		assert.equal(normalizeObjectId({}), undefined);
+	});
+});