@orkestrel/mcp 0.0.19 → 0.0.21

package/README.md

@@ -8,7 +8,7 @@ surfaces its tools as local `ToolInterface`s. No agent runtime is required.
 The dispatch core is transport- and provider-agnostic
 (`src/core` — JSON-RPC 2.0, no HTTP, no `as`); every transport (Streamable
 HTTP over `@orkestrel/router` / `@orkestrel/server`, WebSocket over
-`@orkestrel/websocket`, and stdio over `node:child_process`) lives one layer
+`@orkestrel/websocket`, and stdio over `@orkestrel/process`) lives one layer
 out (`src/server`), each mechanism, not policy. Part of the `@orkestrel` line.
 
 ## Install
@@ -19,8 +19,12 @@ npm install @orkestrel/mcp
 
 ## Requirements
 
-- Node.js >= 24
-- ESM and CommonJS builds ship for both the core and server entry points
+- Node.js >= 22.12.0
+- ESM and CommonJS builds ship for both the core and server entry points; the
+  browser entry point ships ESM only
+- TypeScript `moduleResolution` set to `node16`, `nodenext`, or `bundler`. Under
+  legacy `node` resolution the `./browser` and `./server` subpaths resolve no
+  declarations
 - `@orkestrel/server` and `@orkestrel/router` are peer dependencies (the HTTP
   spine the `./server` transports mount onto)
 
@@ -29,15 +33,16 @@ npm install @orkestrel/mcp
 Expose a tool registry over MCP, mounted on the HTTP spine:
 
 ```ts
-import { createMCPServer } from '@orkestrel/mcp'
+import { createMCPLegacy, createMCPServer } from '@orkestrel/mcp'
 import { createMCPRoutes } from '@orkestrel/mcp/server'
 import { createTool, createToolManager } from '@orkestrel/tool'
 
 const tools = createToolManager()
 tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
 
-const mcp = createMCPServer({ name: 'calculator', version: '1.0.0', tools })
-const routes = createMCPRoutes(mcp) // POST /mcp dispatches JSON-RPC (JSON or SSE per Accept)
+const mcp = createMCPServer({ identity: { name: 'calculator', version: '1.0.0' }, tools })
+// POST /mcp dispatches JSON-RPC (JSON or SSE per Accept):
+const routes = createMCPRoutes(createMCPLegacy(mcp)) // answers `initialize` too; pass `mcp` alone for modern-only
 router.add(routes)
 ```
 
@@ -60,19 +65,15 @@ The SAME `MCPClient` drives a `createWebSocketClientTransport` or
 
 ## Guide
 
