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>
2026-09-11 23:52:12 +02:00
commit 35125b7683
38 changed files with 6317 additions and 0 deletions
--- a/src/http/auth.ts
+++ b/src/http/auth.ts
@@ -0,0 +1,50 @@
+import { timingSafeEqual } from 'node:crypto';
+import type { NextFunction, Request, Response } from 'express';
+
+/**
+ * Bearer-token gate for the public endpoint.
+ *
+ * This server is reachable from the internet by construction — Claude's
+ * connectors call it from Anthropic's cloud, not from the user's machine — so
+ * the token is the only thing between a stranger and the account's data.
+ * Comparison is constant-time, and a miss returns a bare 401 with a
+ * `WWW-Authenticate` challenge and no detail about why.
+ */
+export function bearerAuth(expected: string) {
+	const expectedBytes = Buffer.from(expected, 'utf8');
+
+	return function authenticate(req: Request, res: Response, next: NextFunction): void {
+		const presented = extractToken(req.get('authorization'), req.get('x-api-key'));
+		if (presented === undefined || !constantTimeEquals(Buffer.from(presented, 'utf8'), expectedBytes)) {
+			res.setHeader('WWW-Authenticate', 'Bearer realm="schulcloud-mcp"');
+			res.status(401).json({
+				jsonrpc: '2.0',
+				error: { code: -32001, message: 'Unauthorized' },
+				id: null,
+			});
+			return;
+		}
+		next();
+	};
+}
+
+function extractToken(authorization: string | undefined, apiKey: string | undefined): string | undefined {
+	if (authorization) {
+		const match = /^Bearer\s+(.+)$/i.exec(authorization.trim());
+		if (match?.[1]) return match[1].trim();
+	}
+	// Some connector UIs only offer a custom header rather than Authorization.
+	return apiKey?.trim() || undefined;
+}
+
+function constantTimeEquals(a: Buffer, b: Buffer): boolean {
+	// timingSafeEqual throws on length mismatch, which would itself leak length.
+	// Hash-free equalisation: compare against a padded copy of the same size.
+	if (a.length !== b.length) {
+		const padded = Buffer.alloc(b.length);
+		a.copy(padded, 0, 0, Math.min(a.length, b.length));
+		timingSafeEqual(padded, b);
+		return false;
+	}
+	return timingSafeEqual(a, b);
+}
--- a/src/http/server.ts
+++ b/src/http/server.ts
@@ -0,0 +1,144 @@
+import crypto from 'node:crypto';
+import express, { type Request, type Response } from 'express';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import type { Config } from '../config.ts';
+import { createServer } from '../server.ts';
+import { bearerAuth } from './auth.ts';
+
+/**
+ * Streamable-HTTP front end, for use as a remote MCP connector.
+ *
+ * Sessions are stateful: a client POSTs `initialize`, gets an
+ * `Mcp-Session-Id` back, and reuses it for subsequent POSTs, an optional GET
+ * (the SSE channel for server-initiated messages), and a DELETE to close.
+ * Each session owns one McpServer instance, which keeps per-session caches
+ * (the `/me` lookup) from leaking between callers.
+ */
+
+const MCP_PATH = '/mcp';
+/** Sessions are dropped after this long without traffic, in case DELETE never arrives. */
+const SESSION_IDLE_MS = 30 * 60 * 1000;
+
+interface Session {
+	transport: StreamableHTTPServerTransport;
+	close: () => Promise<void>;
+	lastSeen: number;
+}
+
+export function createHttpApp(config: Config): express.Express {
+	const app = express();
+	app.disable('x-powered-by');
+	// Caddy sits in front and terminates TLS; trust its forwarding headers so
+	// logged client IPs are real rather than the proxy's.
+	app.set('trust proxy', true);
+
+	const sessions = new Map<string, Session>();
+
+	const sweep = setInterval(() => {
+		const cutoff = Date.now() - SESSION_IDLE_MS;
+		for (const [id, session] of sessions) {
+			if (session.lastSeen < cutoff) {
+				sessions.delete(id);
+				void session.close().catch(() => {});
+			}
+		}
+	}, 60_000);
+	sweep.unref();
+
+	// Liveness probe for Docker/Caddy. Deliberately before auth and free of any
+	// detail about the instance or the account.
+	app.get('/healthz', (_req, res) => {
+		res.json({ status: 'ok', sessions: sessions.size });
+	});
+
+	if (config.authToken) {
+		app.use(MCP_PATH, bearerAuth(config.authToken));
+	} else {
+		console.warn(
+			'[schulcloud-mcp] MCP_AUTH_TOKEN is not set — the endpoint is UNAUTHENTICATED. ' +
+				'Only acceptable when bound to localhost or an otherwise private network.',
+		);
+	}
+
+	app.use(MCP_PATH, express.json({ limit: '4mb' }));
+
+	app.post(MCP_PATH, async (req: Request, res: Response) => {
+		const sessionId = req.get('mcp-session-id');
+
+		try {
+			if (sessionId) {
+				const session = sessions.get(sessionId);
+				if (!session) {
+					res.status(404).json(rpcError(-32001, 'Unknown or expired session. Re-initialize.'));
+					return;
+				}
+				session.lastSeen = Date.now();
+				await session.transport.handleRequest(req, res, req.body);
+				return;
+			}
+
+			if (!isInitializeRequest(req.body)) {
+				res.status(400).json(rpcError(-32000, 'Missing Mcp-Session-Id header; send an initialize request first.'));
+				return;
+			}
+
+			const { server } = createServer(config);
+			const transport = new StreamableHTTPServerTransport({
+				sessionIdGenerator: () => crypto.randomUUID(),
+				onsessioninitialized: (id) => {
+					sessions.set(id, {
+						transport,
+						close: async () => {
+							await transport.close().catch(() => {});
+							await server.close().catch(() => {});
+						},
+						lastSeen: Date.now(),
+					});
+					console.log(`[schulcloud-mcp] session ${id} initialized`);
+				},
+			});
+
+			transport.onclose = () => {
+				if (transport.sessionId) {
+					sessions.delete(transport.sessionId);
+					console.log(`[schulcloud-mcp] session ${transport.sessionId} closed`);
+				}
+			};
+
+			await server.connect(transport);
+			await transport.handleRequest(req, res, req.body);
+		} catch (error) {
+			console.error('[schulcloud-mcp] POST failed:', error);
+			if (!res.headersSent) res.status(500).json(rpcError(-32603, 'Internal server error'));
+		}
+	});
+
+	// GET opens the server→client SSE stream; DELETE ends the session.
+	const bySession = async (req: Request, res: Response): Promise<void> => {
+		const sessionId = req.get('mcp-session-id');
+		const session = sessionId ? sessions.get(sessionId) : undefined;
+		if (!session) {
+			res.status(404).json(rpcError(-32001, 'Unknown or expired session.'));
+			return;
+		}
+		session.lastSeen = Date.now();
+		try {
+			await session.transport.handleRequest(req, res);
+		} catch (error) {
+			console.error('[schulcloud-mcp] session request failed:', error);
+			if (!res.headersSent) res.status(500).json(rpcError(-32603, 'Internal server error'));
+		}
+	};
+
+	app.get(MCP_PATH, bySession);
+	app.delete(MCP_PATH, bySession);
+
+	app.use((_req, res) => res.status(404).json({ error: 'not_found' }));
+
+	return app;
+}
+
+function rpcError(code: number, message: string) {
+	return { jsonrpc: '2.0' as const, error: { code, message }, id: null };
+}