@orkestrel/mcp 0.0.1

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

@@ -0,0 +1,1044 @@
+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 { 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 { MiddlewareHandler } from '@orkestrel/server';
+import { NodeWebSocketInterface } from '@orkestrel/websocket';
+import { RouteInput } from '@orkestrel/router';
+import { StreamInterface } from '@orkestrel/server';
+import { UpgradeHandler } from '@orkestrel/server/server';
+
+/**
+ * Whether the request's `Accept` header opts into a Server-Sent-Events response.
+ *
+ * @remarks
+ * Reads the fetch-standard `Request.headers.get('accept')` and returns `true` when it
+ * contains `text/event-stream` (case-insensitive). The MCP `POST` handler uses it
+ * (together with the `streaming` option) to pick the Streamable-HTTP SSE response
+ * framing over a plain JSON body; the JSON-RPC envelope is identical either way. Total
+ * — an absent / unmatched header returns `false`.
+ *
+ * @param request - The fetch-standard `Request`
+ * @returns `true` when the client `Accept`s `text/event-stream`, else `false`
+ */
+export declare function acceptsEventStream(request: Request): boolean;
+
+/**
+ * Create the HTTP CLIENT transport for an {@link import('@src/core').MCPClientInterface}
+ * — a {@link ClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
+ * over `fetch`. The egress mirror of {@link createMCPRoutes}.
+ *
+ * @remarks
+ * Hand it to `createMCPClient({ transport })`: each JSON-RPC message the client sends is
+ * `POST`ed to `options.url` with `content-type: application/json` and an `Accept` of
+ * both `application/json` and `text/event-stream` (the server answers with EITHER — a
+ * plain JSON envelope or a Streamable-HTTP SSE `data:` event, decoded via `@orkestrel/sse`),
+ * 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).
+ *
+ * @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged onto
+ *   every request, optional `fetch` (default `globalThis.fetch`), and optional `timeout`
+ *   (ms, applied via `AbortSignal.timeout`); see {@link HTTPClientTransportOptions}
+ * @returns A working {@link ClientTransportInterface} over `fetch`
+ *
+ * @example
+ * ```ts
+ * import { createMCPClient } from '@src/core'
+ * import { createHTTPClientTransport } from '@src/server'
+ *
+ * const client = createMCPClient({
+ * 	transport: createHTTPClientTransport({ url: 'http://localhost:3000/mcp' }),
+ * })
+ * await client.connect()
+ * const tools = await client.tools()
+ * ```
+ */
+export declare function createHTTPClientTransport(options: HTTPClientTransportOptions): ClientTransportInterface_2;
+
+/**
+ * Create the MCP Streamable-HTTP transport routes — mounts a transport-agnostic
+ * {@link MCPServerInterface} (the `@src/core` dispatch core) on the fetch-standard router
+ * spine, pumping each `POST` body through `mcp.dispatch`. Returns the {@link RouteInput}s to
+ * hand to `router.add(...)`.
+ *
+ * @remarks
+ * A SINGLE `POST {path}` route — `createMCPRoutes` is STATELESS. The handler reads its own
+ * request body (its own JSON parse try/catch), so it works with or without a session
+ * middleware mounted in front. It draws a sharp line between TRANSPORT-level and
+ * DISPATCH-level outcomes:
+ *
+ * - 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 **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).
+ * - A **notification** (a request with no `id`, which `dispatch` resolves to
+ *   `undefined`) is a `202 Accepted` with no body.
+ *
+ * When `streaming` is enabled (the default) and the client `Accept`s `text/event-stream`,
+ * the `200` reply is framed as a Streamable-HTTP SSE response (one `data:` event carrying
+ * the JSON-RPC envelope, then the stream ends) via `@orkestrel/server`'s generic
+ * {@link import('@orkestrel/server').openStream} seam; otherwise it is a plain JSON body.
+ *
+ * **Sessions are a SEPARATE, plug-and-play middleware.** `createMCPRoutes` mints / reads no
+ * session id. To make the transport STATEFUL, mount {@link
+ * import('./middlewares.js').createMCPSession} IN FRONT — it owns the same `path`, mints +
+ * 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.
+ *
+ * @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}
+ * @returns The {@link RouteInput}s to register with the router
+ *
+ * @example
+ * ```ts
+ * import { createMCPServer, createToolManager } from '@src/core'
+ * import { createMCPRoutes } from '@src/server'
+ *
+ * const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
+ * const routes = createMCPRoutes(mcp) // POST /mcp dispatches JSON-RPC (JSON or SSE per Accept)
+ * ```
+ */
+export declare function createMCPRoutes<TState = unknown>(mcp: MCPServerInterface, options?: HTTPTransportOptions): readonly RouteInput<string, TState>[];
+
+/**
+ * Create the native MCP session {@link MiddlewareHandler} — the plug-and-play stateful layer
+ * that fronts a session-agnostic {@link import('./factories.js').createMCPRoutes}. Compose it
+ * via `router.use(createMCPSession())` (or the equivalent middleware seam), mirroring any
+ * other closure-scoped stateful middleware. Has NO dependency on `@orkestrel/middleware` — the
+ * session store, mint-on-`initialize`, and resumable stream are all native to this package.
+ *
+ * @remarks
+ * Owns a closure `Map<string, MCPSessionEntry>` keyed by session id, and a single request
+ * `path` (default {@link DEFAULT_MCP_PATH}); a request to any other path passes straight
+ * through (`next()`).
+ *
+ * - **`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
+ *   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}.
+ * - **`GET {path}`.** Resolves the session the same way (no mint — only `initialize` mints);
+ *   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.
+ * - **`DELETE {path}`.** Resolves the session; a valid id deletes it from the store and answers
+ *   `204`; an invalid / unknown id is the same `404`.
+ *
+ * It is MECHANISM, not policy, and ADDITIVE: omit it entirely for the stateless default
+ * ({@link import('./factories.js').createMCPRoutes}'s only behavior). The `path` MUST match the
+ * `createMCPRoutes` `path` it fronts. The WebSocket transport is inherently one session per
+ * connection (the socket IS the session), so this middleware does not apply to it.
+ *
+ * @typeParam TState - The consumer's `TState`, which MUST extend {@link MCPSessionState} so
+ *   the resolved session can be threaded through `context.state.session`
+ * @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}
+ * @returns A {@link MiddlewareHandler} that mints / validates sessions + serves the resumable
+ *   `GET` / `DELETE`
+ *
+ * @example
+ * ```ts
+ * import { createMCPServer, createToolManager } from '@src/core'
+ * import { createMCPRoutes, createMCPSession } from '@src/server'
+ *
+ * const mcp = createMCPServer({ 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
+ * ```
+ */
+export declare function createMCPSession<TState extends MCPSessionState>(options?: MCPSessionOptions): MiddlewareHandler<TState>;
+
+/**
+ * Create the stdio CLIENT transport for an {@link import('@src/core').MCPClientInterface}
+ * — a {@link ClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
+ * over newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
+ * createHTTPClientTransport} and {@link createWebSocketClientTransport}.
+ *
+ * @remarks
+ * Hand it to `createMCPClient({ transport })`: `start()` (run by `client.connect()`)
+ * spawns `options.command` with `options.args` and `options.env`, piping its
+ * `stdin`/`stdout` for the JSON-RPC channel (its `stderr` inherits the parent's for
+ * diagnostics). Each JSON-RPC message the client `send`s is written as one
+ * newline-terminated line to the child's `stdin`; each decoded reply line from the
+ * child's `stdout` is surfaced on the transport's `message` event for the client's
+ * id correlation.
+ *
+ * @param options - `command` (the executable to spawn; REQUIRED), optional `args`,
+ *   and optional `env`; see {@link StdioClientTransportOptions}
+ * @returns A working {@link ClientTransportInterface} over a child process's stdio
+ *
+ * @example
+ * ```ts
+ * import { createMCPClient } from '@src/core'
+ * import { createStdioClientTransport } from '@src/server'
+ *
+ * const client = createMCPClient({
+ * 	transport: createStdioClientTransport({ command: 'node', args: ['./server.js'] }),
+ * })
+ * await client.connect()
+ * const tools = await client.tools()
+ * ```
+ */
+export declare function createStdioClientTransport(options: StdioClientTransportOptions): ClientTransportInterface_2;
+
+/**
+ * Create the MCP stdio transport INGRESS — pumps a transport-agnostic {@link
+ * MCPServerInterface} over newline-delimited JSON-RPC on `stdin`/`stdout` (or an
+ * injected stream pair), the stdio mirror of {@link createWebSocketServer}.
+ *
+ * @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.
+ *
+ * @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over stdio
+ * @param options - Optional injectable `input` / `output` streams; see
+ *   {@link StdioServerOptions}
+ * @returns A `{ start(): void; stop(): void }` handle to arm / tear down the pump
+ *
+ * @example
+ * ```ts
+ * import { createMCPServer, createToolManager } from '@src/core'
+ * import { createStdioServer } from '@src/server'
+ *
+ * const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
+ * createStdioServer(mcp).start() // an MCP client now connects over this process's stdio
+ * ```
+ */
+export declare function createStdioServer(mcp: MCPServerInterface, options?: StdioServerOptions): {
+    start(): void;
+    stop(): void;
+};
+
+/**
+ * Create the WebSocket CLIENT transport for an {@link import('@src/core').MCPClientInterface}
+ * — a {@link ClientTransportInterface} that drives a REMOTE MCP server over a WebSocket. The
+ * egress mirror of {@link createWebSocketServer} and the WebSocket sibling of {@link
+ * createHTTPClientTransport}.
+ *
+ * @remarks
+ * Hand it to `createMCPClient({ transport })`: `start()` (run by `client.connect()`) performs
+ * the RFC 6455 client handshake against `options.url` (accepting a `ws://` / `wss://` or an
+ * `http://` / `https://` URL — a `ws(s)` scheme is converted to `http(s)` for the underlying
+ * upgrade request), validates the `Sec-WebSocket-Accept` (via `@orkestrel/websocket`'s
+ * `computeWebSocketAccept`), and opens a persistent bidirectional frame channel; each JSON-RPC
+ * message the client `send`s is written as one masked text frame, and each decoded 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.
+ *
+ * @param options - `url` (the remote WebSocket endpoint; REQUIRED) and optional `headers`
+ *   merged onto the upgrade request; see {@link WebSocketClientTransportOptions}
+ * @returns A working {@link ClientTransportInterface} over a WebSocket
+ *
+ * @example
+ * ```ts
+ * import { createMCPClient } from '@src/core'
+ * import { createWebSocketClientTransport } from '@src/server'
+ *
+ * const client = createMCPClient({
+ * 	transport: createWebSocketClientTransport({ url: 'ws://localhost:3000/mcp' }),
+ * })
+ * await client.connect()
+ * const tools = await client.tools()
+ * ```
+ */
+export declare function createWebSocketClientTransport(options: WebSocketClientTransportOptions): ClientTransportInterface_2;
+
+/**
+ * Create the MCP WebSocket transport INGRESS — an {@link UpgradeHandler} that exposes a
+ * transport-agnostic {@link MCPServerInterface} over a WebSocket, the WebSocket mirror of
+ * {@link createMCPRoutes}. Register it on the spine's upgrade seam.
+ *
+ * @remarks
+ * It composes the lean RFC 6455 `@orkestrel/websocket` wrapper over `@orkestrel/server`'s
+ * generic upgrade seam — the spine speaks no WebSocket, this handler does.
+ *
+ * - **Declines (returns `false`)** when the upgrade is not for it, so the spine fans the
+ *   socket to the next handler (or destroys an unclaimed one): the `Upgrade` header is not
+ *   `websocket`, the request path is not `options.path` (default {@link DEFAULT_MCP_PATH},
+ *   `'/mcp'`), the `Sec-WebSocket-Key` is absent, or the `Sec-WebSocket-Version` is not `13`.
+ *   A decline NEVER writes to the socket (it is not yet ours) — the spine owns the unclaimed
+ *   outcome.
+ * - **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.
+ *
+ * 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
+ * upgrade so it never reaches this pump.
+ *
+ * @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over WebSocket
+ * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}) and `subprotocol`
+ *   (default {@link MCP_WEBSOCKET_SUBPROTOCOL}); see {@link WebSocketServerOptions}
+ * @returns An {@link UpgradeHandler} to register with the spine's `upgrade` seam
+ *
+ * @example
+ * ```ts
+ * import { createMCPServer, createToolManager } from '@src/core'
+ * import { createWebSocketServer } from '@src/server'
+ *
+ * const mcp = createMCPServer({ name: 'docs', version: '1.0.0', tools: createToolManager() })
+ * server.upgrade(createWebSocketServer(mcp)) // an MCP client now connects over ws://…/mcp
+ * ```
+ */
+export declare function createWebSocketServer(mcp: MCPServerInterface, options?: WebSocketServerOptions): UpgradeHandler;
+
+/**
+ * Decode one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`
+ * when it is not one — the per-event step {@link readEventStream} folds over.
+ *
+ * @remarks
+ * `JSON.parse`s the `data` (the server serializes the JSON-RPC envelope as the event's
+ * `data`) inside a try/catch and narrows the parsed value with `parseJSONRPCMessage`.
+ * Total (§14): malformed JSON or a non-message value yields `undefined`, never throws.
+ *
+ * @param data - One SSE event's `data` payload
+ * @returns The decoded {@link JSONRPCMessage}, or `undefined`
+ */
+export declare function decodeEvent(data: string): JSONRPCMessage | undefined;
+
+/** The default request path `createMCPRoutes` mounts the transport's `POST` route at. */
+export declare const DEFAULT_MCP_PATH = "/mcp";
+
+/**
+ * The default capacity of a session's FOLDED resumable event log (the per-{@link
+ * import('./MCPSession.js').MCPSession} replay log) — the maximum number of pushed
+ * server→client messages retained for replay before the OLDEST is evicted.
+ *
+ * @remarks
+ * Bounds the replay log's memory: only the most-recent {@link DEFAULT_MCP_SESSION_CAPACITY}
+ * pushes are retained, so a client reconnecting with a `Last-Event-ID` older than that window
+ * replays nothing (its cursor fell off the back). Override per `createMCPSession`'s `capacity`
+ * for a deeper / shallower window.
+ */
+export declare const DEFAULT_MCP_SESSION_CAPACITY = 1024;
+
+/**
+ * The default per-event idle lifetime (ms) of a session's folded resumable event log — an
+ * entry older than this is lazily evicted on the next access (no background timer), bounding
+ * how far back a reconnecting client may replay.
+ *
+ * @remarks
+ * Five minutes — a generous reconnection window for a dropped SSE stream without retaining
+ * stale pushes indefinitely. The session's own idle TTL is the `createMCPSession` `ttl` knob;
+ * this bounds the replay log paired with it.
+ */
+export declare const DEFAULT_MCP_SESSION_TTL = 300000;
+
+/**
+ * Decode and deliver each complete newline-framed line onto a {@link
+ * ClientTransportEventMap} emitter — the shared per-chunk dispatch step both stdio
+ * transports (client and server) run their {@link extractLines} output through.
+ *
+ * @remarks
+ * A blank line is skipped (a stray trailing newline). Every other line is decoded
+ * with {@link decodeEvent} (`JSON.parse` + `parseJSONRPCMessage`, guarded); a
+ * well-formed {@link JSONRPCMessage} emits `message`, a malformed / non-message line
+ * emits `error` (§14 — total, never throws). Pure w.r.t. its own state — the emit is
+ * the caller-owned side effect.
+ *
+ * @param emitter - The transport's {@link EmitterInterface} to emit `message` / `error` onto
+ * @param lines - The complete lines (from {@link extractLines}) to decode and deliver
+ */
+export declare function dispatchLines(emitter: EmitterInterface<ClientTransportEventMap>, lines: readonly string[]): void;
+
+/**
+ * One entry of an {@link MCPSessionInterface}'s folded replay log — a single pushed {@link
+ * JSONRPCMessage} tagged with the monotone event `id` the session assigned and the `timestamp`
+ * it was appended at (for the lazy-TTL replay window).
+ *
+ * @remarks
+ * - `id` — the session-assigned, monotonically-increasing event id (a base36 string), the
+ *   value a resumable client echoes back as its `Last-Event-ID` to replay from here.
+ * - `message` — the server→client {@link JSONRPCMessage} that was pushed.
+ * - `timestamp` — the epoch-ms instant the entry was appended, read by the TTL eviction.
+ *
+ * A plain value record (no behavior, §4.5) — the unit {@link MCPSessionInterface.replay}
+ * returns.
+ */
+export declare interface EventStoreEntry {
+    readonly id: string;
+    readonly message: JSONRPCMessage;
+    readonly timestamp: number;
+}
+
+/**
+ * Fold one more chunk of raw stdio bytes into a newline-framed buffer — the shared
+ * line-framing step both stdio transports (client and server) read their inbound
+ * newline-delimited JSON-RPC messages through.
+ *
+ * @remarks
+ * Concatenates `buffer` (the carried-forward partial line from the previous call)
+ * with `chunk`, splits on `'\n'`, and returns every COMPLETE line (a `'\r'` trailing
+ * a line, from a CRLF-framed peer, is trimmed) plus the final, possibly-empty
+ * fragment as the new `remainder` — the caller threads it back in as the next call's
+ * `buffer`. A chunk containing no `'\n'` yields no lines and the whole (buffer +
+ * chunk) as `remainder`. Pure — no I/O, no instance state.
+ *
+ * @param buffer - The partial line carried forward from the previous chunk (`''` initially)
+ * @param chunk - The newly-read raw bytes (already decoded to a string)
+ * @returns The complete `lines` extracted (in order) and the trailing `remainder`
+ */
+export declare function extractLines(buffer: string, chunk: string): LineExtraction;
+
+/**
+ * The HTTP CLIENT transport for the Model Context Protocol — a
+ * {@link ClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server over
+ * `fetch`, the egress mirror of the server's `createMCPRoutes`.
+ *
+ * @remarks
+ * - **Request/response over `fetch`.** `send(message)` POSTs the JSON-serialized
+ *   message (or batch) 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
+ *   the `message` event the {@link import('@src/core').MCPClientInterface} subscribes
+ *   to.
+ * - **Both reply framings.** A `200` with an `application/json` body is parsed with
+ *   `parseJSONRPCMessage`; a `200` with a `text/event-stream` body is decoded via the
+ *   `@orkestrel/sse` {@link import('@orkestrel/sse').SSEParserInterface} ({@link
+ *   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).
+ * - **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`.
+ * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); fires
+ *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.
+ *
+ * @example
+ * ```ts
+ * const transport = new HTTPClientTransport({ url: 'http://localhost:3000/mcp' })
+ * const client = new MCPClient({ transport })
+ * await client.connect()
+ * ```
+ */
+export declare class HTTPClientTransport implements ClientTransportInterface {
+    #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>;
+    close(): Promise<void>;
+}
+
+/**
+ * Options for `createHTTPClientTransport` — the remote MCP server's URL and any extra
+ * request headers.
+ *
+ * @remarks
+ * - `url` — the absolute URL of the remote server's Streamable-HTTP endpoint (the
+ *   `POST` target every JSON-RPC message is written to, e.g.
+ *   `http://localhost:3000/mcp`). REQUIRED.
+ * - `headers` — extra request headers merged onto every `POST` (e.g. an
+ *   `Authorization` bearer for a guarded server). The transport always sets
+ *   `content-type: application/json` and an `Accept` of both `application/json` and
+ *   `text/event-stream` (so the server may answer with either framing); a key supplied
+ *   here is merged on top.
+ * - `fetch` — the `fetch` implementation to issue each `POST` with; defaults to
+ *   `globalThis.fetch`. Injectable for a test double or a non-global `fetch`.
+ * - `timeout` — an optional per-request timeout in milliseconds; when set, each
+ *   `fetch` call is issued with `signal: AbortSignal.timeout(timeout)`. Omit for no
+ *   transport-level deadline.
+ */
+export declare interface HTTPClientTransportOptions {
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly fetch?: typeof fetch;
+    readonly timeout?: number;
+}
+
+/**
+ * Options for `createMCPRoutes` — the path the transport is mounted at and whether an SSE
+ * response is allowed. `createMCPRoutes` is STATELESS; sessions are a separate middleware
+ * ({@link import('./middlewares.js').createMCPSession}), composed via `server.use`.
+ *
+ * @remarks
+ * - `path` — the request path the single `POST` route answers; defaults to
+ *   {@link import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`). `GET` / `DELETE` to this
+ *   path get the spine's automatic `405` unless a {@link
+ *   import('./middlewares.js').createMCPSession} middleware (which owns the same `path`) is
+ *   mounted IN FRONT to serve them.
+ * - `streaming` — when `true` (the DEFAULT) the transport MAY answer with a
+ *   Server-Sent-Events response (one `data:` event carrying the JSON-RPC reply, then
+ *   the stream ends) whenever the client's `Accept` header includes
+ *   `text/event-stream`; when `false` it always answers with a plain JSON body. Either
+ *   mode carries the SAME JSON-RPC response envelope — the choice is purely the wire
+ *   framing the Streamable-HTTP spec lets the client negotiate.
+ */
+export declare interface HTTPTransportOptions {
+    readonly path?: string;
+    readonly streaming?: boolean;
+}
+
+/**
+ * The result of folding one more chunk of raw stdio bytes into a newline-framed
+ * buffer — every COMPLETE line extracted (newline-terminated in the wire bytes) plus
+ * the trailing partial line carried forward as the new `remainder`.
+ *
+ * @remarks
+ * A plain value record (no behavior, §4.5) {@link import('./helpers.js').extractLines}
+ * returns; the caller threads `remainder` back in as the next call's `buffer`.
+ */
+export declare interface LineExtraction {
+    readonly lines: readonly string[];
+    readonly remainder: string;
+}
+
+/**
+ * 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).
+ */
+export declare const MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
+
+/**
+ * The Streamable-HTTP transport header that carries the MCP session id. When a {@link
+ * import('./middlewares.js').createMCPSession} middleware is mounted, it SETS this header on
+ * the `initialize` response (the minted id) and READS it on every subsequent request
+ * (validating the session); the stateless `createMCPRoutes` default neither sets nor reads it.
+ */
+export declare const MCP_SESSION_HEADER = "mcp-session-id";
+
+/**
+ * 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.
+ *
+ * @remarks
+ * `createWebSocketServer` echoes it in the upgrade response and `createWebSocketClientTransport`
+ * requests it, so an MCP WebSocket endpoint is distinguishable from any other WebSocket on the
+ * same path. The default WebSocket upgrade path is {@link DEFAULT_MCP_PATH} (the same `'/mcp'`
+ * the HTTP transport mounts at) — the upgrade is selected by the `Upgrade: websocket` header,
+ * not a separate path.
+ */
+export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
+
+/**
+ * One MCP transport session — the per-session entity a {@link
+ * import('./middlewares.js').createMCPSession} middleware owns, keyed by its `id`, carrying the
+ * resumable server→client push channel with its bounded replay log FOLDED IN.
+ *
+ * @remarks
+ * The single session entity (the old `SessionState` + `EventStore` merged): it holds the
+ * session `id`, its OWN bounded, replayable log of pushed server→client messages (the
+ * resumable GET-SSE channel — a private `#events` `Map` + a monotone `#counter`, with
+ * `capacity` / `ttl` eviction, NOT a separate store), and the set of currently OPEN
+ * server→client SSE streams (a resumable `GET {path}` registers via `attach`, unregisters via
+ * `detach` on disconnect). Still a small entity (not a record), built minimal + extensible.
+ *
+ * - **`push` is the server-initiated primitive.** It APPENDS the message to the log (assigning
+ *   a monotone base36 event id) and FANS it out to every attached stream as one `id:`-tagged
+ *   SSE event (`stream.write({ id, data })`). A push with NO attached stream is still logged,
+ *   so a client that connects (or reconnects with a `Last-Event-ID`) LATER replays it from the
+ *   log. A `write` to a closed stream is a safe no-op (the {@link
+ *   `@orkestrel/server`'s `openStream` contract), so a just-disconnected stream that
+ *   has not yet been `detach`ed never throws. A replayed event and the live one carry the
+ *   IDENTICAL id (the log assigns it once).
+ *
+ * - **`replay(afterId)` is strictly-after.** It returns every retained log entry whose id sorts
+ *   AFTER `afterId` in append order — the missed-events list the `GET {path}` handler writes
+ *   before attaching the stream for live pushes. The decision for an UNKNOWN / already-evicted
+ *   `afterId` (the client's cursor fell off the back of the capacity window, or never existed):
+ *   replay NOTHING. Replaying the whole retained log would re-deliver events the client never
+ *   lost (its cursor is OLDER than everything retained); returning `[]` lets the handler then
+ *   stream only the fresh pushes that follow `attach` — the spec-sane resume.
+ *
+ * - **Bounded, append-ordered, plain `Map` (§21).** The log lives in ONE insertion-ordered
+ *   `Map<id, entry>` — insertion order IS append order IS id order, so `replay` and capacity
+ *   eviction both walk the map directly. NO database mirror — the log is process-local
+ *   transport mechanics, not durable state. `push` first drops every entry older than `ttl`
+ *   (lazy TTL — no background timer, the middleware's lazy-window idiom), appends, then evicts
+ *   the OLDEST entries until at most `capacity` remain; `replay` also runs the lazy TTL sweep
+ *   first, so a stale entry is never replayed.
+ *
+ * - **No transport coupling beyond the SSE seam.** It holds session state + the generic {@link
+ *   StreamInterface} handles `attach` was handed — never a raw socket, request, or response.
+ *   The middleware opens the stream (the spine seam) and registers it here; this class only
+ *   serializes a message onto the already-open streams.
+ *
+ * - **Injected clock.** `push` / `replay` accept an optional `now` (epoch ms), defaulting to
+ *   `Date.now()` — so a test drives TTL eviction with an elapsed clock rather than a real timer
+ *   (AGENTS §16).
+ *
+ * @example
+ * ```ts
+ * const session = new MCPSession(crypto.randomUUID())
+ * session.attach(stream) // an open resumable GET-SSE stream
+ * session.push({ jsonrpc: '2.0', method: 'notifications/message', params: { text: 'hi' } })
+ * // → logged AND written to `stream` as an `id:`-tagged event; a reconnect replays it
+ * ```
+ */
+export declare class MCPSession implements MCPSessionInterface {
+    #private;
+    constructor(id: string, options?: MCPSessionOptions);
+    get id(): string;
+    attach(stream: StreamInterface): void;
+    detach(stream: StreamInterface): void;
+    push(message: JSONRPCMessage, now?: number): string;
+    replay(afterId: string, now?: number): readonly EventStoreEntry[];
+}
+
+/**
+ * The closure store entry a {@link import('./middlewares.js').createMCPSession} middleware
+ * keeps per minted session — the live {@link MCPSession} entity plus the epoch-ms instant it
+ * was last touched (the lazy-TTL sweep's idle clock, independent of the session's own
+ * replay-log TTL).
+ *
+ * @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
+ *   resolved request so the middleware's lazy sweep can evict an idle entry past `ttl`.
+ */
+export declare interface MCPSessionEntry {
+    readonly session: MCPSession;
+    touched: number;
+}
+
+/**
+ * One MCP transport session — the per-session entity a {@link
+ * import('./middlewares.js').createMCPSession} middleware owns (the {@link
+ * import('./MCPSession.js').MCPSession} entity), carrying the resumable server→client push
+ * channel with its bounded replay log FOLDED IN.
+ *
+ * @remarks
+ * - `id` — the opaque session id (a `crypto.randomUUID()`), echoed in the `mcp-session-id`
+ *   header. The app reads it off `context.state.session` (the {@link MCPSessionState} slice
+ *   {@link import('./middlewares.js').createMCPSession} sets) to address a push.
+ * - `attach(stream)` — register an OPEN server→client SSE stream (a resumable `GET {path}`)
+ *   so future {@link push}es reach it; `detach(stream)` unregisters it (the middleware calls
+ *   it when the client disconnects).
+ * - `push(message)` — APPEND `message` to the session's folded replay log (assigning a
+ *   monotone event id, RETURNED) and FAN it out to every attached stream as one `id:`-tagged
+ *   SSE event — the server-initiated push primitive an in-request handler calls. A push with
+ *   no attached stream is still logged, so a later-connecting / reconnecting client replays it.
+ * - `replay(afterId)` — the missed-events list (every retained log entry STRICTLY AFTER
+ *   `afterId`, in append order) the resumable `GET {path}` handler writes ahead of live pushes;
+ *   an unknown / evicted cursor replays NOTHING (the spec-sane resume).
+ */
+export declare interface MCPSessionInterface {
+    readonly id: string;
+    attach(stream: StreamInterface): void;
+    detach(stream: StreamInterface): void;
+    push(message: JSONRPCMessage): string;
+    replay(afterId: string): readonly EventStoreEntry[];
+}
+
+/**
+ * Options for `createMCPSession` — the path the session middleware owns, the session idle
+ * time-to-live, and the per-session resumable event-log bound.
+ *
+ * @remarks
+ * - `path` — the request path the session middleware OWNS (must match the `createMCPRoutes`
+ *   `path` it fronts); a request to any other path passes straight through. Defaults to
+ *   {@link import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`).
+ * - `ttl` — the session idle lifetime in milliseconds: a session not accessed within `ttl`
+ *   is treated as ABSENT and lazily evicted on the next access (no background timer — the
+ *   `createRateLimiter` lazy-window idiom). Omit it for sessions that live until an explicit
+ *   `DELETE`.
+ * - `capacity` — the FOLDED event-log bound per session: the maximum number of pushed
+ *   server→client messages retained for replay before the OLDEST is evicted, paired with a
+ *   per-event idle lifetime ({@link import('./constants.js').DEFAULT_MCP_SESSION_TTL}) that
+ *   bounds how far a reconnecting client may replay. Omit it for the {@link
+ *   import('./constants.js').DEFAULT_MCP_SESSION_CAPACITY} default. (The session `ttl` bounds
+ *   the session; this `capacity` bounds its replay log — independent knobs.)
+ * - `clock` — the `() => number` epoch-ms clock {@link import('./middlewares.js').createMCPSession}
+ *   uses directly for its own session-touch / TTL-sweep bookkeeping; defaults to `Date.now`. The
+ *   deterministic clock a TTL test advances explicitly instead of racing a real idle window
+ *   against wall-clock (AGENTS §16). Production never sets it.
+ */
+export declare interface MCPSessionOptions {
+    readonly path?: string;
+    readonly ttl?: number;
+    readonly capacity?: number;
+    readonly clock?: () => number;
+}
+
+/**
+ * The `context.state` slice a {@link import('./middlewares.js').createMCPSession}
+ * middleware sets on a validated / minted request — a consumer's `TState` extends
+ * this so the downstream route handler can read `context.state.session` to `push`
+ * a server-initiated message onto the session's resumable stream.
+ *
+ * @remarks
+ * `session` is set on `initialize` (the minted session) and on every validated
+ * non-`initialize` `POST` (the resolved one); absent when the request never
+ * reached a resolved session (the middleware short-circuits those as a `404`
+ * before calling `next`).
+ */
+export declare interface MCPSessionState {
+    session?: MCPSessionInterface;
+}
+
+/**
+ * Decode a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it
+ * carried — the CLIENT-side inverse of the server's Streamable-HTTP SSE response.
+ *
+ * @remarks
+ * Reads the whole `response.body` stream chunk-by-chunk through a `TextDecoder({
+ * stream: true })` (handling a multi-byte char split across reads) and `@orkestrel/sse`'s
+ * {@link SSEParserInterface} (handling a partial line / in-progress event split across
+ * reads), then narrows each dispatched event's `data` to a {@link JSONRPCMessage} via
+ * `parseJSONRPCMessage` (so a non-message / non-JSON `data:` event is DROPPED, never
+ * thrown — total, §14). It reuses the SAME `SSEParser` the server's `openStream` seam
+ * serializes against, so the wire round-trips. A `null` body (no stream) yields no
+ * messages; the {@link import('./transports/HTTPClientTransport.js').HTTPClientTransport}
+ * reads a request/response SSE reply (the server sends one `data:` event then ends), so
+ * this drains to completion.
+ *
+ * @param response - The SSE `fetch` Response to decode (its `body` is read to completion)
+ * @returns Every {@link JSONRPCMessage} the stream carried, in order
+ */
+export declare function readEventStream(response: Response): Promise<readonly JSONRPCMessage[]>;
+
+/**
+ * Read the request's `Last-Event-ID` header — the SSE resume cursor a client sends when it
+ * reconnects to the resumable `GET {path}` stream, or `undefined` when absent.
+ *
+ * @remarks
+ * Reads `request.headers.get('last-event-id')` — a fetch-standard `Headers` lookup — so a
+ * missing header reads as `undefined` (no resume, the stream starts fresh). The resumable
+ * `GET` handler in {@link import('./middlewares.js').createMCPSession} passes a present value
+ * to the session's {@link import('./types.js').MCPSessionInterface.replay} to re-deliver the
+ * missed events before attaching the stream for live pushes. Total — never throws.
+ *
+ * @param request - The fetch-standard `Request`
+ * @returns The last-event-id, or `undefined` when the header is absent
+ */
+export declare function readLastEventId(request: Request): string | undefined;
+
+/**
+ * Read the request's `mcp-session-id` header — the session id a stateful transport
+ * validates, or `undefined` when absent.
+ *
+ * @remarks
+ * Reads `request.headers.get(MCP_SESSION_HEADER)` — a fetch-standard `Headers` lookup
+ * (single-valued by construction, never an array) — so a missing header reads as
+ * `undefined` (no session). {@link import('./middlewares.js').createMCPSession} uses it on
+ * every `POST` / `GET` / `DELETE` to look the session up in its closure store; an
+ * `undefined` id is treated exactly like an unknown one (a `404`). Total — never throws.
+ *
+ * @param request - The fetch-standard `Request`
+ * @returns The session id, or `undefined` when the header is absent
+ */
+export declare function readSessionHeader(request: Request): string | undefined;
+
+/**
+ * Build the stateful transport's "unknown session" rejection — an HTTP `404` carrying a
+ * JSON-RPC error body.
+ *
+ * @remarks
+ * Returns `Response.json(jsonRPCError(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
+ * non-`initialize` `POST` path, the resumable `GET {path}` open, and the `DELETE {path}`
+ * session-end (each a missing / unknown / TTL-evicted id) — so the single `404` envelope
+ * is defined once. Total — never throws.
+ *
+ * @returns The `404` JSON-RPC error `Response`
+ */
+export declare function rejectUnknownSession(): Response;
+
+/**
+ * The stdio CLIENT transport for the Model Context Protocol — a
+ * {@link ClientTransportInterface} that drives a CHILD PROCESS MCP server over
+ * newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
+ * import('./HTTPClientTransport.js').HTTPClientTransport} and {@link
+ * import('./WebSocketClientTransport.js').WebSocketClientTransport}.
+ *
+ * @remarks
+ * - **Spawns the server.** `start()` runs `node:child_process`'s `spawn(options.command,
+ *   options.args, { env: options.env, stdio: ['pipe', 'pipe', 'inherit'] })` — the
+ *   child's `stdin`/`stdout` are piped for the JSON-RPC channel, its `stderr` inherits
+ *   the parent's (diagnostics pass through, never parsed as protocol).
+ * - **Inbound (`message`).** Each `stdout` chunk is folded through the shared
+ *   {@link extractLines} line-framing helper (buffering a partial trailing line
+ *   across reads); every complete line is decoded and delivered via the shared
+ *   {@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`.
+ * - **`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
+ *   fault), distinct from the emitter's own listener-error channel.
+ *
+ * @example
+ * ```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
+ * ```
+ */
+export declare class StdioClientTransport implements ClientTransportInterface {
+    #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>;
+    close(): Promise<void>;
+}
+
+/**
+ * Options for `createStdioClientTransport` — the child process to spawn as a
+ * stdio-framed MCP server (newline-delimited JSON-RPC over `stdin`/`stdout`).
+ *
+ * @remarks
+ * - `command` — the executable to spawn (e.g. `'node'`, `'./my-mcp-server'`). REQUIRED.
+ * - `args` — the command-line arguments passed to `command`; defaults to none.
+ * - `env` — the environment variables for the spawned child, passed straight to
+ *   `node:child_process`'s `spawn`; when OMITTED the child inherits the full
+ *   `process.env` (the `spawn` default), when PROVIDED it REPLACES the inherited
+ *   environment entirely (`spawn` semantics) — a caller wanting to extend rather
+ *   than replace spreads `process.env` into `env` themselves.
+ */
+export declare interface StdioClientTransportOptions {
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Options for `createStdioServer` — the injectable stdin/stdout streams the server
+ * transport reads newline-delimited JSON-RPC requests from and writes responses to.
+ *
+ * @remarks
+ * - `input` — the readable stream carrying newline-delimited JSON-RPC requests;
+ *   defaults to `process.stdin`. Injectable for a test double.
+ * - `output` — the writable stream newline-delimited JSON-RPC responses are written
+ *   to; defaults to `process.stdout`. Injectable for a test double.
+ */
+export declare interface StdioServerOptions {
+    readonly input?: NodeJS.ReadableStream;
+    readonly output?: NodeJS.WritableStream;
+}
+
+/**
+ * The stdio SERVER transport for the Model Context Protocol — wraps an injectable
+ * readable/writable stream pair (`process.stdin`/`process.stdout` in production, a
+ * test double in tests) as a {@link ClientTransportInterface}, the newline-delimited
+ * JSON-RPC channel {@link import('../factories.js').createStdioServer} pumps
+ * `mcp.dispatch` over, the stdio mirror of {@link
+ * import('./WebSocketServerTransport.js').WebSocketServerTransport}.
+ *
+ * @remarks
+ * - **Reuses `ClientTransportInterface` (§21).** The same generic carrier the HTTP
+ *   and WebSocket server transports implement — `emitter` (`message` / `close` /
+ *   `error`), `start`, `send`, `close`. `session` is `undefined` (the stateless v1).
+ * - **Inbound (`message`).** `start()` subscribes to `input`'s `data` event; each
+ *   chunk is folded through the shared {@link extractLines} line-framing helper
+ *   (buffering a partial trailing line across reads), and every complete line is
+ *   decoded and delivered via the shared {@link dispatchLines} helper — a
+ *   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`.
+ * - **`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.
+ * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); the
+ *   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 {
+    #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>;
+    close(): Promise<void>;
+}
+
+/**
+ * Read the path (without the query string) of a raw `node:http` protocol-upgrade request —
+ * the `createWebSocketServer` upgrade-path match.
+ *
+ * @remarks
+ * A `node:http` {@link import('node:http').IncomingMessage}'s `url` is the request TARGET
+ * (`'/mcp?x=1'`), narrowed with `isString` (§14, never `as`) and defaulting to `'/'` for an
+ * absent target; it is parsed against a dummy base (only the pathname matters for the upgrade
+ * decision) and the `pathname` returned. The upgrade handler compares this against its
+ * configured `path` to decide whether to claim the socket. Total — never throws on an
+ * adversarial / absent target.
+ *
+ * @param request - The raw upgrade {@link import('node:http').IncomingMessage}
+ * @returns The request's path (the `pathname`, no query), or `'/'` when the target is absent
+ */
+export declare function upgradeRequestPath(request: IncomingMessage): string;
+
+/**
+ * The WebSocket CLIENT transport for the Model Context Protocol — a
+ * {@link ClientTransportInterface} that drives a REMOTE MCP server over a WebSocket, the
+ * egress mirror of {@link import('./factories.js').createWebSocketServer} and the WebSocket
+ * sibling of {@link import('./HTTPClientTransport.js').HTTPClientTransport}.
+ *
+ * @remarks
+ * - **Persistent bidirectional channel (unlike the HTTP transport).** `start()` performs the
+ *   RFC 6455 client handshake: it opens a `node:http`(`s`) `GET` carrying `Connection: Upgrade`
+ *   / `Upgrade: websocket` / a random `Sec-WebSocket-Key` / `Sec-WebSocket-Version: 13` /
+ *   `Sec-WebSocket-Protocol: mcp` (plus any `options.headers`), awaits the client `'upgrade'`
+ *   event, and VALIDATES `Sec-WebSocket-Accept === computeWebSocketAccept(key)` (the D2 helper)
+ *   — a mismatch (or a non-`101` response, or a request error) REJECTS `start()` and the socket
+ *   is destroyed. On success it wraps the raw upgraded socket in `createNodeWebSocket({ socket,
+ *   head })` (CLIENT mode — no key → frames are MASKED per §5.3) and bridges its `message`.
+ * - **Inbound (`message`).** Each decoded text frame is `JSON.parse`d (guarded) and narrowed
+ *   with `parseJSONRPCMessage` — a {@link JSONRPCMessage} re-emits on this transport's `message`
+ *   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.
+ * - **`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`
+ *   → TLS via `node:https`). Either reaches the same endpoint.
+ * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); every emit
+ *   the emitter isolates a listener throw (a buggy observer never corrupts the transport);
+ *   `error` is a DOMAIN event (a transport-level fault).
+ *
+ * @example
+ * ```ts
+ * const transport = new WebSocketClientTransport({ url: 'ws://localhost:3000/mcp' })
+ * const client = new MCPClient({ transport })
+ * await client.connect() // start() handshakes, then the MCP initialize runs over WS frames
+ * ```
+ */
+export declare class WebSocketClientTransport implements ClientTransportInterface {
+    #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>;
+    close(): Promise<void>;
+}
+
+/**
+ * Options for `createWebSocketClientTransport` — the remote MCP WebSocket endpoint and any
+ * extra handshake headers.
+ *
+ * @remarks
+ * - `url` — the absolute URL of the remote server's WebSocket endpoint. Accepts a `ws://` /
+ *   `wss://` URL OR an `http://` / `https://` one (a `ws(s)` scheme is converted to `http(s)`
+ *   for the underlying `node:http(s)` upgrade request; either reaches the same endpoint).
+ *   REQUIRED.
+ * - `headers` — extra request headers merged onto the upgrade `GET` (e.g. an `Authorization`
+ *   bearer for a guarded server). The transport always sets `Connection: Upgrade`,
+ *   `Upgrade: websocket`, a random `Sec-WebSocket-Key`, `Sec-WebSocket-Version: 13`, and
+ *   `Sec-WebSocket-Protocol: mcp`; a header supplied here is merged on top.
+ */
+export declare interface WebSocketClientTransportOptions {
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Options for `createWebSocketServer` — where the WebSocket upgrade is accepted and the
+ * subprotocol negotiated.
+ *
+ * @remarks
+ * - `path` — the request path the upgrade handler CLAIMS; defaults to
+ *   {@link import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`, the same path the HTTP
+ *   transport mounts at). A protocol-upgrade request to any OTHER path is DECLINED
+ *   (the handler returns `false`, so the spine fans it to the next handler or destroys it).
+ * - `subprotocol` — the WebSocket subprotocol echoed in the `101` handshake's
+ *   `Sec-WebSocket-Protocol`; defaults to {@link import('./constants.js').MCP_WEBSOCKET_SUBPROTOCOL}
+ *   (`'mcp'`). It is echoed unconditionally (the client requests it), so an MCP WebSocket
+ *   endpoint is distinguishable from another WebSocket on the same path.
+ *
+ * Auth / origin policy is deliberately ABSENT: like the HTTP transport, the WebSocket
+ * transport is MECHANISM — compose a guard IN FRONT (a `Server.upgrade` handler registered
+ * before this one can decline an unauthenticated upgrade).
+ */
+export declare interface WebSocketServerOptions {
+    readonly path?: string;
+    readonly subprotocol?: string;
+}
+
+/**
+ * The per-connection JSON-RPC-over-WebSocket SERVER bridge — wraps a
+ * {@link NodeWebSocketInterface} (the RFC 6455 wire wrapper) as a
+ * {@link ClientTransportInterface}, the bidirectional JSON-RPC message channel
+ * `createWebSocketServer` pumps `mcp.dispatch` over and the egress mirror's
+ * {@link import('./WebSocketClientTransport.js').WebSocketClientTransport} reuses.
+ *
+ * @remarks
+ * - **Reuses `ClientTransportInterface` (§21).** It IS the same generic carrier the HTTP
+ *   client transport implements — `emitter` (`message` / `close` / `error`), `start`,
+ *   `send`, `close` — so the WebSocket server and client both speak ONE transport contract,
+ *   no near-duplicate sibling interface. `session` is `undefined` (the stateless v1; a
+ *   session id is the deferred sessions tier). The name keeps the role explicit even though
+ *   the shape is shared.
+ * - **Inbound (`message`).** `start()` subscribes to the socket's `message` event; each text
+ *   frame is `JSON.parse`d inside a try/catch and narrowed with `parseJSONRPCMessage` — a
+ *   well-formed {@link JSONRPCMessage} is re-emitted on this transport's `message` event (the
+ *   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
+ *   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
+ *   once).
+ * - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); the emitter
+ *   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 {
+    #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>;
+    close(): Promise<void>;
+}
+
+export { }