@orkestrel/mcp 0.0.4 → 0.0.6

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

@@ -1,12 +1,13 @@
 import { ClientTransportEventMap } from '../core/index.ts';
 import { ClientTransportEventMap as ClientTransportEventMap_2 } from '../../core/index.ts';
-import { ClientTransportInterface } from '../../core/index.ts';
-import { ClientTransportInterface as ClientTransportInterface_2 } from '../core/index.ts';
+import { ClientTransportInterface } from '../core/index.ts';
+import { ClientTransportInterface as ClientTransportInterface_2 } from '../../core/index.ts';
 import { EmitterInterface } from '@orkestrel/emitter';
 import { IncomingMessage } from 'node:http';
 import { JSONRPCMessage } from '../core/index.ts';
 import { JSONRPCMessage as JSONRPCMessage_2 } from '../../core/index.ts';
 import { MCPServerInterface } from '../core/index.ts';
+import { MCPTransportInterface } from '../core/index.ts';
 import { MiddlewareHandler } from '@orkestrel/server';
 import { NodeWebSocketInterface } from '@orkestrel/websocket';
 import { RouteInput } from '@orkestrel/router';
@@ -28,6 +29,49 @@ import { UpgradeHandler } from '@orkestrel/server';
  */
 export declare function acceptsEventStream(request: Request): boolean;
 
+/**
+ * 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))
+ * ```
+ */
+export declare function bridgeMessageTransport(transport: ClientTransportInterface): MCPTransportInterface;
+
 /**
  * Create the HTTP CLIENT transport for an {@link import('@src/core').MCPClientInterface}
  * — a {@link ClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
@@ -41,8 +85,10 @@ export declare function acceptsEventStream(request: Request): boolean;
  * 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`
@@ -61,7 +107,35 @@ export declare function acceptsEventStream(request: Request): boolean;
  * const tools = await client.tools()
  * ```
  */
-export declare function createHTTPClientTransport(options: HTTPClientTransportOptions): ClientTransportInterface_2;
+export declare function createHTTPClientTransport(options: HTTPClientTransportOptions): ClientTransportInterface;
+
+/**
+ * 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}',
+ * }))
+ * ```
+ */
+export declare function createMCPPostHandler(mcp: MCPServerInterface, streaming: boolean): (request: Request) => Promise<Response>;
 
 /**
  * Create the MCP Streamable-HTTP transport routes — mounts a transport-agnostic
@@ -78,6 +152,9 @@ export declare function createHTTPClientTransport(options: HTTPClientTransportOp
  * - 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).
@@ -202,7 +279,7 @@ export declare function createMCPSession<TState extends MCPSessionState>(options
  * const tools = await client.tools()
  * ```
  */
-export declare function createStdioClientTransport(options: StdioClientTransportOptions): ClientTransportInterface_2;
+export declare function createStdioClientTransport(options: StdioClientTransportOptions): ClientTransportInterface;
 
 /**
  * Create the MCP stdio transport INGRESS — pumps a transport-agnostic {@link
@@ -212,12 +289,13 @@ export declare function createStdioClientTransport(options: StdioClientTransport
  * @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
@@ -270,7 +348,7 @@ export declare function createStdioServer(mcp: MCPServerInterface, options?: Std
  * const tools = await client.tools()
  * ```
  */
-export declare function createWebSocketClientTransport(options: WebSocketClientTransportOptions): ClientTransportInterface_2;
+export declare function createWebSocketClientTransport(options: WebSocketClientTransportOptions): ClientTransportInterface;
 
 /**
  * Create the MCP WebSocket transport INGRESS — an {@link UpgradeHandler} that exposes a
@@ -290,12 +368,13 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
  * - **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
@@ -422,7 +501,7 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
  *
  * @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
@@ -434,13 +513,18 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
  *   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`.
@@ -454,13 +538,13 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
  * await client.connect()
  * ```
  */
