@orkestrel/mcp 0.0.4 → 0.0.6

package/dist/src/server/index.cjs

@@ -2,13 +2,13 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _orkestrel_sse = require("@orkestrel/sse");
 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 node_crypto = require("node:crypto");
 let node_http = require("node:http");
 let node_https = require("node:https");
 let _orkestrel_websocket = require("@orkestrel/websocket");
 let node_child_process = require("node:child_process");
-let _orkestrel_server = require("@orkestrel/server");
 //#region src/server/constants.ts
 /**
 * The Streamable-HTTP transport header that carries the MCP session id. When a {@link
@@ -18,10 +18,13 @@ let _orkestrel_server = require("@orkestrel/server");
 */
 var MCP_SESSION_HEADER = "mcp-session-id";
 /**
-* The Streamable-HTTP transport header that carries the negotiated MCP protocol version
-* on a subsequent request. The version is negotiated in the `initialize` JSON-RPC result
-* body; a stateful transport MAY additionally read this header to pin the per-request
-* protocol version (optional — the result body remains the source of truth).
+* The Streamable-HTTP transport header carrying the negotiated MCP protocol version
+* on every post-initialize client request.
+*
+* @remarks
+* Required by MCP 2025-06-18 after initialization. Both HTTP client transports
+* capture the initialize result's `protocolVersion` and send it on subsequent
+* requests; `createMCPRoutes` rejects a present unsupported value before dispatch.
 */
 var MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
 /** The default request path `createMCPRoutes` mounts the transport's `POST` route at. */
@@ -264,6 +267,131 @@ function dispatchLines(emitter, lines) {
 		emitter.emit("message", message);
 	}
 }
