@orkestrel/mcp 0.0.19 → 0.0.21

package/dist/src/browser/index.js

@@ -33,8 +33,8 @@ var DEFAULT_MCP_SERVER_NAME = "taverna";
 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
+* `'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 `[]`
@@ -47,7 +47,7 @@ var MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
 * 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('@src/server').HTTPClientTransport}, honoring the SAME
+* {@link import('@orkestrel/mcp/server').HTTPClientTransport}, honoring the SAME
 * `mcp-session-id` semantics so it interoperates with an `MCPSession`-based server
 * unchanged.
 *
@@ -55,12 +55,12 @@ var MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
 * - **Request/response over `fetch`.** `send(message)` POSTs the JSON-serialized
 *   message to `options.url` with `content-type: application/json` and an
 *   `Accept` of BOTH `application/json` and `text/event-stream` (so the server may
-*   answer with either framing) — plus any `options.headers` (e.g. an
+*   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('@src/core').MCPClientInterface} subscribes to.
+*   {@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 via the
+*   `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
@@ -78,10 +78,15 @@ var MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
 *   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()`.
-* - **Total at the boundary (§14).** Every reply is narrowed (`parseJSONRPCMessage`,
+* - **`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 (§13).** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
+* - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
 *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.
 *
 * @example
@@ -97,8 +102,10 @@ var HTTPClientTransport = class {
 	#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;
@@ -115,8 +122,19 @@ var HTTPClientTransport = class {
 	get duplex() {
 		return false;
 	}
-	async start() {}
+	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, {
@@ -129,7 +147,7 @@ var HTTPClientTransport = class {
 					...this.#headers
 				},
 				body: JSON.stringify(message),
-				...this.#timeout === void 0 ? {} : { signal: AbortSignal.timeout(this.#timeout) }
+				signal: this.#timeout === void 0 ? signal : AbortSignal.any([signal, AbortSignal.timeout(this.#timeout)])
 			});
 		} catch (error) {
 			this.#emitter.emit("error", error);
@@ -140,6 +158,10 @@ var HTTPClientTransport = class {
 		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");
 	}
@@ -186,13 +208,13 @@ var HTTPClientTransport = class {
 * @remarks
 * - **Symmetric.** Unlike {@link import('./WebSocketClientTransport.js').WebSocketClientTransport}
 *   / {@link import('./HTTPClientTransport.js').HTTPClientTransport} (CLIENT-only
-*   carriers of `@src/core`'s `MCPClientTransportInterface`), a `MessagePort` is a
-*   plain duplex channel — the SAME class implements `@src/core`'s
+*   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
 *   `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`
+*   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
@@ -207,7 +229,7 @@ var HTTPClientTransport = class {
 *   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) —
+*   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`);
 *   silently ignoring is the total, contract-shaped choice.
@@ -225,8 +247,8 @@ var HTTPClientTransport = class {
 *   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
+* - **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.
 *
 * @example
@@ -242,13 +264,15 @@ 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", (event) => this.#receive(event.data));
-		this.#port.addEventListener("messageerror", () => {});
+		this.#port.addEventListener("message", this.#message);
+		this.#port.addEventListener("messageerror", this.#malformed);
 		this.#port.start();
 	}
 	send(message) {
@@ -264,8 +288,13 @@ var MessagePortTransport = class {
 	close() {
 		if (this.#closed) return;
 		this.#closed = true;
+		const onClosed = this.#onClosed;
+		this.#onMessage = void 0;
+		this.#onClosed = void 0;
+		this.#port.removeEventListener("message", this.#message);
+		this.#port.removeEventListener("messageerror", this.#malformed);
 		this.#port.close();
-		this.#onClosed?.();
+		onClosed?.();
 	}
 	#receive(data) {
 		if (!isString(data)) return;
@@ -278,7 +307,7 @@ var MessagePortTransport = class {
 * 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('@src/server').WebSocketClientTransport}.
+* {@link import('@orkestrel/mcp/server').WebSocketClientTransport}.
 *
 * @remarks
 * - **Host-performed handshake.** `start()` opens `new WebSocket(url, protocols)` and
@@ -293,15 +322,16 @@ var MessagePortTransport = class {
 * - **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
+*   non-JSON / non-message text frame surfaces on `error` and is DROPPED (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 MCPClientTransportEventMap}); every
+* - **`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
+*   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
 *   emit the emitter isolates a listener throw; `error` is a DOMAIN event (a
 *   transport-level fault).
 *
@@ -316,7 +346,15 @@ var WebSocketClientTransport = class {
 	#emitter;
 	#url;
 	#protocols;
+	#frame = (event) => this.#receive(event.data);
+	#ending = () => this.#onClose();
+	#failure = (event) => this.#emitter.emit("error", event);
+	#opening = () => this.#onOpen();
+	#rejection = () => this.#onHandshakeError();
 	#socket = void 0;
+	#handshake = void 0;
+	#resolve = void 0;
+	#reject = void 0;
 	#queue = [];
 	#closed = false;
 	constructor(options) {
@@ -339,16 +377,11 @@ var WebSocketClientTransport = class {
 		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 });
+			this.#handshake = socket;
+			this.#resolve = resolve;
+			this.#reject = reject;
+			socket.addEventListener("open", this.#opening);
+			socket.addEventListener("error", this.#rejection);
 		});
 	}
 	async send(message) {
@@ -362,18 +395,55 @@ var WebSocketClientTransport = class {
 		if (this.#closed) return;
 		this.#closed = true;
 		const socket = this.#socket;
+		const resolve = this.#resolve;
+		this.#releaseHandshake();
+		this.#release();
 		this.#socket = void 0;
 		if (socket !== void 0) socket.close();
 		this.#emitter.emit("close");
+		resolve?.();
 	}
 	#bind(socket) {
-		socket.addEventListener("message", (event) => this.#receive(event.data));
-		socket.addEventListener("close", () => this.#onClose());
-		socket.addEventListener("error", (event) => this.#emitter.emit("error", event));
+		socket.addEventListener("message", this.#frame);
+		socket.addEventListener("close", this.#ending);
+		socket.addEventListener("error", this.#failure);
+	}
+	#release() {
+		const socket = this.#socket;
+		if (socket === void 0) return;
+		socket.removeEventListener("message", this.#frame);
+		socket.removeEventListener("close", this.#ending);
+		socket.removeEventListener("error", this.#failure);
+	}
+	#releaseHandshake() {
+		const socket = this.#handshake;
+		if (socket === void 0) return;
+		socket.removeEventListener("open", this.#opening);
+		socket.removeEventListener("error", this.#rejection);
+		this.#handshake = void 0;
+		this.#resolve = void 0;
+		this.#reject = void 0;
 	}
 	#flush(socket) {
 		for (const text of this.#queue.splice(0)) socket.send(text);
 	}
+	#onOpen() {
+		const socket = this.#handshake;
+		const resolve = this.#resolve;
+		if (socket === void 0 || resolve === void 0) return;
+		this.#releaseHandshake();
+		this.#flush(socket);
+		resolve();
+	}
+	#onHandshakeError() {
+		const socket = this.#handshake;
+		const reject = this.#reject;
+		if (socket === void 0 || reject === void 0 || socket.readyState === WebSocket.OPEN) return;
+		this.#releaseHandshake();
+		this.#release();
+		this.#socket = void 0;
+		reject(/* @__PURE__ */ new Error("WebSocket connection failed"));
+	}
 	#receive(data) {
 		if (!isString(data)) {
 			this.#emitter.emit("error", /* @__PURE__ */ new Error("non-text WebSocket frame"));
@@ -396,6 +466,7 @@ var WebSocketClientTransport = class {
 	#onClose() {
 		if (this.#closed) return;
 		this.#closed = true;
+		this.#release();
 		this.#socket = void 0;
 		this.#emitter.emit("close");
 	}
@@ -403,10 +474,10 @@ var WebSocketClientTransport = class {
 //#endregion
 //#region src/browser/factories.ts
 /**
-* Create the browser-face WebSocket CLIENT transport for an
-* {@link import('@src/core').MCPClientInterface} — a {@link MCPClientTransportInterface}
+* 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` (`@src/server`).
+* sibling of the Node face's `createWebSocketClientTransport` (`@orkestrel/mcp/server`).
 *
 * @remarks
 * Hand it to `createMCPClient({ transport })`: `start()` (run by `client.connect()`)
@@ -437,18 +508,18 @@ function createWebSocketClientTransport(options) {
 	return new WebSocketClientTransport(options);
 }
 /**
-* Create the browser-face HTTP CLIENT transport for an
-* {@link import('@src/core').MCPClientInterface} — a {@link MCPClientTransportInterface}
+* 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` (`@src/server`).
+* browser sibling of the Node face's `createHTTPClientTransport` (`@orkestrel/mcp/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
+* 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
 * `initialize` and echoes it on later requests. It also captures the initialize
@@ -459,7 +530,7 @@ function createWebSocketClientTransport(options) {
 *
 * @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
+*   `timeout` (ms, applied with `AbortSignal.timeout`); see
 *   {@link HTTPClientTransportOptions}
 * @returns A working {@link MCPClientTransportInterface} over the native `fetch`
 *
@@ -479,11 +550,11 @@ function createHTTPClientTransport(options) {
 	return new HTTPClientTransport(options);
 }
 /**
-* Create the browser-face `MessagePort` transport — a
-* {@link import('@src/core').MCPTransportInterface} over a native `MessagePort`, the
+* 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
-* which binder ({@link import('@src/core').bindServer} or
-* {@link import('@src/core').bindClient}) it is handed to.
+* which binder ({@link import('@orkestrel/mcp').bindServer} or
+* {@link import('@orkestrel/mcp').bindClient}) it is handed to.
 *
 * @remarks
 * `port.start()` runs at construction (see {@link MessagePortTransport}'s doc for
@@ -493,28 +564,29 @@ function createHTTPClientTransport(options) {
 *
 * @param options - `port` (the `MessagePort` half to drive; REQUIRED); see
 *   {@link MessagePortTransportOptions}
-* @returns A working {@link import('@src/core').MCPTransportInterface} over the port
+* @returns A working {@link import('@orkestrel/mcp').MCPTransportInterface} over the port
 *
 * @example
 * ```ts
-* import { bindServer, createMCPServer } from '@orkestrel/mcp'
+* import { bindServer, createMCPLegacy, createMCPServer } from '@orkestrel/mcp'
 * import { createMessagePortTransport } from '@orkestrel/mcp/browser'
 *
 * const { port1, port2 } = new MessageChannel()
-* bindServer(createMCPServer({ identity: { name: 's', version: '1.0.0' }, tools }), createMessagePortTransport({ port: port1 }))
+* const mcp = createMCPServer({ identity: { name: 's', version: '1.0.0' }, tools })
+* bindServer(createMCPLegacy(mcp), createMessagePortTransport({ port: port1 })) // answers `initialize` too; pass `mcp` alone for modern-only
 * ```
 */
 function createMessagePortTransport(options) {
 	return new MessagePortTransport(options);
 }
 /**
-* Adapt a hostable {@link ServeMCPScopeInterface} (`self` in a dedicated Web Worker,
+* 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.
 *
 * @remarks
-* `send` writes each outbound string via `scope.postMessage`. `listen`/`closed`
+* `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
@@ -524,7 +596,7 @@ function createMessagePortTransport(options) {
 *
 * @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`
+* @returns A {@link ScopeTransportInterface} `serveMCPScope` binds and drives through `deliver`
 *
 * @example
 * ```ts
@@ -556,13 +628,13 @@ function createScopeTransport(scope) {
 //#endregion
 //#region src/browser/helpers.ts
 /**
-* Decode one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`
+* 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.
 *
 * @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
+* `parseJSONRPCMessage`. Total: malformed JSON or a non-message value yields
 * `undefined`, never throws.
 *
 * @param data - One SSE event's `data` payload
@@ -576,7 +648,7 @@ function decodeEvent(data) {
 	}
 }
 /**
-* Decode a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it
+* 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
@@ -584,8 +656,8 @@ function decodeEvent(data) {
 * 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
+* {@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.
@@ -615,7 +687,7 @@ async function readEventStream(response) {
 	return messages;
 }
 /**
-* Build `serveMCPScope`'s `message`-event listener — the unified
+* 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.
 *
@@ -624,26 +696,32 @@ async function readEventStream(response) {
 * — 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.
+* 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.
 *
 * 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.
+* 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 set `serveMCPScope`'s dispose drains; each port-bearing event adds one entry
+* @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`)
 * @returns The `message`-event listener to register (and later remove) on the scope
 *
 * @example
 * ```ts
-* const teardowns = new Set<() => void>()
+* const teardowns = new Map<MessagePort, () => void>()
 * const scopeTransport = createScopeTransport(scope)
 * bindServer(server, scopeTransport)
 * const onMessage = createScopeMessageListener(server, scopeTransport, teardowns, options)
@@ -651,18 +729,16 @@ async function readEventStream(response) {
 * ```
 */
 function createScopeMessageListener(server, scopeTransport, teardowns, options) {
-	const seen = /* @__PURE__ */ new Set();
 	return (event) => {
 		const ports = event.ports;
 		if (ports.length > 0) {
 			if (options.accept !== void 0 && !options.accept(event)) return;
 			const port = ports[0];
 			if (port === void 0) return;
-			if (seen.has(port)) return;
-			seen.add(port);
+			if (teardowns.has(port)) return;
 			const transport = new MessagePortTransport({ port });
 			const unbind = bindServer(server, transport);
-			teardowns.add(() => {
+			teardowns.set(port, () => {
 				unbind();
 				transport.close();
 			});
@@ -672,13 +748,16 @@ function createScopeMessageListener(server, scopeTransport, teardowns, options)
 	};
 }
 /**
-* Boot an `MCPServer` inside a hostable worker scope and wire its message events to it.
+* Boots an `MCPServer` inside a hostable worker scope and wires its message events to it.
 *
 * @remarks
 * Port-bearing events are gated by `options.accept`, deduplicated by port, and receive
 * their own `MessagePortTransport` binding. Portless string events use the scope's
 * implicit channel. The returned disposer removes the listener, unbinds the implicit
-* channel, and closes every accepted port binding.
+* 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.
 *
 * @param scope - The hostable worker scope to wire
 * @param options - The tools, optional identity, and optional port-event gate
@@ -694,7 +773,7 @@ function serveMCPScope(scope, options) {
 	});
 	const scopeTransport = createScopeTransport(scope);
 	const unbindScope = bindServer(server, scopeTransport);
-	const teardowns = /* @__PURE__ */ new Set();
+	const teardowns = /* @__PURE__ */ new Map();
 	const onMessage = createScopeMessageListener(server, scopeTransport, teardowns, options);
 	scope.addEventListener("message", onMessage);
 	let disposed = false;
@@ -703,12 +782,16 @@ function serveMCPScope(scope, options) {
 		disposed = true;
 		scope.removeEventListener("message", onMessage);
 		unbindScope();
-		for (const teardown of teardowns) teardown();
+		for (const teardown of teardowns.values()) teardown();
 		teardowns.clear();
 	};
 }
 /**
-* Boot an `MCPServer` inside the current hostable worker scope.
+* 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}