@orkestrel/mcp 0.0.11 → 0.0.12

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

@@ -677,6 +677,27 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
     readonly path?: string;
 }
 
+/**
+ * Infer 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.
+ *
+ * @param request - The HTTP request carrying the headers
+ * @param reference - The parsed request body, or the active legacy session version
+ * @returns The first header issue, or `undefined` when the applicable headers agree
+ *
+ * @example
+ * ```ts
+ * const issue = inferHeaderIssue(request, rpcRequest)
+ * issue?.header // 'Mcp-Method' when that field is absent or mismatched
+ * ```
+ */
+export declare function inferHeaderIssue(request: Request, reference: JSONRPCRequest | MCPVersion): MCPHeaderIssue | undefined;
+
 /**
  * Infer the legacy revision an `initialize` request negotiates.
  *
@@ -718,21 +739,6 @@ export declare interface LineExtraction {
     readonly remainder: string;
 }
 
-/**
- * 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
- */
-export declare function matchesModernHeaders(request: Request, message: JSONRPCRequest): boolean;
-
 /** The modern Streamable-HTTP request header carrying the JSON-RPC method name. */
 export declare const MCP_METHOD_HEADER = "mcp-method";
 
@@ -788,6 +794,21 @@ export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
  */
 export declare type MCPCallerHandler<TState = unknown> = (request: Request, context: RouteContext<string, TState> | undefined) => unknown;
 
+/**
+ * One required MCP HTTP header that is absent or disagrees with its server-derived value.
+ *
+ * @remarks
+ * - `header` — the canonical HTTP field name safe to show to an integrator.
+ * - `reason` — whether the field is absent or carries a mismatched value.
+ * - `message` — the refusal message naming the expected body, session, or server value without
+ *   echoing the client-supplied header value.
+ */
+export declare interface MCPHeaderIssue {
+    readonly header: 'MCP-Protocol-Version' | 'Mcp-Method' | 'Mcp-Name';
+    readonly reason: 'missing' | 'mismatched';
+    readonly message: string;
+}
+
 /**
  * Shared SSE keepalive options for held-open HTTP responses.
  *

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

@@ -677,6 +677,27 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
     readonly path?: string;
 }
 
+/**
+ * Infer 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.
+ *
+ * @param request - The HTTP request carrying the headers
+ * @param reference - The parsed request body, or the active legacy session version
+ * @returns The first header issue, or `undefined` when the applicable headers agree
+ *
+ * @example
+ * ```ts
+ * const issue = inferHeaderIssue(request, rpcRequest)
+ * issue?.header // 'Mcp-Method' when that field is absent or mismatched
+ * ```
+ */
+export declare function inferHeaderIssue(request: Request, reference: JSONRPCRequest | MCPVersion): MCPHeaderIssue | undefined;
+
 /**
  * Infer the legacy revision an `initialize` request negotiates.
  *
@@ -718,21 +739,6 @@ export declare interface LineExtraction {
     readonly remainder: string;
 }
 
-/**
- * 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
- */
-export declare function matchesModernHeaders(request: Request, message: JSONRPCRequest): boolean;
-
 /** The modern Streamable-HTTP request header carrying the JSON-RPC method name. */
 export declare const MCP_METHOD_HEADER = "mcp-method";
 
@@ -788,6 +794,21 @@ export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
  */
 export declare type MCPCallerHandler<TState = unknown> = (request: Request, context: RouteContext<string, TState> | undefined) => unknown;
 
