@orkestrel/mcp 0.0.8 → 0.0.9

package/dist/src/server/index.cjs

@@ -27,9 +27,28 @@ var MCP_SESSION_HEADER = "mcp-session-id";
 * requests; `createMCPRoutes` rejects a present unsupported value before dispatch.
 */
 var MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
+/** The modern Streamable-HTTP request header carrying the JSON-RPC method name. */
+var MCP_METHOD_HEADER = "mcp-method";
+/** The modern Streamable-HTTP request header carrying a named method's target. */
+var MCP_NAME_HEADER = "mcp-name";
+/** The reverse-proxy response header controlling buffering of an SSE response. */
+var SSE_BUFFERING_HEADER = "x-accel-buffering";
+/** The `X-Accel-Buffering` value that disables reverse-proxy buffering. */
+var SSE_BUFFERING_DISABLED = "no";
 /** The default request path `createMCPRoutes` mounts the transport's `POST` route at. */
 var DEFAULT_MCP_PATH = "/mcp";
 /**
+* The default interval in milliseconds between SSE keepalive comments on held-open MCP
+* responses.
+*
+* @remarks
+* Fifteen seconds is infrequent enough to avoid chatty idle connections while bounding dead
+* client detection and staying comfortably inside common intermediary idle windows.
+*/
+var DEFAULT_MCP_KEEPALIVE_INTERVAL = 15e3;
+/** The comment text written by the held-open MCP response keepalive. */
+var SSE_KEEPALIVE_COMMENT = "keepalive";
+/**
 * The WebSocket subprotocol the MCP-over-WebSocket transports negotiate — sent by the
 * client in `Sec-WebSocket-Protocol`, echoed by the server in its `101` handshake.
 *
@@ -67,6 +86,19 @@ var DEFAULT_MCP_SESSION_TTL = 3e5;
 //#endregion
 //#region src/server/helpers.ts
 /**
+* Create a readable stream from its pull and cancellation behaviours.
+*
+* @param pull - The behaviour that supplies the stream's next chunk
+* @param cancel - The behaviour that releases the stream after consumer cancellation
+* @returns A readable stream backed by the supplied behaviours
+*/
+function createReadableStream(pull, cancel) {
+	return new ReadableStream({
+		pull,
+		cancel
+	});
+}
+/**
 * Whether the request's `Accept` header opts into a Server-Sent-Events response.
 *
 * @remarks
@@ -85,6 +117,55 @@ function acceptsEventStream(request) {
 	return accept.toLowerCase().includes("text/event-stream");
 }
 /**
+* Whether an HTTP request satisfies the endpoint's origin gate.
+*
+* @remarks
+* Validation is enabled by default. A request without `Origin` is allowed. A canonical origin
+* whose host is the `localhost` or `[::1]` literal, or belongs to the `127.0.0.0/8` literal
+* range, is allowed without configuration; every other present origin must occur exactly in
+* the caller-supplied list. Invalid and opaque (`null`) origins are denied. `enabled: false`
+* delegates validation to an upstream layer and allows the request through this gate.
+*
+* @param request - The fetch-standard request to validate
+* @param options - Shared origin validation and delegation options
+* @returns `true` when the request may reach MCP dispatch
+*/
+function allowsOrigin(request, options) {
+	if (options?.enabled === false) return true;
+	const origin = request.headers.get("origin");
+	if (origin === null) return true;
+	let parsed;
+	try {
+		parsed = new URL(origin);
+	} catch {
+		return false;
+	}
+	if (parsed.origin !== origin) return false;
+	if (parsed.hostname === "localhost" || parsed.hostname === "[::1]" || /^127(?:\.\d{1,3}){3}$/.test(parsed.hostname)) return true;
+	return options?.origins?.includes(parsed.origin) ?? false;
+}
+/**
+* Whether a modern HTTP request's required standard headers match its JSON-RPC body.
+*
+* @remarks
+* Requires `MCP-Protocol-Version` to equal the reserved `_meta` version and `Mcp-Method`
+* to equal `method`. `Mcp-Name` is required only for `tools/call`, where it must equal
+* `params.name`; discovery and listing requests need no name because none is derivable.
+* Legacy requests return `false` because this predicate models the modern contract only.
+*
+* @param request - The HTTP request carrying the headers
+* @param message - The parsed JSON-RPC request body
+* @returns `true` only when every method-applicable modern header matches
+*/
+function matchesModernHeaders(request, message) {
+	if (!(0, _src_core.isModernRequest)(message)) return false;
+	const version = ((0, _orkestrel_contract.isRecord)(message.params?.["_meta"]) ? message.params["_meta"] : void 0)?.[_src_core.MCP_META_VERSION];
+	if (!(0, _orkestrel_contract.isString)(version) || request.headers.get("mcp-protocol-version") !== version || request.headers.get("mcp-method") !== message.method) return false;
+	if (message.method !== "tools/call") return true;
+	const name = message.params?.["name"];
+	return (0, _orkestrel_contract.isString)(name) && request.headers.get("mcp-name") === name;
+}
+/**
 * Read the request's `mcp-session-id` header — the session id a stateful transport
 * validates, or `undefined` when absent.
 *
@@ -125,7 +206,7 @@ function readLastEventId(request) {
 * JSON-RPC error body.
 *
 * @remarks
-* Returns `Response.json(jsonRPCError(null, JSONRPC_INVALID_REQUEST, 'Session not found'),
+* Returns `Response.json(buildJSONRPCError(null, JSONRPC_INVALID_REQUEST, 'Session not found'),
 * { status: 404 })`, mirroring `createMCPRoutes`'s `400` transport-failure shape (a
 * JSON-RPC error BODY with a `null` id) but at the session-not-found status. Shared by
 * every {@link import('./middlewares.js').createMCPSession} validation site — the
@@ -136,7 +217,7 @@ function readLastEventId(request) {
 * @returns The `404` JSON-RPC error `Response`
 */
 function rejectUnknownSession() {
-	return Response.json((0, _src_core.jsonRPCError)(null, _src_core.JSONRPC_INVALID_REQUEST, "Session not found"), { status: 404 });
+	return Response.json((0, _src_core.buildJSONRPCError)(null, _src_core.JSONRPC_INVALID_REQUEST, "Session not found"), { status: 404 });
 }
 /**
 * Decode a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it
@@ -336,17 +417,136 @@ function bridgeMessageTransport(transport) {
 	};
 }
 //#endregion
+//#region src/server/inferers.ts
+/**
+* Infer the legacy revision an `initialize` request negotiates.
+*
+* @remarks
+* A supported legacy request is pinned exactly. A modern, malformed, absent, or unsupported
+* request selects the newest supported legacy revision, matching the core initialize result.
+*
+* @param request - The legacy initialize request
+* @returns The negotiated legacy protocol revision
+*/
+function inferLegacyVersion(request) {
+	const requested = request.params?.["protocolVersion"];
+	const version = (0, _src_core.inferVersion)((0, _orkestrel_contract.isString)(requested) ? [requested] : []);
+	if (version !== void 0 && (0, _src_core.inferEra)(version) === "legacy") return version;
+	return _src_core.MCP_PROTOCOL_VERSION;
+}
+/**
+* Infer the HTTP status for one MCP dispatch outcome without changing its JSON-RPC body.
+*
+* @remarks
+* Notifications are accepted with `202`. Legacy response envelopes retain uniform `200`
+* status semantics, including in-band errors. Modern header/capability/version/parameter
+* failures map to `400`, method-not-found maps to `404`, and every other modern result maps
+* to `200`.
+*
+* @param response - The dispatch response, or `undefined` for a notification
+* @param era - The structurally selected request era
+* @returns The HTTP response status
+*/
+function inferStatus(response, era) {
+	if (response === void 0) return 202;
+	if (era === "legacy" || response.error === void 0) return 200;
+	if (response.error.code === _src_core.JSONRPC_METHOD_NOT_FOUND) return 404;
+	if (response.error.code === _src_core.MCP_HEADER_MISMATCH || response.error.code === _src_core.MCP_MISSING_CAPABILITY || response.error.code === _src_core.MCP_UNSUPPORTED_VERSION || response.error.code === _src_core.JSONRPC_INVALID_PARAMS) return 400;
+	return 200;
+}
+//#endregion
+//#region src/server/transports/HTTPDisconnect.ts
+/**
+* The HTTP response-disconnect bridge for an MCP SSE stream.
+*
+* @remarks
+* Composes the incoming request signal with a controller owned by the MCP HTTP face. The
+* returned {@link signal} therefore observes both an incomplete request body and cancellation
+* of the streamed response body. {@link bridge} preserves the supplied SSE response while
+* forwarding its body through a cancellation-aware stream. While that response is held open,
+* the bridge writes SSE comment frames at the configured keepalive interval so an idle dead
+* client becomes observable to the HTTP writer. It never decides how an abort changes handler
+* or session state.
+*/
+var HTTPDisconnect = class {
+	#abort = new AbortController();
+	#lifecycle = new AbortController();
+	#interval;
+	#signal;
+	#timer;
+	constructor(signal, options) {
+		this.#interval = options?.interval ?? 15e3;
+		this.#signal = AbortSignal.any([signal, this.#abort.signal]);
+	}
+	get signal() {
+		return this.#signal;
+	}
+	/**
+	* Bridge cancellation of an SSE response body into this disconnect signal.
+	*
+	* @param stream - The open SSE stream whose response will be consumed by the HTTP writer
+	* @returns A response with the same status and headers whose body forwards the SSE bytes
+	*/
+	bridge(stream) {
+		const response = stream.response;
+		const body = response.body;
+		if (body === null) throw new Error("MCP SSE response has no body");
+		const reader = body.getReader();
+		this.#timer = setInterval(() => {
+			if (stream.closed) this.#stop();
+			else stream.comment(SSE_KEEPALIVE_COMMENT);
+		}, this.#interval);
+		this.#signal.addEventListener("abort", () => this.#stop(), {
+			once: true,
+			signal: this.#lifecycle.signal
+		});
+		if (this.#signal.aborted || stream.closed) this.#stop();
+		return new Response(createReadableStream(async (controller) => {
+			try {
+				const chunk = await reader.read();
+				if (chunk.done) {
+					this.#stop();
+					controller.close();
+				} else controller.enqueue(chunk.value);
+			} catch (error) {
+				this.#stop();
+				controller.error(error);
+			}
+		}, async (reason) => {
+			this.#abort.abort();
+			this.#stop();
+			await reader.cancel(reason);
+		}), {
+			status: response.status,
+			statusText: response.statusText,
+			headers: response.headers
+		});
+	}
+	#stop() {
+		if (this.#timer !== void 0) {
+			clearInterval(this.#timer);
+			this.#timer = void 0;
+		}
+		this.#lifecycle.abort();
+	}
+};
+//#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.
+* 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 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
+* handler through `MCPDispatchOptions.signal`.
 *
 * @param mcp - The transport-agnostic MCP server to dispatch through
