@orkestrel/mcp 0.0.4 → 0.0.6

package/dist/src/browser/index.js

@@ -0,0 +1,690 @@
+import { SUPPORTED_PROTOCOL_VERSIONS, bindServer, createMCPServer, isJSONRPCResponse, parseJSONRPCMessage } from "../core/index.js";
+import { isRecord, isString } from "@orkestrel/contract";
+import { createSSEParser } from "@orkestrel/sse";
+import { Emitter } from "@orkestrel/emitter";
+//#region src/browser/constants.ts
+/**
+* The Streamable-HTTP transport header that carries the MCP session id. The browser
+* face's {@link import('./transports/HTTPClientTransport.js').HTTPClientTransport}
+* ECHOES this header exactly like the Node face's `HTTPClientTransport`
+* (`src/server`), so the same client interoperates with an `MCPSession`-based
+* server unchanged.
+*/
+var MCP_SESSION_HEADER = "mcp-session-id";
+/**
+* The Streamable-HTTP transport header carrying the negotiated MCP protocol version
+* on every post-initialize request. The browser HTTP client captures the initialize
+* result's `protocolVersion` and sends this header on each subsequent request.
+*/
+var MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
+/** The default server name `serveMCPScope` reports (`initialize`'s `serverInfo.name`) when `options.name` is omitted. */
+var DEFAULT_MCP_SERVER_NAME = "taverna";
+/** The default server version `serveMCPScope` reports (`initialize`'s `serverInfo.version`) when `options.version` is omitted. */
+var DEFAULT_MCP_SERVER_VERSION = "1.0.0";
+/**
+* The WebSocket subprotocol `createWebSocketClientTransport` requests by default —
+* `'mcp'`, matching `createWebSocketServer`'s unconditional `Sec-WebSocket-Protocol:
+* mcp` echo. Per RFC 6455 §4.1 a client MUST fail the connection if the server returns
+* a subprotocol it did not request; Node ≥ 22 (undici) enforces this strictly, so the
+* default bakes the correct value in. Override `WebSocketClientTransportOptions.protocols`
+* only when connecting to a foreign server that speaks a different subprotocol (or `[]`
+* for no subprotocol negotiation at all).
+*/
+var MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
+//#endregion
+//#region src/browser/transports/MessagePortTransport.ts
+/**
+* The browser-face `MessagePort` transport for the Model Context Protocol — a
+* {@link MCPTransportInterface} over a native `MessagePort`, the genuinely new
+* capability this face adds: MCP over `postMessage`.
+*
+* @remarks
+* - **Symmetric.** Unlike {@link import('./WebSocketClientTransport.js').WebSocketClientTransport}
+*   / {@link import('./HTTPClientTransport.js').HTTPClientTransport} (CLIENT-only
+*   carriers of `@src/core`'s `ClientTransportInterface`), a `MessagePort` is a
+*   plain duplex channel — the SAME class implements `@src/core`'s
+*   `MCPTransportInterface` and is handed to EITHER `bindServer` or
+*   `bindClient`/`createDuplexClientTransport`; which role it plays comes entirely
+*   from the binder it is given to, not from anything this class decides.
+* - **`start()` at construction — bind synchronously.** `MessagePort.start()` is only
+*   REQUIRED when listening via `addEventListener` (as opposed to the `onmessage`
+*   setter, which implies it) — this transport uses `addEventListener`, and
+*   `MCPTransportInterface` has no separate open/connect step for the caller to hook
+*   a start into, so the constructor calls `port.start()` immediately: the port
+*   begins dispatching QUEUED messages the moment the transport exists. This is safe
+*   inside `serveMCP`'s flow (the transport is synchronously handed to `bindServer`
+*   before control returns to the event loop), but is a **footgun for direct use**:
+*   if you construct `new MessagePortTransport({ port })` and then `await` anything
+*   before calling `listen`, messages that arrived in the gap are DROPPED. **Bind
+*   synchronously after construction** — do not interleave an `await` between
+*   `new MessagePortTransport(…)` and `bindServer` / `listen`.
+* - **String payloads only.** `send` posts the message string as-is (`postMessage`
+*   structured-clones it — a string clones to an identical string, so the wire stays
+*   plain JSON-RPC text like every other transport in this package). Inbound: a
+*   non-string `event.data` (a host or a misbehaving peer posting a structured
+*   object) is IGNORED — dropped silently, never forwarded, never thrown (§14) —
+*   because `MCPTransportInterface` carries no `error` channel for this port to
+*   surface a non-string frame on (unlike `ClientTransportInterface`'s `emitter`);
+*   silently ignoring is the total, contract-shaped choice.
+* - **`messageerror` is IGNORED, not routed to `closed`.** A `messageerror` event
+*   (the structured-clone deserialization of an inbound message threw) reports one
+*   BAD FRAME, not a dead channel — the port itself keeps working and later, well-
+*   formed messages still arrive. Routing it to `closed` would tear down the
+*   `bindServer`/`bindClient` wiring (and, transitively, every session it carries)
+*   over a single malformed frame, which is far more destructive than dropping that
+*   one frame — so this transport registers a `messageerror` listener that does
+*   nothing, deliberately.
+* - **`close()`** is idempotent: it closes the underlying `port` (`MessagePort.close()`
+*   disconnects it — further `postMessage` calls on EITHER end are silently
+*   undelivered, per the platform contract) and fires the registered `closed`
+*   handler exactly once, whether the caller closes it once or twice. There is no
+*   native "peer closed" signal for a `MessagePort` (unlike a WebSocket's `close`
+*   event) — `closed` fires ONLY from this transport's own `close()`.
+* - **Single-handler-replace (the port contract, `@src/core`'s `MCPTransportInterface`
+*   doc).** `listen`/`closed` each hold the ONE currently registered handler; a
+*   second call REPLACES the first rather than adding a second subscriber.
+*
+* @example
+* ```ts
+* const { port1, port2 } = new MessageChannel()
+* const serverTransport = new MessagePortTransport({ port: port1 })
+* bindServer(server, serverTransport) // port1 side dispatches inbound requests
+*
+* const clientTransport = new MessagePortTransport({ port: port2 })
+* const client = createMCPClient({ transport: createDuplexClientTransport(clientTransport) })
+* bindClient(client, clientTransport) // port2 side is the client's carrier
+* ```
+*/
+var MessagePortTransport = class {
+	#port;
+	#onMessage = void 0;
+	#onClosed = void 0;
+	#closed = false;
+	constructor(options) {
+		this.#port = options.port;
+		this.#port.addEventListener("message", (event) => this.#receive(event.data));
+		this.#port.addEventListener("messageerror", () => {});
+		this.#port.start();
+	}
+	send(message) {
+		if (this.#closed) return;
+		this.#port.postMessage(message);
+	}
+	listen(handler) {
+		this.#onMessage = handler;
+	}
+	closed(handler) {
+		this.#onClosed = handler;
+	}
+	close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#port.close();
+		this.#onClosed?.();
+	}
+	#receive(data) {
+		if (!isString(data)) return;
+		this.#onMessage?.(data);
+	}
+};
+//#endregion
+//#region src/browser/helpers.ts
+/**
+* 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;
+	}
+}
+/**
+* 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 {@link decodeEvent} (so a non-message / non-JSON `data:`
+* event is DROPPED, never thrown — total, §14). A `null` body (no stream) yields no
+* messages; {@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;
+}
+/**
+* Build `serveMCPScope`'s `message`-event listener — the unified
+* dispatcher that routes EVERY inbound event on a hostable scope, portless or
+* port-bearing, to the right binding.
+*
+* @remarks
+* Port-bearing events (`event.ports.length > 0`) are gated by `options.accept` FIRST
+* — when the gate returns `false` the event is dropped entirely (no binding, no reply).
+* Accepted events spawn a fresh `MessagePortTransport` over `event.ports[0]`,
+* `bindServer` `server` onto it, and record a teardown (`unbind` then `transport.close()`)
+* into `teardowns`. A port that was already seen is IGNORED — repeated delivery of the
+* same `MessagePort` would create duplicate bindings over one port (→ duplicated replies),
+* so the listener tracks seen ports and silently drops repeats.
+*
+* This branch fires on EITHER a Service-Worker-shaped scope (its normal per-client
+* channel) or a dedicated-worker-shaped one that happens to receive a port-bearing event
+* (the unified design's deliberate cross-case, needing no upfront shape flag). An event
+* with NO ports and a STRING `data` is pushed onto `scopeTransport.deliver` (the
+* implicit, already-bound scope channel); any other event (no ports, non-string data)
+* is silently dropped — total (§14), never throws.
+*
+* @param server - The `MCPServerInterface` every spawned/implicit binding dispatches over
+* @param scopeTransport - The implicit scope channel (already `bindServer`-bound) portless events deliver onto
+* @param teardowns - The shared teardown set `serveMCPScope`'s dispose drains; each port-bearing event adds one entry
+* @param options - The `ServeMCPOptions` (for `options.accept`)
+* @returns The `message`-event listener to register (and later remove) on the scope
+*
+* @example
+* ```ts
+* const teardowns = new Set<() => void>()
+* const scopeTransport = createScopeTransport(scope)
+* bindServer(server, scopeTransport)
+* const onMessage = createScopeMessageListener(server, scopeTransport, teardowns, options)
+* scope.addEventListener('message', onMessage)
+* ```
+*/
+function createScopeMessageListener(server, scopeTransport, teardowns, options) {
+	const seen = /* @__PURE__ */ new Set();
+	return (event) => {
+		const ports = event.ports;
+		if (ports.length > 0) {
+			if (options.accept !== void 0 && !options.accept(event)) return;
+			const port = ports[0];
+			if (port === void 0) return;
+			if (seen.has(port)) return;
+			seen.add(port);
+			const transport = new MessagePortTransport({ port });
+			const unbind = bindServer(server, transport);
+			teardowns.add(() => {
+				unbind();
+				transport.close();
+			});
+			return;
+		}
+		if (isString(event.data)) scopeTransport.deliver(event.data);
+	};
+}
+//#endregion
+//#region src/browser/transports/HTTPClientTransport.ts
+/**
+* The browser-face HTTP CLIENT transport for the Model Context Protocol — a
+* {@link ClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
+* over the native `fetch`, the browser sibling of the Node face's
+* {@link import('@src/server').HTTPClientTransport}, honoring the SAME
+* `mcp-session-id` semantics so it interoperates with an `MCPSession`-based server
+* unchanged.
+*
+* @remarks
+* - **Request/response over `fetch`.** `send(message)` POSTs the JSON-serialized
+*   message to `options.url` with `content-type: application/json` and an
+*   `Accept` of BOTH `application/json` and `text/event-stream` (so the server may
+*   answer with either framing) — plus any `options.headers` (e.g. an
+*   `Authorization` bearer). It then decodes the reply and emits each decoded
+*   {@link JSONRPCMessage} on 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} (the browser
+*   face's own `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 and protocol echo.** `start()` is a no-op (a
+*   request/response transport opens no long-lived connection). The
+*   `mcp-session-id` response header, when a STATEFUL server sends one (on
+*   `initialize`), is captured into `session` and then ECHOED as the
+*   `mcp-session-id` request header on every SUBSEQUENT request — so an
+*   `MCPClient` passes a stateful server's session validation. The
+*   initialize result's `protocolVersion` is likewise captured, but only
+*   when it is a SUPPORTED value, and echoed as `mcp-protocol-version` on
+*   every subsequent request, as required by the 2025-06-18 Streamable-HTTP
+*   transport. Before initialize returns, neither captured header is sent.
+*   `close()` clears the captured protocol so a reconnect's `initialize`
+*   POST is headerless; the captured `session` persists across `close()`.
+* - **Total at the boundary (§14).** Every reply is narrowed (`parseJSONRPCMessage`,
+*   the SSE decoder) — a non-message reply is dropped, never asserted; a `fetch` /
+*   decode failure surfaces on the `error` event rather than escaping `send`.
+* - **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;
+	#protocol = void 0;
+	constructor(options) {
+		this.#emitter = new Emitter();
+		this.#url = options.url;
+		this.#headers = options.headers ?? {};
+		this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+		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.#protocol === void 0 ? {} : { [MCP_PROTOCOL_VERSION_HEADER]: this.#protocol },
+					...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.#protocol = void 0;
+		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.#capture(message);
+				return;
+			}
+			if (type.includes("application/json")) {
+				const message = parseJSONRPCMessage(await response.json());
+				if (message !== void 0) this.#capture(message);
+			}
+		} catch (error) {
+			this.#emitter.emit("error", error);
+		}
+	}
+	#capture(message) {
+		if (isJSONRPCResponse(message) && isRecord(message.result) && isString(message.result["protocolVersion"]) && SUPPORTED_PROTOCOL_VERSIONS.includes(message.result["protocolVersion"])) this.#protocol = message.result["protocolVersion"];
+		this.#emitter.emit("message", message);
+	}
+};
+//#endregion
+//#region src/browser/transports/WebSocketClientTransport.ts
+/**
+* The browser-face WebSocket CLIENT transport for the Model Context Protocol — a
+* {@link ClientTransportInterface} that drives a REMOTE MCP server over the native
+* `WebSocket` global, the browser sibling of the Node face's
+* {@link import('@src/server').WebSocketClientTransport}.
+*
+* @remarks
+* - **Host-performed handshake.** `start()` opens `new WebSocket(url, protocols)` and
+*   waits for the native `'open'` event — the RFC 6455 handshake itself is entirely
+*   the host's concern, so this transport carries none of the Node client's
+*   `node:crypto` / `node:http(s)` machinery. A connection failure (the native
+*   `'error'` event while not yet `OPEN`) REJECTS `start()`.
+* - **Queued sends.** `send` writes each message as one text frame immediately once
+*   the socket is `OPEN`; a `send` issued before `'open'` fires (or before `start()`
+*   is even called) is QUEUED and flushed, IN ORDER, the moment the socket opens —
+*   so a caller need not await `start()` before calling `send`.
+* - **Inbound (`message`).** Each decoded text frame is `JSON.parse`d (guarded) and
+*   narrowed with `parseJSONRPCMessage` — a well-formed {@link JSONRPCMessage}
+*   re-emits on this transport's `message` event; a non-text (binary) frame or a
+*   non-JSON / non-message text frame surfaces on `error` and is DROPPED (§14 — never
+*   throws on adversarial wire input).
+* - **`close()`** closes the underlying socket and fires `close` (idempotent); the
+*   socket's native `close` event (a server-initiated close) fires the SAME `close`
+*   exactly once total — `close()` first flips the guard, so the native event never
+*   double-emits. **This transport is not reusable after `close()`** — a `send` issued
+*   after `close()` is silently dropped (not queued, not delivered even on a later
+*   `start()`).
+* - **Observable (§13).** Owns the `emitter` ({@link ClientTransportEventMap}); every
+*   emit the emitter isolates a listener throw; `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() // the browser handshakes, then the MCP initialize runs over WS frames
+* ```
+*/
+var WebSocketClientTransport = class {
+	#emitter;
+	#url;
+	#protocols;
+	#socket = void 0;
+	#queue = [];
+	#closed = false;
+	constructor(options) {
+		this.#emitter = new Emitter();
+		this.#url = options.url;
+		const protocols = options.protocols;
+		this.#protocols = typeof protocols === "string" ? protocols : protocols === void 0 ? "mcp" : protocols.length === 0 ? void 0 : [...protocols];
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get session() {}
+	async start() {
+		if (this.#socket !== void 0) return;
+		this.#closed = false;
+		const socket = new WebSocket(this.#url, this.#protocols);
+		this.#socket = socket;
+		this.#bind(socket);
+		await new Promise((resolve, reject) => {
+			socket.addEventListener("open", () => {
+				this.#flush(socket);
+				resolve();
+			}, { once: true });
+			socket.addEventListener("error", () => {
+				if (socket.readyState !== WebSocket.OPEN) {
+					this.#socket = void 0;
+					reject(/* @__PURE__ */ new Error("WebSocket connection failed"));
+				}
+			}, { once: true });
+		});
+	}
+	async send(message) {
+		if (this.#closed) return;
+		const text = JSON.stringify(message);
+		const socket = this.#socket;
+		if (socket !== void 0 && socket.readyState === WebSocket.OPEN) socket.send(text);
+		else this.#queue.push(text);
+	}
+	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(socket) {
+		socket.addEventListener("message", (event) => this.#receive(event.data));
+		socket.addEventListener("close", () => this.#onClose());
+		socket.addEventListener("error", (event) => this.#emitter.emit("error", event));
+	}
+	#flush(socket) {
+		for (const text of this.#queue.splice(0)) socket.send(text);
+	}
+	#receive(data) {
+		if (!isString(data)) {
+			this.#emitter.emit("error", /* @__PURE__ */ new Error("non-text WebSocket frame"));
+			return;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(data);
+		} 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");
+	}
+};
+//#endregion
+//#region src/browser/factories.ts
+/**
+* Create the browser-face WebSocket CLIENT transport for an
+* {@link import('@src/core').MCPClientInterface} — a {@link ClientTransportInterface}
+* that drives a REMOTE MCP server over the native `WebSocket` global, the browser
+* sibling of the Node face's `createWebSocketClientTransport` (`@src/server`).
+*
+* @remarks
+* Hand it to `createMCPClient({ transport })`: `start()` (run by `client.connect()`)
+* opens `new WebSocket(options.url, options.protocols)` and awaits the native
+* `'open'` event — the RFC 6455 handshake itself is the browser's concern. Each
+* JSON-RPC message the client `send`s before the socket opens is QUEUED and flushed,
+* in order, once it does; each decoded reply is surfaced on the transport's
+* `message` event for the client's id correlation.
+*
+* @param options - `url` (the remote WebSocket endpoint; REQUIRED) and optional
+*   `protocols` (the WebSocket subprotocol(s) to request); see
+*   {@link WebSocketClientTransportOptions}
+* @returns A working {@link ClientTransportInterface} over the native `WebSocket`
+*
+* @example
+* ```ts
+* import { createMCPClient } from '@orkestrel/mcp'
+* import { createWebSocketClientTransport } from '@orkestrel/mcp/browser'
+*
+* 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 browser-face HTTP CLIENT transport for an
+* {@link import('@src/core').MCPClientInterface} — a {@link ClientTransportInterface}
+* that drives a REMOTE Streamable-HTTP MCP server over the native `fetch`, the
+* browser sibling of the Node face's `createHTTPClientTransport` (`@src/server`).
+*
+* @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. It also captures the initialize
+* result's `protocolVersion` and sends `mcp-protocol-version` on every subsequent
+* request, so the same `MCPClient` passes the session and 2025-06-18 protocol
+* gates without caller wiring.
+*
+* @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged
+*   onto every request, optional `fetch` (default `globalThis.fetch`), and optional
+*   `timeout` (ms, applied via `AbortSignal.timeout`); see
+*   {@link HTTPClientTransportOptions}
+* @returns A working {@link ClientTransportInterface} over the native `fetch`
+*
+* @example
+* ```ts
+* import { createMCPClient } from '@orkestrel/mcp'
+* import { createHTTPClientTransport } from '@orkestrel/mcp/browser'
+*
+* 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 browser-face `MessagePort` transport — a
+* {@link import('@src/core').MCPTransportInterface} over a native `MessagePort`, the
+* SYMMETRIC carrier that works as either a server or a client transport depending on
+* which binder ({@link import('@src/core').bindServer} or
+* {@link import('@src/core').bindClient}) it is handed to.
+*
+* @remarks
+* `port.start()` runs at construction (see {@link MessagePortTransport}'s doc for
+* why); inbound payloads are string-only (a non-string `postMessage` payload is
+* dropped, never thrown); `messageerror` is ignored (one bad frame does not close the
+* channel); `close()` closes the port and fires `closed` exactly once.
+*
+* @param options - `port` (the `MessagePort` half to drive; REQUIRED); see
+*   {@link MessagePortTransportOptions}
+* @returns A working {@link import('@src/core').MCPTransportInterface} over the port
+*
+* @example
+* ```ts
+* import { bindServer, createMCPServer } from '@orkestrel/mcp'
+* import { createMessagePortTransport } from '@orkestrel/mcp/browser'
+*
+* const { port1, port2 } = new MessageChannel()
+* bindServer(createMCPServer({ name: 's', version: '1.0.0', tools }), createMessagePortTransport({ port: port1 }))
+* ```
+*/
+function createMessagePortTransport(options) {
+	return new MessagePortTransport(options);
+}
+/**
+* Adapt a hostable {@link ServeMCPScopeInterface} (`self` in a dedicated Web Worker,
+* or any structurally matching double) into a {@link ScopeTransportInterface} — the
+* implicit, portless message channel `serveMCPScope` binds for the
+* dedicated-worker shape.
+*
+* @remarks
+* `send` writes each outbound string via `scope.postMessage`. `listen`/`closed`
+* register the SINGLE handler `deliver` / the underlying close path route through —
+* `serveMCPScope`'s own `scope` `message`-event listener calls `deliver(event.data)`
+* for every portless, string-payload event (there is no native registration point on
+* the scope itself for `serveMCPScope` to hand a `listen` handler to, so `deliver` is
+* the bridge). `close()` fires the registered `closed` handler — a scope has nothing
+* physically closable, so this is the only teardown signal available.
+*
+* @param scope - The hostable scope to adapt (structurally, `self` / `globalThis`
+*   inside a dedicated Web Worker)
+* @returns A {@link ScopeTransportInterface} `serveMCPScope` binds and drives via `deliver`
+*
+* @example
+* ```ts
+* const scopeTransport = createScopeTransport(self)
+* const unbind = bindServer(server, scopeTransport)
+* ```
+*/
+function createScopeTransport(scope) {
+	let onMessage;
+	let onClosed;
+	return {
+		send(message) {
+			scope.postMessage(message);
+		},
+		listen(handler) {
+			onMessage = handler;
+		},
+		closed(handler) {
+			onClosed = handler;
+		},
+		close() {
+			onClosed?.();
+		},
+		deliver(message) {
+			onMessage?.(message);
+		}
+	};
+}
+/**
+* Boot an `MCPServer` inside a hostable worker scope and wire its message events to it.
+*
+* @remarks
+* Port-bearing events are gated by `options.accept`, deduplicated by port, and receive
+* their own `MessagePortTransport` binding. Portless string events use the scope's
+* implicit channel. The returned disposer removes the listener, unbinds the implicit
+* channel, and closes every accepted port binding.
+*
+* @param scope - The hostable worker scope to wire
+* @param options - The tools, optional identity, and optional port-event gate
+* @returns An idempotent disposer for every binding owned by this call
+*/
+function serveMCPScope(scope, options) {
+	const server = createMCPServer({
+		tools: options.tools,
+		name: options.name ?? "taverna",
+		version: options.version ?? "1.0.0"
+	});
+	const scopeTransport = createScopeTransport(scope);
+	const unbindScope = bindServer(server, scopeTransport);
+	const teardowns = /* @__PURE__ */ new Set();
+	const onMessage = createScopeMessageListener(server, scopeTransport, teardowns, options);
+	scope.addEventListener("message", onMessage);
+	let disposed = false;
+	return () => {
+		if (disposed) return;
+		disposed = true;
+		scope.removeEventListener("message", onMessage);
+		unbindScope();
+		for (const teardown of teardowns) teardown();
+		teardowns.clear();
+	};
+}
+/**
+* Boot an `MCPServer` inside the current hostable worker scope.
+*
+* @param options - The tools, optional identity, and optional port-event gate
+* @returns The disposer returned by {@link serveMCPScope}
+*/
+function serveMCP(options) {
+	return serveMCPScope(globalThis, options);
+}
+//#endregion
+export { DEFAULT_MCP_SERVER_NAME, DEFAULT_MCP_SERVER_VERSION, HTTPClientTransport, MCP_PROTOCOL_VERSION_HEADER, MCP_SESSION_HEADER, MCP_WEBSOCKET_SUBPROTOCOL, MessagePortTransport, WebSocketClientTransport, createHTTPClientTransport, createMessagePortTransport, createScopeMessageListener, createScopeTransport, createWebSocketClientTransport, decodeEvent, readEventStream, serveMCP, serveMCPScope };
+
+//# sourceMappingURL=index.js.map