@orkestrel/mcp 0.0.27 → 0.0.29

package/dist/src/browser/index.js

@@ -1,298 +1,64 @@
-import { bindServer, buildHeaderParameters, buildHeaderProjection, createMCPServer, encodeSentinel, inferRequestVersion, isJSONRPCResponse, isMCPVersion, isModernRequest, parseJSONRPCMessage } from "../core/index.js";
-import { isArray, isRecord, isString } from "@orkestrel/contract";
-import { createSSEParser } from "@orkestrel/sse";
+import { isString } from "@orkestrel/contract";
+import { HTTPClientTransport, MCP_WEBSOCKET_SUBPROTOCOL, bindServer, createMCPServer, deliverMessage } from "../core/index.js";
 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 MCP protocol version. Modern
-* requests derive it from their own `_meta`; legacy requests echo the negotiated
-* initialize result on each subsequent request.
-*/
-var MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
-/**
-* The modern Streamable-HTTP request header carrying the JSON-RPC method. It is
-* emitted on every modern request and never on a legacy request.
-*/
-var MCP_METHOD_HEADER = "mcp-method";
-/**
-* The modern Streamable-HTTP request header carrying a named target. The browser
-* HTTP client emits it only for `tools/call`, from that request's `params.name`.
-*/
-var MCP_NAME_HEADER = "mcp-name";
-/** 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. */
+/** Supplies the default server name `createScopeServer` reports (`initialize`'s `serverInfo.name`) when `options.name` is omitted. */
+var DEFAULT_MCP_SERVER_NAME = "@orkestrel/mcp";
+/** Supplies the default server version `createScopeServer` 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'`, which `createWebSocketServer` selects when the client offers it. 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/HTTPClientTransport.ts
-/**
-* The browser-face HTTP CLIENT transport for the Model Context Protocol — a
-* {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
-* over the native `fetch`, the browser sibling of the Node face's
-* {@link import('@orkestrel/mcp/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` (for example, an
-*   `Authorization` bearer). It then decodes the reply and emits each decoded
-*   {@link JSONRPCMessage} on the `message` event the
-*   {@link import('@orkestrel/mcp').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 with 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 headers.** `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` alone on
-*   subsequent legacy requests. Modern requests instead derive protocol and method
-*   headers from the message, plus the name header only for `tools/call` — carried in the
-*   protocol's Base64 sentinel form whenever the tool name cannot ride as plain ASCII.
-*   Before initialize returns, neither captured legacy header is sent.
-*   `close()` clears the captured protocol so a reconnect's `initialize`
-*   POST is headerless; the captured `session` persists across `close()`.
-* - **`close()` releases what is in flight.** Every `fetch` this transport still has open is
-*   ABORTED, which cancels the response body a `send` is reading — an SSE reply the server
-*   never ends would otherwise outlive the transport, with nothing left able to reach it. The
-*   aborted read surfaces on `error` and the `send` reporting it resolves. `close()` is
-*   idempotent (one `close` event per connected lifetime), and `start()` opens the next one.
-* - **Total at the boundary.** 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.** Owns the `emitter` ({@link MCPClientTransportEventMap}); 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;
-	#pending = /* @__PURE__ */ new Set();
-	#parameters = /* @__PURE__ */ new Map();
-	#stamps = /* @__PURE__ */ new WeakMap();
-	#session = void 0;
-	#protocol = void 0;
-	#generation = 0;
-	#closed = false;
-	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;
-	}
-	get duplex() {
-		return false;
-	}
-	async start() {
-		this.#closed = false;
-	}
-	async send(message) {
-		this.#stamp(message);
-		const request = new AbortController();
-		this.#pending.add(request);
-		try {
-			await this.#exchange(message, request.signal);
-		} finally {
-			this.#pending.delete(request);
-		}
-	}
-	#stamp(message) {
-		if (!isModernRequest(message) || message.method !== "tools/list") return;
-		if (message.params?.["cursor"] === void 0) this.#generation += 1;
-		this.#stamps.set(message, this.#generation);
-	}
-	async #exchange(message, signal) {
-		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.#buildHeaders(message),
-					...this.#headers
-				},
-				body: JSON.stringify(message),
-				signal: this.#timeout === void 0 ? signal : AbortSignal.any([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, message);
-	}
-	async close() {
-		if (this.#closed) return;
-		this.#closed = true;
-		for (const request of this.#pending) request.abort();
-		this.#pending.clear();
-		this.#protocol = void 0;
-		this.#emitter.emit("close");
-	}
-	#buildHeaders(message) {
-		if (isModernRequest(message)) {
-			const version = inferRequestVersion(message);
-			const name = message.params?.["name"];
-			return {
-				...version === void 0 ? {} : { [MCP_PROTOCOL_VERSION_HEADER]: version },
-				[MCP_METHOD_HEADER]: message.method,
-				...message.method === "tools/call" && isString(name) ? {
-					[MCP_NAME_HEADER]: encodeSentinel(name),
-					...buildHeaderProjection(this.#parameters.get(name) ?? [], message.params?.["arguments"])
-				} : {}
-			};
-		}
-		return this.#protocol === void 0 ? {} : { [MCP_PROTOCOL_VERSION_HEADER]: this.#protocol };
-	}
-	async #deliver(response, sent) {
-		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, sent);
-				return;
-			}
-			if (type.includes("application/json")) {
-				const message = parseJSONRPCMessage(await response.json());
-				if (message !== void 0) this.#capture(message, sent);
-			}
-		} catch (error) {
-			this.#emitter.emit("error", error);
-		}
-	}
-	#capture(message, sent) {
-		if (isJSONRPCResponse(message) && isRecord(message.result) && isMCPVersion(message.result["protocolVersion"])) this.#protocol = message.result["protocolVersion"];
-		this.#emitter.emit("message", this.#select(message, sent));
-	}
-	#select(message, sent) {
-		if (!isModernRequest(sent) || sent.method !== "tools/list") return message;
-		if (!isJSONRPCResponse(message) || message.error !== void 0) return message;
-		const result = message.result;
-		const listed = isRecord(result) ? result["tools"] : void 0;
-		if (!isRecord(result) || !isArray(listed)) return message;
-		const current = this.#stamps.get(sent) === this.#generation;
-		if (current && sent.params?.["cursor"] === void 0) this.#parameters.clear();
-		const kept = [];
-		for (const tool of listed) {
-			if (!isRecord(tool) || !isString(tool["name"])) {
-				kept.push(tool);
-				continue;
-			}
-			const parameters = buildHeaderParameters(tool["inputSchema"]);
-			if (parameters === void 0) {
-				this.#emitter.emit("error", /* @__PURE__ */ new Error(`MCP tool '${tool["name"]}' is excluded from tools/list: its inputSchema carries an invalid x-mcp-header annotation`));
-				continue;
-			}
-			if (current) this.#parameters.set(tool["name"], parameters);
-			kept.push(tool);
-		}
-		return {
-			...message,
-			result: {
-				...result,
-				tools: kept
-			}
-		};
-	}
-};
 //#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`.