+/**
+* Bridge a message-channel {@link ClientTransportInterface} (the shape the stdio and
+* WebSocket SERVER transports already implement) into the environment-agnostic
+* {@link import('@src/core').MCPTransportInterface} port — the adapter
+* {@link import('./factories.js').createStdioServer} and {@link
+* import('./factories.js').createWebSocketServer} pipe through `bindServer`, so the
+* request/reply/error pump those two factories used to hand-roll identically now
+* lives ONCE in the core binder.
+*
+* @remarks
+* `send` decodes the already-serialized reply string back to a {@link JSONRPCMessage}
+* and writes it via `transport.send` (the SAME `JSON.stringify` the underlying
+* transport already performs, so the wire bytes are unchanged). `listen` filters
+* `transport`'s `message` event to REQUESTS ONLY — a stray response is ignored,
+* exactly as the prior hand-rolled pumps did — and re-serializes each one back to a
+* string for `bindServer`. `closed` bridges `transport`'s `close` event. `close`
+* closes the underlying `transport`.
+*
+* @remarks Per {@link import('@src/core').MCPTransportInterface}, `listen`/`closed`
+* each hold THE SINGLE current handler (a second call REPLACES the first, never adds).
+* Since the underlying `transport.emitter` is ADD-based (`on` subscribes, never
+* replaces), this bridge installs ONE stable emitter listener per event on first use
+* and re-routes it to whichever handler is CURRENTLY registered (`undefined` while
+* none is), so rebinding never double-dispatches.
+*
+* @remarks A response whose `result` serializes away (e.g. `undefined`) is dropped by
+* the message validators on the wire's decode side — an asymmetry the stdio/WS carrier
+* shares with the streamable-HTTP face, since both round-trip through `JSON.stringify`
+* / `JSON.parse` before re-validation.
+*
+* @param transport - The message-channel transport to bridge (stdio or WebSocket)
+* @returns An {@link import('@src/core').MCPTransportInterface} `bindServer` can drive
+*
+* @example
+* ```ts
+* import { bindServer } from '@src/core'
+*
+* const transport = new StdioServerTransport(process.stdin, process.stdout)
+* bindServer(mcp, bridgeMessageTransport(transport))
+* ```
+*/
+function bridgeMessageTransport(transport) {
+	let onMessage;
+	let onClosed;
+	transport.emitter.on("message", (message) => {
+		if (!(0, _src_core.isJSONRPCRequest)(message)) return;
+		onMessage?.(JSON.stringify(message));
+	});
+	transport.emitter.on("close", () => {
+		onClosed?.();
+	});
+	return {
+		async send(message) {
+			const decoded = decodeEvent(message);
+			if (decoded === void 0) return;
+			await transport.send(decoded);
+		},
+		listen(handler) {
+			onMessage = handler;
+		},
+		closed(handler) {
+			onClosed = handler;
+		},
+		async close() {
+			await transport.close();
+		}
+	};
+}
+//#endregion
+//#region src/server/handlers.ts
+/**
+* Create the Streamable-HTTP POST handler used by `createMCPRoutes`.
+*
+* @remarks
+* A present `mcp-protocol-version` header must name a supported revision; an
+* unsupported value returns an HTTP `400` JSON-RPC invalid-request error without
+* dispatching. An absent header is accepted for the initialize/bootstrap request.
+*
+* @param mcp - The transport-agnostic MCP server to dispatch through
+* @param streaming - Whether an event-stream response may be negotiated
+* @returns A request handler for the stateless MCP POST route
+*
+* @example
+* ```ts
+* import { createMCPServer } from '@orkestrel/mcp'
+* import { createMCPPostHandler } from '@orkestrel/mcp/server'
+* import { createToolManager } from '@orkestrel/agent'
+*
+* const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
+* const handler = createMCPPostHandler(mcp, true)
+* await handler(new Request('http://localhost/mcp', {
+* 	method: 'POST',
+* 	body: '{"jsonrpc":"2.0","method":"ping","id":1}',
+* }))
+* ```
+*/
+function createMCPPostHandler(mcp, streaming) {
+	return async (request) => {
+		const protocol = request.headers.get(MCP_PROTOCOL_VERSION_HEADER);
+		if (protocol !== null && !_src_core.SUPPORTED_PROTOCOL_VERSIONS.includes(protocol)) return Response.json((0, _src_core.jsonRPCError)(null, _src_core.JSONRPC_INVALID_REQUEST, `Unsupported MCP protocol version '${protocol}'`), { status: 400 });
+		let text;
+		try {
+			text = await request.text();
+		} catch {
+			return Response.json((0, _src_core.jsonRPCError)(null, _src_core.JSONRPC_PARSE_ERROR, "Parse error"), { status: 400 });
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch {
+			return Response.json((0, _src_core.jsonRPCError)(null, _src_core.JSONRPC_PARSE_ERROR, "Parse error"), { status: 400 });
+		}
+		const rpcRequest = (0, _src_core.parseJSONRPCMessage)(parsed);
+		if (rpcRequest === void 0 || !("method" in rpcRequest)) return Response.json((0, _src_core.jsonRPCError)(null, _src_core.JSONRPC_INVALID_REQUEST, "Invalid Request"), { status: 400 });
+		const response = await mcp.dispatch(rpcRequest);
+		if (response === void 0) return new Response(null, { status: 202 });
+		if (streaming && acceptsEventStream(request)) {
+			const stream = (0, _orkestrel_server.openStream)();
+			stream.write({ data: JSON.stringify(response) });
+			stream.end();
+			return stream.response;
+		}
+		return Response.json(response);
+	};
+}
 //#endregion
 //#region src/server/transports/HTTPClientTransport.ts
 /**
@@ -273,7 +401,7 @@ function dispatchLines(emitter, lines) {
 *
 * @remarks
 * - **Request/response over `fetch`.** `send(message)` POSTs the JSON-serialized
-*   message (or batch) to `options.url` with `content-type: application/json` and an
+*   message to `options.url` with `content-type: application/json` and an
 *   `Accept` of BOTH `application/json` and `text/event-stream` (so the server may
 *   answer with either framing) — plus any `options.headers` (e.g. an `Authorization`
 *   bearer). It then decodes the reply and emits each decoded {@link JSONRPCMessage} on
@@ -285,13 +413,18 @@ function dispatchLines(emitter, lines) {
 *   readEventStream}) — the inverse of the server's `openStream` seam, so the wire
 *   round-trips. A `202`
 *   Accepted (a notification) carries no body and emits nothing.
-* - **Session echo.** `start()` / `close()` are no-ops (a request/response transport
-*   holds no long-lived connection). The `mcp-session-id` response header, when a
-*   STATEFUL server sends one (on `initialize`), is captured into `session` and then
-*   ECHOED as the `mcp-session-id` request header on every SUBSEQUENT request — so an
-*   `MCPClient` passes a stateful server's session validation. Before initialize returns
-*   an id, `session` is `undefined` and no header is sent (safe against a stateless
-*   server, which neither sends nor expects one).
+* - **Session and protocol echo.** `start()` is a no-op (a
+*   request/response transport opens no long-lived connection). The
+*   `mcp-session-id` response header, when a STATEFUL server sends one (on
+*   `initialize`), is captured into `session` and then ECHOED as the
+*   `mcp-session-id` request header on every SUBSEQUENT request — so an
+*   `MCPClient` passes a stateful server's session validation. The
+*   initialize result's `protocolVersion` is likewise captured, but only
+*   when it is a SUPPORTED value, and echoed as `mcp-protocol-version` on
+*   every subsequent request, as required by the 2025-06-18 Streamable-HTTP
+*   transport. Before initialize returns, neither captured header is sent.
+*   `close()` clears the captured protocol so a reconnect's `initialize`
+*   POST is headerless; the captured `session` persists across `close()`.
 * - **Total at the boundary (§14).** Every reply is narrowed (`parseJSONRPCMessage`,
 *   the SSE decoder) — a non-message reply is dropped, never asserted; a `fetch` /
 *   decode failure surfaces on the `error` event rather than escaping `send`.
@@ -312,6 +445,7 @@ var HTTPClientTransport = class {
 	#fetch;
 	#timeout;
 	#session = void 0;
+	#protocol = void 0;
 	constructor(options) {
 		this.#emitter = new _orkestrel_emitter.Emitter();
 		this.#url = options.url;
@@ -335,6 +469,7 @@ var HTTPClientTransport = class {
 					"content-type": "application/json",
 					accept: "application/json, text/event-stream",
 					...this.#session === void 0 ? {} : { [MCP_SESSION_HEADER]: this.#session },
+					...this.#protocol === void 0 ? {} : { [MCP_PROTOCOL_VERSION_HEADER]: this.#protocol },
 					...this.#headers
 				},
 				body: JSON.stringify(message),
@@ -349,6 +484,7 @@ var HTTPClientTransport = class {
 		await this.#deliver(response);
 	}
 	async close() {
+		this.#protocol = void 0;
 		this.#emitter.emit("close");
 	}
 	async #deliver(response) {
@@ -356,17 +492,21 @@ var HTTPClientTransport = class {
 		const type = response.headers.get("content-type") ?? "";
 		try {
 			if (type.includes("text/event-stream")) {
-				for (const message of await readEventStream(response)) this.#emitter.emit("message", message);
+				for (const message of await readEventStream(response)) this.#capture(message);
 				return;
 			}
 			if (type.includes("application/json")) {
 				const message = (0, _src_core.parseJSONRPCMessage)(await response.json());
-				if (message !== void 0) this.#emitter.emit("message", message);
+				if (message !== void 0) this.#capture(message);
 			}
 		} catch (error) {
 			this.#emitter.emit("error", error);
 		}
 	}
+	#capture(message) {
+		if ((0, _src_core.isJSONRPCResponse)(message) && (0, _orkestrel_contract.isRecord)(message.result) && (0, _orkestrel_contract.isString)(message.result["protocolVersion"]) && _src_core.SUPPORTED_PROTOCOL_VERSIONS.includes(message.result["protocolVersion"])) this.#protocol = message.result["protocolVersion"];
+		this.#emitter.emit("message", message);
+	}
 };
 //#endregion
 //#region src/server/MCPSession.ts
@@ -508,8 +648,8 @@ var MCPSession = class {
 *   parsed envelope the {@link import('@src/core').MCPServerInterface} pump dispatches), while
 *   a non-JSON or non-message frame is surfaced on `error` and DROPPED, never thrown (§14). It
 *   also bridges the socket's `close` → this transport's `close`, and the socket's `error`.
-* - **Outbound (`send`).** `send(message | messages)` writes ONE text frame per message
-*   (`nodeWs.send(JSON.stringify(...))`); the underlying wrapper no-ops a write on a
+* - **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.
 * - **`close()`** 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
@@ -539,8 +679,7 @@ var WebSocketServerTransport = class {
 		this.#socket.emitter.on("error", (error) => this.#emitter.emit("error", error));
 	}
 	async send(message) {
-		const messages = Array.isArray(message) ? message : [message];
-		for (const one of messages) this.#socket.send(JSON.stringify(one));
+		this.#socket.send(JSON.stringify(message));
 	}
 	async close() {
 		if (this.#closed) return;
@@ -591,7 +730,7 @@ var WebSocketServerTransport = class {
 *   event (the reply the {@link import('@src/core').MCPClientInterface} correlates by `id`); a
 *   non-JSON / non-message frame surfaces on `error` and is dropped (§14). The socket's `close`
 *   / `error` bridge to this transport's events.
-* - **Outbound (`send`).** `send(message | messages)` writes ONE masked text frame per message.
+* - **Outbound (`send`).** `send(message)` writes one masked text frame.
 * - **`close()`** closes the underlying socket and fires `close` (idempotent).
 * - **URL scheme.** `options.url` accepts a `ws://` / `wss://` URL or an `http://` / `https://`
 *   one; a `ws(s)` scheme is converted to `http(s)` for the underlying upgrade request (`wss`
@@ -630,12 +769,6 @@ var WebSocketClientTransport = class {
 		const secure = url.protocol === "https:";
 		const send = secure ? node_https.request : node_http.request;
 		await new Promise((resolve, reject) => {
-			let settled = false;
-			const fail = (error) => {
-				if (settled) return;
-				settled = true;
-				reject(error);
-			};
 			const request = send({
 				hostname: url.hostname,
 				port: url.port.length > 0 ? Number(url.port) : secure ? 443 : 80,
@@ -653,7 +786,7 @@ var WebSocketClientTransport = class {
 				const accept = response.headers["sec-websocket-accept"];
 				if (!(0, _orkestrel_contract.isString)(accept) || accept !== (0, _orkestrel_websocket.computeWebSocketAccept)(key)) {
 					socket.destroy();
-					fail(/* @__PURE__ */ new Error("WebSocket handshake failed: Sec-WebSocket-Accept mismatch"));
+					reject(/* @__PURE__ */ new Error("WebSocket handshake failed: Sec-WebSocket-Accept mismatch"));
 					return;
 				}
 				const ws = (0, _orkestrel_websocket.createNodeWebSocket)({
@@ -662,24 +795,20 @@ var WebSocketClientTransport = class {
 				});
 				this.#socket = ws;
 				this.#bind(ws);
-				if (!settled) {
-					settled = true;
-					resolve();
-				}
+				resolve();
 			});
 			request.on("response", (response) => {
 				response.resume();
-				fail(/* @__PURE__ */ new Error(`WebSocket upgrade declined with status ${response.statusCode ?? 0}`));
+				reject(/* @__PURE__ */ new Error(`WebSocket upgrade declined with status ${response.statusCode ?? 0}`));
 			});
