@orkestrel/mcp 0.0.4 → 0.0.5

package/dist/src/browser/index.js

@@ -0,0 +1,755 @@
+import { bindServer, createMCPServer, parseJSONRPCMessage } from "../core/index.js";
+import { 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 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 (`serve.ts`) `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 (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 (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} (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 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/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 messages = Array.isArray(message) ? message : [message];
+		for (const one of messages) {
+			const text = JSON.stringify(one);
+			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, 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 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` (`serve.ts`) 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);
+		}
+	};
+}
+//#endregion
+//#region src/browser/serve.ts
+/**
+* Boot an `MCPServer` inside a hostable scope (a dedicated Web Worker's `self`, or a
+* Service Worker's `self`) and wire its message events to it.
+*
+* @remarks
+* **Trust boundary — mechanism, not policy.** `serveMCPScope` exposes the ENTIRE
+* supplied `tools` registry to EVERY client the scope accepts a port from, with NO
+* built-in origin or identity check. In a Service Worker that means every same-origin
+* context the SW controls (any window, worker, or iframe can
+* `controller.postMessage(msg, [port])` and get a fully-bound server with complete
+* tool-call access). Origin allow-listing, handshake tokens, and any other gating are
+* the embedding application's responsibility — compose a guard in front. Use the
+* `accept` option to gate port-bearing events before binding: return `false` to drop
+* the event entirely (no binding, no reply).
+*
+* **Lifetime / per-client binding accumulation.** Each accepted port-bearing event
+* creates a fresh `MessagePortTransport` + `bindServer` binding that lives for the
+* scope's lifetime — there is NO per-client reaping, because `MessagePort` provides
+* no "peer closed" signal. For bounded, long-lived client sets this is fine; embedders
+* with high client churn must track and invoke the dispose function themselves to
+* avoid unbounded accumulation.
+*
+* **Portless events and the implicit scope channel.** A portless `message` event
+* (e.g. `controller.postMessage('<json-rpc>')` in a Service Worker) delivers its
+* string directly to the implicit scope transport — **the tool EXECUTES** — even
+* though no reply can reach the caller. In a `ServiceWorkerGlobalScope` the reply
+* path (`scopeTransport.send` → `scope.postMessage`) throws (no `self.postMessage`),
+* and `bindServer` routes the throw to the server emitter's `error` event (see
+* `@src/core bindServer`), so the un-repliable reply is dropped. The net effect is
+* **blind side-effecting ingress**: the tool runs but the caller gets no result.
+* Crucially, **`accept` does NOT gate this channel** — it is consulted only for
+* port-bearing events. In a Service Worker, if `accept` is your sole guard, ensure
+* all clients connect through transferred `MessagePort`s (port-bearing messages), or
+* restrict the exposed tools to side-effect-free operations, or validate a token
+* inside the tools themselves.
+*
+* Binds the implicit scope channel EAGERLY (at call time, not lazily on first use) —
+* `bindServer` is called once against a {@link import('./types.js').ScopeTransportInterface}
+* wrapping `scope` for the whole lifetime of the returned dispose, so a dedicated
+* worker's very first portless message is served with no first-use setup cost or
+* ordering hazard.
+*
+* Every inbound `message` event is inspected structurally: `event.ports.length > 0`
+* spawns a fresh {@link import('./factories.js').createMessagePortTransport} +
+* `bindServer` for THAT port (tracked for teardown) — this holds even on a
+* dedicated-worker-shaped scope, the unified design's deliberate cross-case. An
+* event with NO ports and a STRING `event.data` is delivered onto the implicit scope
+* channel; any other event (no ports, non-string data) is dropped.
+*
+* @param scope - The hostable scope to wire (structurally, `self` inside a worker)
+* @param options - `tools` (the live registry to expose; REQUIRED), optional
+*   `name`/`version` (default {@link import('./constants.js').DEFAULT_MCP_SERVER_NAME} /
+*   {@link import('./constants.js').DEFAULT_MCP_SERVER_VERSION}), optional `accept`
+*   (origin/identity gate for port-bearing events); see {@link ServeMCPOptions}
+* @returns A dispose function — unbinds every binding, closes every accepted
+*   `MessagePort`, and removes the scope's `message` listener. Idempotent.
+*
+* @example
+* ```ts
+* const scope = { postMessage() {}, addEventListener() {}, removeEventListener() {} }
+* const dispose = serveMCPScope(scope, {
+*   tools: createToolManager(),
+*   // Prefer token-in-data — event.origin is empty for same-origin worker messages.
+*   accept: (event) => event.data === 'my-secret-token',
+* })
+* // ... later:
+* dispose()
+* ```
+*/
+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 scope (`globalThis` — a dedicated
+* Web Worker or a Service Worker) and wire its message events to it.
+*
+* @remarks
+* A one-liner over {@link serveMCPScope}: `serveMCP(options)` is exactly
+* `serveMCPScope(globalThis, options)`. Kept as its own export so the scope-facing
+* wiring stays independently testable (AGENTS §5) — drive {@link serveMCPScope}
+* directly with a scope double for a test, and this thin wrapper for real deploys.
+*
+* **Trust boundary and lifecycle** — see {@link serveMCPScope}'s `@remarks`. The same
+* considerations apply: ENTIRE tool registry exposed to every accepted port-bearing
+* event; use `accept` to gate; per-client bindings accumulate for the scope's lifetime.
+*
+* @param options - `tools` (the live registry to expose; REQUIRED), optional
+*   `name`/`version`, optional `accept` (origin/identity gate); see {@link ServeMCPOptions}
+* @returns A dispose function — see {@link serveMCPScope}
+*
+* @example
+* ```ts
+* // Inside a dedicated Web Worker's entry module:
+* import { serveMCP } from '@orkestrel/mcp/browser'
+* import { createToolManager, createTool } from '@orkestrel/agent'
+*
+* const tools = createToolManager()
+* tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
+* const dispose = serveMCP({ tools, name: 'worker-mcp', version: '1.0.0' })
+* // ... later, on teardown:
+* dispose()
+* ```
+*/
+function serveMCP(options) {
+	return serveMCPScope(globalThis, options);
+}
+//#endregion
+export { DEFAULT_MCP_SERVER_NAME, DEFAULT_MCP_SERVER_VERSION, HTTPClientTransport, MCP_SESSION_HEADER, MCP_WEBSOCKET_SUBPROTOCOL, MessagePortTransport, WebSocketClientTransport, createHTTPClientTransport, createMessagePortTransport, createScopeMessageListener, createScopeTransport, createWebSocketClientTransport, decodeEvent, readEventStream, serveMCP, serveMCPScope };
+
+//# sourceMappingURL=index.js.map