+* Carries the Model Context Protocol over a native `MessagePort` from the browser face — a
+* {@link MCPTransportInterface}, 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 `@orkestrel/mcp`'s `MCPClientTransportInterface`), a `MessagePort` is a
-*   plain duplex channel — the SAME class implements `@orkestrel/mcp`'s
-*   `MCPTransportInterface` and is handed to EITHER `bindServer` or
+*   / {@link import('@orkestrel/mcp').HTTPClientTransport} (CLIENT-only
+*   carriers of `@orkestrel/mcp`'s `MCPMessageTransportInterface`), a `MessagePort` is a
+*   plain duplex channel — the same class implements `@orkestrel/mcp`'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 with `addEventListener` (as opposed to the `onmessage`
+*   required when listening with `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`
+*   begins dispatching queued messages the moment the transport exists. This is safe
+*   inside `createScopeServer`'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
+*   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 —
+*   object) is ignored — dropped silently, never forwarded, never thrown —
 *   because `MCPTransportInterface` carries no `error` channel for this port to
-*   surface a non-string frame on (unlike `MCPClientTransportInterface`'s `emitter`);
+*   surface a non-string frame on (unlike `MCPMessageTransportInterface`'s `emitter`);
 *   silently ignoring is the total, contract-shaped choice.
-* - **`messageerror` is IGNORED, not routed to `closed`.** A `messageerror` event
+* - **`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
+*   bad frame, not a dead channel — the port itself keeps working and later, well-
+*   formed messages still arrive. This transport registers no listener for it: an
+*   unhandled `messageerror` on a `MessagePort` neither throws, closes the port, nor
+*   reaches this transport, so one bad frame costs exactly that frame and nothing
+*   tears the binding down. 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.
+*   over a single malformed frame.
 * - **`close()`** is idempotent: it closes the underlying `port` (`MessagePort.close()`
-*   disconnects it — further `postMessage` calls on EITHER end are silently
+*   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()`.
+*   event) — `closed` fires only from this transport's own `close()`.
 * - **Single-handler-replace (the port contract, `@orkestrel/mcp`'s `MCPTransportInterface`
 *   doc).** `listen`/`closed` each hold the one active handler; a
-*   second call REPLACES the first rather than adding a second subscriber.
+*   second call replaces the first rather than adding a second subscriber.
 *
 * @example
 * ```ts
@@ -308,14 +74,12 @@ var HTTPClientTransport = class {
 var MessagePortTransport = class {
 	#port;
 	#message = (event) => this.#receive(event.data);
-	#malformed = () => {};
 	#onMessage = void 0;
 	#onClosed = void 0;
 	#closed = false;
 	constructor(options) {
 		this.#port = options.port;
 		this.#port.addEventListener("message", this.#message);
-		this.#port.addEventListener("messageerror", this.#malformed);
 		this.#port.start();
 	}
 	send(message) {
@@ -335,7 +99,6 @@ var MessagePortTransport = class {
 		this.#onMessage = void 0;
 		this.#onClosed = void 0;
 		this.#port.removeEventListener("message", this.#message);
-		this.#port.removeEventListener("messageerror", this.#malformed);
 		this.#port.close();
 		onClosed?.();
 	}
@@ -347,43 +110,42 @@ var MessagePortTransport = class {
 //#endregion
 //#region src/browser/transports/WebSocketClientTransport.ts
 /**
-* The browser-face WebSocket CLIENT transport for the Model Context Protocol — a
-* {@link MCPClientTransportInterface} that drives a REMOTE MCP server over the native
-* `WebSocket` global, the browser sibling of the Node face's
-* {@link import('@orkestrel/mcp/server').WebSocketClientTransport}.
+* Drives a remote MCP server over the native `WebSocket` global from the browser face, as a
+* client {@link MCPMessageTransportInterface}. This class is the browser sibling of the Node
+* face's {@link import('@orkestrel/mcp/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()`.
+*   `'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`. A queue rides ONE
-*   connection: a close DISCARDS whatever is still in it.
-* - **A closed channel REJECTS.** The native socket confirms nothing about a write, so this
+*   is even called) is queued and flushed, in order, the moment the socket opens —
+*   so a caller need not await `start()` before calling `send`. A queue rides one
+*   connection: a close discards whatever is still in it.
+* - **A closed channel rejects.** The native socket confirms nothing about a write, so this
 *   transport answers from its own state: a `send` after `close()`, or on a socket already
