@orkestrel/mcp 0.0.26 → 0.0.27

package/dist/src/server/index.js

@@ -1,12 +1,12 @@
 import { createSSEParser } from "@orkestrel/sse";
-import { JSONRPC_INVALID_PARAMS, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_PARSE_ERROR, MCP_HANDSHAKE_VERSION, MCP_HEADER_MISMATCH, MCP_META_VERSION, MCP_MISSING_CAPABILITY, MCP_UNSUPPORTED_VERSION, SUPPORTED_LEGACY_PROTOCOL_VERSIONS, bindServer, buildJSONRPCError, inferRequestVersion, isInitializeRequest, isJSONRPCInvocation, isJSONRPCResponse, isMCPLegacyVersion, isMCPVersion, isModernRequest, parseJSONRPCMessage, parseRequestContext } from "../core/index.js";
-import { isRecord, isString, sanitizeBudget } from "@orkestrel/contract";
+import { JSONRPC_INVALID_PARAMS, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_PARSE_ERROR, MCP_HANDSHAKE_VERSION, MCP_HEADER_MISMATCH, MCP_LOOKUP_PAGES, MCP_META_VERSION, MCP_MISSING_CAPABILITY, MCP_PARAM_PREFIX, MCP_UNSUPPORTED_VERSION, SUPPORTED_LEGACY_PROTOCOL_VERSIONS, bindServer, buildHeaderParameters, buildHeaderProjection, buildJSONRPCError, decodeSentinel, encodeSentinel, extractToolSchema, inferRequestVersion, isInitializeRequest, isJSONRPCInvocation, isJSONRPCResponse, isMCPLegacyVersion, isMCPModernVersion, isMCPVersion, isModernRequest, parseJSONRPCMessage, parseRequestContext, renderHeaderValue } from "../core/index.js";
+import { isArray, isRecord, isString, sanitizeBudget } from "@orkestrel/contract";
 import { openStream, signToken, verifyToken } from "@orkestrel/server";
 import { Emitter } from "@orkestrel/emitter";
+import { WEBSOCKET_READY_OPEN, WEBSOCKET_VERSION, computeWebSocketAccept, createNodeWebSocket } from "@orkestrel/websocket";
 import { randomBytes } from "node:crypto";
 import { request } from "node:http";
 import { request as request$1 } from "node:https";
-import { WEBSOCKET_VERSION, computeWebSocketAccept, createNodeWebSocket } from "@orkestrel/websocket";
 import { Process } from "@orkestrel/process/server";
 import { PROCESS_GRACE } from "@orkestrel/process";
 import { Readable } from "node:stream";
