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/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');
+	});
+});