-* @param streaming - Whether an event-stream response may be negotiated
+* @param options - Optional streaming, origin-validation, and SSE keepalive options
 * @returns A request handler for the stateless MCP POST route
 *
 * @example
@@ -355,41 +555,75 @@ function bridgeMessageTransport(transport) {
 * import { createMCPPostHandler } from '@orkestrel/mcp/server'
 * import { createToolManager } from '@orkestrel/tool'
 *
-* const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
-* const handler = createMCPPostHandler(mcp, true)
+* const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
+* const handler = createMCPPostHandler(mcp, { streaming: true })
 * await handler(new Request('http://localhost/mcp', {
 * 	method: 'POST',
 * 	body: '{"jsonrpc":"2.0","method":"ping","id":1}',
 * }))
 * ```
 */
-function createMCPPostHandler(mcp, streaming) {
+function createMCPPostHandler(mcp, options) {
+	const streaming = options?.streaming ?? true;
+	const origin = options?.origin;
 	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 });
+		if (!allowsOrigin(request, origin)) return new Response(null, { status: 403 });
 		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 });
+			return Response.json((0, _src_core.buildJSONRPCError)(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 });
+			return Response.json((0, _src_core.buildJSONRPCError)(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)) {
+		if (rpcRequest === void 0 || !("method" in rpcRequest)) return Response.json((0, _src_core.buildJSONRPCError)(null, _src_core.JSONRPC_INVALID_REQUEST, "Invalid Request"), { status: 400 });
+		const era = (0, _src_core.isModernRequest)(rpcRequest) ? "modern" : "legacy";
+		const id = rpcRequest.id ?? null;
+		const protocol = request.headers.get(MCP_PROTOCOL_VERSION_HEADER);
+		if (era === "modern") {
+			if ((0, _src_core.parseRequestContext)(rpcRequest) === void 0) return Response.json((0, _src_core.buildJSONRPCError)(id, _src_core.JSONRPC_INVALID_PARAMS, "Invalid params: malformed modern request metadata"), { status: 400 });
+			if (!matchesModernHeaders(request, rpcRequest)) return Response.json((0, _src_core.buildJSONRPCError)(id, _src_core.MCP_HEADER_MISMATCH, "MCP request headers do not match the request body"), { status: 400 });
+		} else {
+			if (protocol === null && !(0, _src_core.isInitializeRequest)(rpcRequest)) return Response.json((0, _src_core.buildJSONRPCError)(id, _src_core.MCP_HEADER_MISMATCH, "MCP request headers do not match the request body"), { status: 400 });
+			if (protocol !== null && !(0, _src_core.isMCPVersion)(protocol)) return Response.json((0, _src_core.buildJSONRPCError)(id, _src_core.MCP_UNSUPPORTED_VERSION, `Unsupported MCP protocol version '${protocol}'`, {
+				supported: _src_core.SUPPORTED_PROTOCOL_VERSIONS,
+				requested: protocol
+			}), { status: 400 });
+		}
+		const disconnect = new HTTPDisconnect(request.signal, options?.keepalive);
+		const response = await mcp.dispatch(rpcRequest, { signal: disconnect.signal });
+		if (response !== void 0 && Symbol.asyncIterator in response) {
+			const stream = (0, _orkestrel_server.openStream)();
+			stream.response.headers.set(SSE_BUFFERING_HEADER, "no");
+			queueMicrotask(async () => {
+				try {
+					let next = await response.next();
+					while (!next.done) {
+						stream.write({ data: JSON.stringify(next.value) });
+						next = await response.next();
+					}
+					stream.write({ data: JSON.stringify(next.value) });
+				} catch {} finally {
+					stream.end();
+				}
+			});
+			return disconnect.bridge(stream);
+		}
+		const status = inferStatus(response, era);
+		if (response === void 0) return new Response(null, { status });
+		if (status === 200 && streaming && acceptsEventStream(request)) {
 			const stream = (0, _orkestrel_server.openStream)();
+			stream.response.headers.set(SSE_BUFFERING_HEADER, "no");
 			stream.write({ data: JSON.stringify(response) });
 			stream.end();
 			return stream.response;
 		}
-		return Response.json(response);
+		return Response.json(response, { status });
 	};
 }
 //#endregion
@@ -413,16 +647,17 @@ function createMCPPostHandler(mcp, streaming) {
 *   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 and protocol echo.** `start()` is a no-op (a
+* - **Session and protocol headers.** `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.
+*   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`.
+*   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()`.
 * - **Total at the boundary (§14).** Every reply is narrowed (`parseJSONRPCMessage`,
@@ -469,7 +704,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.#buildHeaders(message),
 					...this.#headers
 				},
 				body: JSON.stringify(message),
@@ -487,6 +722,18 @@ var HTTPClientTransport = class {
 		this.#protocol = void 0;
 		this.#emitter.emit("close");
 	}
+	#buildHeaders(message) {
+		if ((0, _src_core.isJSONRPCRequest)(message) && (0, _src_core.isModernRequest)(message)) {
+			const version = ((0, _orkestrel_contract.isRecord)(message.params?.["_meta"]) ? message.params["_meta"] : void 0)?.[_src_core.MCP_META_VERSION];
+			const name = message.params?.["name"];
+			return {
+				...(0, _orkestrel_contract.isString)(version) ? { [MCP_PROTOCOL_VERSION_HEADER]: version } : {},
+				[MCP_METHOD_HEADER]: message.method,
+				...message.method === "tools/call" && (0, _orkestrel_contract.isString)(name) ? { [MCP_NAME_HEADER]: name } : {}
+			};
+		}
+		return this.#protocol === void 0 ? {} : { [MCP_PROTOCOL_VERSION_HEADER]: this.#protocol };
+	}
 	async #deliver(response) {
 		if (response.status === 202) return;
 		const type = response.headers.get("content-type") ?? "";