@@ -526,13 +526,51 @@ function bridgeMessageTransport(transport) {
 //#endregion
 //#region src/server/inferers.ts
 /**
+* Infers the target one modern request's `Mcp-Name` header must carry.
+*
+* @remarks
+* The protocol scopes the header to the methods whose body carries a name-shaped field, and
+* names the field per method: `tools/call` and `prompts/get` carry `params.name`, and
+* `resources/read` carries `params.uri`. Every other method — `server/discover`, `tools/list`,
+* `resources/list`, `prompts/list` — has nothing to derive a target from, so the header is not
+* required there and a peer that sent one anyway is not held to it.
+*
+* A method within the scope whose named member is absent or is not a string reads as no
+* target. There is nothing for a header to match, and refusing the request over a body member
+* the header rule does not own would report a parameter fault as a header fault. Total.
+*
+* @param request - The parsed modern invocation to read the target from
+* @returns The target the header must carry, or `undefined` when the method carries none
+*
+* @example
+* ```ts
+* inferHeaderTarget({ jsonrpc: '2.0', id: 1, method: 'resources/read', params: { uri: 'file:///a' } })
+* // → 'file:///a'
+* ```
+*/
+function inferHeaderTarget(request) {
+	if (request.method === "tools/call" || request.method === "prompts/get") {
+		const name = request.params?.["name"];
+		return isString(name) ? name : void 0;
+	}
+	if (request.method === "resources/read") {
+		const uri = request.params?.["uri"];
+		return isString(uri) ? uri : void 0;
+	}
+}
+/**
 * Infers the first required MCP HTTP header that is missing or mismatched.
 *
 * @remarks
-* A modern request derives its protocol, method, and tools/call-only name expectations from
-* the JSON-RPC body. A legacy request body requires a protocol header after initialization,
-* while a supplied legacy session version additionally diagnoses a header that disagrees with
-* the active session. Messages name the expected value but never echo the client-supplied one.
+* A modern request derives its protocol, method, and name expectations from the JSON-RPC body,
+* the name expectation scoped to the methods {@link inferHeaderTarget} reads a target for. A
+* name header carrying the Base64 sentinel is decoded through
+* {@link import('@orkestrel/mcp').decodeSentinel} before the comparison, so a peer that had
+* to encode its value still matches; a sentinel whose payload is invalid decodes to nothing
+* and therefore mismatches, which is how an invalid header value is refused. A legacy request
+* body requires a protocol header after initialization, while a supplied legacy session
+* version additionally diagnoses a header that disagrees with the active session. Messages
+* name the expected value but never echo the client-supplied one.
 *
 * @param request - The HTTP request carrying the headers
 * @param reference - The parsed invocation body, or the active legacy session version
@@ -591,22 +629,73 @@ function inferHeaderIssue(request, reference) {
 		reason: "mismatched",
 		message: `Mcp-Method header does not match the request body method '${message.method}'.`
 	};
-	if (message.method !== "tools/call") return void 0;
-	const name = message.params?.["name"];
-	if (!isString(name)) return void 0;
+	const target = inferHeaderTarget(message);
+	if (target === void 0) return void 0;
 	const header = request.headers.get(MCP_NAME_HEADER);
 	if (header === null) return {
 		header: "Mcp-Name",
 		reason: "missing",
-		message: `Required Mcp-Name header is missing; the request body tool name is '${name}'.`
+		message: `Required Mcp-Name header is missing; the request body target is '${target}'.`
 	};
-	if (header !== name) return {
+	if (decodeSentinel(header) !== target) return {
 		header: "Mcp-Name",
 		reason: "mismatched",
-		message: `Mcp-Name header does not match the request body tool name '${name}'.`
+		message: `Mcp-Name header does not match the request body target '${target}'.`
 	};
 }
 /**
+* Infers the refusal one `tools/call` earns for a `Mcp-Param-*` header the body contradicts.
+*
+* @remarks
+* The custom-header half of the standard-header seam {@link inferHeaderIssue} owns, and it
+* takes the SERVED definition's projections rather than a header issue: SEP-2243 scopes the
+* rule to the `Mcp-Param-*` names the server's OWN tool definitions annotate, so a name no
+* parameter claims is another party's header and travels through untouched.
+*
+* For each recognized parameter the body's value at the parameter's own property path fixes
+* the expectation. A value the call omits or supplies as `null` requires no header, and a
+* header sent anyway is refused because it asserts something the body never said. A value the
+* call does supply requires its header: an absent one, a Base64 sentinel whose payload is
+* invalid, and a decoded value that disagrees are each refused. An `integer` parameter
+* compares numerically, so a peer that padded its decimal still matches. A supplied value
+* whose runtime shape contradicts the declared type is left alone — the tool's own argument
+* validation owns that disagreement, and refusing it here would report an argument fault as a
+* header fault.
+*
+* Messages name the field and the body path the expectation came from, and never echo the
+* value the peer supplied.
+*
+* @param request - The HTTP request carrying the headers
+* @param parameters - The projections the served tool definition declares
+* @param values - The call's `arguments` record
+* @returns The refusal message for the first disagreeing parameter, or `undefined`
+*
+* @example
+* ```ts
+* inferParameterRefusal(request, [{ name: 'Region', path: ['region'], primitive: 'string' }], {})
+* // → undefined when the request carries no `Mcp-Param-Region` either
+* ```
+*/
+function inferParameterRefusal(request, parameters, values) {
+	for (const parameter of parameters) {
+		let carried = values;
+		for (const key of parameter.path) carried = isRecord(carried) ? carried[key] : void 0;
+		const field = `${MCP_PARAM_PREFIX}${parameter.name}`;
+		const path = parameter.path.join(".");
+		const header = request.headers.get(field);
+		if (carried === void 0 || carried === null) {
+			if (header === null) continue;
+			return `${field} header carries a value the request body omits at '${path}'.`;
+		}
+		const expected = renderHeaderValue(carried, parameter.primitive);
+		if (expected === void 0) continue;
+		if (header === null) return `Required ${field} header is missing; the request body carries '${path}'.`;
+		const decoded = decodeSentinel(header);
+		if (decoded === void 0) return `${field} header value is not a valid Base64 sentinel.`;
+		if (!(parameter.primitive === "integer" ? decoded.trim() !== "" && Number(decoded) === Number(expected) : decoded === expected)) return `${field} header does not match the request body value at '${path}'.`;
+	}
+}
+/**
 * Infers the legacy revision an `initialize` request negotiates.
 *
 * @remarks
@@ -784,12 +873,17 @@ var HTTPDisconnect = class {
 * Creates the Streamable-HTTP POST handler used by `createMCPRoutes`.
 *
 * @remarks
-* Modern requests require matching protocol/method headers and a matching name header only
-* for `tools/call`; mismatch returns HTTP `400` + `-32020`. Headerless `initialize` is
-* accepted, while every other headerless request needs a live legacy session to supply its
-* pinned version. A legacy-shaped request carrying a protocol header is admitted only for a
-* legacy revision; any other value, the modern revision included, returns HTTP `400` + `-32022`
-* whose `supported` names the legacy revisions this door accepts. A present origin must occur in `origin.origins` unless validation is
+* Modern requests require matching protocol/method headers and a matching name header on each
+* method carrying a named target — `tools/call` and `prompts/get` against `params.name`,
+* `resources/read` against `params.uri` — with a Base64-sentinel value decoded before the
+* comparison; a missing, mismatched, or invalidly encoded value returns HTTP `400` + `-32020`.
+* A protocol header naming a MODERN revision holds the request to that revision whatever shape
+* its body arrived in, so a body with no parsable modern `_meta` returns HTTP `400` + `-32602`.
+* Headerless `initialize` is accepted, while every other headerless request needs a live legacy
+* session to supply its pinned version. A legacy-shaped request carrying a protocol header is
+* otherwise admitted only for a legacy revision; a revision this server does not implement
+* returns HTTP `400` + `-32022` whose `supported` names the legacy revisions this door accepts.
+* A present origin must occur in `origin.origins` unless validation is
 * explicitly delegated upstream. Modern dispatch errors use their protocol status map; legacy
 * errors remain in-band at HTTP `200`. A streamed response composes the fetch-standard request
 * signal with response-body cancellation and supplies the result to every dispatched modern
@@ -838,11 +932,42 @@ function createMCPPostHandler(mcp, options) {
 		const era = isModernRequest(invocation) ? "modern" : "legacy";
 		const id = invocation.id;
 		const protocol = request.headers.get(MCP_PROTOCOL_VERSION_HEADER);
-		if (era === "modern") {
+		if (era === "modern" || isMCPModernVersion(protocol)) {
 			if (parseRequestContext(invocation) === void 0) return Response.json(buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: malformed modern request metadata"), { status: 400 });
 		}
 		const issue = inferHeaderIssue(request, invocation);
 		if (issue !== void 0) return Response.json(buildJSONRPCError(id, MCP_HEADER_MISMATCH, issue.message), { status: 400 });
+		const called = invocation.params?.["name"];
+		if (era === "modern" && invocation.method === "tools/call" && isString(called)) {
+			let parameters = [];
+			let cursor = void 0;
+			for (let page = 0; page < MCP_LOOKUP_PAGES; page += 1) {
+				const answer = await mcp.dispatch({
+					jsonrpc: "2.0",
+					id: 0,
+					method: "tools/list",
+					params: {
+						_meta: invocation.params?.["_meta"],
+						...cursor === void 0 ? {} : { cursor }
+					}
+				});
+				if (Symbol.asyncIterator in answer) {
+					answer.stop();
+					break;
+				}
+				const schema = extractToolSchema(answer, called);
+				if (schema !== void 0) {
+					parameters = buildHeaderParameters(schema) ?? [];
+					break;
+				}
+				const listing = answer.result;
+				const next = isRecord(listing) ? listing["nextCursor"] : void 0;
+				if (!isString(next)) break;
+				cursor = next;
+			}
+			const refusal = inferParameterRefusal(request, parameters, invocation.params?.["arguments"]);
+			if (refusal !== void 0) return Response.json(buildJSONRPCError(id, MCP_HEADER_MISMATCH, refusal), { status: 400 });
+		}
 		if (era === "legacy") {
 			if (protocol !== null && !isMCPLegacyVersion(protocol)) return Response.json(buildJSONRPCError(id, MCP_UNSUPPORTED_VERSION, `Unsupported MCP protocol version '${protocol}'`, {
 				supported: SUPPORTED_LEGACY_PROTOCOL_VERSIONS,
@@ -903,7 +1028,8 @@ function createMCPPostHandler(mcp, options) {
 *   initialize result's `protocolVersion` is likewise captured, but only
 *   when it is a SUPPORTED value, and echoed as `mcp-protocol-version` alone on
 *   subsequent legacy requests. Modern requests instead derive protocol and method
-*   headers from the message, plus the name header only for `tools/call`.
+*   headers from the message, plus the name header only for `tools/call` — carried in the
+*   protocol's Base64 sentinel form whenever the tool name cannot ride as plain ASCII.
 *   Before initialize returns, neither captured legacy header is sent.
 *   `close()` clears the captured protocol so a reconnect's `initialize`
 *   POST is headerless; the captured `session` persists across `close()`.
@@ -934,8 +1060,11 @@ var HTTPClientTransport = class {
 	#fetch;
 	#timeout;
 	#pending = /* @__PURE__ */ new Set();
+	#parameters = /* @__PURE__ */ new Map();
+	#stamps = /* @__PURE__ */ new WeakMap();
 	#session = void 0;
 	#protocol = void 0;
+	#generation = 0;
 	#closed = false;
 	constructor(options) {
 		this.#emitter = new Emitter();
@@ -957,6 +1086,7 @@ var HTTPClientTransport = class {
 		this.#closed = false;
 	}
 	async send(message) {
+		this.#stamp(message);
 		const request = new AbortController();
 		this.#pending.add(request);
 		try {
@@ -965,6 +1095,11 @@ var HTTPClientTransport = class {
 			this.#pending.delete(request);
 		}
 	}
+	#stamp(message) {
+		if (!isModernRequest(message) || message.method !== "tools/list") return;
+		if (message.params?.["cursor"] === void 0) this.#generation += 1;
+		this.#stamps.set(message, this.#generation);
+	}
 	async #exchange(message, signal) {
 		let response;
 		try {
@@ -986,7 +1121,7 @@ var HTTPClientTransport = class {
 		}
 		const session = response.headers.get(MCP_SESSION_HEADER);
 		if (session !== null) this.#session = session;
-		await this.#deliver(response);
+		await this.#deliver(response, message);
 	}
 	async close() {
 		if (this.#closed) return;
@@ -1003,12 +1138,15 @@ var HTTPClientTransport = class {
 			return {
 				...version === void 0 ? {} : { [MCP_PROTOCOL_VERSION_HEADER]: version },
 				[MCP_METHOD_HEADER]: message.method,
-				...message.method === "tools/call" && isString(name) ? { [MCP_NAME_HEADER]: name } : {}
+				...message.method === "tools/call" && isString(name) ? {
+					[MCP_NAME_HEADER]: encodeSentinel(name),
+					...buildHeaderProjection(this.#parameters.get(name) ?? [], message.params?.["arguments"])
+				} : {}
 			};
 		}
 		return this.#protocol === void 0 ? {} : { [MCP_PROTOCOL_VERSION_HEADER]: this.#protocol };
 	}
-	async #deliver(response) {
+	async #deliver(response, sent) {
 		if (response.status === 202) return;
 		const type = response.headers.get("content-type") ?? "";
 		let messages = [];
@@ -1022,13 +1160,43 @@ var HTTPClientTransport = class {
 		} catch (error) {
 			failure = { error };
 		}
-		for (const message of messages) this.#capture(message);
+		for (const message of messages) this.#capture(message, sent);
 		if (!response.ok && messages.length === 0) throw buildResponseError(response, type);
 		if (failure !== void 0) this.#emitter.emit("error", failure.error);
 	}
-	#capture(message) {
+	#capture(message, sent) {
 		if (isJSONRPCResponse(message) && isRecord(message.result) && isMCPVersion(message.result["protocolVersion"])) this.#protocol = message.result["protocolVersion"];
-		this.#emitter.emit("message", message);
+		this.#emitter.emit("message", this.#select(message, sent));
+	}
+	#select(message, sent) {
+		if (!isModernRequest(sent) || sent.method !== "tools/list") return message;
+		if (!isJSONRPCResponse(message) || message.error !== void 0) return message;
+		const result = message.result;
+		const listed = isRecord(result) ? result["tools"] : void 0;
+		if (!isRecord(result) || !isArray(listed)) return message;
+		const current = this.#stamps.get(sent) === this.#generation;
+		if (current && sent.params?.["cursor"] === void 0) this.#parameters.clear();
+		const kept = [];
+		for (const tool of listed) {
+			if (!isRecord(tool) || !isString(tool["name"])) {
+				kept.push(tool);
+				continue;
+			}
+			const parameters = buildHeaderParameters(tool["inputSchema"]);
+			if (parameters === void 0) {
+				this.#emitter.emit("error", /* @__PURE__ */ new Error(`MCP tool '${tool["name"]}' is excluded from tools/list: its inputSchema carries an invalid x-mcp-header annotation`));
+				continue;
+			}
+			if (current) this.#parameters.set(tool["name"], parameters);
+			kept.push(tool);
+		}
+		return {
+			...message,
+			result: {
+				...result,
+				tools: kept
+			}
+		};
 	}
 };
 //#endregion
