Schulcloud-MCP/src/config.ts

/**
 * 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.
 */

import { resolve } from 'node:path';

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;
	/**
	 * How often to ping the instance to hold the session open. Must stay well
	 * under the instance's `JWT_TIMEOUT_SECONDS` (7200s here) — see
	 * src/core/keepalive.ts. Zero disables the keepalive.
	 */
	keepaliveIntervalMs: number;

	/** Postgres for the search index and file mirror. Unset = live-only mode. */
	databaseUrl: string | undefined;
	/** Where mirrored file bytes live on disk. */
	mirrorDir: string;
	/** Files larger than this are indexed as metadata but not mirrored. */
	mirrorMaxBytes: number;
	/** Index personal files and submitted/returned work as well as course content. */
	indexPersonalFiles: boolean;
	/** How often to re-crawl on a timer. Zero = only on demand. */
	crawlIntervalMs: number;
}

function required(name: string): string {
	const value = process.env[name]?.trim();
	if (!value) throw new Error(`Missing required environment variable ${name}`);
	return value;
}

/** `1`, `true`, `yes` and `on` are all true; anything else falls back. */
function bool(name: string, fallback: boolean): boolean {
	const raw = process.env[name]?.trim().toLowerCase();
	if (!raw) return fallback;
	return ['1', 'true', 'yes', 'on'].includes(raw);
}

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;
}

/** Like `int`, but 0 is meaningful (it disables the feature) rather than invalid. */
function intAllowingZero(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 non-negative 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),
		keepaliveIntervalMs: intAllowingZero('KEEPALIVE_INTERVAL_MS', 30 * 60_000),
		databaseUrl: process.env.DATABASE_URL?.trim() || undefined,
		// Absolute: res.sendFile rejects a relative path, and resolveWithin only
		// returns an absolute path if the root it is given is one.
		mirrorDir: resolve(process.env.MIRROR_DIR?.trim() || '/var/lib/schulcloud-mcp/mirror'),
		mirrorMaxBytes: int('MIRROR_MAX_BYTES', 64 * 1024 * 1024),
		// Off by default: submissions are per task, so this roughly doubles the
		// cost of a full crawl. Worth turning on to make your own handed-in work
		// searchable, which no other route offers.
		indexPersonalFiles: bool('INDEX_PERSONAL_FILES', false),
		crawlIntervalMs: intAllowingZero('CRAWL_INTERVAL_MS', 6 * 60 * 60_000),
	};
}