-export declare class HTTPClientTransport implements ClientTransportInterface {
+export declare class HTTPClientTransport implements ClientTransportInterface_2 {
     #private;
     constructor(options: HTTPClientTransportOptions);
     get emitter(): EmitterInterface<ClientTransportEventMap_2>;
     get session(): string | undefined;
     start(): Promise<void>;
-    send(message: JSONRPCMessage_2 | readonly JSONRPCMessage_2[]): Promise<void>;
+    send(message: JSONRPCMessage_2): Promise<void>;
     close(): Promise<void>;
 }
 
@@ -528,10 +612,13 @@ export declare interface LineExtraction {
 }
 
 /**
- * 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.
  */
 export declare const MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
 
@@ -629,12 +716,12 @@ export declare class MCPSession implements MCPSessionInterface {
  *
  * @remarks
  * - `session` — the live {@link MCPSession} entity the store keys by session id.
- * - `touched` — the epoch-ms instant of the last access; mutated (not replaced) on every
+ * - `touched` — the epoch-ms instant of the last access; the entry is replaced on every
  *   resolved request so the middleware's lazy sweep can evict an idle entry past `ttl`.
  */
 export declare interface MCPSessionEntry {
     readonly session: MCPSession;
-    touched: number;
+    readonly touched: number;
 }
 
 /**
@@ -709,7 +796,7 @@ export declare interface MCPSessionOptions {
  * before calling `next`).
  */
 export declare interface MCPSessionState {
-    session?: MCPSessionInterface;
+    readonly session?: MCPSessionInterface;
 }
 
 /**
@@ -800,8 +887,8 @@ export declare function rejectUnknownSession(): Response;
  *   {@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
@@ -814,13 +901,13 @@ export declare function rejectUnknownSession(): Response;
  * await client.connect() // start() spawns the child, then the MCP initialize runs over stdio
  * ```
  */
-export declare class StdioClientTransport implements ClientTransportInterface {
+export declare class StdioClientTransport implements ClientTransportInterface_2 {
     #private;
     constructor(options: StdioClientTransportOptions);
     get emitter(): EmitterInterface<ClientTransportEventMap_2>;
     get session(): string | undefined;
     start(): Promise<void>;
-    send(message: JSONRPCMessage_2 | readonly JSONRPCMessage_2[]): Promise<void>;
+    send(message: JSONRPCMessage_2): Promise<void>;
     close(): Promise<void>;
 }
 
@@ -877,8 +964,8 @@ export declare interface StdioServerOptions {
  *   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.
@@ -886,13 +973,13 @@ export declare interface StdioServerOptions {
  *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
  *   fault), distinct from the emitter's own listener-error channel.
  */
-export declare class StdioServerTransport implements ClientTransportInterface {
+export declare class StdioServerTransport implements ClientTransportInterface_2 {
     #private;
     constructor(input: NodeJS.ReadableStream, output: NodeJS.WritableStream);
     get emitter(): EmitterInterface<ClientTransportEventMap_2>;
     get session(): string | undefined;
     start(): Promise<void>;
-    send(message: JSONRPCMessage_2 | readonly JSONRPCMessage_2[]): Promise<void>;
+    send(message: JSONRPCMessage_2): Promise<void>;
     close(): Promise<void>;
 }
 
@@ -933,7 +1020,7 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
  *   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`
@@ -949,13 +1036,13 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
  * await client.connect() // start() handshakes, then the MCP initialize runs over WS frames
  * ```
  */
-export declare class WebSocketClientTransport implements ClientTransportInterface {
+export declare class WebSocketClientTransport implements ClientTransportInterface_2 {
     #private;
     constructor(options: WebSocketClientTransportOptions);
     get emitter(): EmitterInterface<ClientTransportEventMap_2>;
     get session(): string | undefined;
     start(): Promise<void>;
-    send(message: JSONRPCMessage_2 | readonly JSONRPCMessage_2[]): Promise<void>;
+    send(message: JSONRPCMessage_2): Promise<void>;
     close(): Promise<void>;
 }
 
@@ -1021,8 +1108,8 @@ export declare interface WebSocketServerOptions {
  *   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
@@ -1031,13 +1118,13 @@ export declare interface WebSocketServerOptions {
  *   isolates a listener throw (a buggy observer never corrupts the bridge). `error` is a
  *   DOMAIN event (a transport-level fault), distinct from the emitter's listener-error channel.
  */
-export declare class WebSocketServerTransport implements ClientTransportInterface {
+export declare class WebSocketServerTransport implements ClientTransportInterface_2 {
     #private;
     constructor(socket: NodeWebSocketInterface);
     get emitter(): EmitterInterface<ClientTransportEventMap_2>;
     get session(): string | undefined;
     start(): Promise<void>;
-    send(message: JSONRPCMessage_2 | readonly JSONRPCMessage_2[]): Promise<void>;
+    send(message: JSONRPCMessage_2): Promise<void>;
     close(): Promise<void>;
 }