@orkestrel/mcp 0.0.1

package/dist/src/server/index.js

@@ -0,0 +1,1344 @@
+import { createSSEParser } from "@orkestrel/sse";
+import { JSONRPC_INVALID_REQUEST, JSONRPC_PARSE_ERROR, isInitializeRequest, isJSONRPCRequest, jsonRPCError, parseJSONRPCMessage } from "../core/index.js";
+import { isString } from "@orkestrel/contract";
+import { Emitter } from "@orkestrel/emitter";
+import { randomBytes } from "node:crypto";
+import { request } from "node:http";
+import { request as request$1 } from "node:https";
+import { WEBSOCKET_VERSION, computeWebSocketAccept, createNodeWebSocket } from "@orkestrel/websocket";
+import { spawn } from "node:child_process";
+import { openStream } from "@orkestrel/server";
+//#region src/server/constants.ts
+/**
+* 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.
+*/
+var MCP_SESSION_HEADER = "mcp-session-id";
+/**
+* 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).
+*/
+var MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
+/** The default request path `createMCPRoutes` mounts the transport's `POST` route at. */
+var DEFAULT_MCP_PATH = "/mcp";
+/**
+* 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.
+*/
+var MCP_WEBSOCKET_SUBPROTOCOL = "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.
+*/
+var 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.
+*/
+var DEFAULT_MCP_SESSION_TTL = 3e5;
+//#endregion
+//#region src/server/helpers.ts
+/**
+* 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`
+*/
+function acceptsEventStream(request) {
+	const accept = request.headers.get("accept");
+	if (accept === null) return false;
+	return accept.toLowerCase().includes("text/event-stream");
+}
+/**
+* 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
+*/
+function readSessionHeader(request) {
+	const id = request.headers.get(MCP_SESSION_HEADER);
+	return id === null ? void 0 : id;
+}
+/**
+* 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
+*/
+function readLastEventId(request) {
+	const id = request.headers.get("last-event-id");
+	return id === null ? void 0 : id;
+}
+/**
+* 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`
+*/
+function rejectUnknownSession() {
+	return Response.json(jsonRPCError(null, JSONRPC_INVALID_REQUEST, "Session not found"), { status: 404 });
+}
+/**
+* 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
+*/
+async function readEventStream(response) {
+	const body = response.body;
+	if (body === null) return [];
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	const parser = createSSEParser();
+	const messages = [];
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			for (const event of parser.parse(decoder.decode(value, { stream: true }))) {
+				const message = decodeEvent(event.data);
+				if (message !== void 0) messages.push(message);
+			}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	return messages;
+}
+/**
+* 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`
+*/
+function decodeEvent(data) {
+	try {
+		return parseJSONRPCMessage(JSON.parse(data));
+	} catch {
+		return;
+	}
+}
+/**
+* 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
+*/
+function upgradeRequestPath(request) {
+	const target = isString(request.url) ? request.url : "/";
+	return new URL(target, "http://localhost").pathname;
+}
+/**
+* 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`
+*/
+function extractLines(buffer, chunk) {
+	const parts = (buffer + chunk).split("\n");
+	const remainder = parts[parts.length - 1] ?? "";
+	return {
+		lines: parts.slice(0, -1).map((line) => line.endsWith("\r") ? line.slice(0, -1) : line),
+		remainder
+	};
+}
+/**
+* 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
+*/
+function dispatchLines(emitter, lines) {
+	for (const line of lines) {
+		if (line.length === 0) continue;
+		const message = decodeEvent(line);
+		if (message === void 0) {
+			emitter.emit("error", /* @__PURE__ */ new Error("non-JSON-RPC stdio line"));
+			continue;
+		}
+		emitter.emit("message", message);
+	}
+}
+//#endregion
+//#region src/server/transports/HTTPClientTransport.ts
+/**
+* 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()
+* ```
+*/
+var HTTPClientTransport = class {
+	#emitter;
+	#url;
+	#headers;
+	#fetch;
+	#timeout;
+	#session = void 0;
+	constructor(options) {
+		this.#emitter = new Emitter();
+		this.#url = options.url;
+		this.#headers = options.headers ?? {};
+		this.#fetch = options.fetch ?? globalThis.fetch;
+		this.#timeout = options.timeout;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get session() {
+		return this.#session;
+	}
+	async start() {}
+	async send(message) {
+		let response;
+		try {
+			response = await this.#fetch(this.#url, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					accept: "application/json, text/event-stream",
+					...this.#session === void 0 ? {} : { [MCP_SESSION_HEADER]: this.#session },
+					...this.#headers
+				},
+				body: JSON.stringify(message),
+				...this.#timeout === void 0 ? {} : { signal: AbortSignal.timeout(this.#timeout) }
+			});
+		} catch (error) {
+			this.#emitter.emit("error", error);
+			return;
+		}
+		const session = response.headers.get(MCP_SESSION_HEADER);
+		if (session !== null) this.#session = session;
+		await this.#deliver(response);
+	}
+	async close() {
+		this.#emitter.emit("close");
+	}
+	async #deliver(response) {
+		if (response.status === 202) return;
+		const type = response.headers.get("content-type") ?? "";
+		try {
+			if (type.includes("text/event-stream")) {
+				for (const message of await readEventStream(response)) this.#emitter.emit("message", message);
+				return;
+			}
+			if (type.includes("application/json")) {
+				const message = parseJSONRPCMessage(await response.json());
+				if (message !== void 0) this.#emitter.emit("message", message);
+			}
+		} catch (error) {
+			this.#emitter.emit("error", error);
+		}
+	}
+};
+//#endregion
+//#region src/server/MCPSession.ts
+/**
+* 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
+* ```
+*/
+var MCPSession = class {
+	#id;
+	#events = /* @__PURE__ */ new Map();
+	#streams = /* @__PURE__ */ new Set();
+	#capacity;
+	#ttl;
+	#counter = 0;
+	constructor(id, options) {
+		this.#id = id;
+		this.#capacity = options?.capacity ?? 1024;
+		this.#ttl = options?.ttl ?? 3e5;
+	}
+	get id() {
+		return this.#id;
+	}
+	attach(stream) {
+		this.#streams.add(stream);
+	}
+	detach(stream) {
+		this.#streams.delete(stream);
+	}
+	push(message, now = Date.now()) {
+		const id = this.#append(message, now);
+		const data = JSON.stringify(message);
+		for (const stream of this.#streams) stream.write({
+			id,
+			data
+		});
+		return id;
+	}
+	replay(afterId, now = Date.now()) {
+		this.#evict(now);
+		const out = [];
+		let found = false;
+		for (const entry of this.#events.values()) if (found) out.push(entry);
+		else if (entry.id === afterId) found = true;
+		return found ? out : [];
+	}
+	#append(message, now) {
+		this.#evict(now);
+		this.#counter += 1;
+		const id = this.#counter.toString(36);
+		this.#events.set(id, {
+			id,
+			message,
+			timestamp: now
+		});
+		while (this.#events.size > this.#capacity) {
+			const oldest = this.#events.keys().next().value;
+			if (oldest === void 0) break;
+			this.#events.delete(oldest);
+		}
+		return id;
+	}
+	#evict(now) {
+		if (this.#ttl <= 0) return;
+		const cutoff = now - this.#ttl;
+		for (const [id, entry] of this.#events) if (entry.timestamp <= cutoff) this.#events.delete(id);
+		else break;
+	}
+};
+//#endregion
+//#region src/server/transports/WebSocketServerTransport.ts
+/**
+* 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.
+*/
+var WebSocketServerTransport = class {
+	#emitter;
+	#socket;
+	#started = false;
+	#closed = false;
+	constructor(socket) {
+		this.#emitter = new Emitter();
+		this.#socket = socket;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get session() {}
+	async start() {
+		if (this.#started || this.#closed) return;
+		this.#started = true;
+		this.#socket.emitter.on("message", (text) => this.#receive(text));
+		this.#socket.emitter.on("close", () => this.#onClose());
+		this.#socket.emitter.on("error", (error) => this.#emitter.emit("error", error));
+	}
+	async send(message) {
+		const messages = Array.isArray(message) ? message : [message];
+		for (const one of messages) this.#socket.send(JSON.stringify(one));
+	}
+	async close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#socket.close();
+		this.#emitter.emit("close");
+	}
+	#receive(text) {
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch (error) {
+			this.#emitter.emit("error", error);
+			return;
+		}
+		const message = parseJSONRPCMessage(parsed);
+		if (message === void 0) {
+			this.#emitter.emit("error", /* @__PURE__ */ new Error("non-JSON-RPC WebSocket frame"));
+			return;
+		}
+		this.#emitter.emit("message", message);
+	}
+	#onClose() {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#emitter.emit("close");
+	}
+};
+//#endregion
+//#region src/server/transports/WebSocketClientTransport.ts
+/**
+* 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
+* ```
+*/
+var WebSocketClientTransport = class {
+	#emitter;
+	#url;
+	#headers;
+	#socket = void 0;
+	#closed = false;
+	constructor(options) {
+		this.#emitter = new Emitter();
+		this.#url = options.url;
+		this.#headers = options.headers ?? {};
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get session() {}
+	async start() {
+		if (this.#socket !== void 0) return;
+		this.#closed = false;
+		const url = this.#httpURL();
+		const key = randomBytes(16).toString("base64");
+		const secure = url.protocol === "https:";
+		const send = secure ? request$1 : request;
+		await new Promise((resolve, reject) => {
+			let settled = false;
+			const fail = (error) => {
+				if (settled) return;
+				settled = true;
+				reject(error);
+			};
+			const request = send({
+				hostname: url.hostname,
+				port: url.port.length > 0 ? Number(url.port) : secure ? 443 : 80,
+				path: `${url.pathname}${url.search}`,
+				headers: {
+					Connection: "Upgrade",
+					Upgrade: "websocket",
+					"Sec-WebSocket-Key": key,
+					"Sec-WebSocket-Version": WEBSOCKET_VERSION,
+					"Sec-WebSocket-Protocol": "mcp",
+					...this.#headers
+				}
+			});
+			request.on("upgrade", (response, socket, head) => {
+				const accept = response.headers["sec-websocket-accept"];
+				if (!isString(accept) || accept !== computeWebSocketAccept(key)) {
+					socket.destroy();
+					fail(/* @__PURE__ */ new Error("WebSocket handshake failed: Sec-WebSocket-Accept mismatch"));
+					return;
+				}
+				const ws = createNodeWebSocket({
+					socket,
+					head
+				});
+				this.#socket = ws;
+				this.#bind(ws);
+				if (!settled) {
+					settled = true;
+					resolve();
+				}
+			});
+			request.on("response", (response) => {
+				response.resume();
+				fail(/* @__PURE__ */ new Error(`WebSocket upgrade declined with status ${response.statusCode ?? 0}`));
+			});
+			request.on("error", (error) => fail(error instanceof Error ? error : new Error(String(error))));
+			request.end();
+		});
+	}
+	async send(message) {
+		const socket = this.#socket;
+		if (socket === void 0) throw new Error("WebSocket transport is not connected");
+		const messages = Array.isArray(message) ? message : [message];
+		for (const one of messages) socket.send(JSON.stringify(one));
+	}
+	async close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		const socket = this.#socket;
+		this.#socket = void 0;
+		if (socket !== void 0) socket.close();
+		this.#emitter.emit("close");
+	}
+	#bind(ws) {
+		ws.emitter.on("message", (text) => this.#receive(text));
+		ws.emitter.on("close", () => this.#onClose());
+		ws.emitter.on("error", (error) => this.#emitter.emit("error", error));
+	}
+	#receive(text) {
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch (error) {
+			this.#emitter.emit("error", error);
+			return;
+		}
+		const message = parseJSONRPCMessage(parsed);
+		if (message === void 0) {
+			this.#emitter.emit("error", /* @__PURE__ */ new Error("non-JSON-RPC WebSocket frame"));
+			return;
+		}
+		this.#emitter.emit("message", message);
+	}
+	#onClose() {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#socket = void 0;
+		this.#emitter.emit("close");
+	}
+	#httpURL() {
+		const url = new URL(this.#url);
+		if (url.protocol === "ws:") url.protocol = "http:";
+		else if (url.protocol === "wss:") url.protocol = "https:";
+		else if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`unsupported WebSocket URL scheme '${url.protocol}'`);
+		return url;
+	}
+};
+//#endregion
+//#region src/server/transports/StdioClientTransport.ts
+/**
+* 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
+* ```
+*/
+var StdioClientTransport = class {
+	#emitter;
+	#command;
+	#args;
+	#env;
+	#child = void 0;
+	#buffer = "";
+	#closed = false;
+	constructor(options) {
+		this.#emitter = new Emitter();
+		this.#command = options.command;
+		this.#args = options.args ?? [];
+		this.#env = options.env;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get session() {}
+	async start() {
+		if (this.#child !== void 0) return;
+		this.#closed = false;
+		this.#buffer = "";
+		const child = spawn(this.#command, [...this.#args], {
+			env: this.#env,
+			stdio: [
+				"pipe",
+				"pipe",
+				"inherit"
+			]
+		});
+		this.#child = child;
+		child.stdout.on("data", (chunk) => this.#receive(chunk.toString()));
+		child.on("close", () => this.#onClose());
+		child.on("error", (error) => this.#emitter.emit("error", error));
+	}
+	async send(message) {
+		const child = this.#child;
+		if (child === void 0) throw new Error("stdio transport is not connected");
+		const messages = Array.isArray(message) ? message : [message];
+		for (const one of messages) child.stdin.write(`${JSON.stringify(one)}\n`);
+	}
+	async close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		const child = this.#child;
+		this.#child = void 0;
+		if (child !== void 0) child.kill();
+		this.#emitter.emit("close");
+	}
+	#receive(chunk) {
+		const { lines, remainder } = extractLines(this.#buffer, chunk);
+		this.#buffer = remainder;
+		dispatchLines(this.#emitter, lines);
+	}
+	#onClose() {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#child = void 0;
+		this.#emitter.emit("close");
+	}
+};
+//#endregion
+//#region src/server/transports/StdioServerTransport.ts
+/**
+* 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.
+*/
+var StdioServerTransport = class {
+	#emitter;
+	#input;
+	#output;
+	#buffer = "";
+	#started = false;
+	#closed = false;
+	constructor(input, output) {
+		this.#emitter = new Emitter();
+		this.#input = input;
+		this.#output = output;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get session() {}
+	async start() {
+		if (this.#started || this.#closed) return;
+		this.#started = true;
+		this.#input.on("data", (chunk) => this.#receive(chunk.toString()));
+		this.#input.on("close", () => this.#onClose());
+		this.#input.on("error", (error) => this.#emitter.emit("error", error));
+	}
+	async send(message) {
+		const messages = Array.isArray(message) ? message : [message];
+		for (const one of messages) this.#output.write(`${JSON.stringify(one)}\n`);
+	}
+	async close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#emitter.emit("close");
+	}
+	#receive(chunk) {
+		const { lines, remainder } = extractLines(this.#buffer, chunk);
+		this.#buffer = remainder;
+		dispatchLines(this.#emitter, lines);
+	}
+	#onClose() {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#emitter.emit("close");
+	}
+};
+//#endregion
+//#region src/server/factories.ts
+/**
+* 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)
+* ```
+*/
+function createMCPRoutes(mcp, options) {
+	const path = options?.path ?? "/mcp";
+	const streaming = options?.streaming ?? true;
+	return [{
+		method: "POST",
+		path,
+		name: "mcp",
+		handler: async (request) => {
+			let text;
+			try {
+				text = await request.text();
+			} catch {
+				return Response.json(jsonRPCError(null, JSONRPC_PARSE_ERROR, "Parse error"), { status: 400 });
+			}
+			let parsed;
+			try {
+				parsed = JSON.parse(text);
+			} catch {
+				return Response.json(jsonRPCError(null, JSONRPC_PARSE_ERROR, "Parse error"), { status: 400 });
+			}
+			const rpcRequest = parseJSONRPCMessage(parsed);
+			if (rpcRequest === void 0 || !("method" in rpcRequest)) return Response.json(jsonRPCError(null, JSONRPC_INVALID_REQUEST, "Invalid Request"), { status: 400 });
+			const response = await mcp.dispatch(rpcRequest);
+			if (response === void 0) return new Response(null, { status: 202 });
+			if (streaming && acceptsEventStream(request)) {
+				const s = openStream();
+				s.write({ data: JSON.stringify(response) });
+				s.end();
+				return s.response;
+			}
+			return Response.json(response);
+		}
+	}];
+}
+/**
+* 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()
+* ```
+*/
+function createHTTPClientTransport(options) {
+	return new HTTPClientTransport(options);
+}
+/**
+* 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
+* ```
+*/
+function createWebSocketServer(mcp, options) {
+	const path = options?.path ?? "/mcp";
+	const subprotocol = options?.subprotocol ?? "mcp";
+	return (request, socket, head) => {
+		const upgrade = request.headers["upgrade"];
+		if (!isString(upgrade) || upgrade.toLowerCase() !== "websocket") return false;
+		if (upgradeRequestPath(request) !== path) return false;
+		const key = request.headers["sec-websocket-key"];
+		if (!isString(key)) return false;
+		const version = request.headers["sec-websocket-version"];
+		if (!isString(version) || version !== WEBSOCKET_VERSION) return false;
+		const transport = new WebSocketServerTransport(createNodeWebSocket({
+			socket,
+			key,
+			head,
+			protocol: subprotocol
+		}));
+		transport.emitter.on("message", (message) => {
+			if (!isJSONRPCRequest(message)) return;
+			(async () => {
+				try {
+					const response = await mcp.dispatch(message);
+					if (response !== void 0) await transport.send(response);
+				} catch (error) {
+					try {
+						transport.emitter.emit("error", error);
+					} catch {}
+				}
+			})();
+		});
+		transport.start();
+		return true;
+	};
+}
+/**
+* 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()
+* ```
+*/
+function createWebSocketClientTransport(options) {
+	return new WebSocketClientTransport(options);
+}
+/**
+* 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()
+* ```
+*/
+function createStdioClientTransport(options) {
+	return new StdioClientTransport(options);
+}
+/**
+* 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
+* ```
+*/
+function createStdioServer(mcp, options) {
+	const transport = new StdioServerTransport(options?.input ?? process.stdin, options?.output ?? process.stdout);
+	transport.emitter.on("message", (message) => {
+		if (!isJSONRPCRequest(message)) return;
+		(async () => {
+			try {
+				const response = await mcp.dispatch(message);
+				if (response !== void 0) await transport.send(response);
+			} catch (error) {
+				try {
+					transport.emitter.emit("error", error);
+				} catch {}
+			}
+		})();
+	});
+	return {
+		start() {
+			transport.start();
+		},
+		stop() {
+			transport.close();
+		}
+	};
+}
+//#endregion
+//#region src/server/middlewares.ts
+/**
+* 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
+* ```
+*/
+function createMCPSession(options) {
+	const path = options?.path ?? "/mcp";
+	const capacity = options?.capacity;
+	const ttl = options?.ttl;
+	const clock = options?.clock ?? Date.now;
+	const store = /* @__PURE__ */ new Map();
+	return async (request, context, next) => {
+		if (context.url.pathname !== path) return next();
+		sweep();
+		if (context.method === "GET") {
+			const entry = resolve(request);
+			if (entry === void 0) return rejectUnknownSession();
+			const stream = openStream();
+			stream.comment("open");
+			const lastEventId = readLastEventId(request);
+			if (lastEventId !== void 0) for (const e of entry.session.replay(lastEventId)) stream.write({
+				id: e.id,
+				data: JSON.stringify(e.message)
+			});
+			entry.session.attach(stream);
+			if (request.signal.aborted) entry.session.detach(stream);
+			else request.signal.addEventListener("abort", () => entry.session.detach(stream), { once: true });
+			return stream.response;
+		}
+		if (context.method === "DELETE") {
+			const id = readSessionHeader(request);
+			if (id === void 0 || !store.has(id)) return rejectUnknownSession();
+			store.delete(id);
+			return new Response(null, { status: 204 });
+		}
+		const text = await request.text();
+		let entry = resolve(request);
+		if (entry === void 0) {
+			let parsed;
+			try {
+				parsed = parseJSONRPCMessage(JSON.parse(text));
+			} catch {
+				parsed = void 0;
+			}
+			if (parsed !== void 0 && isInitializeRequest(parsed)) {
+				const session = new MCPSession(crypto.randomUUID(), { capacity });
+				entry = {
+					session,
+					touched: clock()
+				};
+				store.set(session.id, entry);
+			} else return rejectUnknownSession();
+		}
+		context.state.session = entry.session;
+		const response = await next(new Request(context.url, {
+			method: "POST",
+			headers: request.headers,
+			body: text
+		}));
+		response.headers.set(MCP_SESSION_HEADER, entry.session.id);
+		return response;
+	};
+	function resolve(request) {
+		const id = readSessionHeader(request);
+		if (id === void 0) return void 0;
+		const entry = store.get(id);
+		if (entry === void 0) return void 0;
+		entry.touched = clock();
+		return entry;
+	}
+	function sweep() {
+		if (ttl === void 0) return;
+		const cutoff = clock() - ttl;
+		for (const [id, entry] of store) if (entry.touched <= cutoff) store.delete(id);
+	}
+}
+//#endregion
+export { DEFAULT_MCP_PATH, DEFAULT_MCP_SESSION_CAPACITY, DEFAULT_MCP_SESSION_TTL, HTTPClientTransport, MCPSession, MCP_PROTOCOL_VERSION_HEADER, MCP_SESSION_HEADER, MCP_WEBSOCKET_SUBPROTOCOL, StdioClientTransport, StdioServerTransport, WebSocketClientTransport, WebSocketServerTransport, acceptsEventStream, createHTTPClientTransport, createMCPRoutes, createMCPSession, createStdioClientTransport, createStdioServer, createWebSocketClientTransport, createWebSocketServer, decodeEvent, dispatchLines, extractLines, readEventStream, readLastEventId, readSessionHeader, rejectUnknownSession, upgradeRequestPath };
+
+//# sourceMappingURL=index.js.map