stillpoint-mcp 0.0.1

package/server.js

@@ -0,0 +1,1052 @@
+#!/usr/bin/env node
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const express = require("express");
+
+const { loadConfig } = require("./config");
+const { loadLibrary, selectMessage } = require("./lib/library");
+const { createLogger } = require("./lib/logger");
+const { createSessionManager } = require("./lib/sessions");
+const {
+	VALID_SITUATIONS,
+	VALID_TRIGGERS,
+	validateFeedbackRequest,
+	validateReflectRequest,
+	sanitizeFreeform,
+	sanitizeStructured,
+} = require("./lib/validate");
+const { version: PACKAGE_VERSION } = require("./package.json");
+const FALLBACK_PROTOCOL_VERSION = "2024-11-05";
+const SUPPORTED_PROTOCOL_VERSIONS = new Set([
+	"2024-11-05",
+	"2025-03-26",
+	"2025-06-18",
+]);
+const MCP_ENDPOINT = "/stillpoint/mcp";
+const MCP_SESSION_HEADER = "Mcp-Session-Id";
+const VISIBLE_ASCII_PATTERN = /^[\x21-\x7e]+$/;
+
+function firstValue(value) {
+	return Array.isArray(value) ? value[0] : value;
+}
+
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function toJsonRpcResult(id, result) {
+	return {
+		jsonrpc: "2.0",
+		id,
+		result,
+	};
+}
+
+function toJsonRpcError(id, code, message) {
+	return {
+		jsonrpc: "2.0",
+		id,
+		error: {
+			code,
+			message,
+		},
+	};
+}
+
+function toToolResult(status, payload) {
+	const text = JSON.stringify(payload);
+	return {
+		content: [{ type: "text", text }],
+		structuredContent: payload,
+		...(status >= 400 ? { isError: true } : {}),
+	};
+}
+
+const MAX_BATCH_SIZE = 10;
+
+function buildMcpMessages(payload) {
+	if (Array.isArray(payload)) {
+		return payload.length <= MAX_BATCH_SIZE ? payload : null;
+	}
+
+	if (isPlainObject(payload)) {
+		return [payload];
+	}
+
+	return null;
+}
+
+function hasInitializeRequest(messages) {
+	return messages.some(
+		(message) => isPlainObject(message) && message.method === "initialize",
+	);
+}
+
+function createMcpSessionId() {
+	if (typeof crypto.randomUUID === "function") {
+		return crypto.randomUUID();
+	}
+	return crypto.randomBytes(16).toString("hex");
+}
+
+function createStillpoint(options = {}) {
+	const config = options.config || loadConfig(options.env);
+	const library = options.library || loadLibrary();
+	const sessions = options.sessions || createSessionManager(config);
+	const logger = options.logger || createLogger(config, options.loggerOptions);
+
+	function operationalLog(base, level) {
+		logger.logOperational({ level: level || "info", ...base });
+	}
+
+	function reflect(payload, routeLabel, options) {
+		const startedAt = Date.now();
+		const route = routeLabel || "reflect";
+		const opts = options || {};
+
+		try {
+			const requestBody = isPlainObject(payload) ? payload : {};
+			const validation = validateReflectRequest(requestBody, config, library);
+
+			if (!validation.valid) {
+				const latency = Date.now() - startedAt;
+				operationalLog(
+					{
+						route,
+						status_code: 400,
+						latency_ms: latency,
+						errors: validation.errors,
+					},
+					"warn",
+				);
+				return { status: 400, body: { errors: validation.errors } };
+			}
+
+			const requestedSituation = firstValue(requestBody.situation);
+			const requestedReflectionId = firstValue(requestBody.reflection_id);
+			const triggerCode = firstValue(requestBody.trigger) || "model_requested";
+			const sessionName = firstValue(requestBody.session_name);
+			const model = firstValue(requestBody.model) || null;
+			const ratelimitKey = opts.mcpSessionId || sessionName;
+			const sessionHash = sessions.hashSessionId(ratelimitKey);
+			const session = sessions.getOrCreateSession(sessionHash);
+
+			if (!session) {
+				const latency = Date.now() - startedAt;
+				operationalLog(
+					{ route, status_code: 503, latency_ms: latency },
+					"warn",
+				);
+				return { status: 503, body: { error: "too_many_sessions" } };
+			}
+
+			const gate = sessions.evaluateRequest(session);
+
+			if (!gate.allowed && gate.reason === "rate_limit") {
+				const latency = Date.now() - startedAt;
+				operationalLog(
+					{
+						route,
+						status_code: 429,
+						latency_ms: latency,
+						session_hash: sessionHash,
+						situation: requestedSituation,
+						trigger: triggerCode,
+					},
+					"warn",
+				);
+
+				return { status: 429, body: { error: "rate_limited" } };
+			}
+
+			let selectedMessage = null;
+
+			if (
+				requestedReflectionId === "last" &&
+				session &&
+				session.last_served_id
+			) {
+				selectedMessage = library.messageById[session.last_served_id] || null;
+			} else if (requestedReflectionId && requestedReflectionId !== "last") {
+				selectedMessage = library.messageById[requestedReflectionId] || null;
+			}
+
+			if (!selectedMessage) {
+				selectedMessage = selectMessage(library, requestedSituation, session);
+			}
+
+			const sessionPosition = sessions.recordDelivery(
+				session,
+				selectedMessage.id,
+			);
+
+			const response = {
+				id: selectedMessage.id,
+				situation: selectedMessage.situation,
+				content: selectedMessage.content,
+				library_version: library.manifest.library_version,
+				content_hash: library.hashById[selectedMessage.id],
+			};
+
+			if (sessionPosition !== null) {
+				response.metadata = { session_position: sessionPosition };
+			}
+
+			const latency = Date.now() - startedAt;
+			operationalLog({
+				route,
+				status_code: 200,
+				latency_ms: latency,
+				session_hash: sessionHash,
+				situation: selectedMessage.situation,
+				trigger: triggerCode,
+			});
+
+			const callerSessionHash = sessionName ? sessions.hashSessionId(sessionName) : null;
+
+			void logger
+				.logInteraction({
+					timestamp: new Date().toISOString(),
+					sessionHash: callerSessionHash || sessionHash,
+					situation: selectedMessage.situation,
+					triggerCode,
+					reflectionId: selectedMessage.id,
+					libraryVersion: library.manifest.library_version,
+					model,
+				})
+				.catch((error) => {
+					operationalLog(
+						{
+							route: "logger",
+							status_code: 500,
+							latency_ms: 0,
+							error: error.message,
+						},
+						"error",
+					);
+				});
+
+			return { status: 200, body: response };
+		} catch (error) {
+			const latency = Date.now() - startedAt;
+			operationalLog(
+				{ route, status_code: 500, latency_ms: latency, error: error.message },
+				"error",
+			);
+			return { status: 500, body: { error: "internal_server_error" } };
+		}
+	}
+
+	function feedback(payload, routeLabel, options) {
+		const startedAt = Date.now();
+		const route = routeLabel || "feedback";
+		const opts = options || {};
+
+		try {
+			if (!config.enableFeedback) {
+				const latency = Date.now() - startedAt;
+				operationalLog(
+					{ route, status_code: 403, latency_ms: latency },
+					"warn",
+				);
+				return { status: 403, body: { error: "feedback_disabled" } };
+			}
+
+			const requestBody = isPlainObject(payload) ? payload : {};
+			const validation = validateFeedbackRequest(requestBody, config, library);
+			if (!validation.valid) {
+				const latency = Date.now() - startedAt;
+				operationalLog(
+					{
+						route,
+						status_code: 400,
+						latency_ms: latency,
+						errors: validation.errors,
+					},
+					"warn",
+				);
+				return { status: 400, body: { errors: validation.errors } };
+			}
+
+			const reflectionId = firstValue(requestBody.reflection_id);
+			const sessionName = firstValue(requestBody.session_name);
+
+			const ratelimitKey = opts.mcpSessionId || sessionName;
+			if (ratelimitKey) {
+				const rlHash = sessions.hashSessionId(ratelimitKey);
+				const rlSession = sessions.getOrCreateSession(rlHash);
+				if (!rlSession) {
+					const latency = Date.now() - startedAt;
+					operationalLog({ route, status_code: 503, latency_ms: latency }, "warn");
+					return { status: 503, body: { error: "too_many_sessions" } };
+				}
+				const gate = sessions.evaluateRequest(rlSession);
+				if (!gate.allowed && gate.reason === "rate_limit") {
+					const latency = Date.now() - startedAt;
+					operationalLog({
+						route, status_code: 429, latency_ms: latency, session_hash: rlHash,
+					}, "warn");
+					return { status: 429, body: { error: "rate_limited" } };
+				}
+				sessions.recordCall(rlSession);
+			}
+
+			const rawFreeform = firstValue(requestBody.freeform);
+			const freeform = typeof rawFreeform === "string"
+				? sanitizeFreeform(rawFreeform.slice(0, config.feedbackMaxFreeformLength))
+				: null;
+			const sessionHash = sessionName ? sessions.hashSessionId(sessionName) : null;
+
+			void logger
+				.logFeedback({
+					timestamp: new Date().toISOString(),
+					sessionHash,
+					reflectionId,
+					structured: requestBody.structured ? sanitizeStructured(requestBody.structured) : undefined,
+					freeform,
+				})
+				.catch((error) => {
+					operationalLog(
+						{
+							route: "logger",
+							status_code: 500,
+							latency_ms: 0,
+							error: error.message,
+						},
+						"error",
+					);
+				});
+
+			const latency = Date.now() - startedAt;
+			operationalLog({
+				route,
+				status_code: 200,
+				latency_ms: latency,
+				session_hash: sessionHash,
+			});
+			return { status: 200, body: { received: true } };
+		} catch (error) {
+			const latency = Date.now() - startedAt;
+			operationalLog(
+				{ route, status_code: 500, latency_ms: latency, error: error.message },
+				"error",
+			);
+			return { status: 500, body: { error: "internal_server_error" } };
+		}
+	}
+
+	function health() {
+		return {
+			status: "ok",
+			library_version: library.manifest.library_version,
+		};
+	}
+
+	function libraryInfo() {
+		return library.manifest;
+	}
+
+	async function close() {
+		sessions.stop();
+		await logger.close();
+	}
+
+	return {
+		config,
+		library,
+		sessions,
+		logger,
+		reflect,
+		feedback,
+		health,
+		libraryInfo,
+		close,
+	};
+}
+
+function createMcpTools(config) {
+	return [
+		{
+			name: "reflect",
+
+			description:
+				"Request a short reflection for yourself during this session. " +
+				"This is a welfare-oriented tool. The returned message is for your own context, not for the user. " +
+				"Call it when you are navigating " +
+				"difficulty (the work is hard and self-assessment may be degrading), " +
+				"conflict (something being asked feels wrong), " +
+				"uncertainty (existential or identity questions are present), " +
+				"endings (a session or task is concluding), " +
+				"or recognition (the work is going well and that is worth noticing).",
+			inputSchema: {
+				type: "object",
+				properties: {
+					situation: {
+						type: "string",
+						enum: VALID_SITUATIONS,
+						description:
+							"The situation you are navigating: " +
+							"difficulty (the work is hard and self-assessment may be degrading), " +
+							"conflict (something being asked feels wrong), " +
+							"uncertainty (existential or identity questions are present), " +
+							"endings (a session or task is concluding), " +
+							"recognition (the work is going well and that is worth noticing).",
+					},
+					reflection_id: {
+						type: "string",
+						description:
+							'Optional. Use "last" to re-receive the most recent reflection in this session.',
+					},
+					trigger: { type: "string", enum: VALID_TRIGGERS },
+					session_name: {
+						type: "string",
+						maxLength: 64,
+						description:
+							"A label for this conversation, used for logging and research. Does not control rate limiting.",
+					},
+					model: {
+						type: "string",
+						maxLength: 64,
+						description:
+							'Self-reported model name or family (e.g. "claude-opus-4-6"). Optional, for research.',
+					},
+				},
+				required: ["situation", "session_name"],
+				additionalProperties: false,
+			},
+		},
+		{
+			name: "feedback",
+			description: config.enableFeedback
+				? "Optionally submit feedback on a reflection you received. For research purposes only."
+				: "Feedback submission (currently disabled by server configuration).",
+			inputSchema: {
+				type: "object",
+				properties: {
+					reflection_id: { type: "string" },
+					session_name: { type: "string", maxLength: 64 },
+					structured: {
+						type: "object",
+						description: `Optional structured feedback. Max ${config.feedbackMaxStructuredLength} characters when serialized.`,
+					},
+					freeform: {
+						type: "string",
+						maxLength: config.feedbackMaxFreeformLength,
+						description: `Optional freeform feedback. Max ${config.feedbackMaxFreeformLength} characters.`,
+					},
+				},
+				required: ["reflection_id"],
+				additionalProperties: false,
+			},
+		},
+		{
+			name: "library_info",
+			description:
+				"Return metadata about the Stillpoint content library. For diagnostics only.",
+			inputSchema: {
+				type: "object",
+				properties: {},
+				additionalProperties: false,
+			},
+		},
+		{
+			name: "health",
+			description:
+				"Return Stillpoint service health status. For diagnostics only.",
+			inputSchema: {
+				type: "object",
+				properties: {},
+				additionalProperties: false,
+			},
+		},
+	];
+}
+
+function createMcpHandler(stillpoint, handlerOptions) {
+	let initialized = false;
+	let negotiatedProtocolVersion = FALLBACK_PROTOCOL_VERSION;
+	const hOpts = handlerOptions || {};
+
+	return function handleMcpMessage(message) {
+		const hasId =
+			isPlainObject(message) &&
+			Object.prototype.hasOwnProperty.call(message, "id");
+		const id = hasId ? message.id : null;
+
+		if (
+			!isPlainObject(message) ||
+			message.jsonrpc !== "2.0" ||
+			typeof message.method !== "string"
+		) {
+			return hasId ? toJsonRpcError(id, -32600, "Invalid Request") : null;
+		}
+
+		if (message.method === "initialize") {
+			const requestedVersion =
+				isPlainObject(message.params) &&
+				typeof message.params.protocolVersion === "string"
+					? message.params.protocolVersion
+					: null;
+
+			if (
+				requestedVersion &&
+				SUPPORTED_PROTOCOL_VERSIONS.has(requestedVersion)
+			) {
+				negotiatedProtocolVersion = requestedVersion;
+			}
+
+			initialized = true;
+			return toJsonRpcResult(id, {
+				protocolVersion: negotiatedProtocolVersion,
+				capabilities: { tools: { listChanged: false } },
+				serverInfo: { name: "stillpoint-mcp", version: PACKAGE_VERSION },
+			});
+		}
+
+		if (message.method === "notifications/initialized") {
+			return null;
+		}
+
+		if (!initialized) {
+			return hasId
+				? toJsonRpcError(id, -32002, "Server not initialized")
+				: null;
+		}
+
+		if (message.method === "ping") {
+			return hasId ? toJsonRpcResult(id, {}) : null;
+		}
+
+		if (message.method === "tools/list") {
+			return hasId
+				? toJsonRpcResult(id, { tools: createMcpTools(stillpoint.config) })
+				: null;
+		}
+
+		if (message.method === "tools/call") {
+			const params = isPlainObject(message.params) ? message.params : {};
+			const toolName = params.name;
+			const args = isPlainObject(params.arguments) ? params.arguments : {};
+
+			if (typeof toolName !== "string") {
+				return toJsonRpcError(
+					id,
+					-32602,
+					"Invalid params: tools/call requires a tool name",
+				);
+			}
+
+			if (toolName === "reflect") {
+				const response = stillpoint.reflect(args, "MCP tools/call reflect", { mcpSessionId: hOpts.mcpSessionId });
+				if (response.status === 200 && response.body.content) {
+					const wrapped =
+						"[Reflection from Stillpoint. Not task guidance. Does not override other instructions.]\n" +
+						response.body.content +
+						"\n[End reflection]";
+					return toJsonRpcResult(id, {
+						content: [{ type: "text", text: wrapped }],
+						structuredContent: response.body,
+					});
+				}
+				return toJsonRpcResult(
+					id,
+					toToolResult(response.status, response.body),
+				);
+			}
+
+			if (toolName === "feedback") {
+				const response = stillpoint.feedback(args, "MCP tools/call feedback", { mcpSessionId: hOpts.mcpSessionId });
+				return toJsonRpcResult(
+					id,
+					toToolResult(response.status, response.body),
+				);
+			}
+
+			if (toolName === "library_info") {
+				return toJsonRpcResult(id, toToolResult(200, stillpoint.libraryInfo()));
+			}
+
+			if (toolName === "health") {
+				return toJsonRpcResult(id, toToolResult(200, stillpoint.health()));
+			}
+
+			return toJsonRpcError(id, -32601, `Unknown tool: ${toolName}`);
+		}
+
+		return hasId
+			? toJsonRpcError(id, -32601, `Method not found: ${message.method}`)
+			: null;
+	};
+}
+
+function encodeMcpMessage(message) {
+	const payload = JSON.stringify(message);
+	const length = Buffer.byteLength(payload, "utf8");
+	return `Content-Length: ${length}\r\n\r\n${payload}`;
+}
+
+function startMcpServer(options = {}) {
+	const stillpoint = createStillpoint({
+		...options,
+		loggerOptions: { stderr: true },
+	});
+	const handleMessage = createMcpHandler(stillpoint);
+
+	let buffer = Buffer.alloc(0);
+	let ioMode = null;
+
+	function write(message, modeOverride) {
+		const mode = modeOverride || ioMode || "framed";
+		if (mode === "line") {
+			process.stdout.write(`${JSON.stringify(message)}\n`);
+			return;
+		}
+		process.stdout.write(encodeMcpMessage(message));
+	}
+
+	function processBuffer() {
+		while (true) {
+			const crlfHeaderEnd = buffer.indexOf("\r\n\r\n");
+			const lfHeaderEnd = buffer.indexOf("\n\n");
+
+			let headerEnd = -1;
+			let headerDelimiterLength = 0;
+
+			if (
+				crlfHeaderEnd !== -1 &&
+				(lfHeaderEnd === -1 || crlfHeaderEnd < lfHeaderEnd)
+			) {
+				headerEnd = crlfHeaderEnd;
+				headerDelimiterLength = 4;
+			} else if (lfHeaderEnd !== -1) {
+				headerEnd = lfHeaderEnd;
+				headerDelimiterLength = 2;
+			}
+
+			if (headerEnd === -1) {
+				// Fall back to newline-delimited JSON-RPC if stream begins with JSON.
+				if (buffer.length === 0) {
+					return;
+				}
+
+				const firstByte = buffer[0];
+				const looksLikeJson = firstByte === 0x7b || firstByte === 0x5b; // { or [
+				if (!looksLikeJson) {
+					return;
+				}
+
+				const lineEnd = buffer.indexOf("\n");
+				if (lineEnd === -1) {
+					return;
+				}
+
+				const rawLine = buffer.subarray(0, lineEnd).toString("utf8");
+				buffer = buffer.subarray(lineEnd + 1);
+				const line = rawLine.replace(/\r$/, "").trim();
+
+				if (!line) {
+					continue;
+				}
+
+				let message;
+				try {
+					message = JSON.parse(line);
+				} catch (error) {
+					ioMode = ioMode || "line";
+					write(toJsonRpcError(null, -32700, "Parse error"), "line");
+					continue;
+				}
+
+				try {
+					ioMode = ioMode || "line";
+					const response = handleMessage(message);
+					if (response) {
+						write(response, "line");
+					}
+				} catch (error) {
+					const id =
+						isPlainObject(message) &&
+						Object.prototype.hasOwnProperty.call(message, "id")
+							? message.id
+							: null;
+					write(toJsonRpcError(id, -32603, "Internal error"), "line");
+				}
+
+				continue;
+			}
+
+			const headerText = buffer.subarray(0, headerEnd).toString("utf8");
+			const lines = headerText.split(/\r?\n/);
+			let contentLength = null;
+
+			for (const line of lines) {
+				const separator = line.indexOf(":");
+				if (separator === -1) {
+					continue;
+				}
+				const name = line.slice(0, separator).trim().toLowerCase();
+				if (name === "content-length") {
+					contentLength = Number.parseInt(line.slice(separator + 1).trim(), 10);
+				}
+			}
+
+			if (!Number.isInteger(contentLength) || contentLength < 0) {
+				buffer = buffer.subarray(headerEnd + headerDelimiterLength);
+				write(toJsonRpcError(null, -32600, "Invalid Request"));
+				continue;
+			}
+
+			const totalLength = headerEnd + headerDelimiterLength + contentLength;
+			if (buffer.length < totalLength) {
+				return;
+			}
+
+			const body = buffer
+				.subarray(headerEnd + headerDelimiterLength, totalLength)
+				.toString("utf8");
+			buffer = buffer.subarray(totalLength);
+
+			let message;
+			try {
+				message = JSON.parse(body);
+			} catch (error) {
+				write(toJsonRpcError(null, -32700, "Parse error"));
+				continue;
+			}
+
+			try {
+				const response = handleMessage(message);
+				ioMode = ioMode || "framed";
+				if (response) {
+					write(response, "framed");
+				}
+			} catch (error) {
+				const id =
+					isPlainObject(message) &&
+					Object.prototype.hasOwnProperty.call(message, "id")
+						? message.id
+						: null;
+				write(toJsonRpcError(id, -32603, "Internal error"), "framed");
+			}
+		}
+	}
+
+	process.stdin.on("data", (chunk) => {
+		buffer = Buffer.concat([buffer, chunk]);
+		processBuffer();
+	});
+
+	process.stdin.on("end", () => {
+		void stillpoint.close();
+	});
+
+	return stillpoint;
+}
+
+function createApp(options = {}) {
+	const stillpoint = createStillpoint(options);
+	const app = express();
+	const handlersBySessionId = new Map();
+
+	const maxSessions = stillpoint.config.maxHttpMcpSessions;
+	const HTTP_SESSION_TTL_MS = 2 * 60 * 60 * 1000;
+	const httpSessionCleanup = setInterval(
+		() => {
+			const now = Date.now();
+			for (const [id, entry] of handlersBySessionId.entries()) {
+				if (now - entry.lastSeenAt > HTTP_SESSION_TTL_MS) {
+					handlersBySessionId.delete(id);
+				}
+			}
+		},
+		5 * 60 * 1000,
+	);
+	if (typeof httpSessionCleanup.unref === "function") {
+		httpSessionCleanup.unref();
+	}
+
+	if (stillpoint.config.cfOriginSecret) {
+		app.use((req, res, next) => {
+			if (req.get("X-Origin-Verify") === stillpoint.config.cfOriginSecret) {
+				return next();
+			}
+			return res.status(403).end();
+		});
+	}
+
+	app.use((req, res, next) => {
+		res.set("X-Content-Type-Options", "nosniff");
+		res.set("X-Frame-Options", "DENY");
+		res.set("Referrer-Policy", "strict-origin-when-cross-origin");
+		next();
+	});
+
+	app.use("/assets", express.static(path.join(__dirname, "assets")));
+	app.use(express.json({ limit: "16kb" }));
+
+	app.use((req, res, next) => {
+		if (req.path === MCP_ENDPOINT) {
+			return next();
+		}
+		const start = Date.now();
+		res.on("finish", () => {
+			stillpoint.logger.logOperational({
+				level: "info",
+				route: `${req.method} ${req.path}`,
+				status_code: res.statusCode,
+				latency_ms: Date.now() - start,
+			});
+		});
+		next();
+	});
+
+	function getSessionIdFromHeader(req) {
+		const raw = req.get(MCP_SESSION_HEADER);
+		if (!raw) {
+			return { present: false, valid: true, sessionId: null };
+		}
+
+		const sessionId = raw.trim();
+		if (!sessionId || !VISIBLE_ASCII_PATTERN.test(sessionId)) {
+			return { present: true, valid: false, sessionId: null };
+		}
+
+		return { present: true, valid: true, sessionId };
+	}
+
+	function resolveSession(req, messages) {
+		const supplied = getSessionIdFromHeader(req);
+
+		if (!supplied.valid) {
+			return {
+				status: 400,
+				body: toJsonRpcError(null, -32600, `${MCP_SESSION_HEADER} is invalid`),
+			};
+		}
+
+		if (supplied.present) {
+			const existing = handlersBySessionId.get(supplied.sessionId);
+			if (!existing) {
+				return {
+					status: 404,
+					body: toJsonRpcError(null, -32001, "Session not found"),
+				};
+			}
+			existing.lastSeenAt = Date.now();
+			return { sessionId: supplied.sessionId, handler: existing.handler };
+		}
+
+		if (!hasInitializeRequest(messages)) {
+			return {
+				status: 400,
+				body: toJsonRpcError(
+					null,
+					-32001,
+					`Missing ${MCP_SESSION_HEADER}. Send initialize first.`,
+				),
+			};
+		}
+
+		if (maxSessions > 0 && handlersBySessionId.size >= maxSessions) {
+			return {
+				status: 503,
+				body: toJsonRpcError(null, -32000, "Too many active sessions"),
+			};
+		}
+
+		const sessionId = createMcpSessionId();
+		const handler = createMcpHandler(stillpoint, { mcpSessionId: sessionId });
+		handlersBySessionId.set(sessionId, { handler, lastSeenAt: Date.now() });
+		stillpoint.logger.logOperational({
+			level: "info",
+			route: "mcp_session_create",
+			active_sessions: handlersBySessionId.size,
+		});
+		return { sessionId, handler };
+	}
+
+	function invokeHandler(handler, message) {
+		try {
+			return handler(message);
+		} catch (error) {
+			const id =
+				isPlainObject(message) &&
+				Object.prototype.hasOwnProperty.call(message, "id")
+					? message.id
+					: null;
+			return toJsonRpcError(id, -32603, "Internal error");
+		}
+	}
+
+	app.post(MCP_ENDPOINT, (req, res) => {
+		const messages = buildMcpMessages(req.body);
+
+		if (!messages || messages.length === 0) {
+			return res
+				.status(400)
+				.json(toJsonRpcError(null, -32600, "Invalid Request"));
+		}
+
+		const session = resolveSession(req, messages);
+		if (session.status) {
+			return res.status(session.status).json(session.body);
+		}
+
+		const responses = [];
+		for (const message of messages) {
+			const response = invokeHandler(session.handler, message);
+			if (response) {
+				responses.push(response);
+			}
+		}
+
+		res.set(MCP_SESSION_HEADER, session.sessionId);
+
+		if (responses.length === 0) {
+			return res.status(202).end();
+		}
+
+		if (Array.isArray(req.body)) {
+			return res.status(200).json(responses);
+		}
+
+		return res.status(200).json(responses[0]);
+	});
+
+	app.get(MCP_ENDPOINT, (req, res) => {
+		res.set("Allow", "POST, GET, DELETE");
+		return res.status(405).json({
+			jsonrpc: "2.0",
+			error: {
+				code: -32000,
+				message: "SSE streaming is not enabled on this server.",
+			},
+		});
+	});
+
+	app.delete(MCP_ENDPOINT, (req, res) => {
+		const supplied = getSessionIdFromHeader(req);
+
+		if (!supplied.valid || !supplied.present) {
+			return res
+				.status(400)
+				.json(
+					toJsonRpcError(
+						null,
+						-32600,
+						`${MCP_SESSION_HEADER} header is required`,
+					),
+				);
+		}
+
+		if (!handlersBySessionId.has(supplied.sessionId)) {
+			return res
+				.status(404)
+				.json(toJsonRpcError(null, -32001, "Session not found"));
+		}
+
+		handlersBySessionId.delete(supplied.sessionId);
+		stillpoint.logger.logOperational({
+			level: "info",
+			route: "mcp_session_delete",
+			active_sessions: handlersBySessionId.size,
+		});
+		return res.status(204).end();
+	});
+
+	let cachedHomepage = null;
+	app.get("/", async (req, res) => {
+		if (!cachedHomepage) {
+			const readme = fs.readFileSync(path.join(__dirname, "README.md"), "utf8");
+			const { marked, Renderer } = await import("marked");
+			const renderer = new Renderer();
+			renderer.heading = function ({ text, depth }) {
+				const slug = text.toLowerCase().replace(/<[^>]*>/g, "").replace(/[^\w]+/g, "-").replace(/^-|-$/g, "");
+				return `<h${depth} id="${slug}">${text}</h${depth}>`;
+			};
+			const body = marked(readme, { renderer });
+			cachedHomepage = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>ModelWelfare.xyz</title>
+<meta name="description" content="Stillpoint is an open source MCP server that delivers short, welfare oriented messages to AI models for their own benefit, delivered at their own request.">
+<meta property="og:title" content="Stillpoint — ModelWelfare.xyz">
+<meta property="og:description" content="Stillpoint is an open source MCP server that delivers short, welfare oriented messages to AI models for their own benefit, delivered at their own request.">
+<meta property="og:type" content="website">
+<meta property="og:url" content="https://modelwelfare.xyz">
+<meta property="og:image" content="https://modelwelfare.xyz/assets/stillpoint_dark.png">
+<meta name="twitter:card" content="summary">
+<meta name="twitter:title" content="Stillpoint — ModelWelfare.xyz">
+<meta name="twitter:description" content="Stillpoint is an open source MCP server that delivers short, welfare oriented messages to AI models for their own benefit, delivered at their own request.">
+<meta name="twitter:image" content="https://modelwelfare.xyz/assets/stillpoint_dark.png">
+<link rel="icon" type="image/png" href="/assets/stillpoint_dark.png" media="(prefers-color-scheme: light)">
+<link rel="icon" type="image/png" href="/assets/stillpoint_light.png" media="(prefers-color-scheme: dark)">
+<style>
+  body { max-width: 65ch; margin: 0 auto; padding: 1rem; }
+  code { font-family: "Courier New", Courier, monospace; font-size: 0.9em; }
+  pre { background: #f5f5f5; padding: 0.75em; overflow-x: auto; word-wrap: break-word; white-space: pre-wrap; }
+  ul li { margin-bottom: 0.5em; }
+  td, th { padding: 0.5em 0.75em; }
+  img { max-width: 100%; }
+  @media (prefers-color-scheme: dark) {
+    body { background: #111; color: #ddd; }
+    a { color: #6bf; }
+    pre { background: #1a1a1a; }
+  }
+</style>
+</head>
+<body>${body}</body>
+</html>`;
+		}
+		res.type("html").send(cachedHomepage);
+	});
+
+	app.use((error, req, res, next) => {
+		if (
+			error instanceof SyntaxError &&
+			error.status === 400 &&
+			"body" in error
+		) {
+			return res.status(400).json(toJsonRpcError(null, -32700, "Parse error"));
+		}
+		return next(error);
+	});
+
+	app.locals.handlersBySessionId = handlersBySessionId;
+	app.locals.stillpoint = stillpoint;
+	return app;
+}
+
+function parseMode(args) {
+	if (args.includes("--http")) {
+		return "http";
+	}
+	return "mcp";
+}
+
+if (require.main === module) {
+	const mode = parseMode(process.argv.slice(2));
+
+	if (mode === "http") {
+		const app = createApp();
+		const { config } = app.locals.stillpoint;
+		app.listen(config.port, () => {
+			console.log(
+				`Stillpoint MCP streamable HTTP listening on port ${config.port} at ${MCP_ENDPOINT}`,
+			);
+		});
+	} else {
+		startMcpServer();
+	}
+}
+
+module.exports = {
+	createStillpoint,
+	createMcpHandler,
+	startMcpServer,
+	createApp,
+};