-*   reporting `CLOSING` / `CLOSED`, REJECTS with `WebSocket transport is not connected` rather
+*   reporting `CLOSING` / `CLOSED`, rejects with `WebSocket transport is not connected` rather
 *   than resolving on a frame nobody wrote. Only the closed state rejects — a pre-open `send`
 *   still queues.
-* - **Inbound (`message`).** Each decoded text frame is `JSON.parse`d (guarded) and
-*   narrowed with `parseJSONRPCMessage` — a well-formed {@link JSONRPCMessage}
+* - **Inbound (`message`).** Each decoded text frame runs through the shared
+*   `deliverMessage` fold (parse, then narrow) — 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 (never
+*   non-JSON / non-message text frame surfaces on `error` and is dropped (never
 *   throws on adversarial wire input).
 * - **`close()`** unsubscribes from the underlying socket, closes it, 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
+*   same `close` exactly once total — `close()` first flips the guard, so the native event
 *   never double-emits, and the released socket reports its own close to nobody. Closing before
 *   the socket opens resolves the pending `start()` rather than leaving it pending, matching the
-*   Node face. A `send` issued after `close()` REJECTS (it is never queued), and the
-*   pre-open queue is DISCARDED — by `close()` and by the native `close` event alike — so a
+*   Node face. A `send` issued after `close()` rejects (it is never queued), and the
+*   pre-open queue is discarded — by `close()` and by the native `close` event alike — so a
 *   closed transport delivers nothing until a `start()` opens a new connection, and nothing
 *   the caller handed the abandoned connection rides that one.
-* - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); every
-*   emit the emitter isolates a listener throw; `error` is a DOMAIN event (a
+* - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); every
+*   emit the emitter isolates a listener throw; `error` is a domain event (a
 *   transport-level fault).
 *
 * @example