@@ -504,7 +751,7 @@ var HTTPClientTransport = class {
 		}
 	}
 	#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"];
+		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);
 	}
 };
@@ -1035,12 +1282,11 @@ 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).
+* - Modern protocol/method/name headers are validated against the body; a mismatch is
+*   HTTP `400` + `-32020`. Headerless initialize is accepted, a live legacy session supplies
+*   its pinned revision, and every other headerless request is rejected.
+* - Legacy dispatch errors stay IN-BAND at HTTP `200`; modern errors map to `400` for
+*   `-32020` / `-32021` / `-32022` / `-32602`, `404` for `-32601`, and `200` otherwise.
 * - A **notification** (a request with no `id`, which `dispatch` resolves to
 *   `undefined`) is a `202 Accepted` with no body.
 *
@@ -1055,13 +1301,15 @@ var StdioServerTransport = class {
 * validates the `mcp-session-id`, and serves the resumable `GET {path}` + `DELETE {path}`,
 * leaving this route to dispatch the validated `POST`.
 *
-* This is MECHANISM, not policy: compose auth / CORS / rate-limiting (and the session
-* middleware) IN FRONT as ordinary middleware — the transport route adds none.
+* This is MECHANISM, not policy: compose auth / rate-limiting (and the session middleware)
+* IN FRONT as ordinary middleware; the optional `origin` group carries the deployment's shared
+* allowlist or explicitly delegates validation to an upstream layer.
 *
 * @typeParam TState - The consumer's opaque per-request state type
 * @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over HTTP
 * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}) and `streaming`
