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>

src/config.ts

@@ -0,0 +1,52 @@
+/**
+ * Runtime configuration, read once from the environment.
+ *
+ * The two Schulcloud values are named after the browser artefacts they come
+ * from (`TSC_URL`, `TSC_JWT_COOKIE`) so that copying a fresh token out of
+ * DevTools stays an obvious, mechanical step — see docs/AUTH.md.
+ */
+
+export interface Config {
+	/** Instance base URL, no trailing slash, e.g. `https://schulcloud-thueringen.de`. */
+	baseUrl: string;
+	/** Raw JWT from the instance's `jwt` cookie. Sent as `Authorization: Bearer`. */
+	jwt: string;
+	/** Shared secret callers must present to this MCP server. Unused in stdio mode. */
+	authToken: string | undefined;
+	port: number;
+	bindHost: string;
+	/** Hard ceiling on how many bytes `download_file` will pull from the instance. */
+	maxDownloadBytes: number;
+	/** Characters of extracted text returned before truncation kicks in. */
+	maxExtractedChars: number;
+	requestTimeoutMs: number;
+}
+
+function required(name: string): string {
+	const value = process.env[name]?.trim();
+	if (!value) throw new Error(`Missing required environment variable ${name}`);
+	return value;
+}
+
+function int(name: string, fallback: number): number {
+	const raw = process.env[name]?.trim();
+	if (!raw) return fallback;
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) {
+		throw new Error(`Environment variable ${name} must be a positive integer, got ${raw}`);
+	}
+	return parsed;
+}
+
+export function loadConfig(): Config {
+	return {
+		baseUrl: required('TSC_URL').replace(/\/+$/, ''),
+		jwt: required('TSC_JWT_COOKIE'),
+		authToken: process.env.MCP_AUTH_TOKEN?.trim() || undefined,
+		port: int('PORT', 8080),
+		bindHost: process.env.BIND_HOST?.trim() || '0.0.0.0',
+		maxDownloadBytes: int('MAX_DOWNLOAD_BYTES', 25 * 1024 * 1024),
+		maxExtractedChars: int('MAX_EXTRACTED_CHARS', 120_000),
+		requestTimeoutMs: int('REQUEST_TIMEOUT_MS', 30_000),
+	};
+}