@@ -412,7 +174,7 @@ var WebSocketClientTransport = class {
 		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];
+		this.#protocols = typeof protocols === "string" ? protocols : protocols === void 0 ? MCP_WEBSOCKET_SUBPROTOCOL : protocols.length === 0 ? void 0 : [...protocols];
 	}
 	get emitter() {
 		return this.#emitter;
@@ -501,19 +263,7 @@ var WebSocketClientTransport = class {
 			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);
+		deliverMessage(this.#emitter, data, "non-JSON-RPC WebSocket frame");
 	}
 	#onClose() {
 		if (this.#closed) return;
@@ -527,23 +277,23 @@ var WebSocketClientTransport = class {
 //#endregion
 //#region src/browser/factories.ts
 /**
-* Creates the browser-face WebSocket CLIENT transport for an
-* {@link import('@orkestrel/mcp').MCPClientInterface} — a {@link MCPClientTransportInterface}
-* that drives a REMOTE MCP server over the native `WebSocket` global, the browser
-* sibling of the Node face's `createWebSocketClientTransport` (`@orkestrel/mcp/server`).
+* Creates the browser-face WebSocket client transport for an
+* {@link import('@orkestrel/mcp').MCPClientInterface} — a {@link MCPMessageTransportInterface}
+* that drives a remote MCP server over the native `WebSocket` global. This factory is the
+* browser sibling of the Node face's `createWebSocketClientTransport` (`@orkestrel/mcp/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,
+* 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
+* @param options - `url` (the remote WebSocket endpoint; required) and optional
 *   `protocols` (the WebSocket subprotocol(s) to request); see
 *   {@link WebSocketClientTransportOptions}
-* @returns A working {@link MCPClientTransportInterface} over the native `WebSocket`
+* @returns A working {@link MCPMessageTransportInterface} over the native `WebSocket`
 *
 * @example
 * ```ts
@@ -561,31 +311,36 @@ function createWebSocketClientTransport(options) {
 	return new WebSocketClientTransport(options);
 }
 /**
-* Creates the browser-face HTTP CLIENT transport for an
-* {@link import('@orkestrel/mcp').MCPClientInterface} — a {@link MCPClientTransportInterface}
-* that drives a REMOTE Streamable-HTTP MCP server over the native `fetch`, the
-* browser sibling of the Node face's `createHTTPClientTransport` (`@orkestrel/mcp/server`).
+* Creates the HTTP client transport for an
+* {@link import('@orkestrel/mcp').MCPClientInterface} — a {@link MCPMessageTransportInterface}
+* that drives a remote Streamable-HTTP MCP server over the native `fetch`.
+*
+* @remarks
+* It returns the core {@link import('@orkestrel/mcp').HTTPClientTransport}, the same class the
+* Node face's `createHTTPClientTransport` returns, because the class touches `fetch`,
+* `Response`, `AbortController`, `AbortSignal`, and `WeakMap` alone. This factory exists so a
+* page imports its transport from the face it already imports everything else from.
 *
 * @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,
+* with either — a plain JSON envelope or a Streamable-HTTP SSE `data:` event,
 * decoded with `@orkestrel/sse`), and the reply is surfaced on the transport's
 * `message` event for the client's id correlation. Add `options.headers` (for example, an
 * `Authorization` bearer) to reach a guarded server. `start` / `close` hold no
-* connection; against a STATEFUL server it captures the `mcp-session-id` from
+* 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` alone on subsequent
 * legacy requests. Modern requests instead derive `mcp-protocol-version` and
 * `mcp-method` from the message, plus `mcp-name` only for `tools/call`, so the
 * same `MCPClient` passes either era's protocol gates without caller wiring.
 *
-* @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged
+* @param options - `url` (the remote endpoint; required), optional `headers` merged
 *   onto every request, optional `fetch` (default `globalThis.fetch`), and optional
 *   `timeout` (ms, applied with `AbortSignal.timeout`); see
 *   {@link HTTPClientTransportOptions}
-* @returns A working {@link MCPClientTransportInterface} over the native `fetch`
+* @returns A working {@link MCPMessageTransportInterface} over the native `fetch`
 *
 * @example
 * ```ts
@@ -605,7 +360,7 @@ function createHTTPClientTransport(options) {
 /**
 * Creates the browser-face `MessagePort` transport — a
 * {@link import('@orkestrel/mcp').MCPTransportInterface} over a native `MessagePort`, the
-* SYMMETRIC carrier that works as either a server or a client transport depending on
+* symmetric carrier that works as either a server or a client transport depending on
 * which binder ({@link import('@orkestrel/mcp').bindServer} or
 * {@link import('@orkestrel/mcp').bindClient}) it is handed to.
 *
@@ -615,7 +370,7 @@ function createHTTPClientTransport(options) {
 * 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
+* @param options - `port` (the `MessagePort` half to drive; required); see
 *   {@link MessagePortTransportOptions}
 * @returns A working {@link import('@orkestrel/mcp').MCPTransportInterface} over the port
 *
@@ -633,143 +388,92 @@ function createMessagePortTransport(options) {
 	return new MessagePortTransport(options);
 }
 /**
-* Adapts 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.
+* Creates an `MCPServer` hosted inside a worker scope and wires that scope's message events
+* to it — the browser face's bootstrap, and the twin of the Node face's `createStdioServer`.
 *
 * @remarks
-* `send` writes each outbound string through `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.
+* `scope` defaults to `globalThis`, which is `self` inside a dedicated Web Worker or a
+* Service Worker, so a worker boots with `createScopeServer({ tools })` alone; pass a scope
+* explicitly to host a server on a double or on another message-event-bearing object.
 *
-* @param scope - The hostable scope to adapt (structurally, `self` / `globalThis`
-*   inside a dedicated Web Worker)
-* @returns A {@link ScopeTransportInterface} `serveMCPScope` binds and drives through `deliver`
+* 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 handle's `stop` removes the listener, unbinds the implicit
+* channel, closes every accepted port binding, and drops the ports themselves — the
+* bindings are held in one map keyed by port, so nothing survives the clear. The served
+* endpoint is modern-only: it answers a legacy `initialize` with `-32601`. A dual-era
+* worker composes `bindServer(createMCPLegacy(mcp), …)` instead of this factory.
+*
+* @param options - The tools, optional identity, and optional port-event gate; see
+*   {@link ScopeServerOptions}
+* @param scope - The hostable scope to wire; defaults to `globalThis`
+* @returns A {@link ScopeServerInterface} whose `stop` ends every binding this call owns
 *
 * @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/helpers.ts
-/**
-* Decodes 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.
+* import { createScopeServer } from '@orkestrel/mcp/browser'
+* import { createToolManager } from '@orkestrel/tool'
 *
-* @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: 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;
-	}
-}
-/**
-* Decodes 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} through {@link decodeEvent} (so a non-message / non-JSON `data:`
-* event is DROPPED, never thrown — total). 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
+* // Inside a Web Worker: the scope defaults to `globalThis`.
+* const worker = createScopeServer({ tools: createToolManager() })
+* // ... later, release every binding this call owns:
+* worker.stop()
+* ```
 */
-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);
-			}
+function createScopeServer(options, scope = globalThis) {
+	const server = createMCPServer({
+		tools: options.tools,
+		identity: {
+			name: options.name ?? "@orkestrel/mcp",
+			version: options.version ?? "1.0.0"
 		}
-	} finally {
-		reader.releaseLock();
-	}
-	return messages;
+	});
+	const scopeTransport = createScopeTransport(scope);
+	const unbindScope = bindServer(server, scopeTransport);
+	const teardowns = /* @__PURE__ */ new Map();
+	const onMessage = createScopeMessageListener(server, scopeTransport, teardowns, options);
+	scope.addEventListener("message", onMessage);
+	let stopped = false;
+	return { stop() {
+		if (stopped) return;
+		stopped = true;
+		scope.removeEventListener("message", onMessage);
+		unbindScope();
+		for (const teardown of teardowns.values()) teardown();
+		teardowns.clear();
+	} };
 }
 /**
-* Builds `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.
+* Builds {@link createScopeServer}'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
+* 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` KEYED BY THAT PORT. A port already present is IGNORED — repeated delivery
+* into `teardowns` keyed by that port. A port already present is ignored — repeated delivery
 * of the same `MessagePort` would create duplicate bindings over one port (→ duplicated
 * replies), so a repeat is silently dropped.
 *
-* The key is what makes `teardowns` the ONLY place an accepted port is remembered. A separate
-* seen-port set would be a second collection over the same lifetime, and the caller's disposer
-* would have to remember to empty both — so a long-lived scope such as a Service Worker would
-* retain every port it ever accepted, closed and unbound ones included. Membership answers
-* "already bound?" and `clear()` drops the binding and the dedup together.
+* The key is what makes `teardowns` the only place an accepted port is remembered. A separate
+* seen-port set would be a second collection over the same lifetime, and the scope server's
+* `stop` would have to remember to empty both — so a long-lived scope such as a Service Worker
+* would retain every port it ever accepted, closed and unbound ones included. Membership
+* answers "already bound?" and `clear()` drops the binding and the dedup together.
 *
-* This branch fires on EITHER a Service-Worker-shaped scope (its normal per-client
+* 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
+* 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, 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 map `serveMCPScope`'s dispose drains and clears, keyed by the accepted port; each port-bearing event adds one entry
-* @param options - The `ServeMCPOptions` (for `options.accept`)
+* @param teardowns - The shared teardown map the scope server's `stop` drains and clears, keyed by the accepted port; each port-bearing event adds one entry
+* @param options - The `ScopeServerOptions` (for `options.accept`)
 * @returns The `message`-event listener to register (and later remove) on the scope
 *
 * @example
@@ -801,58 +505,51 @@ function createScopeMessageListener(server, scopeTransport, teardowns, options)
 	};
 }
 /**
-* Boots an `MCPServer` inside a hostable worker scope and wires its message events to it.
+* Adapts a hostable {@link ScopeInterface} (`self` in a dedicated Web Worker, or any
+* structurally matching double) into a {@link ScopeTransportInterface} — the implicit,
+* portless message channel {@link createScopeServer} binds for the dedicated-worker shape.
 *
 * @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, closes every accepted port binding, and drops the ports themselves — the
-* bindings are held in one map keyed by port, so nothing survives the clear. The served
-* endpoint is modern-only: it answers a legacy `initialize` with `-32601`. A dual-era
-* worker composes `bindServer(createMCPLegacy(mcp), …)` instead of this function.
+* `send` writes each outbound string through `scope.postMessage`. `listen`/`closed`
+* register the single handler `deliver` / the underlying close path route through —
+* the scope server'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 the scope server 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 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
+* @param scope - The hostable scope to adapt (structurally, `self` / `globalThis`
+*   inside a dedicated Web Worker)
+* @returns A {@link ScopeTransportInterface} the scope server binds and drives through `deliver`
+*
+* @example
+* ```ts
+* const scopeTransport = createScopeTransport(self)
+* const unbind = bindServer(server, scopeTransport)
+* ```
 */