-*   (default `true`); see {@link HTTPTransportOptions}
+*   (default `true`), plus the shared `origin` validation options; see
+*   {@link HTTPTransportOptions}
 * @returns The {@link RouteInput}s to register with the router
 *
 * @example
@@ -1069,7 +1317,7 @@ var StdioServerTransport = class {
 * import { createMCPServer, createToolManager } from '@src/core'
 * import { createMCPRoutes } from '@src/server'
 *
-* const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
+* const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
 * const routes = createMCPRoutes(mcp) // POST /mcp dispatches JSON-RPC (JSON or SSE per Accept)
 * ```
 */
@@ -1078,7 +1326,7 @@ function createMCPRoutes(mcp, options) {
 		method: "POST",
 		path: options?.path ?? "/mcp",
 		name: "mcp",
-		handler: createMCPPostHandler(mcp, options?.streaming ?? true)
+		handler: createMCPPostHandler(mcp, options)
 	}];
 }
 /**
@@ -1095,9 +1343,9 @@ function createMCPRoutes(mcp, options) {
 * 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. 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.
+* the initialize result's `protocolVersion` and sends `mcp-protocol-version` alone on each
+* subsequent legacy request. Modern requests derive protocol and method headers directly
+* from the message, plus a name header only for `tools/call`.
 *
 * @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged onto
 *   every request, optional `fetch` (default `globalThis.fetch`), and optional `timeout`
@@ -1159,7 +1407,7 @@ function createHTTPClientTransport(options) {
 * import { createMCPServer, createToolManager } from '@src/core'
 * import { createWebSocketServer } from '@src/server'
 *
-* const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
+* const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
 * server.upgrade(createWebSocketServer(mcp)) // an MCP client now connects over ws://…/mcp
 * ```
 */
@@ -1280,7 +1528,7 @@ function createStdioClientTransport(options) {
 * import { createMCPServer, createToolManager } from '@src/core'
 * import { createStdioServer } from '@src/server'
 *
-* const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
+* const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
 * createStdioServer(mcp).start() // an MCP client now connects over this process's stdio
 * ```
 */
@@ -1310,12 +1558,17 @@ function createStdioServer(mcp, options) {
 * `path` (default {@link DEFAULT_MCP_PATH}); a request to any other path passes straight
 * through (`next()`).
 *
+* A modern-shaped POST also passes straight through via `next()`, ignoring any session id.
+* The remaining behavior is the legacy session layer:
+*
 * - **`POST {path}`.** Buffers `const text = await request.text()` (so the downstream route
 *   can re-read it via a freshly-built forwarded `Request`). Resolves a session via {@link
 *   readSessionHeader}: a VALID id touches the entry and sets `context.state.session`; an
 *   ABSENT / unknown id whose (guarded) body parses to an `initialize` request ({@link
 *   isInitializeRequest}) MINTS a fresh {@link MCPSession} (`crypto.randomUUID()`, `capacity`)
-*   and sets `context.state.session`; neither → {@link rejectUnknownSession} (`404`). It then
+*   and sets `context.state.session`; neither → {@link rejectUnknownSession} (`404`). The
+*   minted entry pins the negotiated legacy revision, which is supplied to a later headerless
+*   live-session request. It then
 *   FORWARDS a fresh `Request` carrying the buffered `text` (`next(forwarded)`) — never the
 *   already-consumed original — so the route re-reads the same body, and stamps the response
 *   with {@link MCP_SESSION_HEADER}.
@@ -1323,8 +1576,8 @@ function createStdioServer(mcp, options) {
 *   an invalid / unknown id is the same `404`. A valid session opens the resumable
 *   server→client stream via `@orkestrel/server`'s {@link import('@orkestrel/server').openStream}:
 *   replays every event after the client's `Last-Event-ID` ({@link readLastEventId}) BEFORE
-*   attaching the stream for live pushes, then attaches; a client disconnect (`request.signal`)
-*   detaches it. Long-lived — never `end()`ed here.
+*   attaching the stream for live pushes, then attaches; cancellation of the streamed response
+*   body composes with `request.signal` and detaches it. Long-lived — never `end()`ed here.
 * - **`DELETE {path}`.** Resolves the session; a valid id deletes it from the store and answers
 *   `204`; an invalid / unknown id is the same `404`.
 *
@@ -1338,7 +1591,8 @@ function createStdioServer(mcp, options) {
 * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}), `ttl` (idle-session
 *   sweep window, ms — omit for sessions that live until an explicit `DELETE`), `capacity`
 *   (the folded per-session replay-log bound), and `clock` (the deterministic epoch-ms clock;
-*   defaults to `Date.now`); see {@link MCPSessionOptions}
+*   defaults to `Date.now`), plus the shared `origin` validation options; see
+*   {@link MCPSessionOptions}
 * @returns A {@link MiddlewareHandler} that mints / validates sessions + serves the resumable
 *   `GET` / `DELETE`
 *
@@ -1347,7 +1601,7 @@ function createStdioServer(mcp, options) {
 * import { createMCPServer, createToolManager } from '@src/core'
 * import { createMCPRoutes, createMCPSession } from '@src/server'
 *
-* const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
+* const mcp = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools: createToolManager() })
 * router.use(createMCPSession({ ttl: 60_000 })) // stateful: mint + validate + resumable GET / DELETE
 * router.add(createMCPRoutes(mcp)) // the route stays session-agnostic
 * ```
@@ -1357,9 +1611,27 @@ function createMCPSession(options) {
 	const capacity = options?.capacity;
 	const ttl = options?.ttl;
 	const clock = options?.clock ?? Date.now;
+	const origin = options?.origin;
 	const store = /* @__PURE__ */ new Map();
 	return async (request, context, next) => {
 		if (context.url.pathname !== path) return next();
+		if (!allowsOrigin(request, origin)) return new Response(null, { status: 403 });
+		let parsed;
+		let text;
+		if (context.method === "POST") {
+			try {
+				text = await request.text();
+				parsed = (0, _src_core.parseJSONRPCMessage)(JSON.parse(text));
+			} catch {
+				parsed = void 0;
+			}
+			if (text !== void 0 && parsed !== void 0 && (0, _src_core.isModernRequest)(parsed)) return next(new Request(context.url, {
+				method: "POST",
+				headers: request.headers,
+				body: text,
+				signal: request.signal
+			}));
+		}
 		if (ttl !== void 0) {
 			const cutoff = clock() - ttl;
 			for (const [id, entry] of store) if (entry.touched <= cutoff) store.delete(id);
@@ -1376,7 +1648,8 @@ function createMCPSession(options) {
 			if (current !== void 0) {
 				entry = {
 					session: current.session,
-					touched: clock()
+					touched: clock(),
+					version: current.version
 				};
 				store.set(id, entry);
 			}
@@ -1385,6 +1658,8 @@ function createMCPSession(options) {
 			if (entry === void 0) return rejectUnknownSession();
 			const session = entry.session;
 			const stream = (0, _orkestrel_server.openStream)();
+			const disconnect = new HTTPDisconnect(request.signal, options?.keepalive);
+			stream.response.headers.set(SSE_BUFFERING_HEADER, "no");
 			stream.comment("open");
 			const lastEventId = readLastEventId(request);
 			if (lastEventId !== void 0) for (const e of session.replay(lastEventId)) stream.write({
@@ -1392,56 +1667,71 @@ function createMCPSession(options) {
 				data: JSON.stringify(e.message)
 			});
 			session.attach(stream);
-			if (request.signal.aborted) session.detach(stream);
-			else request.signal.addEventListener("abort", () => session.detach(stream), { once: true });
-			return stream.response;
+			if (disconnect.signal.aborted) session.detach(stream);
+			else disconnect.signal.addEventListener("abort", () => session.detach(stream), { once: true });
+			return disconnect.bridge(stream);
 		}
-		const text = await request.text();
-		if (entry === void 0) {
-			let parsed;
-			try {
-				parsed = (0, _src_core.parseJSONRPCMessage)(JSON.parse(text));
-			} catch {
-				parsed = void 0;
+		if (context.method !== "POST" || text === void 0) return next();
+		let created;
+		if (entry === void 0) if (parsed !== void 0 && (0, _src_core.isInitializeRequest)(parsed)) {
+			created = {
+				session: new MCPSession(crypto.randomUUID(), capacity !== void 0 ? { capacity } : {}),
+				touched: clock(),
+				version: inferLegacyVersion(parsed)
+			};
+			entry = created;
+		} else return rejectUnknownSession();
+		if (!Reflect.set(context.state, "session", entry.session)) throw new Error("MCP session state is not writable");
+		const headers = new Headers(request.headers);
+		if (parsed === void 0 || !(0, _src_core.isInitializeRequest)(parsed)) {
+			const protocol = headers.get(MCP_PROTOCOL_VERSION_HEADER);
+			if (protocol === null) headers.set(MCP_PROTOCOL_VERSION_HEADER, entry.version);
+			else if (protocol !== entry.version) {
+				const requestId = parsed !== void 0 && "method" in parsed ? parsed.id ?? null : null;
+				return Response.json((0, _src_core.buildJSONRPCError)(requestId, _src_core.MCP_HEADER_MISMATCH, "MCP protocol version does not match the active session"), { status: 400 });
 			}
-			if (parsed !== void 0 && (0, _src_core.isInitializeRequest)(parsed)) {
-				const session = new MCPSession(crypto.randomUUID(), capacity !== void 0 ? { capacity } : {});
-				entry = {
-					session,
-					touched: clock()
-				};
-				store.set(session.id, entry);
-			} else return rejectUnknownSession();
 		}
-		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,
-			body: text
+			headers,
+			body: text,
+			signal: request.signal
 		}));
+		if (created !== void 0) {
+			if (!response.ok) return response;
+			store.set(created.session.id, created);
+		}
 		response.headers.set(MCP_SESSION_HEADER, entry.session.id);
 		return response;
 	};
 }
 //#endregion
+exports.DEFAULT_MCP_KEEPALIVE_INTERVAL = DEFAULT_MCP_KEEPALIVE_INTERVAL;
 exports.DEFAULT_MCP_PATH = DEFAULT_MCP_PATH;
 exports.DEFAULT_MCP_SESSION_CAPACITY = DEFAULT_MCP_SESSION_CAPACITY;
 exports.DEFAULT_MCP_SESSION_TTL = DEFAULT_MCP_SESSION_TTL;
 exports.HTTPClientTransport = HTTPClientTransport;
 exports.MCPSession = MCPSession;
+exports.MCP_METHOD_HEADER = MCP_METHOD_HEADER;
+exports.MCP_NAME_HEADER = MCP_NAME_HEADER;
 exports.MCP_PROTOCOL_VERSION_HEADER = MCP_PROTOCOL_VERSION_HEADER;
 exports.MCP_SESSION_HEADER = MCP_SESSION_HEADER;
 exports.MCP_WEBSOCKET_SUBPROTOCOL = MCP_WEBSOCKET_SUBPROTOCOL;
+exports.SSE_BUFFERING_DISABLED = SSE_BUFFERING_DISABLED;
+exports.SSE_BUFFERING_HEADER = SSE_BUFFERING_HEADER;
+exports.SSE_KEEPALIVE_COMMENT = SSE_KEEPALIVE_COMMENT;
 exports.StdioClientTransport = StdioClientTransport;
 exports.StdioServerTransport = StdioServerTransport;
 exports.WebSocketClientTransport = WebSocketClientTransport;
 exports.WebSocketServerTransport = WebSocketServerTransport;
 exports.acceptsEventStream = acceptsEventStream;
+exports.allowsOrigin = allowsOrigin;
 exports.bridgeMessageTransport = bridgeMessageTransport;
 exports.createHTTPClientTransport = createHTTPClientTransport;
 exports.createMCPPostHandler = createMCPPostHandler;
 exports.createMCPRoutes = createMCPRoutes;
 exports.createMCPSession = createMCPSession;
+exports.createReadableStream = createReadableStream;
 exports.createStdioClientTransport = createStdioClientTransport;
 exports.createStdioServer = createStdioServer;
 exports.createWebSocketClientTransport = createWebSocketClientTransport;
@@ -1449,6 +1739,9 @@ exports.createWebSocketServer = createWebSocketServer;
 exports.decodeEvent = decodeEvent;
 exports.dispatchLines = dispatchLines;
 exports.extractLines = extractLines;
+exports.inferLegacyVersion = inferLegacyVersion;
+exports.inferStatus = inferStatus;
+exports.matchesModernHeaders = matchesModernHeaders;
 exports.readEventStream = readEventStream;
 exports.readLastEventId = readLastEventId;
 exports.readSessionHeader = readSessionHeader;