@@ -1172,8 +1340,13 @@ var MCPSession = class {
 *   a non-JSON or non-message frame is surfaced on `error` and DROPPED, never thrown. It
 *   also bridges the socket's `close` → this transport's `close`, and the socket's `error`.
 * - **Outbound (`send`).** `send(message)` writes one text frame
-*   (`nodeWs.send(JSON.stringify(message))`); the underlying wrapper no-ops a write on a
-*   non-open socket, so a closed connection drops silently rather than throwing.
+*   (`nodeWs.send(JSON.stringify(message))`). The underlying wrapper no-ops a write on a
+*   non-open socket and confirms nothing, so this bridge answers a closed channel from its own
+*   state and the socket's `readyState`: a `send` after `close()`, after the peer's close, or on
+*   a socket that is not `OPEN` REJECTS with `WebSocket transport is not connected` rather than
+*   resolving on a frame nobody wrote. `bindServer` catches that rejection and routes it to the
+*   dispatcher's `error` event, and it aborts every in-flight request the moment this transport's
+*   `close` fires — so a peer that disconnects mid-request is answered by no write at all.
 * - **`close()`** removes the subscriptions `start()` installed on the socket, closes the
 *   underlying socket (the RFC 6455 close handshake), and fires the transport's `close` event
 *   (idempotent — a second `close`, or a socket-driven close, emits once). A frame that arrives
@@ -1210,6 +1383,7 @@ var WebSocketServerTransport = class {
 		this.#socket.emitter.on("error", this.#failure);
 	}
 	async send(message) {
+		if (this.#closed || this.#socket.readyState !== WEBSOCKET_READY_OPEN) throw new Error("WebSocket transport is not connected");
 		this.#socket.send(JSON.stringify(message));
 	}
 	async close() {
@@ -1276,10 +1450,12 @@ var WebSocketServerTransport = class {
 *   non-JSON / non-message frame surfaces on `error` and is dropped. The socket's `close`
 *   / `error` bridge to this transport's events.
 * - **Outbound (`send`).** `send(message)` writes one masked text frame. A socket write is not
-*   confirmed, so this transport answers a closed channel from its OWN state: a `send` with no
-*   bound socket — before `start()`, after `close()`, or after the peer ended the socket —
-*   REJECTS with `WebSocket transport is not connected`. It neither drops the message (the
-*   browser face's posture) nor queues it for a connection this transport is not holding.
+*   confirmed, so this transport answers a closed channel from its own state AND the socket's
+*   `readyState`: a `send` with no bound socket — before `start()`, after `close()`, or after the
+*   peer ended the socket — and a `send` on a bound socket that is not `OPEN` both REJECT with
+*   `WebSocket transport is not connected`. It neither drops the message nor queues it for a
+*   connection this transport is not holding — the browser face queues a pre-open send, and this
+*   one, holding no connection to flush it onto, rejects that too.
 * - **`close()`** unsubscribes from the socket, closes it, and fires `close` (idempotent). An
 *   upgrade still on the wire is DESTROYED, so a `close()` during the handshake ends the
 *   transport at once instead of waiting for a peer that may never answer — the suspended
@@ -1331,7 +1507,7 @@ var WebSocketClientTransport = class {
 	}
 	async send(message) {
 		const socket = this.#socket;
-		if (socket === void 0) throw new Error("WebSocket transport is not connected");
+		if (socket === void 0 || socket.readyState !== WEBSOCKET_READY_OPEN) throw new Error("WebSocket transport is not connected");
 		socket.send(JSON.stringify(message));
 	}
 	async close() {
@@ -2031,7 +2207,8 @@ function createStdioClientTransport(options) {
 * @param mcp - The transport-agnostic {@link MCPDispatcherInterface} to expose over stdio
 * @param options - Optional injectable `input` / `output` streams; see
 *   {@link StdioServerOptions}
-* @returns A `{ start(): void; stop(): void }` handle to arm / tear down the pump
+* @returns A {@link StdioServerInterface} handle to arm / tear down the pump; `stop()` ends
+*   that handle's lifetime permanently
 *
 * @example
 * ```ts
@@ -2232,6 +2409,6 @@ function createMCPSession(options) {
 	};
 }
 //#endregion
-export { DEFAULT_MCP_DELIVERY, DEFAULT_MCP_KEEPALIVE_INTERVAL, DEFAULT_MCP_PATH, DEFAULT_MCP_SESSION_CAPACITY, DEFAULT_MCP_SESSION_TTL, HTTPClientTransport, HTTPDisconnect, MCPSession, MCP_METHOD_HEADER, MCP_NAME_HEADER, MCP_PROTOCOL_VERSION_HEADER, MCP_SESSION_HEADER, MCP_WEBSOCKET_SUBPROTOCOL, SSE_BUFFERING_DISABLED, SSE_BUFFERING_HEADER, SSE_KEEPALIVE_COMMENT, StdioClientTransport, StdioServerTransport, WebSocketClientTransport, WebSocketServerTransport, acceptsEventStream, allowsOrigin, bridgeMessageTransport, buildResponseError, createHTTPClientTransport, createMCPContinuation, createMCPPostHandler, createMCPRoutes, createMCPSession, createReadableStream, createStdioClientTransport, createStdioServer, createWebSocketClientTransport, createWebSocketServer, decodeEvent, dispatchLines, extractLines, inferHeaderIssue, inferLegacyVersion, inferStatus, readEventStream, readLastEventId, readSessionHeader, rejectUnknownSession, sendEventStream, upgradeRequestPath, writeLine };
+export { DEFAULT_MCP_DELIVERY, DEFAULT_MCP_KEEPALIVE_INTERVAL, DEFAULT_MCP_PATH, DEFAULT_MCP_SESSION_CAPACITY, DEFAULT_MCP_SESSION_TTL, HTTPClientTransport, HTTPDisconnect, MCPSession, MCP_METHOD_HEADER, MCP_NAME_HEADER, MCP_PROTOCOL_VERSION_HEADER, MCP_SESSION_HEADER, MCP_WEBSOCKET_SUBPROTOCOL, SSE_BUFFERING_DISABLED, SSE_BUFFERING_HEADER, SSE_KEEPALIVE_COMMENT, StdioClientTransport, StdioServerTransport, WebSocketClientTransport, WebSocketServerTransport, acceptsEventStream, allowsOrigin, bridgeMessageTransport, buildResponseError, createHTTPClientTransport, createMCPContinuation, createMCPPostHandler, createMCPRoutes, createMCPSession, createReadableStream, createStdioClientTransport, createStdioServer, createWebSocketClientTransport, createWebSocketServer, decodeEvent, dispatchLines, extractLines, inferHeaderIssue, inferHeaderTarget, inferLegacyVersion, inferParameterRefusal, inferStatus, readEventStream, readLastEventId, readSessionHeader, rejectUnknownSession, sendEventStream, upgradeRequestPath, writeLine };
 
 //# sourceMappingURL=index.js.map