-function serveMCPScope(scope, options) {
-	const server = createMCPServer({
-		tools: options.tools,
-		identity: {
-			name: options.name ?? "taverna",
-			version: options.version ?? "1.0.0"
+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);
 		}
-	});
-	const scopeTransport = createScopeTransport(scope);
-	const unbindScope = bindServer(server, scopeTransport);
-	const teardowns = /* @__PURE__ */ new Map();
-	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.values()) teardown();
-		teardowns.clear();
 	};
 }
-/**
-* Boots an `MCPServer` inside the current hostable worker scope.
-*
-* @remarks
-* The served endpoint is modern-only: it answers a legacy `initialize` with `-32601`. A
-* dual-era worker composes `bindServer(createMCPLegacy(mcp), …)` instead of this function.
-*
-* @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_METHOD_HEADER, MCP_NAME_HEADER, MCP_PROTOCOL_VERSION_HEADER, MCP_SESSION_HEADER, MCP_WEBSOCKET_SUBPROTOCOL, MessagePortTransport, WebSocketClientTransport, createHTTPClientTransport, createMessagePortTransport, createScopeMessageListener, createScopeTransport, createWebSocketClientTransport, decodeEvent, readEventStream, serveMCP, serveMCPScope };
+export { DEFAULT_MCP_SERVER_NAME, DEFAULT_MCP_SERVER_VERSION, MessagePortTransport, WebSocketClientTransport, createHTTPClientTransport, createMessagePortTransport, createScopeMessageListener, createScopeServer, createScopeTransport, createWebSocketClientTransport };
 
 //# sourceMappingURL=index.js.map