Schulcloud-MCP/src/mcp/resources.ts

import { ResourceTemplate, type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import type { ReadResourceResult, Resource } from '@modelcontextprotocol/sdk/types.js';
import type { ServerContext } from '../context.ts';
import { readCourse } from './tools/content.ts';
import { readRoom } from './tools/rooms.ts';
import { toProtocolError } from './tools/result.ts';

/**
 * Courses and rooms as MCP resources: things a person attaches to a message,
 * where tools are things the model decides to call.
 *
 * A resource carries exactly what get_course or get_room returns, so an
 * attached course and a fetched one read the same, and the ids in it lead to
 * the same tools. Deliberately coarse: a picker lists every resource at once,
 * which suits some twenty-odd courses and not the thousand-odd files.
 *
 * The labels are German because people read them in a picker; the content
 * stays the English Markdown the tools return, since the model reads that.
 */

const MARKDOWN = 'text/markdown';

export function courseUri(courseId: string): string {
	return `schulcloud://courses/${courseId}`;
}

export function roomUri(roomId: string): string {
	return `schulcloud://rooms/${roomId}`;
}

export function registerResources(server: McpServer, context: ServerContext): void {
	server.registerResource(
		'course',
		new ResourceTemplate(courseUri('{courseId}'), {
			list: async () => ({
				resources: await listOrEmpty('courses', async () =>
					(await context.client.listAllCourses()).map((course) => entry(courseUri(course.id), 'Kurs', course.title)),
				),
			}),
		}),
		{
			title: 'Kurs',
			description: 'Ein Kurs aus der Schulcloud: Boards, Themen, Aufgaben und Kurs-Dateien im Überblick.',
			mimeType: MARKDOWN,
		},
		async (uri, { courseId }) => read(uri, `read course ${courseId}`, () => readCourse(context, String(courseId))),
	);

	server.registerResource(
		'room',
		new ResourceTemplate(roomUri('{roomId}'), {
			list: async () => ({
				resources: await listOrEmpty('rooms', async () =>
					(await context.client.listRooms()).map((room) => entry(roomUri(room.id), 'Raum', room.name)),
				),
			}),
		}),
		{
			title: 'Raum',
			description: 'Ein Raum aus der Schulcloud: seine Boards und wer darin ist.',
			mimeType: MARKDOWN,
		},
		async (uri, { roomId }) => read(uri, `read room ${roomId}`, () => readRoom(context, String(roomId))),
	);
}

function entry(uri: string, kind: string, name: string): Resource {
	return {
		uri,
		name,
		title: name,
		// Claude Code's @ autocomplete shows the description in place of the
		// name, so a description without the name would leave every entry
		// reading as an opaque id.
		description: `${kind}: ${name}`,
		mimeType: MARKDOWN,
	};
}

/**
 * A listing that fails yields no entries instead of an error.
 *
 * Every resource kind is listed in one `resources/list` reply, so one refused
 * kind would otherwise cost the rest. A client may also treat a failed
 * listing as a failed server and drop its tools with it — and the tools are
 * where an expired token gets explained.
 */
async function listOrEmpty(kind: string, load: () => Promise<Resource[]>): Promise<Resource[]> {
	try {
		return await load();
	} catch (error) {
		console.error(`[schulcloud-mcp] resources: listing ${kind} failed:`, toProtocolError(error, `list ${kind}`).message);
		return [];
	}
}

async function read(uri: URL, action: string, render: () => Promise<string>): Promise<ReadResourceResult> {
	try {
		return { contents: [{ uri: uri.href, mimeType: MARKDOWN, text: await render() }] };
	} catch (error) {
		throw toProtocolError(error, action);
	}
}