@orkestrel/mcp 0.0.24 → 0.0.25

package/dist/src/server/index.d.cts

@@ -11,6 +11,7 @@ import { MCPClientTransportInterface as MCPClientTransportInterface_2 } from '@o
 import { MCPContinuationInterface } from '@orkestrel/mcp';
 import { MCPDispatcherInterface } from '@orkestrel/mcp';
 import { MCPEra } from '@orkestrel/mcp';
+import { MCPLegacyVersion } from '@orkestrel/mcp';
 import { MCPStreamControllerInterface } from '@orkestrel/mcp';
 import { MCPTransportInterface } from '@orkestrel/mcp';
 import { MCPVersion } from '@orkestrel/mcp';
@@ -108,6 +109,20 @@ export declare function allowsOrigin(request: Request, options?: MCPOriginOption
  */
 export declare function bridgeMessageTransport(transport: MCPClientTransportInterface): MCPTransportInterface;
 
+/**
+ * Builds the error for a non-success HTTP response that carried no JSON-RPC message.
+ *
+ * @param response - The response whose status is reported
+ * @param type - The response's content type, or an empty string when absent
+ * @returns An error naming the HTTP status and unsupported response shape
+ *
+ * @example
+ * ```ts
+ * const error = buildResponseError(new Response('', { status: 500 }), '')
+ * ```
+ */
+export declare function buildResponseError(response: Response, type: string): Error;
+
 /**
  * Creates the HTTP CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
  * — a {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
@@ -160,7 +175,9 @@ export declare function createMCPContinuation(secret: TokenSecret): MCPContinuat
  * 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
+ * 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
  * 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
@@ -648,8 +665,10 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
  *   aborted read surfaces on `error` and the `send` reporting it resolves. `close()` is
  *   idempotent (one `close` event per connected lifetime), and `start()` opens the next one.
  * - **Total at the boundary.** 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`.
+ *   the SSE decoder). A non-message success reply is dropped, never asserted. A non-success
+ *   reply that carries no valid JSON-RPC message rejects `send` with its HTTP status and body
+ *   shape. A valid JSON-RPC error body is emitted at any HTTP status. A `fetch` / decode failure
+ *   on a success response surfaces on the `error` event rather than escaping `send`.
  * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
  *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.
  *
@@ -840,12 +859,18 @@ export declare function inferHeaderIssue(request: Request, reference: JSONRPCInv
  *
  * @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.
+ * request selects the newest supported legacy revision. The read is deliberately the SAME one
+ * {@link import('@orkestrel/mcp').buildInitializeResult} performs — `isMCPLegacyVersion` over
+ * the requested revision — because the session version this pins and the version that result
+ * echoes must be the one value. Routing through `inferVersion` cannot do it: that inferer is
+ * modern-only, so it answers `undefined` for every legacy offer and the session would pin
+ * `2025-11-25` while the handshake echoed `2025-06-18`, which the client's own protocol
+ * header then contradicts.
  *
  * @param request - The legacy initialize invocation
  * @returns The negotiated legacy protocol revision
  */
-export declare function inferLegacyVersion(request: JSONRPCInvocation): MCPVersion;
+export declare function inferLegacyVersion(request: JSONRPCInvocation): MCPLegacyVersion;
 
 /**
  * Infers the HTTP status for one MCP dispatch outcome without changing its JSON-RPC body.
@@ -1314,7 +1339,7 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  * ```ts
  * const transport = new StdioClientTransport({ command: 'node', args: ['./server.js'] })
  * const client = new MCPClient({ transport })
- * await client.connect() // start() spawns the child, then the MCP initialize runs over stdio
+ * await client.connect() // start() spawns the child, then modern discovery runs over stdio
  * ```
  */
 export declare class StdioClientTransport implements StdioClientTransportInterface {

package/dist/src/server/index.d.ts

@@ -11,6 +11,7 @@ import { MCPClientTransportInterface as MCPClientTransportInterface_2 } from '@o
 import { MCPContinuationInterface } from '@orkestrel/mcp';
 import { MCPDispatcherInterface } from '@orkestrel/mcp';
 import { MCPEra } from '@orkestrel/mcp';
+import { MCPLegacyVersion } from '@orkestrel/mcp';
 import { MCPStreamControllerInterface } from '@orkestrel/mcp';
 import { MCPTransportInterface } from '@orkestrel/mcp';
 import { MCPVersion } from '@orkestrel/mcp';
@@ -108,6 +109,20 @@ export declare function allowsOrigin(request: Request, options?: MCPOriginOption
  */
 export declare function bridgeMessageTransport(transport: MCPClientTransportInterface): MCPTransportInterface;
 
+/**
+ * Builds the error for a non-success HTTP response that carried no JSON-RPC message.
+ *
+ * @param response - The response whose status is reported
+ * @param type - The response's content type, or an empty string when absent
+ * @returns An error naming the HTTP status and unsupported response shape
+ *
+ * @example
+ * ```ts
+ * const error = buildResponseError(new Response('', { status: 500 }), '')
+ * ```
+ */
+export declare function buildResponseError(response: Response, type: string): Error;
+
 /**
  * Creates the HTTP CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
  * — a {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
@@ -160,7 +175,9 @@ export declare function createMCPContinuation(secret: TokenSecret): MCPContinuat
  * 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
+ * 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
  * 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
@@ -648,8 +665,10 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
  *   aborted read surfaces on `error` and the `send` reporting it resolves. `close()` is
  *   idempotent (one `close` event per connected lifetime), and `start()` opens the next one.
  * - **Total at the boundary.** 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`.
+ *   the SSE decoder). A non-message success reply is dropped, never asserted. A non-success
+ *   reply that carries no valid JSON-RPC message rejects `send` with its HTTP status and body
+ *   shape. A valid JSON-RPC error body is emitted at any HTTP status. A `fetch` / decode failure
+ *   on a success response surfaces on the `error` event rather than escaping `send`.
  * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
  *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.
  *
@@ -840,12 +859,18 @@ export declare function inferHeaderIssue(request: Request, reference: JSONRPCInv
  *
  * @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.
+ * request selects the newest supported legacy revision. The read is deliberately the SAME one
+ * {@link import('@orkestrel/mcp').buildInitializeResult} performs — `isMCPLegacyVersion` over
+ * the requested revision — because the session version this pins and the version that result
+ * echoes must be the one value. Routing through `inferVersion` cannot do it: that inferer is
+ * modern-only, so it answers `undefined` for every legacy offer and the session would pin
+ * `2025-11-25` while the handshake echoed `2025-06-18`, which the client's own protocol
+ * header then contradicts.
  *
  * @param request - The legacy initialize invocation
  * @returns The negotiated legacy protocol revision
  */
-export declare function inferLegacyVersion(request: JSONRPCInvocation): MCPVersion;
+export declare function inferLegacyVersion(request: JSONRPCInvocation): MCPLegacyVersion;
 
 /**
  * Infers the HTTP status for one MCP dispatch outcome without changing its JSON-RPC body.
@@ -1314,7 +1339,7 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  * ```ts
  * const transport = new StdioClientTransport({ command: 'node', args: ['./server.js'] })
  * const client = new MCPClient({ transport })
- * await client.connect() // start() spawns the child, then the MCP initialize runs over stdio
+ * await client.connect() // start() spawns the child, then modern discovery runs over stdio
  * ```
  */
 export declare class StdioClientTransport implements StdioClientTransportInterface {

package/dist/src/server/index.js

@@ -1,5 +1,5 @@
 import { createSSEParser } from "@orkestrel/sse";
-import { JSONRPC_INVALID_PARAMS, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_PARSE_ERROR, MCP_HEADER_MISMATCH, MCP_META_VERSION, MCP_MISSING_CAPABILITY, MCP_PROTOCOL_VERSION, MCP_UNSUPPORTED_VERSION, SUPPORTED_PROTOCOL_VERSIONS, bindServer, buildJSONRPCError, inferEra, inferRequestVersion, inferVersion, isInitializeRequest, isJSONRPCInvocation, isJSONRPCResponse, isMCPVersion, isModernRequest, parseJSONRPCMessage, parseRequestContext } from "../core/index.js";
+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 { openStream, signToken, verifyToken } from "@orkestrel/server";
 import { Emitter } from "@orkestrel/emitter";
@@ -99,6 +99,24 @@ var DEFAULT_MCP_DELIVERY = 1e4;
 //#endregion
 //#region src/server/helpers.ts
 /**
+* Builds the error for a non-success HTTP response that carried no JSON-RPC message.
+*
+* @param response - The response whose status is reported
+* @param type - The response's content type, or an empty string when absent
+* @returns An error naming the HTTP status and unsupported response shape
+*
+* @example
+* ```ts
+* const error = buildResponseError(new Response('', { status: 500 }), '')
+* ```
+*/
+function buildResponseError(response, type) {
+	if (type.includes("application/json")) return /* @__PURE__ */ new Error(`HTTP ${response.status} response contained an application/json body that was not a JSON-RPC message`);
+	if (type.includes("text/event-stream")) return /* @__PURE__ */ new Error(`HTTP ${response.status} response contained a text/event-stream body without a JSON-RPC message`);
+	const shape = type === "" ? "a body without a content type" : `an unsupported '${type}' body`;
+	return /* @__PURE__ */ new Error(`HTTP ${response.status} response contained ${shape}`);
+}
+/**
 * Creates a readable stream from its pull and cancellation behaviours.
 *
 * @param pull - The behaviour that supplies the stream's next chunk
@@ -546,7 +564,7 @@ function inferHeaderIssue(request, reference) {
 		return {
 			header: "MCP-Protocol-Version",
 			reason: "missing",
-			message: `Required MCP-Protocol-Version header is missing; this server offers '${MCP_PROTOCOL_VERSION}'.`
+			message: `Required MCP-Protocol-Version header is missing; this server offers '${MCP_HANDSHAKE_VERSION}'.`
 		};
 	}
 	const message = reference;
@@ -593,16 +611,20 @@ function inferHeaderIssue(request, reference) {
 *
 * @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.
+* request selects the newest supported legacy revision. The read is deliberately the SAME one
+* {@link import('@orkestrel/mcp').buildInitializeResult} performs — `isMCPLegacyVersion` over
+* the requested revision — because the session version this pins and the version that result
+* echoes must be the one value. Routing through `inferVersion` cannot do it: that inferer is
+* modern-only, so it answers `undefined` for every legacy offer and the session would pin
+* `2025-11-25` while the handshake echoed `2025-06-18`, which the client's own protocol
+* header then contradicts.
 *
 * @param request - The legacy initialize invocation
 * @returns The negotiated legacy protocol revision
 */
 function inferLegacyVersion(request) {
 	const requested = request.params?.["protocolVersion"];
-	const version = inferVersion(isString(requested) ? [requested] : []);
-	if (version !== void 0 && inferEra(version) === "legacy") return version;
-	return MCP_PROTOCOL_VERSION;
+	return isMCPLegacyVersion(requested) ? requested : MCP_HANDSHAKE_VERSION;
 }
 /**
 * Infers the HTTP status for one MCP dispatch outcome without changing its JSON-RPC body.
@@ -765,7 +787,9 @@ var HTTPDisconnect = class {
 * 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
+* 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
 * 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
@@ -820,8 +844,8 @@ function createMCPPostHandler(mcp, options) {
 		const issue = inferHeaderIssue(request, invocation);
 		if (issue !== void 0) return Response.json(buildJSONRPCError(id, MCP_HEADER_MISMATCH, issue.message), { status: 400 });
 		if (era === "legacy") {
-			if (protocol !== null && !isMCPVersion(protocol)) return Response.json(buildJSONRPCError(id, MCP_UNSUPPORTED_VERSION, `Unsupported MCP protocol version '${protocol}'`, {
-				supported: SUPPORTED_PROTOCOL_VERSIONS,
+			if (protocol !== null && !isMCPLegacyVersion(protocol)) return Response.json(buildJSONRPCError(id, MCP_UNSUPPORTED_VERSION, `Unsupported MCP protocol version '${protocol}'`, {
+				supported: SUPPORTED_LEGACY_PROTOCOL_VERSIONS,
 				requested: protocol
 			}), { status: 400 });
 		}
@@ -889,8 +913,10 @@ function createMCPPostHandler(mcp, options) {
 *   aborted read surfaces on `error` and the `send` reporting it resolves. `close()` is
 *   idempotent (one `close` event per connected lifetime), and `start()` opens the next one.
 * - **Total at the boundary.** 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`.
+*   the SSE decoder). A non-message success reply is dropped, never asserted. A non-success
+*   reply that carries no valid JSON-RPC message rejects `send` with its HTTP status and body
+*   shape. A valid JSON-RPC error body is emitted at any HTTP status. A `fetch` / decode failure
+*   on a success response surfaces on the `error` event rather than escaping `send`.
 * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
 *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.
 *
@@ -985,18 +1011,20 @@ var HTTPClientTransport = class {
 	async #deliver(response) {
 		if (response.status === 202) return;
 		const type = response.headers.get("content-type") ?? "";
+		let messages = [];
+		let failure;
 		try {
-			if (type.includes("text/event-stream")) {
-				for (const message of await readEventStream(response)) this.#capture(message);
-				return;
-			}
-			if (type.includes("application/json")) {
+			if (type.includes("text/event-stream")) messages = await readEventStream(response);
+			else if (type.includes("application/json")) {
 				const message = parseJSONRPCMessage(await response.json());
-				if (message !== void 0) this.#capture(message);
+				if (message !== void 0) messages = [message];
 			}
 		} catch (error) {
-			this.#emitter.emit("error", error);
+			failure = { error };
 		}
+		for (const message of messages) this.#capture(message);
+		if (!response.ok && messages.length === 0) throw buildResponseError(response, type);
+		if (failure !== void 0) this.#emitter.emit("error", failure.error);
 	}
 	#capture(message) {
 		if (isJSONRPCResponse(message) && isRecord(message.result) && isMCPVersion(message.result["protocolVersion"])) this.#protocol = message.result["protocolVersion"];
@@ -1467,7 +1495,7 @@ var WebSocketClientTransport = class {
 * ```ts
 * const transport = new StdioClientTransport({ command: 'node', args: ['./server.js'] })
 * const client = new MCPClient({ transport })
-* await client.connect() // start() spawns the child, then the MCP initialize runs over stdio
+* await client.connect() // start() spawns the child, then modern discovery runs over stdio
 * ```
 */
 var StdioClientTransport = class {
@@ -2204,6 +2232,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, 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, inferLegacyVersion, inferStatus, readEventStream, readLastEventId, readSessionHeader, rejectUnknownSession, sendEventStream, upgradeRequestPath, writeLine };
 
 //# sourceMappingURL=index.js.map