-			request.on("error", (error) => fail(error instanceof Error ? error : new Error(String(error))));
+			request.on("error", (error) => reject(error instanceof Error ? error : new Error(String(error))));
 			request.end();
 		});
 	}
 	async send(message) {
 		const socket = this.#socket;
 		if (socket === void 0) throw new Error("WebSocket transport is not connected");
-		const messages = Array.isArray(message) ? message : [message];
-		for (const one of messages) socket.send(JSON.stringify(one));
+		socket.send(JSON.stringify(message));
 	}
 	async close() {
 		if (this.#closed) return;
@@ -743,8 +872,8 @@ var WebSocketClientTransport = class {
 *   {@link dispatchLines} helper — a well-formed {@link JSONRPCMessage} emits
 *   `message`, a malformed line emits `error` (§14, never throws). The child's
 *   `close` bridges to this transport's `close`.
-* - **Outbound (`send`).** `send(message | messages)` writes ONE newline-terminated
-*   `JSON.stringify`d line per message to the child's `stdin`.
+* - **Outbound (`send`).** `send(message)` writes one newline-terminated
+*   `JSON.stringify`d line to the child's `stdin`.
 * - **`close()`** kills the child process and fires `close` (idempotent).
 * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); the
 *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
@@ -795,8 +924,7 @@ var StdioClientTransport = class {
 	async send(message) {
 		const child = this.#child;
 		if (child === void 0) throw new Error("stdio transport is not connected");
-		const messages = Array.isArray(message) ? message : [message];
-		for (const one of messages) child.stdin.write(`${JSON.stringify(one)}\n`);
+		child.stdin.write(`${JSON.stringify(message)}\n`);
 	}
 	async close() {
 		if (this.#closed) return;
@@ -839,8 +967,8 @@ var StdioClientTransport = class {
 *   well-formed {@link JSONRPCMessage} re-emits on `message`, a malformed line
 *   emits `error` (§14, never throws). `input`'s `close` bridges to this
 *   transport's `close`.
-* - **Outbound (`send`).** `send(message | messages)` writes ONE newline-terminated
-*   `JSON.stringify`d line per message to `output`.
+* - **Outbound (`send`).** `send(message)` writes one newline-terminated
+*   `JSON.stringify`d line to `output`.
 * - **`close()`** fires this transport's `close` (idempotent) — the injected streams
 *   are owned by the caller (typically `process.stdin`/`process.stdout`, which must
 *   never be closed out from under the process) and are not torn down here.
@@ -872,8 +1000,7 @@ var StdioServerTransport = class {
 		this.#input.on("error", (error) => this.#emitter.emit("error", error));
 	}
 	async send(message) {
-		const messages = Array.isArray(message) ? message : [message];
-		for (const one of messages) this.#output.write(`${JSON.stringify(one)}\n`);
+		this.#output.write(`${JSON.stringify(message)}\n`);
 	}
 	async close() {
 		if (this.#closed) return;
@@ -908,6 +1035,9 @@ var StdioServerTransport = class {
 * - A **transport** failure — a malformed JSON body, or a parsed value that is not a
 *   JSON-RPC REQUEST — is an HTTP `400` carrying a JSON-RPC error BODY (`-32700` Parse
 *   error / `-32600` Invalid Request, id `null`).
+* - A present `mcp-protocol-version` header is validated before dispatch: a supported
+*   value proceeds, while an unsupported value returns HTTP `400` with a JSON-RPC
+*   `-32600` body. An absent value proceeds for initialize/bootstrap compatibility.
 * - A **dispatch** result — a success OR an IN-BAND JSON-RPC error from `mcp.dispatch`
 *   (e.g. `-32601` method-not-found) — is an HTTP `200` carrying the JSON-RPC response
 *   envelope (the error is in-band per JSON-RPC, NOT an HTTP error).
@@ -944,37 +1074,11 @@ var StdioServerTransport = class {
 * ```
 */
 function createMCPRoutes(mcp, options) {
-	const path = options?.path ?? "/mcp";
-	const streaming = options?.streaming ?? true;
 	return [{
 		method: "POST",
-		path,
+		path: options?.path ?? "/mcp",
 		name: "mcp",
-		handler: async (request) => {
-			let text;
-			try {
-				text = await request.text();
-			} catch {
-				return Response.json((0, _src_core.jsonRPCError)(null, _src_core.JSONRPC_PARSE_ERROR, "Parse error"), { status: 400 });
-			}
-			let parsed;
-			try {
-				parsed = JSON.parse(text);
-			} catch {
-				return Response.json((0, _src_core.jsonRPCError)(null, _src_core.JSONRPC_PARSE_ERROR, "Parse error"), { status: 400 });
-			}
-			const rpcRequest = (0, _src_core.parseJSONRPCMessage)(parsed);
-			if (rpcRequest === void 0 || !("method" in rpcRequest)) return Response.json((0, _src_core.jsonRPCError)(null, _src_core.JSONRPC_INVALID_REQUEST, "Invalid Request"), { status: 400 });
-			const response = await mcp.dispatch(rpcRequest);
-			if (response === void 0) return new Response(null, { status: 202 });
-			if (streaming && acceptsEventStream(request)) {
-				const s = (0, _orkestrel_server.openStream)();
-				s.write({ data: JSON.stringify(response) });
-				s.end();
-				return s.response;
-			}
-			return Response.json(response);
-		}
+		handler: createMCPPostHandler(mcp, options?.streaming ?? true)
 	}];
 }
 /**
@@ -990,8 +1094,10 @@ function createMCPRoutes(mcp, options) {
 * and the reply is surfaced on the transport's `message` event for the client's id
 * correlation. Add `options.headers` (e.g. an `Authorization` bearer) to reach a guarded
 * server. `start` / `close` hold no connection; against a STATEFUL server it captures the
-* `mcp-session-id` from `initialize` and echoes it on later requests, so the same
-* `MCPClient` passes session validation (a stateless server sends none).
+* `mcp-session-id` from `initialize` and echoes it on later requests. It also captures
+* the initialize result's `protocolVersion` and sends `mcp-protocol-version` on every
+* subsequent request, so the same `MCPClient` passes the session and 2025-06-18
+* protocol gates without caller wiring.
 *
 * @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged onto
 *   every request, optional `fetch` (default `globalThis.fetch`), and optional `timeout`
@@ -1031,12 +1137,13 @@ function createHTTPClientTransport(options) {
 * - **Claims (returns `true`)** otherwise: it builds `createNodeWebSocket({ socket, key, head,
 *   protocol })` (SERVER mode → writes the `101` handshake, echoing the `subprotocol`, default
 *   {@link MCP_WEBSOCKET_SUBPROTOCOL} `'mcp'`, and sends UNMASKED frames), wraps it in a
-*   {@link WebSocketServerTransport}, and PUMPS: each inbound {@link
-*   import('@src/core').JSONRPCMessage} that is a REQUEST runs through `mcp.dispatch`, and a
-*   defined response is written back as a frame — a NOTIFICATION (`dispatch` → `undefined`)
-*   sends nothing. A non-request message (a stray response) is ignored. The dispatch is
-*   guarded so a `dispatch` / `send` fault surfaces on the transport's `error` event rather
-*   than escaping the (async) message listener.
+*   {@link WebSocketServerTransport}, and pipes it through the core {@link
+*   import('@src/core').MCPTransportInterface} port via {@link
+*   import('./helpers.js').bridgeMessageTransport} + {@link import('@src/core').bindServer}:
+*   each inbound REQUEST runs through `mcp.dispatch`, and a defined response is written back
+*   as a frame — a NOTIFICATION sends nothing, and a non-request message (a stray response) is
+*   ignored. A `dispatch` / `send` fault surfaces on `mcp.emitter`'s `error` event rather than
+*   escaping the (async) message pump.
 *
 * It is MECHANISM, not policy: compose an auth guard IN FRONT by registering an upgrade
 * handler BEFORE this one — that handler can claim (decline + destroy) an unauthenticated
@@ -1073,19 +1180,7 @@ function createWebSocketServer(mcp, options) {
 			head,
 			protocol: subprotocol
 		}));
-		transport.emitter.on("message", (message) => {
-			if (!(0, _src_core.isJSONRPCRequest)(message)) return;
-			(async () => {
-				try {
-					const response = await mcp.dispatch(message);
-					if (response !== void 0) await transport.send(response);
-				} catch (error) {
-					try {
-						transport.emitter.emit("error", error);
-					} catch {}
-				}
-			})();
-		});
+		(0, _src_core.bindServer)(mcp, bridgeMessageTransport(transport));
 		transport.start();
 		return true;
 	};
@@ -1167,12 +1262,13 @@ function createStdioClientTransport(options) {
 * @remarks
 * Wraps `options.input` (default `process.stdin`) / `options.output` (default
 * `process.stdout`) in a {@link import('./transports/StdioServerTransport.js').StdioServerTransport}
-* and PUMPS: each inbound {@link import('@src/core').JSONRPCMessage} that is a
-* REQUEST runs through `mcp.dispatch`, and a defined response is written back as a
-* newline-terminated line — a NOTIFICATION (`dispatch` → `undefined`) writes
-* nothing. A non-request message is ignored. The dispatch is guarded so a
-* `dispatch` / `send` fault surfaces on the transport's `error` event rather than
-* escaping the (async) message listener.
+* and pipes it through the core {@link import('@src/core').MCPTransportInterface} port
+* via {@link import('./helpers.js').bridgeMessageTransport} + {@link
+* import('@src/core').bindServer}: each inbound REQUEST runs through `mcp.dispatch`, and
+* a defined response is written back as a newline-terminated line — a NOTIFICATION
+* writes nothing, and a non-request message is ignored. A `dispatch` / `send` fault
+* surfaces on `mcp.emitter`'s `error` event rather than escaping the (async) message
+* pump.
 *
 * @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over stdio
 * @param options - Optional injectable `input` / `output` streams; see
@@ -1190,19 +1286,7 @@ function createStdioClientTransport(options) {
 */
 function createStdioServer(mcp, options) {
 	const transport = new StdioServerTransport(options?.input ?? process.stdin, options?.output ?? process.stdout);
-	transport.emitter.on("message", (message) => {
-		if (!(0, _src_core.isJSONRPCRequest)(message)) return;
-		(async () => {
-			try {
-				const response = await mcp.dispatch(message);
-				if (response !== void 0) await transport.send(response);
-			} catch (error) {
-				try {
-					transport.emitter.emit("error", error);
-				} catch {}
-			}
-		})();
-	});
+	(0, _src_core.bindServer)(mcp, bridgeMessageTransport(transport));
 	return {
 		start() {
 			transport.start();
@@ -1276,30 +1360,43 @@ function createMCPSession(options) {
 	const store = /* @__PURE__ */ new Map();
 	return async (request, context, next) => {
 		if (context.url.pathname !== path) return next();
-		sweep();
+		if (ttl !== void 0) {
+			const cutoff = clock() - ttl;
+			for (const [id, entry] of store) if (entry.touched <= cutoff) store.delete(id);
+		}
+		if (context.method === "DELETE") {
+			const id = readSessionHeader(request);
+			if (id === void 0 || !store.delete(id)) return rejectUnknownSession();
+			return new Response(null, { status: 204 });
+		}
+		let entry;
+		const id = readSessionHeader(request);
+		if (id !== void 0) {
+			const current = store.get(id);
+			if (current !== void 0) {
+				entry = {
+					session: current.session,
+					touched: clock()
+				};
+				store.set(id, entry);
+			}
+		}
 		if (context.method === "GET") {
-			const entry = resolve(request);
 			if (entry === void 0) return rejectUnknownSession();
+			const session = entry.session;
 			const stream = (0, _orkestrel_server.openStream)();
 			stream.comment("open");
 			const lastEventId = readLastEventId(request);
-			if (lastEventId !== void 0) for (const e of entry.session.replay(lastEventId)) stream.write({
+			if (lastEventId !== void 0) for (const e of session.replay(lastEventId)) stream.write({
 				id: e.id,
 				data: JSON.stringify(e.message)
 			});
-			entry.session.attach(stream);
-			if (request.signal.aborted) entry.session.detach(stream);
-			else request.signal.addEventListener("abort", () => entry.session.detach(stream), { once: true });
+			session.attach(stream);
+			if (request.signal.aborted) session.detach(stream);
+			else request.signal.addEventListener("abort", () => session.detach(stream), { once: true });
 			return stream.response;
 		}
-		if (context.method === "DELETE") {
-			const id = readSessionHeader(request);
-			if (id === void 0 || !store.has(id)) return rejectUnknownSession();
-			store.delete(id);
-			return new Response(null, { status: 204 });
-		}
 		const text = await request.text();
-		let entry = resolve(request);
 		if (entry === void 0) {
 			let parsed;
 			try {
@@ -1308,7 +1405,7 @@ function createMCPSession(options) {
 				parsed = void 0;
 			}
 			if (parsed !== void 0 && (0, _src_core.isInitializeRequest)(parsed)) {
-				const session = new MCPSession(crypto.randomUUID(), { capacity });
+				const session = new MCPSession(crypto.randomUUID(), capacity !== void 0 ? { capacity } : {});
 				entry = {
 					session,
 					touched: clock()
@@ -1316,7 +1413,7 @@ function createMCPSession(options) {
 				store.set(session.id, entry);
 			} else return rejectUnknownSession();
 		}
-		context.state.session = entry.session;
+		if (!Reflect.set(context.state, "session", entry.session)) throw new Error("MCP session state is not writable");
 		const response = await next(new Request(context.url, {
 			method: "POST",
 			headers: request.headers,
@@ -1325,19 +1422,6 @@ function createMCPSession(options) {
 		response.headers.set(MCP_SESSION_HEADER, entry.session.id);
 		return response;
 	};
-	function resolve(request) {
-		const id = readSessionHeader(request);
-		if (id === void 0) return void 0;
-		const entry = store.get(id);
-		if (entry === void 0) return void 0;
-		entry.touched = clock();
-		return entry;
-	}
-	function sweep() {
-		if (ttl === void 0) return;
-		const cutoff = clock() - ttl;
-		for (const [id, entry] of store) if (entry.touched <= cutoff) store.delete(id);
-	}
 }
 //#endregion
 exports.DEFAULT_MCP_PATH = DEFAULT_MCP_PATH;
@@ -1353,7 +1437,9 @@ exports.StdioServerTransport = StdioServerTransport;
 exports.WebSocketClientTransport = WebSocketClientTransport;
 exports.WebSocketServerTransport = WebSocketServerTransport;
 exports.acceptsEventStream = acceptsEventStream;
+exports.bridgeMessageTransport = bridgeMessageTransport;
 exports.createHTTPClientTransport = createHTTPClientTransport;
+exports.createMCPPostHandler = createMCPPostHandler;
 exports.createMCPRoutes = createMCPRoutes;
 exports.createMCPSession = createMCPSession;
 exports.createStdioClientTransport = createStdioClientTransport;