+/**
+ * One required MCP HTTP header that is absent or disagrees with its server-derived value.
+ *
+ * @remarks
+ * - `header` — the canonical HTTP field name safe to show to an integrator.
+ * - `reason` — whether the field is absent or carries a mismatched value.
+ * - `message` — the refusal message naming the expected body, session, or server value without
+ *   echoing the client-supplied header value.
+ */
+export declare interface MCPHeaderIssue {
+    readonly header: 'MCP-Protocol-Version' | 'Mcp-Method' | 'Mcp-Name';
+    readonly reason: 'missing' | 'mismatched';
+    readonly message: string;
+}
+
 /**
  * Shared SSE keepalive options for held-open HTTP responses.
  *

package/dist/src/server/index.js

@@ -144,27 +144,6 @@ function allowsOrigin(request, options) {
 	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 (!isModernRequest(message)) return false;
-	const version = (isRecord(message.params?.["_meta"]) ? message.params["_meta"] : void 0)?.[MCP_META_VERSION];
-	if (!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 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.
 *
@@ -418,6 +397,87 @@ function bridgeMessageTransport(transport) {
 //#endregion
 //#region src/server/inferers.ts
 /**
+* Infer 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.
+*
+* @param request - The HTTP request carrying the headers
+* @param reference - The parsed request body, or the active legacy session version
+* @returns The first header issue, or `undefined` when the applicable headers agree
+*
+* @example
+* ```ts
+* const issue = inferHeaderIssue(request, rpcRequest)
+* issue?.header // 'Mcp-Method' when that field is absent or mismatched
+* ```
+*/
+function inferHeaderIssue(request, reference) {
+	const protocol = request.headers.get(MCP_PROTOCOL_VERSION_HEADER);
+	if (isString(reference)) {
+		if (protocol === null) return {
+			header: "MCP-Protocol-Version",
+			reason: "missing",
+			message: `Required MCP-Protocol-Version header is missing; the active session uses '${reference}'.`
+		};
+		if (protocol !== reference) return {
+			header: "MCP-Protocol-Version",
+			reason: "mismatched",
+			message: `MCP-Protocol-Version header does not match the active session version '${reference}'.`
+		};
+		return;
+	}
+	if (!isModernRequest(reference)) {
+		if (isInitializeRequest(reference) || protocol !== null) return void 0;
+		return {
+			header: "MCP-Protocol-Version",
+			reason: "missing",
+			message: `Required MCP-Protocol-Version header is missing; this server offers '${MCP_PROTOCOL_VERSION}'.`
+		};
+	}
+	const message = reference;
+	const version = (isRecord(message.params?.["_meta"]) ? message.params["_meta"] : void 0)?.[MCP_META_VERSION];
+	if (!isString(version)) return void 0;
+	if (protocol === null) return {
+		header: "MCP-Protocol-Version",
+		reason: "missing",
+		message: `Required MCP-Protocol-Version header is missing; the request body version is '${version}'.`
+	};
+	if (protocol !== version) return {
+		header: "MCP-Protocol-Version",
+		reason: "mismatched",
+		message: `MCP-Protocol-Version header does not match the request body version '${version}'.`
+	};
+	const method = request.headers.get(MCP_METHOD_HEADER);
+	if (method === null) return {
+		header: "Mcp-Method",
+		reason: "missing",
+		message: `Required Mcp-Method header is missing; the request body method is '${message.method}'.`
+	};
+	if (method !== message.method) return {
+		header: "Mcp-Method",
+		reason: "mismatched",
+		message: `Mcp-Method header does not match the request body method '${message.method}'.`
+	};
+	if (message.method !== "tools/call") return void 0;
+	const name = message.params?.["name"];
+	if (!isString(name)) return void 0;
+	const 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}'.`
+	};
+	if (header !== name) return {
+		header: "Mcp-Name",
+		reason: "mismatched",
+		message: `Mcp-Name header does not match the request body tool name '${name}'.`
+	};
+}
+/**
 * Infer the legacy revision an `initialize` request negotiates.
 *
 * @remarks
@@ -589,9 +649,10 @@ function createMCPPostHandler(mcp, options) {
 		const protocol = request.headers.get(MCP_PROTOCOL_VERSION_HEADER);
 		if (era === "modern") {
 			if (parseRequestContext(rpcRequest) === void 0) return Response.json(buildJSONRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: malformed modern request metadata"), { status: 400 });
-			if (!matchesModernHeaders(request, rpcRequest)) return Response.json(buildJSONRPCError(id, MCP_HEADER_MISMATCH, "MCP request headers do not match the request body"), { status: 400 });
-		} else {
-			if (protocol === null && !isInitializeRequest(rpcRequest)) return Response.json(buildJSONRPCError(id, MCP_HEADER_MISMATCH, "MCP request headers do not match the request body"), { status: 400 });
+		}
+		const issue = inferHeaderIssue(request, rpcRequest);
+		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,
 				requested: protocol
@@ -1690,11 +1751,11 @@ function createMCPSession(options) {
 		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 || !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 issue = inferHeaderIssue(request, entry.version);
+			if (issue?.reason === "missing") headers.set(MCP_PROTOCOL_VERSION_HEADER, entry.version);
+			else if (issue !== void 0) {
 				const requestId = parsed !== void 0 && "method" in parsed ? parsed.id ?? null : null;
-				return Response.json(buildJSONRPCError(requestId, MCP_HEADER_MISMATCH, "MCP protocol version does not match the active session"), { status: 400 });
+				return Response.json(buildJSONRPCError(requestId, MCP_HEADER_MISMATCH, issue.message), { status: 400 });
 			}
 		}
 		const response = await next(new Request(context.url, {
@@ -1712,6 +1773,6 @@ function createMCPSession(options) {
 	};
 }
 //#endregion
-export { DEFAULT_MCP_KEEPALIVE_INTERVAL, DEFAULT_MCP_PATH, DEFAULT_MCP_SESSION_CAPACITY, DEFAULT_MCP_SESSION_TTL, HTTPClientTransport, 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, createMCPPostHandler, createMCPRoutes, createMCPSession, createReadableStream, createStdioClientTransport, createStdioServer, createWebSocketClientTransport, createWebSocketServer, decodeEvent, dispatchLines, extractLines, inferLegacyVersion, inferStatus, matchesModernHeaders, readEventStream, readLastEventId, readSessionHeader, rejectUnknownSession, upgradeRequestPath };
+export { DEFAULT_MCP_KEEPALIVE_INTERVAL, DEFAULT_MCP_PATH, DEFAULT_MCP_SESSION_CAPACITY, DEFAULT_MCP_SESSION_TTL, HTTPClientTransport, 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, createMCPPostHandler, createMCPRoutes, createMCPSession, createReadableStream, createStdioClientTransport, createStdioServer, createWebSocketClientTransport, createWebSocketServer, decodeEvent, dispatchLines, extractLines, inferHeaderIssue, inferLegacyVersion, inferStatus, readEventStream, readLastEventId, readSessionHeader, rejectUnknownSession, upgradeRequestPath };
 
 //# sourceMappingURL=index.js.map