alepha 0.20.3 → 0.20.4

package/dist/mcp/index.js

@@ -1,9 +1,25 @@
-import { $atom, $inject, $module, $state, Alepha, AlephaError, KIND, Primitive, createPrimitive, t } from "alepha";
+import { $atom, $inject, $module, $state, Alepha, AlephaError, KIND, Primitive, TypeBoxError, createPrimitive, t } from "alepha";
 import { $logger } from "alepha/logger";
 import { $route } from "alepha/server";
 //#region ../../src/mcp/helpers/jsonrpc.ts
 const JSONRPC_VERSION = "2.0";
-const MCP_PROTOCOL_VERSION = "2024-11-05";
+/**
+* The latest MCP protocol revision Alepha targets.
+* See {@link SUPPORTED_PROTOCOL_VERSIONS} for the full negotiation list.
+*/
+const MCP_PROTOCOL_VERSION = "2025-11-25";
+/**
+* Protocol versions Alepha will accept during `initialize` negotiation,
+* highest preference first. The server echoes back whichever version the
+* client requested if it appears here, otherwise picks the first entry.
+*/
+const SUPPORTED_PROTOCOL_VERSIONS = [
+	"2025-11-25",
+	"2025-06-18",
+	"2025-03-26",
+	"2024-11-05"
+];
+const isSupportedProtocolVersion = (v) => typeof v === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(v);
 const JsonRpcErrorCodes = {
 	PARSE_ERROR: -32700,
 	INVALID_REQUEST: -32600,
@@ -170,6 +186,18 @@ var McpServerProvider = class {
 	resources = /* @__PURE__ */ new Map();
 	prompts = /* @__PURE__ */ new Map();
 	initialized = false;
+	/**
+	* Protocol version negotiated with the client during `initialize`.
+	* Used by transports to validate the `MCP-Protocol-Version` header on
+	* subsequent HTTP requests (per spec 2025-06-18+).
+	*/
+	negotiatedVersion = MCP_PROTOCOL_VERSION;
+	/**
+	* Server identity returned during `initialize`. Consumers may override
+	* fields directly (e.g. `mcpServer.serverInfo = { name: "roadmap-mcp",
+	* version: "0.20.3", description: "..." }`) — the `description` field
+	* is supported per spec 2025-11-25 (minor change #2).
+	*/
 	serverInfo = {
 		name: "alepha-mcp",
 		version: "1.0.0"
@@ -298,13 +326,17 @@ var McpServerProvider = class {
 		}
 	}
 	handleInitialize(params) {
+		const requested = params.protocolVersion;
+		const negotiated = isSupportedProtocolVersion(requested) ? requested : SUPPORTED_PROTOCOL_VERSIONS[0];
 		this.log.info("MCP client initializing", {
 			clientInfo: params.clientInfo,
-			protocolVersion: params.protocolVersion
+			requestedProtocolVersion: requested,
+			negotiatedProtocolVersion: negotiated
 		});
 		this.initialized = true;
+		this.negotiatedVersion = negotiated;
 		return {
-			protocolVersion: MCP_PROTOCOL_VERSION,
+			protocolVersion: negotiated,
 			capabilities: this.getCapabilities(),
 			serverInfo: this.serverInfo
 		};
@@ -322,11 +354,28 @@ var McpServerProvider = class {
 		if (!tool) throw new McpToolNotFoundError(name);
 		try {
 			const result = await tool.execute(args, context);
-			return { content: [{
+			const callResult = { content: [{
 				type: "text",
 				text: typeof result === "string" ? result : JSON.stringify(result ?? null)
 			}] };
+			if (tool.hasOutputSchema() && result !== void 0) callResult.structuredContent = result;
+			return callResult;
 		} catch (error) {
+			if (error instanceof TypeBoxError) {
+				const path = error.value?.path || "/";
+				const message = error.value?.message || error.message;
+				return {
+					content: [{
+						type: "text",
+						text: `Validation error at ${path}: ${message}`
+					}],
+					structuredContent: { errors: [{
+						path,
+						message
+					}] },
+					isError: true
+				};
+			}
 			return {
 				content: [{
 					type: "text",
@@ -456,11 +505,14 @@ var PromptPrimitive = class extends Primitive {
 	* Convert the prompt to an MCP prompt descriptor for protocol messages.
 	*/
 	toDescriptor() {
-		return {
+		const descriptor = {
 			name: this.name,
 			description: this.description,
 			arguments: this.options.args ? this.schemaToArguments(this.options.args) : []
 		};
+		if (this.options.title) descriptor.title = this.options.title;
+		if (this.options.icons && this.options.icons.length > 0) descriptor.icons = this.options.icons;
+		return descriptor;
 	}
 	/**
 	* Convert a TypeBox schema to an array of prompt arguments.
@@ -561,12 +613,15 @@ var ResourcePrimitive = class extends Primitive {
 	* Convert the resource to an MCP resource descriptor for protocol messages.
 	*/
 	toDescriptor() {
-		return {
+		const descriptor = {
 			uri: this.uri,
 			name: this.name,
 			description: this.description,
 			mimeType: this.mimeType
 		};
+		if (this.options.title) descriptor.title = this.options.title;
+		if (this.options.icons && this.options.icons.length > 0) descriptor.icons = this.options.icons;
+		return descriptor;
 	}
 };
 $resource[KIND] = ResourcePrimitive;
@@ -633,6 +688,14 @@ var ToolPrimitive = class extends Primitive {
 	get description() {
 		return this.options.description;
 	}
+	/**
+	* Whether the tool declared a result schema. When true, `tools/call`
+	* responses include `structuredContent` populated with the validated
+	* result (spec 2025-06-18).
+	*/
+	hasOutputSchema() {
+		return !!this.options.schema?.result;
+	}
 	onInit() {
 		this.mcpServer.registerTool(this);
 	}
@@ -655,33 +718,57 @@ var ToolPrimitive = class extends Primitive {
 	}
 	/**
 	* Convert the tool to an MCP tool descriptor for protocol messages.
+	*
+	* Emits the spec 2025-11-25 surface: `title`, `annotations`, `icons`,
+	* and (when `schema.result` is defined) `outputSchema` so the server
+	* can populate `structuredContent` on call results.
 	*/
 	toDescriptor() {
-		return {
+		const inputSchema = this.options.schema?.params ? this.schemaToJsonSchema(this.options.schema.params) : {
+			type: "object",
+			properties: {},
+			required: []
+		};
+		const descriptor = {
 			name: this.name,
 			description: this.description,
-			inputSchema: this.options.schema?.params ? this.schemaToJsonSchema(this.options.schema.params) : {
+			inputSchema
+		};
+		if (this.options.title) descriptor.title = this.options.title;
+		if (this.options.annotations) descriptor.annotations = this.options.annotations;
+		if (this.options.icons && this.options.icons.length > 0) descriptor.icons = this.options.icons;
+		if (this.options.schema?.result) {
+			const out = this.propertyToJsonSchema(this.options.schema.result);
+			descriptor.outputSchema = typeof out === "object" && out !== null && "type" in out ? out : {
 				type: "object",
 				properties: {},
 				required: []
-			}
-		};
+			};
+		}
+		return descriptor;
 	}
 	/**
 	* Convert a TypeBox schema to JSON Schema format.
+	*
+	* Emits the 2020-12 dialect annotation at the root (spec 2025-11-25 /
+	* SEP-1613 — JSON Schema 2020-12 is the default dialect for MCP).
+	* The TypeBox shapes Alepha emits today are already 2020-12-compatible;
+	* this is just the dialect declaration.
 	*/
-	schemaToJsonSchema(schema) {
+	schemaToJsonSchema(schema, options) {
 		const properties = {};
 		const required = [];
 		for (const [key, propSchema] of Object.entries(schema.properties)) {
 			properties[key] = this.propertyToJsonSchema(propSchema);
 			if (!t.schema.isOptional(propSchema)) required.push(key);
 		}
-		return {
+		const result = {
 			type: "object",
 			properties,
 			required
 		};
+		if (options?.root !== false) result.$schema = "https://json-schema.org/draft/2020-12/schema";
+		return result;
 	}
 	/**
 	* Convert a single property schema to JSON Schema format.
@@ -707,7 +794,7 @@ var ToolPrimitive = class extends Primitive {
 		else if (t.schema.isArray(schema)) {
 			result.type = "array";
 			if ("items" in schema) result.items = this.propertyToJsonSchema(schema.items);
-		} else if (t.schema.isObject(schema)) Object.assign(result, this.schemaToJsonSchema(schema));
+		} else if (t.schema.isObject(schema)) Object.assign(result, this.schemaToJsonSchema(schema, { root: false }));
 		else if (t.schema.isUnsafe(schema) || t.schema.isOptional(schema)) {
 			const schemaAny = schema;
 			if (schemaAny.type === "string") {
@@ -726,32 +813,59 @@ var ToolPrimitive = class extends Primitive {
 };
 $tool[KIND] = ToolPrimitive;
 //#endregion
-//#region ../../src/mcp/transports/SseMcpTransport.ts
-const mcpSseOptions = $atom({
-	name: "alepha.mcp.sse.options",
-	description: "Configuration options for the MCP SSE transport.",
-	schema: t.object({ 
-	/**
-	* Path for the MCP SSE endpoint.
-	*/
-path: t.text({ default: "/mcp" }) }),
-	default: { path: "/mcp" }
+//#region ../../src/mcp/transports/StreamableHttpMcpTransport.ts
+const mcpStreamableHttpOptions = $atom({
+	name: "alepha.mcp.streamableHttp.options",
+	description: "Configuration options for the MCP Streamable HTTP transport.",
+	schema: t.object({
+		/**
+		* Path for the MCP endpoint. Single endpoint for both requests and
+		* (optional) server-streamed responses, per spec 2025-03-26+.
+		*/
+		path: t.text({ default: "/mcp" }),
+		/**
+		* Allow-list of `Origin` header values accepted on incoming requests.
+		* Empty array (default) means "allow any". When set, browser-originated
+		* requests with a non-matching `Origin` are rejected with 403 Forbidden,
+		* blocking DNS-rebinding attacks against localhost MCP servers.
+		*
+		* Server-to-server callers (no `Origin` header) are always allowed.
+		*
+		* Spec 2025-11-25, PR #1439.
+		*/
+		allowedOrigins: t.array(t.text(), { default: [] })
+	}),
+	default: {
+		path: "/mcp",
+		allowedOrigins: []
+	}
 });
+const mcpSseOptions = mcpStreamableHttpOptions;
 /**
-* SSE (Server-Sent Events) transport for MCP communication.
+* Streamable HTTP transport for MCP communication.
+*
+* Implements the 2025-03-26+ Streamable HTTP transport: a single `/mcp`
+* endpoint that accepts JSON-RPC over POST and returns either
+* `application/json` (single response, the default) or
+* `text/event-stream` (when the server wants to stream multiple messages).
 *
-* This transport uses HTTP with SSE for server-to-client messages
-* and POST requests for client-to-server messages.
+* Designed for serverless deployment (Cloudflare Workers, etc.) — there is
+* no long-lived GET stream. GET on the endpoint returns 405 Method Not
+* Allowed; clients that want server-initiated push must rely on the POST
+* response stream when the server upgrades to SSE for that particular call.
 *
-* Endpoints:
-* - GET /mcp - SSE stream for server events
-* - POST /mcp - JSON-RPC request endpoint
+* Spec compliance:
+* - 2025-06-18: validates `MCP-Protocol-Version` header on every request
+*   after `initialize` against the version negotiated and stored on
+*   `McpServerProvider`.
+* - 2025-11-25: rejects requests with a non-allow-listed `Origin` header
+*   (PR #1439). See {@link mcpStreamableHttpOptions.allowedOrigins}.
 *
 * @example
 * ```ts
 * import { Alepha, run } from "alepha";
 * import { AlephaServer } from "alepha/server";
-* import { AlephaMcp, AlephaMcpSse } from "alepha/mcp";
+* import { AlephaMcp, StreamableHttpMcpTransport } from "alepha/mcp";
 *
 * class MyTools {
 *   // ... tool definitions
@@ -761,50 +875,36 @@ path: t.text({ default: "/mcp" }) }),
 *   Alepha.create()
 *     .with(AlephaServer)
 *     .with(AlephaMcp)
-*     .with(AlephaMcpSse)
+*     .with(StreamableHttpMcpTransport)
 *     .with(MyTools)
 * );
 * ```
 */
-var SseMcpTransport = class {
+var StreamableHttpMcpTransport = class {
 	log = $logger();
-	options = $state(mcpSseOptions);
+	options = $state(mcpStreamableHttpOptions);
 	mcpServer = $inject(McpServerProvider);
 	/**
-	* SSE endpoint for server-to-client messages.
-	*
-	* Returns a text/event-stream response with server capabilities
-	* and keeps the connection open for notifications.
+	* GET on the MCP endpoint is not supported in this transport. Returning
+	* 405 (rather than serving the legacy two-endpoint SSE pattern) is the
+	* spec-allowed response for servers that don't offer server-initiated
+	* push outside of an active POST.
 	*/
-	sse = $route({
+	notAllowed = $route({
 		method: "GET",
 		path: this.options.path,
-		handler: async (request) => {
-			this.log.debug("MCP SSE connection established");
-			const encoder = new TextEncoder();
-			const stream = new ReadableStream({
-				start: (controller) => {
-					const endpointEvent = this.formatSseEvent("endpoint", `${this.options.path}`);
-					controller.enqueue(encoder.encode(endpointEvent));
-					const capabilitiesNotification = createNotification("notifications/capabilities", { capabilities: this.mcpServer.getCapabilities() });
-					const capabilitiesEvent = this.formatSseEvent("message", JSON.stringify(capabilitiesNotification));
-					controller.enqueue(encoder.encode(capabilitiesEvent));
-				},
-				cancel: () => {
-					this.log.debug("MCP SSE connection closed");
-				}
-			});
-			request.reply.status = 200;
-			request.reply.headers = {
-				"content-type": "text/event-stream",
-				"cache-control": "no-cache",
-				connection: "keep-alive"
-			};
-			request.reply.body = stream;
+		handler: (request) => {
+			request.reply.status = 405;
+			request.reply.headers.allow = "POST";
+			request.reply.headers["content-type"] = "application/json";
+			request.reply.body = JSON.stringify({ error: "Method Not Allowed. Use POST for MCP messages." });
 		}
 	});
 	/**
 	* POST endpoint for client-to-server JSON-RPC messages.
+	* Returns `application/json` for single responses; tools that need to
+	* stream progress would upgrade to `text/event-stream` (deferred until a
+	* concrete need exists).
 	*/
 	message = $route({
 		method: "POST",
@@ -812,13 +912,40 @@ var SseMcpTransport = class {
 		schema: { body: t.json() },
 		handler: async (request) => {
 			try {
+				const originRaw = request.headers.origin;
+				const origin = Array.isArray(originRaw) ? originRaw[0] : originRaw;
+				if (origin && this.options.allowedOrigins.length > 0 && !this.options.allowedOrigins.includes(origin)) {
+					this.log.warn("Rejected MCP request with non-allowed Origin", {
+						origin,
+						allowed: this.options.allowedOrigins
+					});
+					request.reply.status = 403;
+					request.reply.headers["content-type"] = "application/json";
+					request.reply.body = JSON.stringify({ error: "Forbidden: Origin not allowed" });
+					return;
+				}
 				const body = typeof request.body === "string" ? request.body : JSON.stringify(request.body);
 				this.log.debug("MCP request body", {
 					body,
 					bodyType: typeof request.body
 				});
 				const rpcRequest = parseMessage(body);
-				const context = { headers: { ...request.headers } };
+				const headers = { ...request.headers };
+				if (rpcRequest.method !== "initialize") {
+					const headerRaw = headers["mcp-protocol-version"];
+					const headerVersion = Array.isArray(headerRaw) ? headerRaw[0] : headerRaw;
+					if (headerVersion && headerVersion !== this.mcpServer.negotiatedVersion) {
+						this.log.warn("MCP-Protocol-Version header mismatch", {
+							header: headerVersion,
+							negotiated: this.mcpServer.negotiatedVersion
+						});
+						request.reply.status = 400;
+						request.reply.headers["content-type"] = "application/json";
+						request.reply.body = JSON.stringify({ error: `MCP-Protocol-Version mismatch: expected ${this.mcpServer.negotiatedVersion}, got ${headerVersion}` });
+						return;
+					}
+				}
+				const context = { headers };
 				const response = await this.mcpServer.handleMessage(rpcRequest, context);
 				if (response) {
 					request.reply.headers["content-type"] = "application/json";
@@ -837,13 +964,13 @@ var SseMcpTransport = class {
 			}
 		}
 	});
-	/**
-	* Format a message as an SSE event.
-	*/
-	formatSseEvent(event, data) {
-		return `event: ${event}\ndata: ${data}\n\n`;
-	}
 };
+/**
+* @deprecated Use {@link StreamableHttpMcpTransport}. The 2024-11-05
+* two-endpoint HTTP+SSE pattern was replaced by Streamable HTTP in spec
+* 2025-03-26. This alias is preserved for one release to ease migration.
+*/
+const SseMcpTransport = StreamableHttpMcpTransport;
 //#endregion
 //#region ../../src/mcp/index.ts
 /**
@@ -854,7 +981,7 @@ var SseMcpTransport = class {
 * - MCP tool definitions
 * - MCP prompt definitions
 * - JSON-RPC protocol
-* - SSE and Stdio transports
+* - Streamable HTTP transport (spec 2025-03-26+)
 *
 * @module alepha.mcp
 */
@@ -866,9 +993,9 @@ const AlephaMcp = $module({
 		$prompt
 	],
 	services: [McpServerProvider],
-	variants: [SseMcpTransport]
+	variants: [StreamableHttpMcpTransport]
 });
 //#endregion
-export { $prompt, $resource, $tool, AlephaMcp, JSONRPC_VERSION, JsonRpcErrorCodes, JsonRpcParseError, MCP_PROTOCOL_VERSION, McpError, McpErrorCodes, McpForbiddenError, McpInvalidParamsError, McpMethodNotFoundError, McpPromptNotFoundError, McpResourceNotFoundError, McpServerProvider, McpToolNotFoundError, McpUnauthorizedError, PromptPrimitive, ResourcePrimitive, SseMcpTransport, ToolPrimitive, createErrorResponse, createInternalError, createInvalidParamsError, createInvalidRequestError, createMethodNotFoundError, createNotification, createParseError, createResponse, isNotification, isValidJsonRpcRequest, mcpSseOptions, parseMessage };
+export { $prompt, $resource, $tool, AlephaMcp, JSONRPC_VERSION, JsonRpcErrorCodes, JsonRpcParseError, MCP_PROTOCOL_VERSION, McpError, McpErrorCodes, McpForbiddenError, McpInvalidParamsError, McpMethodNotFoundError, McpPromptNotFoundError, McpResourceNotFoundError, McpServerProvider, McpToolNotFoundError, McpUnauthorizedError, PromptPrimitive, ResourcePrimitive, SUPPORTED_PROTOCOL_VERSIONS, SseMcpTransport, StreamableHttpMcpTransport, ToolPrimitive, createErrorResponse, createInternalError, createInvalidParamsError, createInvalidRequestError, createMethodNotFoundError, createNotification, createParseError, createResponse, isNotification, isSupportedProtocolVersion, isValidJsonRpcRequest, mcpSseOptions, mcpStreamableHttpOptions, parseMessage };
 
 //# sourceMappingURL=index.js.map