@orkestrel/mcp 0.0.26 → 0.0.27

package/dist/src/server/index.cjs

@@ -4,10 +4,10 @@ let _src_core = require("../core/index.cjs");
 let _orkestrel_contract = require("@orkestrel/contract");
 let _orkestrel_server = require("@orkestrel/server");
 let _orkestrel_emitter = require("@orkestrel/emitter");
+let _orkestrel_websocket = require("@orkestrel/websocket");
 let node_crypto = require("node:crypto");
 let node_http = require("node:http");
 let node_https = require("node:https");
-let _orkestrel_websocket = require("@orkestrel/websocket");
 let _orkestrel_process_server = require("@orkestrel/process/server");
 let _orkestrel_process = require("@orkestrel/process");
 let node_stream = require("node:stream");
@@ -527,13 +527,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 (0, _orkestrel_contract.isString)(name) ? name : void 0;
+	}
+	if (request.method === "resources/read") {
+		const uri = request.params?.["uri"];
+		return (0, _orkestrel_contract.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
@@ -592,22 +630,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 (!(0, _orkestrel_contract.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 ((0, _src_core.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 = (0, _orkestrel_contract.isRecord)(carried) ? carried[key] : void 0;
+		const field = `${_src_core.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 = (0, _src_core.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 = (0, _src_core.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
@@ -785,12 +874,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
@@ -839,11 +933,42 @@ function createMCPPostHandler(mcp, options) {
 		const era = (0, _src_core.isModernRequest)(invocation) ? "modern" : "legacy";
 		const id = invocation.id;
 		const protocol = request.headers.get(MCP_PROTOCOL_VERSION_HEADER);
-		if (era === "modern") {
+		if (era === "modern" || (0, _src_core.isMCPModernVersion)(protocol)) {
 			if ((0, _src_core.parseRequestContext)(invocation) === void 0) return Response.json((0, _src_core.buildJSONRPCError)(id, _src_core.JSONRPC_INVALID_PARAMS, "Invalid params: malformed modern request metadata"), { status: 400 });
 		}
 		const issue = inferHeaderIssue(request, invocation);
 		if (issue !== void 0) return Response.json((0, _src_core.buildJSONRPCError)(id, _src_core.MCP_HEADER_MISMATCH, issue.message), { status: 400 });
+		const called = invocation.params?.["name"];
+		if (era === "modern" && invocation.method === "tools/call" && (0, _orkestrel_contract.isString)(called)) {
+			let parameters = [];
+			let cursor = void 0;
+			for (let page = 0; page < _src_core.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 = (0, _src_core.extractToolSchema)(answer, called);
+				if (schema !== void 0) {
+					parameters = (0, _src_core.buildHeaderParameters)(schema) ?? [];
+					break;
+				}
+				const listing = answer.result;
+				const next = (0, _orkestrel_contract.isRecord)(listing) ? listing["nextCursor"] : void 0;
+				if (!(0, _orkestrel_contract.isString)(next)) break;
+				cursor = next;
+			}
+			const refusal = inferParameterRefusal(request, parameters, invocation.params?.["arguments"]);
+			if (refusal !== void 0) return Response.json((0, _src_core.buildJSONRPCError)(id, _src_core.MCP_HEADER_MISMATCH, refusal), { status: 400 });
+		}
 		if (era === "legacy") {
 			if (protocol !== null && !(0, _src_core.isMCPLegacyVersion)(protocol)) return Response.json((0, _src_core.buildJSONRPCError)(id, _src_core.MCP_UNSUPPORTED_VERSION, `Unsupported MCP protocol version '${protocol}'`, {
 				supported: _src_core.SUPPORTED_LEGACY_PROTOCOL_VERSIONS,
@@ -904,7 +1029,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()`.
@@ -935,8 +1061,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 _orkestrel_emitter.Emitter();
@@ -958,6 +1087,7 @@ var HTTPClientTransport = class {
 		this.#closed = false;
 	}
 	async send(message) {
+		this.#stamp(message);
 		const request = new AbortController();
 		this.#pending.add(request);
 		try {
@@ -966,6 +1096,11 @@ var HTTPClientTransport = class {
 			this.#pending.delete(request);
 		}
 	}
+	#stamp(message) {
+		if (!(0, _src_core.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 {
@@ -987,7 +1122,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;
@@ -1004,12 +1139,15 @@ var HTTPClientTransport = class {
 			return {
 				...version === void 0 ? {} : { [MCP_PROTOCOL_VERSION_HEADER]: version },
 				[MCP_METHOD_HEADER]: message.method,
-				...message.method === "tools/call" && (0, _orkestrel_contract.isString)(name) ? { [MCP_NAME_HEADER]: name } : {}
+				...message.method === "tools/call" && (0, _orkestrel_contract.isString)(name) ? {
+					[MCP_NAME_HEADER]: (0, _src_core.encodeSentinel)(name),
+					...(0, _src_core.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 = [];
@@ -1023,13 +1161,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 ((0, _src_core.isJSONRPCResponse)(message) && (0, _orkestrel_contract.isRecord)(message.result) && (0, _src_core.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 (!(0, _src_core.isModernRequest)(sent) || sent.method !== "tools/list") return message;
+		if (!(0, _src_core.isJSONRPCResponse)(message) || message.error !== void 0) return message;
+		const result = message.result;
+		const listed = (0, _orkestrel_contract.isRecord)(result) ? result["tools"] : void 0;
+		if (!(0, _orkestrel_contract.isRecord)(result) || !(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isRecord)(tool) || !(0, _orkestrel_contract.isString)(tool["name"])) {
+				kept.push(tool);
+				continue;
+			}
+			const parameters = (0, _src_core.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
@@ -1173,8 +1341,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
@@ -1211,6 +1384,7 @@ var WebSocketServerTransport = class {
 		this.#socket.emitter.on("error", this.#failure);
 	}
 	async send(message) {
+		if (this.#closed || this.#socket.readyState !== _orkestrel_websocket.WEBSOCKET_READY_OPEN) throw new Error("WebSocket transport is not connected");
 		this.#socket.send(JSON.stringify(message));
 	}
 	async close() {
@@ -1277,10 +1451,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
@@ -1332,7 +1508,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 !== _orkestrel_websocket.WEBSOCKET_READY_OPEN) throw new Error("WebSocket transport is not connected");
 		socket.send(JSON.stringify(message));
 	}
 	async close() {
@@ -2032,7 +2208,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
@@ -2271,7 +2448,9 @@ exports.decodeEvent = decodeEvent;
 exports.dispatchLines = dispatchLines;
 exports.extractLines = extractLines;
 exports.inferHeaderIssue = inferHeaderIssue;
+exports.inferHeaderTarget = inferHeaderTarget;
 exports.inferLegacyVersion = inferLegacyVersion;
+exports.inferParameterRefusal = inferParameterRefusal;
 exports.inferStatus = inferStatus;
 exports.readEventStream = readEventStream;
 exports.readLastEventId = readLastEventId;