@orkestrel/mcp 0.0.26 → 0.0.28

package/dist/src/browser/index.js

@@ -1,214 +1,22 @@
-import { bindServer, createMCPServer, inferRequestVersion, isJSONRPCResponse, isMCPVersion, isModernRequest, parseJSONRPCMessage } from "../core/index.js";
-import { 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`.
-*   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();
-	#session = void 0;
-	#protocol = void 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) {
-		const request = new AbortController();
-		this.#pending.add(request);
-		try {
-			await this.#exchange(message, request.signal);
-		} finally {
-			this.#pending.delete(request);
-		}
-	}
-	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);
-	}
-	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]: name } : {}
-			};
-		}
-		return this.#protocol === void 0 ? {} : { [MCP_PROTOCOL_VERSION_HEADER]: this.#protocol };
-	}
-	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) && isMCPVersion(message.result["protocolVersion"])) this.#protocol = message.result["protocolVersion"];
-		this.#emitter.emit("message", message);
-	}
-};
 //#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
+*   / {@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
@@ -219,7 +27,7 @@ var HTTPClientTransport = class {
 *   `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`
+*   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
@@ -231,16 +39,17 @@ var HTTPClientTransport = class {
 *   non-string `event.data` (a host or a misbehaving peer posting a structured
 *   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
 *   (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
+*   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
 *   undelivered, per the platform contract) and fires the registered `closed`
@@ -265,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) {
@@ -292,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?.();
 	}
@@ -304,9 +110,8 @@ 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
+* Drives a REMOTE MCP server over the native `WebSocket` global from the browser face — a
+* CLIENT {@link MCPMessageTransportInterface}, the browser sibling of the Node face's
 * {@link import('@orkestrel/mcp/server').WebSocketClientTransport}.
 *
 * @remarks
@@ -318,9 +123,15 @@ var MessagePortTransport = class {
 * - **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}
+*   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
+*   than resolving on a frame nobody wrote. Only the closed state rejects — a pre-open `send`
+*   still queues.
+* - **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
 *   throws on adversarial wire input).
@@ -329,9 +140,11 @@ var MessagePortTransport = class {
 *   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()` is silently dropped (not queued), so a closed
-*   transport delivers nothing until a `start()` opens a new connection.
-* - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); every
+*   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 MCPMessageTransportEventMap}); every
 *   emit the emitter isolates a listener throw; `error` is a DOMAIN event (a
 *   transport-level fault).
 *
@@ -361,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;
@@ -385,15 +198,16 @@ var WebSocketClientTransport = class {
 		});
 	}
 	async send(message) {
-		if (this.#closed) return;
-		const text = JSON.stringify(message);
 		const socket = this.#socket;
+		if (this.#closed || socket?.readyState === WebSocket.CLOSING || socket?.readyState === WebSocket.CLOSED) throw new Error("WebSocket transport is not connected");
+		const text = JSON.stringify(message);
 		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;
+		this.#queue = [];
 		const socket = this.#socket;
 		const resolve = this.#resolve;
 		this.#releaseHandshake();
@@ -449,23 +263,12 @@ 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;
 		this.#closed = true;
+		this.#queue = [];
 		this.#release();
 		this.#socket = void 0;
 		this.#emitter.emit("close");
@@ -475,7 +278,7 @@ var WebSocketClientTransport = class {
 //#region src/browser/factories.ts
 /**
 * Creates the browser-face WebSocket CLIENT transport for an
-* {@link import('@orkestrel/mcp').MCPClientInterface} — a {@link MCPClientTransportInterface}
+* {@link import('@orkestrel/mcp').MCPClientInterface} — a {@link MCPMessageTransportInterface}
 * that drives a REMOTE MCP server over the native `WebSocket` global, the browser
 * sibling of the Node face's `createWebSocketClientTransport` (`@orkestrel/mcp/server`).
 *
@@ -490,7 +293,7 @@ var WebSocketClientTransport = class {
 * @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
@@ -508,10 +311,15 @@ 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
@@ -532,7 +340,7 @@ function createWebSocketClientTransport(options) {
 *   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
@@ -580,116 +388,65 @@ 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
@@ -701,10 +458,10 @@ async function readEventStream(response) {
 * 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.
+* 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
 * channel) or a dedicated-worker-shaped one that happens to receive a port-bearing event
@@ -715,8 +472,8 @@ async function readEventStream(response) {
 *
 * @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
@@ -748,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