-For the full surface — the JSON-RPC dispatch core, the three server
-transports (HTTP, WebSocket, stdio), the native session middleware, and
-usage patterns — see [`guides/src/mcp.md`](guides/src/mcp.md).
+For the full surface — the JSON-RPC dispatch core, the server transports
+(HTTP, WebSocket, stdio), the native session middleware, and usage
+patterns — see the [MCP guide](https://github.com/orkestrel/mcp/blob/main/guides/mcp.md).
 
 ## Package
 
-Published with two entry points per the `exports` field in `package.json`:
-the environment-agnostic core (`.`) and the Node-only server surface
-(`./server`). The browser face (`./browser`) is ESM only. The tarball is
-625.0 kB packed across 18 files, 2.5 MB unpacked.
-
-[`CHANGELOG.md`](CHANGELOG.md) lives in the repository and is not in the
-tarball, because `files` is `["dist/src", "README.md"]`.
+Published per the `exports` field in `package.json`: the
+environment-agnostic core (`.`), the Node-only server surface (`./server`),
+and the browser face (`./browser`), which is ESM only.
 
 ## Proven
 
@@ -91,9 +92,9 @@ of the IDE class has.
 
 ## Declared limits
 
-Four publication facts, each with its number. Full detail, plus every
+The publication facts, each with its number. Full detail, plus every
 protocol-level gap and non-goal, is in
-[`guides/src/mcp.md`](guides/src/mcp.md#declared-packaging-limits).
+[the MCP guide](https://github.com/orkestrel/mcp/blob/main/guides/mcp.md#declared-packaging-limits).
 
 - **No IDE evidence.** See above. The conformance number is about the wire
   and does not transfer to a host application.
@@ -101,12 +102,12 @@ protocol-level gap and non-goal, is in
   condition, so `node16`, `nodenext`, and `bundler` resolution find
   declarations. A consumer on legacy `moduleResolution: node` does not read
   `exports` and sees an untyped package.
-- **A build-time version notice, three times.** API Extractor bundles
+- **A build-time version notice on every built face.** API Extractor bundles
   TypeScript 5.9.3 through a transitive pin and this project compiles with
   6.0.3, so `build` prints one notice per built face. It is informational:
   `build` exits 0 and every declaration is emitted.
-- **Source maps ship.** Five `.map` files are 1,130 kB of the 2.5 MB
-  unpacked, about 45 percent. They are kept so a consumer debugging a
+- **Source maps ship.** Measured on 2026-08-20, the `.map` files are
+  1,168,764 of 2,543,024 unpacked bytes (46.0 percent). They are kept so a consumer debugging a
   protocol library steps into real source.
 
 The notice, verbatim:
@@ -117,4 +118,4 @@ The notice, verbatim:
 
 ## License
 
-MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).
+MIT © [Orkestrel](https://github.com/orkestrel) — see the [license](https://github.com/orkestrel/mcp/blob/main/LICENSE).

package/dist/src/browser/index.d.ts

@@ -10,18 +10,18 @@ import { MCPTransportInterface as MCPTransportInterface_2 } from '@orkestrel/mcp
 import { ToolManagerInterface } from '@orkestrel/tool';
 
 /**
- * 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
@@ -32,7 +32,7 @@ import { ToolManagerInterface } from '@orkestrel/tool';
  *
  * @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`
  *
@@ -51,11 +51,11 @@ import { ToolManagerInterface } from '@orkestrel/tool';
 export declare function createHTTPClientTransport(options: HTTPClientTransportOptions): MCPClientTransportInterface_2;
 
 /**
- * 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
@@ -65,21 +65,22 @@ export declare function createHTTPClientTransport(options: HTTPClientTransportOp
  *
  * @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
  * ```
  */
 export declare function createMessagePortTransport(options: MessagePortTransportOptions): MCPTransportInterface;
 
 /**
- * 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.
  *
@@ -88,42 +89,48 @@ export declare function createMessagePortTransport(options: MessagePortTransport
  * — 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)
  * scope.addEventListener('message', onMessage)
  * ```
  */
-export declare function createScopeMessageListener(server: MCPServerInterface, scopeTransport: ScopeTransportInterface, teardowns: Set<() => void>, options: ServeMCPOptions): (event: MessageEvent) => void;
+export declare function createScopeMessageListener(server: MCPServerInterface, scopeTransport: ScopeTransportInterface, teardowns: Map<MessagePort, () => void>, options: ServeMCPOptions): (event: MessageEvent) => void;
 
 /**
- * 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
@@ -133,7 +140,7 @@ export declare function createScopeMessageListener(server: MCPServerInterface, s
  *
  * @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
@@ -144,10 +151,10 @@ export declare function createScopeMessageListener(server: MCPServerInterface, s
 export declare function createScopeTransport(scope: ServeMCPScopeInterface): ScopeTransportInterface;
 
 /**
- * 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()`)
@@ -177,13 +184,13 @@ export declare function createScopeTransport(scope: ServeMCPScopeInterface): Sco
 export declare function createWebSocketClientTransport(options: WebSocketClientTransportOptions): MCPClientTransportInterface_2;
 
 /**
- * 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
@@ -201,7 +208,7 @@ export declare const DEFAULT_MCP_SERVER_VERSION = "1.0.0";
  * 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.
  *
@@ -209,12 +216,12 @@ export declare const DEFAULT_MCP_SERVER_VERSION = "1.0.0";
  * - **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
@@ -232,10 +239,15 @@ export declare const DEFAULT_MCP_SERVER_VERSION = "1.0.0";
  *   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
@@ -263,15 +275,17 @@ export declare class HTTPClientTransport implements MCPClientTransportInterface
  * @remarks
  * - `url` — the absolute URL of the remote server's Streamable-HTTP endpoint (the
  *   `POST` target every JSON-RPC message is written to). REQUIRED.
- * - `headers` — extra request headers merged onto every `POST` (e.g. an
+ * - `headers` — extra request headers merged onto every `POST` (for example, an
  *   `Authorization` bearer for a guarded server). The transport always sets
  *   `content-type: application/json` and an `Accept` of both `application/json` and
  *   `text/event-stream`; a key supplied here is merged on top.
  * - `fetch` — the `fetch` implementation to issue each `POST` with; defaults to
  *   `globalThis.fetch`. Injectable for a test double or a non-global `fetch`.
  * - `timeout` — an optional per-request timeout in milliseconds; when set, each
- *   `fetch` call is issued with `signal: AbortSignal.timeout(timeout)`. Omit for no
- *   transport-level deadline.
+ *   `fetch` call composes that deadline with the transport's own close through
+ *   `AbortSignal.any([close, AbortSignal.timeout(timeout)])`, so whichever fires first
+ *   ends the request. Omit for no transport-level deadline; the close signal is passed
+ *   either way.
  */
 export declare interface HTTPClientTransportOptions {
     readonly url: string;
@@ -310,8 +324,8 @@ export declare const MCP_SESSION_HEADER = "mcp-session-id";
 
 /**
  * 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 `[]`
@@ -327,13 +341,13 @@ export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
  * @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
@@ -348,7 +362,7 @@ export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
  *   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.
@@ -366,8 +380,8 @@ export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
  *   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
@@ -395,17 +409,17 @@ export declare class MessagePortTransport implements MCPTransportInterface_2 {
  * {@link MessagePortTransport} sends and listens on.
  *
  * @remarks
- * `port` — the channel half to drive (e.g. one side of a `new MessageChannel()`, or
+ * `port` — the channel half to drive (for example, one side of a `new MessageChannel()`, or
  * the port a `message` event's `ports[0]` carried). REQUIRED. The SAME transport
  * works as either a server or a client carrier — the role comes from whether it is
- * handed to `bindServer` or `bindClient`/`createDuplexClientTransport` (`@src/core`).
+ * handed to `bindServer` or `bindClient`/`createDuplexClientTransport` (`@orkestrel/mcp`).
  */
 export declare interface MessagePortTransportOptions {
     readonly port: MessagePort;
 }
 
 /**
- * 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
@@ -413,8 +427,8 @@ export declare interface MessagePortTransportOptions {
  * 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.
@@ -430,15 +444,19 @@ export declare function readEventStream(response: Response): Promise<readonly JS
  * internal carrier `serveMCPScope` binds to route the implicit (portless) message
  * channel, plus the `deliver` entry point the scope's own `message` listener pushes
  * an inbound string through (the scope itself never registers `listen`'s handler
- * for the caller — `serveMCPScope`'s dispatcher does, via this `deliver`).
+ * for the caller — `serveMCPScope`'s dispatcher does, through this `deliver`).
  */
 export declare interface ScopeTransportInterface extends MCPTransportInterface {
-    /** Push one inbound message string into the currently registered `listen` handler. */
+    /** Pushes one inbound message string into the active `listen` handler. */
     deliver(message: string): void;
 }
 
 /**
- * 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}
@@ -448,7 +466,7 @@ export declare function serveMCP(options: ServeMCPOptions): () => void;
 /**
  * Options for `serveMCP` / `serveMCPScope` — the live {@link ToolManagerInterface} to
  * expose plus the optional server identity, mirroring `createMCPServer`'s
- * `MCPServerOptions` (`@src/core`) but with `name`/`version` OPTIONAL (defaulting to
+ * `MCPServerOptions` (`@orkestrel/mcp`) but with `name`/`version` OPTIONAL (defaulting to
  * {@link import('./constants.js').DEFAULT_MCP_SERVER_NAME} /
  * {@link import('./constants.js').DEFAULT_MCP_SERVER_VERSION}).
  *
@@ -459,7 +477,7 @@ export declare function serveMCP(options: ServeMCPOptions): () => void;
  *   deliver directly to the implicit scope channel (the tool executes, blind; in a
  *   Service Worker the reply is silently dropped — see `serveMCPScope`'s portless note).
  *   Prefer a handshake token in `event.data` as the primary pattern
- *   (e.g. `(event) => event.data === token`) — for same-origin worker/MessagePort
+ *   (for example, `(event) => event.data === token`) — for same-origin worker/MessagePort
  *   messages `event.origin` is frequently the empty string, making origin
  *   allow-listing unreliable; origin checks are meaningful for cross-origin
  *   `postMessage` only. When omitted, ALL port-bearing events are accepted — every
@@ -474,13 +492,16 @@ export declare interface ServeMCPOptions {
 }
 
 /**
- * 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
@@ -493,7 +514,7 @@ export declare function serveMCPScope(scope: ServeMCPScopeInterface, options: Se
  * dedicated Web Worker or a Service Worker (or any double matching this shape).
  *
  * @remarks
- * Only the three members `serveMCPScope` actually touches: `postMessage` (the
+ * Only the members `serveMCPScope` actually touches: `postMessage` (the
  * dedicated-worker implicit reply channel), and `addEventListener` /
  * `removeEventListener` for `'message'` (every inbound event, portless or
  * port-bearing, arrives through the SAME listener — see {@link ServeMCPOptions}'s
@@ -510,7 +531,7 @@ export declare interface ServeMCPScopeInterface {
  * 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
@@ -525,15 +546,16 @@ export declare interface ServeMCPScopeInterface {
  * - **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).
  *
@@ -564,8 +586,8 @@ export declare class WebSocketClientTransport implements MCPClientTransportInter
  *   the native `WebSocket` constructor the same way) URL of the remote server's
  *   WebSocket endpoint. REQUIRED.
  * - `protocols` — the WebSocket subprotocol(s) to request. **Defaults to
- *   {@link import('./constants.js').MCP_WEBSOCKET_SUBPROTOCOL} (`'mcp'`)**, matching
- *   `createWebSocketServer`'s unconditional `Sec-WebSocket-Protocol: mcp` echo. Per
+ *   {@link import('./constants.js').MCP_WEBSOCKET_SUBPROTOCOL} (`'mcp'`)**, which
+ *   `createWebSocketServer` selects when the offer contains 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 saves
  *   you from that trap when connecting to this repo's own server. Override only when