@orkestrel/mcp 0.0.27 → 0.0.29

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

@@ -1,40 +1,43 @@
-import { EmitterInterface } from '@orkestrel/emitter';
-import { JSONRPCMessage } from '@orkestrel/mcp';
-import { JSONRPCMessage as JSONRPCMessage_2 } from '@orkestrel/mcp';
-import { MCPClientTransportEventMap } from '@orkestrel/mcp';
-import { MCPClientTransportInterface } from '@orkestrel/mcp';
-import { MCPClientTransportInterface as MCPClientTransportInterface_2 } from '@orkestrel/mcp';
-import { MCPServerInterface } from '@orkestrel/mcp';
-import { MCPTransportInterface } from '@orkestrel/mcp';
-import { MCPTransportInterface as MCPTransportInterface_2 } from '@orkestrel/mcp';
-import { ToolManagerInterface } from '@orkestrel/tool';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { HTTPClientTransportOptions } from '@orkestrel/mcp';
+import type { JSONRPCMessage } from '@orkestrel/mcp';
+import type { MCPMessageTransportEventMap } from '@orkestrel/mcp';
+import type { MCPMessageTransportInterface } from '@orkestrel/mcp';
+import type { MCPServerInterface } from '@orkestrel/mcp';
+import type { MCPTransportInterface } from '@orkestrel/mcp';
+import type { ToolManagerInterface } from '@orkestrel/tool';
 
 /**
- * Creates the browser-face HTTP CLIENT transport for an
- * {@link import('@orkestrel/mcp').MCPClientInterface} — a {@link MCPClientTransportInterface}
- * that drives a REMOTE Streamable-HTTP MCP server over the native `fetch`, the
- * browser sibling of the Node face's `createHTTPClientTransport` (`@orkestrel/mcp/server`).
+ * Creates the HTTP client transport for an
+ * {@link import('@orkestrel/mcp').MCPClientInterface} — a {@link MCPMessageTransportInterface}
+ * that drives a remote Streamable-HTTP MCP server over the native `fetch`.
+ *
+ * @remarks
+ * It returns the core {@link import('@orkestrel/mcp').HTTPClientTransport}, the same class the
+ * Node face's `createHTTPClientTransport` returns, because the class touches `fetch`,
+ * `Response`, `AbortController`, `AbortSignal`, and `WeakMap` alone. This factory exists so a
+ * page imports its transport from the face it already imports everything else from.
  *
  * @remarks
  * Hand it to `createMCPClient({ transport })`: each JSON-RPC message the client
  * sends is `POST`ed to `options.url` with `content-type: application/json` and an
  * `Accept` of both `application/json` and `text/event-stream` (the server answers
- * with EITHER — a plain JSON envelope or a Streamable-HTTP SSE `data:` event,
+ * with either — a plain JSON envelope or a Streamable-HTTP SSE `data:` event,
  * decoded with `@orkestrel/sse`), and the reply is surfaced on the transport's
  * `message` event for the client's id correlation. Add `options.headers` (for example, an
  * `Authorization` bearer) to reach a guarded server. `start` / `close` hold no
- * connection; against a STATEFUL server it captures the `mcp-session-id` from
+ * connection; against a stateful server it captures the `mcp-session-id` from
  * `initialize` and echoes it on later requests. It also captures the initialize
  * result's `protocolVersion` and sends `mcp-protocol-version` alone on subsequent
  * legacy requests. Modern requests instead derive `mcp-protocol-version` and
  * `mcp-method` from the message, plus `mcp-name` only for `tools/call`, so the
  * same `MCPClient` passes either era's protocol gates without caller wiring.
  *
- * @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged
+ * @param options - `url` (the remote endpoint; required), optional `headers` merged
  *   onto every request, optional `fetch` (default `globalThis.fetch`), and optional
  *   `timeout` (ms, applied with `AbortSignal.timeout`); see
  *   {@link HTTPClientTransportOptions}
- * @returns A working {@link MCPClientTransportInterface} over the native `fetch`
+ * @returns A working {@link MCPMessageTransportInterface} over the native `fetch`
  *
  * @example
  * ```ts
@@ -48,12 +51,12 @@ import { ToolManagerInterface } from '@orkestrel/tool';
  * const tools = await client.tools()
  * ```
  */
-export declare function createHTTPClientTransport(options: HTTPClientTransportOptions): MCPClientTransportInterface_2;
+export declare function createHTTPClientTransport(options: HTTPClientTransportOptions): MCPMessageTransportInterface;
 
 /**
  * Creates the browser-face `MessagePort` transport — a
  * {@link import('@orkestrel/mcp').MCPTransportInterface} over a native `MessagePort`, the
- * SYMMETRIC carrier that works as either a server or a client transport depending on
+ * symmetric carrier that works as either a server or a client transport depending on
  * which binder ({@link import('@orkestrel/mcp').bindServer} or
  * {@link import('@orkestrel/mcp').bindClient}) it is handed to.
  *
@@ -63,7 +66,7 @@ export declare function createHTTPClientTransport(options: HTTPClientTransportOp
  * dropped, never thrown); `messageerror` is ignored (one bad frame does not close the
  * channel); `close()` closes the port and fires `closed` exactly once.
  *
- * @param options - `port` (the `MessagePort` half to drive; REQUIRED); see
+ * @param options - `port` (the `MessagePort` half to drive; required); see
  *   {@link MessagePortTransportOptions}
  * @returns A working {@link import('@orkestrel/mcp').MCPTransportInterface} over the port
  *
@@ -80,36 +83,36 @@ export declare function createHTTPClientTransport(options: HTTPClientTransportOp
 export declare function createMessagePortTransport(options: MessagePortTransportOptions): MCPTransportInterface;
 
 /**
- * Builds `serveMCPScope`'s `message`-event listener — the unified
- * dispatcher that routes EVERY inbound event on a hostable scope, portless or
- * port-bearing, to the right binding.
+ * Builds {@link createScopeServer}'s `message`-event listener — the unified dispatcher that
+ * routes every inbound event on a hostable scope, portless or port-bearing, to the right
+ * binding.
  *
  * @remarks
- * Port-bearing events (`event.ports.length > 0`) are gated by `options.accept` FIRST
+ * Port-bearing events (`event.ports.length > 0`) are gated by `options.accept` first
  * — when the gate returns `false` the event is dropped entirely (no binding, no reply).
  * Accepted events spawn a fresh `MessagePortTransport` over `event.ports[0]`,
  * `bindServer` `server` onto it, and record a teardown (`unbind` then `transport.close()`)
- * into `teardowns` KEYED BY THAT PORT. A port already present is IGNORED — repeated delivery
+ * into `teardowns` keyed by that port. A port already present is ignored — repeated delivery
  * of the same `MessagePort` would create duplicate bindings over one port (→ duplicated
  * replies), so a repeat is silently dropped.
  *
- * The key is what makes `teardowns` the ONLY place an accepted port is remembered. A separate
- * seen-port set would be a second collection over the same lifetime, and the caller's disposer
- * would have to remember to empty both — so a long-lived scope such as a Service Worker would
- * retain every port it ever accepted, closed and unbound ones included. Membership answers
- * "already bound?" and `clear()` drops the binding and the dedup together.
+ * The key is what makes `teardowns` the only place an accepted port is remembered. A separate
+ * seen-port set would be a second collection over the same lifetime, and the scope server's
+ * `stop` would have to remember to empty both — so a long-lived scope such as a Service Worker
+ * would retain every port it ever accepted, closed and unbound ones included. Membership
+ * answers "already bound?" and `clear()` drops the binding and the dedup together.
  *
- * This branch fires on EITHER a Service-Worker-shaped scope (its normal per-client
+ * This branch fires on either a Service-Worker-shaped scope (its normal per-client
  * channel) or a dedicated-worker-shaped one that happens to receive a port-bearing event
  * (the unified design's deliberate cross-case, needing no upfront shape flag). An event
- * with NO ports and a STRING `data` is pushed onto `scopeTransport.deliver` (the
+ * with no ports and a string `data` is pushed onto `scopeTransport.deliver` (the
  * implicit, already-bound scope channel); any other event (no ports, non-string data)
  * is silently dropped — total, never throws.
  *
  * @param server - The `MCPServerInterface` every spawned/implicit binding dispatches over
  * @param scopeTransport - The implicit scope channel (already `bindServer`-bound) portless events deliver onto
- * @param teardowns - The shared teardown map `serveMCPScope`'s dispose drains and clears, keyed by the accepted port; each port-bearing event adds one entry
- * @param options - The `ServeMCPOptions` (for `options.accept`)
+ * @param teardowns - The shared teardown map the scope server's `stop` drains and clears, keyed by the accepted port; each port-bearing event adds one entry
+ * @param options - The `ScopeServerOptions` (for `options.accept`)
  * @returns The `message`-event listener to register (and later remove) on the scope
  *
  * @example
@@ -121,26 +124,60 @@ export declare function createMessagePortTransport(options: MessagePortTransport
  * scope.addEventListener('message', onMessage)
  * ```
  */
-export declare function createScopeMessageListener(server: MCPServerInterface, scopeTransport: ScopeTransportInterface, teardowns: Map<MessagePort, () => void>, options: ServeMCPOptions): (event: MessageEvent) => void;
+export declare function createScopeMessageListener(server: MCPServerInterface, scopeTransport: ScopeTransportInterface, teardowns: Map<MessagePort, () => void>, options: ScopeServerOptions): (event: MessageEvent) => void;
+
+/**
+ * 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
+ * `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.
+ *
+ * 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
+ * import { createScopeServer } from '@orkestrel/mcp/browser'
+ * import { createToolManager } from '@orkestrel/tool'
+ *
+ * // Inside a Web Worker: the scope defaults to `globalThis`.
+ * const worker = createScopeServer({ tools: createToolManager() })
+ * // ... later, release every binding this call owns:
+ * worker.stop()
+ * ```
+ */
+export declare function createScopeServer(options: ScopeServerOptions, scope?: ScopeInterface): ScopeServerInterface;
 
 /**
- * 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.
+ * 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
  * `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)`
+ * 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 `serveMCPScope` to hand a `listen` handler to, so `deliver` is
+ * 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 scope to adapt (structurally, `self` / `globalThis`
  *   inside a dedicated Web Worker)
- * @returns A {@link ScopeTransportInterface} `serveMCPScope` binds and drives through `deliver`
+ * @returns A {@link ScopeTransportInterface} the scope server binds and drives through `deliver`
  *
  * @example
  * ```ts
@@ -148,26 +185,26 @@ export declare function createScopeMessageListener(server: MCPServerInterface, s
  * const unbind = bindServer(server, scopeTransport)
  * ```
  */
-export declare function createScopeTransport(scope: ServeMCPScopeInterface): ScopeTransportInterface;
+export declare function createScopeTransport(scope: ScopeInterface): ScopeTransportInterface;
 
 /**
- * Creates the browser-face WebSocket CLIENT transport for an
- * {@link import('@orkestrel/mcp').MCPClientInterface} — a {@link MCPClientTransportInterface}
- * that drives a REMOTE MCP server over the native `WebSocket` global, the browser
- * sibling of the Node face's `createWebSocketClientTransport` (`@orkestrel/mcp/server`).
+ * Creates the browser-face WebSocket client transport for an
+ * {@link import('@orkestrel/mcp').MCPClientInterface} — a {@link MCPMessageTransportInterface}
+ * that drives a remote MCP server over the native `WebSocket` global. This factory is the
+ * browser sibling of the Node face's `createWebSocketClientTransport` (`@orkestrel/mcp/server`).
  *
  * @remarks
  * Hand it to `createMCPClient({ transport })`: `start()` (run by `client.connect()`)
  * opens `new WebSocket(options.url, options.protocols)` and awaits the native
  * `'open'` event — the RFC 6455 handshake itself is the browser's concern. Each
- * JSON-RPC message the client `send`s before the socket opens is QUEUED and flushed,
+ * JSON-RPC message the client `send`s before the socket opens is queued and flushed,
  * in order, once it does; each decoded reply is surfaced on the transport's
  * `message` event for the client's id correlation.
  *
- * @param options - `url` (the remote WebSocket endpoint; REQUIRED) and optional
+ * @param options - `url` (the remote WebSocket endpoint; required) and optional
  *   `protocols` (the WebSocket subprotocol(s) to request); see
  *   {@link WebSocketClientTransportOptions}
- * @returns A working {@link MCPClientTransportInterface} over the native `WebSocket`
+ * @returns A working {@link MCPMessageTransportInterface} over the native `WebSocket`
  *
  * @example
  * ```ts
@@ -181,209 +218,65 @@ export declare function createScopeTransport(scope: ServeMCPScopeInterface): Sco
  * const tools = await client.tools()
  * ```
  */
-export declare function createWebSocketClientTransport(options: WebSocketClientTransportOptions): MCPClientTransportInterface_2;
+export declare function createWebSocketClientTransport(options: WebSocketClientTransportOptions): MCPMessageTransportInterface;
 
-/**
- * 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: 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`
- */
-export declare function decodeEvent(data: string): JSONRPCMessage | undefined;
-
-/** The default server name `serveMCPScope` reports (`initialize`'s `serverInfo.name`) when `options.name` is omitted. */
-export declare const DEFAULT_MCP_SERVER_NAME = "taverna";
+/** Supplies the default server name `createScopeServer` reports (`initialize`'s `serverInfo.name`) when `options.name` is omitted. */
+export declare const DEFAULT_MCP_SERVER_NAME = "@orkestrel/mcp";
 
-/** The default server version `serveMCPScope` reports (`initialize`'s `serverInfo.version`) when `options.version` is omitted. */
+/** Supplies the default server version `createScopeServer` reports (`initialize`'s `serverInfo.version`) when `options.version` is omitted. */
 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('@orkestrel/mcp/server').HTTPClientTransport}, honoring the SAME
- * `mcp-session-id` semantics so it interoperates with an `MCPSession`-based server
- * unchanged.
- *
- * @remarks
- * - **Request/response over `fetch`.** `send(message)` POSTs the JSON-serialized
- *   message to `options.url` with `content-type: application/json` and an
- *   `Accept` of BOTH `application/json` and `text/event-stream` (so the server may
- *   answer with either framing) — plus any `options.headers` (for example, an
- *   `Authorization` bearer). It then decodes the reply and emits each decoded
- *   {@link JSONRPCMessage} on the `message` event the
- *   {@link import('@orkestrel/mcp').MCPClientInterface} subscribes to.
- * - **Both reply framings.** A `200` with an `application/json` body is parsed with
- *   `parseJSONRPCMessage`; a `200` with a `text/event-stream` body is decoded with the
- *   `@orkestrel/sse` {@link import('@orkestrel/sse').SSEParserInterface} (the browser
- *   face's own `readEventStream`) — the inverse of the server's `openStream` seam, so
- *   the wire round-trips. A `202` Accepted (a notification) carries no body and emits
- *   nothing.
- * - **Session and protocol headers.** `start()` is a no-op (a
- *   request/response transport opens no long-lived connection). The
- *   `mcp-session-id` response header, when a STATEFUL server sends one (on
- *   `initialize`), is captured into `session` and then ECHOED as the
- *   `mcp-session-id` request header on every SUBSEQUENT request — so an
- *   `MCPClient` passes a stateful server's session validation. The
- *   initialize result's `protocolVersion` is likewise captured, but only
- *   when it is a SUPPORTED value, and echoed as `mcp-protocol-version` alone on
- *   subsequent legacy requests. Modern requests instead derive protocol and method
- *   headers from the message, plus the name header only for `tools/call` — carried in the
- *   protocol's Base64 sentinel form whenever the tool name cannot ride as plain ASCII.
- *   Before initialize returns, neither captured legacy header is sent.
- *   `close()` clears the captured protocol so a reconnect's `initialize`
- *   POST is headerless; the captured `session` persists across `close()`.
- * - **`close()` releases what is in flight.** Every `fetch` this transport still has open is
- *   ABORTED, which cancels the response body a `send` is reading — an SSE reply the server
- *   never ends would otherwise outlive the transport, with nothing left able to reach it. The
- *   aborted read surfaces on `error` and the `send` reporting it resolves. `close()` is
- *   idempotent (one `close` event per connected lifetime), and `start()` opens the next one.
- * - **Total at the boundary.** Every reply is narrowed (`parseJSONRPCMessage`,
- *   the SSE decoder) — a non-message reply is dropped, never asserted; a `fetch` /
- *   decode failure surfaces on the `error` event rather than escaping `send`.
- * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
- *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.
- *
- * @example
- * ```ts
- * const transport = new HTTPClientTransport({ url: 'http://localhost:3000/mcp' })
- * const client = new MCPClient({ transport })
- * await client.connect()
- * ```
- */
-export declare class HTTPClientTransport implements MCPClientTransportInterface {
-    #private;
-    constructor(options: HTTPClientTransportOptions);
-    get emitter(): EmitterInterface<MCPClientTransportEventMap>;
-    get session(): string | undefined;
-    get duplex(): boolean;
-    start(): Promise<void>;
-    send(message: JSONRPCMessage_2): Promise<void>;
-    close(): Promise<void>;
-}
-
-/**
- * Options for `createHTTPClientTransport` (browser face) — the remote MCP server's
- * URL and any extra request headers.
- *
- * @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` (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 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;
-    readonly headers?: Readonly<Record<string, string>>;
-    readonly fetch?: typeof fetch;
-    readonly timeout?: number;
-}
-
-/**
- * The modern Streamable-HTTP request header carrying the JSON-RPC method. It is
- * emitted on every modern request and never on a legacy request.
- */
-export declare const 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`.
- */
-export declare const MCP_NAME_HEADER = "mcp-name";
-
-/**
- * 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.
- */
-export declare const MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
-
-/**
- * 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.
- */
-export declare const MCP_SESSION_HEADER = "mcp-session-id";
-
-/**
- * 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).
- */
-export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
-
-/**
- * The browser-face `MessagePort` transport for the Model Context Protocol — a
- * {@link MCPTransportInterface} over a native `MessagePort`, the genuinely new
- * capability this face adds: MCP over `postMessage`.
+ * Carries the Model Context Protocol over a native `MessagePort` from the browser face — a
+ * {@link MCPTransportInterface}, the genuinely new capability this face adds: MCP over
+ * `postMessage`.
  *
  * @remarks
  * - **Symmetric.** Unlike {@link import('./WebSocketClientTransport.js').WebSocketClientTransport}
- *   / {@link import('./HTTPClientTransport.js').HTTPClientTransport} (CLIENT-only
- *   carriers of `@orkestrel/mcp`'s `MCPClientTransportInterface`), a `MessagePort` is a
- *   plain duplex channel — the SAME class implements `@orkestrel/mcp`'s
- *   `MCPTransportInterface` and is handed to EITHER `bindServer` or
+ *   / {@link import('@orkestrel/mcp').HTTPClientTransport} (CLIENT-only
+ *   carriers of `@orkestrel/mcp`'s `MCPMessageTransportInterface`), a `MessagePort` is a
+ *   plain duplex channel — the same class implements `@orkestrel/mcp`'s
+ *   `MCPTransportInterface` and is handed to either `bindServer` or
  *   `bindClient`/`createDuplexClientTransport`; which role it plays comes entirely
  *   from the binder it is given to, not from anything this class decides.
  * - **`start()` at construction — bind synchronously.** `MessagePort.start()` is only
- *   REQUIRED when listening with `addEventListener` (as opposed to the `onmessage`
+ *   required when listening with `addEventListener` (as opposed to the `onmessage`
  *   setter, which implies it) — this transport uses `addEventListener`, and
  *   `MCPTransportInterface` has no separate open/connect step for the caller to hook
  *   a start into, so the constructor calls `port.start()` immediately: the port
- *   begins dispatching QUEUED messages the moment the transport exists. This is safe
- *   inside `serveMCP`'s flow (the transport is synchronously handed to `bindServer`
+ *   begins dispatching queued messages the moment the transport exists. This is safe
+ *   inside `createScopeServer`'s flow (the transport is synchronously handed to `bindServer`
  *   before control returns to the event loop), but is a **footgun for direct use**:
  *   if you construct `new MessagePortTransport({ port })` and then `await` anything
- *   before calling `listen`, messages that arrived in the gap are DROPPED. **Bind
+ *   before calling `listen`, messages that arrived in the gap are dropped. **Bind
  *   synchronously after construction** — do not interleave an `await` between
  *   `new MessagePortTransport(…)` and `bindServer` / `listen`.
  * - **String payloads only.** `send` posts the message string as-is (`postMessage`
  *   structured-clones it — a string clones to an identical string, so the wire stays
  *   plain JSON-RPC text like every other transport in this package). Inbound: a
  *   non-string `event.data` (a host or a misbehaving peer posting a structured
- *   object) is IGNORED — dropped silently, never forwarded, never thrown —
+ *   object) is ignored — dropped silently, never forwarded, never thrown —
  *   because `MCPTransportInterface` carries no `error` channel for this port to
- *   surface a non-string frame on (unlike `MCPClientTransportInterface`'s `emitter`);
+ *   surface a non-string frame on (unlike `MCPMessageTransportInterface`'s `emitter`);
  *   silently ignoring is the total, contract-shaped choice.
- * - **`messageerror` is IGNORED, not routed to `closed`.** A `messageerror` event
+ * - **`messageerror` is ignored, not routed to `closed`.** A `messageerror` event
  *   (the structured-clone deserialization of an inbound message threw) reports one
- *   BAD FRAME, not a dead channel — the port itself keeps working and later, well-
- *   formed messages still arrive. Routing it to `closed` would tear down the
+ *   bad frame, not a dead channel — the port itself keeps working and later, well-
+ *   formed messages still arrive. This transport registers no listener for it: an
+ *   unhandled `messageerror` on a `MessagePort` neither throws, closes the port, nor
+ *   reaches this transport, so one bad frame costs exactly that frame and nothing
+ *   tears the binding down. Routing it to `closed` would tear down the
  *   `bindServer`/`bindClient` wiring (and, transitively, every session it carries)
- *   over a single malformed frame, which is far more destructive than dropping that
- *   one frame — so this transport registers a `messageerror` listener that does
- *   nothing, deliberately.
+ *   over a single malformed frame.
  * - **`close()`** is idempotent: it closes the underlying `port` (`MessagePort.close()`
- *   disconnects it — further `postMessage` calls on EITHER end are silently
+ *   disconnects it — further `postMessage` calls on either end are silently
  *   undelivered, per the platform contract) and fires the registered `closed`
  *   handler exactly once, whether the caller closes it once or twice. There is no
  *   native "peer closed" signal for a `MessagePort` (unlike a WebSocket's `close`
- *   event) — `closed` fires ONLY from this transport's own `close()`.
+ *   event) — `closed` fires only from this transport's own `close()`.
  * - **Single-handler-replace (the port contract, `@orkestrel/mcp`'s `MCPTransportInterface`
  *   doc).** `listen`/`closed` each hold the one active handler; a
- *   second call REPLACES the first rather than adding a second subscriber.
+ *   second call replaces the first rather than adding a second subscriber.
  *
  * @example
  * ```ts
@@ -396,7 +289,7 @@ export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
  * bindClient(client, clientTransport) // port2 side is the client's carrier
  * ```
  */
-export declare class MessagePortTransport implements MCPTransportInterface_2 {
+export declare class MessagePortTransport implements MCPTransportInterface {
     #private;
     constructor(options: MessagePortTransportOptions);
     send(message: string): void;
@@ -411,7 +304,7 @@ export declare class MessagePortTransport implements MCPTransportInterface_2 {
  *
  * @remarks
  * `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
+ * 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` (`@orkestrel/mcp`).
  */
@@ -420,72 +313,63 @@ export declare interface MessagePortTransportOptions {
 }
 
 /**
- * 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.
+ * Describes the structural shape {@link import('./factories.js').createScopeServer} needs
+ * from a
+ * hostable scope — `self` in a dedicated Web Worker or a Service Worker (or any double
+ * matching this shape).
  *
  * @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
- */
-export declare function readEventStream(response: Response): Promise<readonly JSONRPCMessage[]>;
-
-/**
- * A duplex {@link MCPTransportInterface} adapting a message-event-bearing SCOPE
- * (`self` in a dedicated Web Worker, or any object shaped the same way) — the
- * 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, through this `deliver`).
+ * Only the members the scope server 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 ScopeServerOptions}'s
+ * doc and the factory). A real `self` / `globalThis` inside a worker satisfies this
+ * structurally (it exposes far more, which this narrower shape ignores).
  */
-export declare interface ScopeTransportInterface extends MCPTransportInterface {
-    /** Pushes one inbound message string into the active `listen` handler. */
-    deliver(message: string): void;
+export declare interface ScopeInterface {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
 }
 
 /**
- * Boots an `MCPServer` inside the current hostable worker scope.
+ * Represents one MCP server hosted inside a worker scope — what
+ * {@link import('./factories.js').createScopeServer} returns.
  *
  * @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}
+ * The browser twin of the Node face's `StdioServerInterface`, and it publishes only the
+ * terminal: the factory arms the scope's `message` listener before it returns, because an
+ * event delivered between construction and an explicit `start` would reach nothing. `stop`
+ * removes that listener, unbinds the implicit scope channel, and tears down every accepted
+ * port binding; it is idempotent, and it ends this handle's lifetime permanently.
  */
-export declare function serveMCP(options: ServeMCPOptions): () => void;
+export declare interface ScopeServerInterface {
+    /** Ends every binding this scope server owns — idempotent, and permanent for this handle. */
+    stop(): void;
+}
 
 /**
- * Options for `serveMCP` / `serveMCPScope` — the live {@link ToolManagerInterface} to
- * expose plus the optional server identity, mirroring `createMCPServer`'s
- * `MCPServerOptions` (`@orkestrel/mcp`) but with `name`/`version` OPTIONAL (defaulting to
- * {@link import('./constants.js').DEFAULT_MCP_SERVER_NAME} /
+ * Options for {@link import('./factories.js').createScopeServer} — the live
+ * {@link ToolManagerInterface} to expose plus the optional server identity, mirroring
+ * `createMCPServer`'s `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}).
  *
  * @remarks
  * - `accept` — optional identity gate consulted **before** a port-bearing `message`
  *   event is accepted; return `false` to drop the event (no binding, no reply).
- *   **`accept` gates ONLY port-bearing events** — portless messages bypass it and
+ *   **`accept` gates only port-bearing events** — portless messages bypass it and
  *   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).
+ *   Service Worker the reply is silently dropped — see `createScopeServer`'s portless note).
  *   Prefer a handshake token in `event.data` as the primary pattern
  *   (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
+ *   `postMessage` only. When omitted, all port-bearing events are accepted — every
  *   same-origin context that can reach the scope gets full tool-call access.
- *   See `serveMCPScope`'s trust-boundary and portless-events notes.
+ *   See `createScopeServer`'s trust-boundary and portless-events notes.
  */
-export declare interface ServeMCPOptions {
+export declare interface ScopeServerOptions {
     readonly tools: ToolManagerInterface;
     readonly name?: string;
     readonly version?: string;
@@ -493,79 +377,55 @@ export declare interface ServeMCPOptions {
 }
 
 /**
- * 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, 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
- * @returns An idempotent disposer for every binding owned by this call
- */
-export declare function serveMCPScope(scope: ServeMCPScopeInterface, options: ServeMCPOptions): () => void;
-
-/**
- * The structural shape `serveMCPScope` needs from a hostable scope — `self` in a
- * dedicated Web Worker or a Service Worker (or any double matching this shape).
- *
- * @remarks
- * 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
- * doc and the bootstrap factories). A real `self` / `globalThis` inside a worker satisfies this
- * structurally (it exposes far more, which this narrower shape ignores).
+ * Adapts a message-event-bearing scope (`self` in a dedicated Web Worker, or any object
+ * shaped the same way) as a duplex {@link MCPTransportInterface} — the
+ * internal carrier `createScopeServer` 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 — the scope server's dispatcher does, through this `deliver`).
  */
-export declare interface ServeMCPScopeInterface {
-    postMessage(message: unknown): void;
-    addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
-    removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+export declare interface ScopeTransportInterface extends MCPTransportInterface {
+    /** Pushes one inbound message string into the active `listen` handler. */
+    deliver(message: string): void;
 }
 
 /**
- * The browser-face WebSocket CLIENT transport for the Model Context Protocol — a
- * {@link MCPClientTransportInterface} that drives a REMOTE MCP server over the native
- * `WebSocket` global, the browser sibling of the Node face's
- * {@link import('@orkestrel/mcp/server').WebSocketClientTransport}.
+ * Drives a remote MCP server over the native `WebSocket` global from the browser face, as a
+ * client {@link MCPMessageTransportInterface}. This class is the browser sibling of the Node
+ * face's {@link import('@orkestrel/mcp/server').WebSocketClientTransport}.
  *
  * @remarks
  * - **Host-performed handshake.** `start()` opens `new WebSocket(url, protocols)` and
  *   waits for the native `'open'` event — the RFC 6455 handshake itself is entirely
  *   the host's concern, so this transport carries none of the Node client's
  *   `node:crypto` / `node:http(s)` machinery. A connection failure (the native
- *   `'error'` event while not yet `OPEN`) REJECTS `start()`.
+ *   `'error'` event while not yet `OPEN`) rejects `start()`.
  * - **Queued sends.** `send` writes each message as one text frame immediately once
  *   the socket is `OPEN`; a `send` issued before `'open'` fires (or before `start()`
- *   is even called) is QUEUED and flushed, IN ORDER, the moment the socket opens —
- *   so a caller need not await `start()` before calling `send`. A queue rides ONE
- *   connection: a close DISCARDS whatever is still in it.
- * - **A closed channel REJECTS.** The native socket confirms nothing about a write, so this
+ *   is even called) is queued and flushed, in order, the moment the socket opens —
+ *   so a caller need not await `start()` before calling `send`. A queue rides one
+ *   connection: a close discards whatever is still in it.
+ * - **A closed channel rejects.** The native socket confirms nothing about a write, so this
  *   transport answers from its own state: a `send` after `close()`, or on a socket already
- *   reporting `CLOSING` / `CLOSED`, REJECTS with `WebSocket transport is not connected` rather
+ *   reporting `CLOSING` / `CLOSED`, rejects with `WebSocket transport is not connected` rather
  *   than resolving on a frame nobody wrote. Only the closed state rejects — a pre-open `send`
  *   still queues.
- * - **Inbound (`message`).** Each decoded text frame is `JSON.parse`d (guarded) and
- *   narrowed with `parseJSONRPCMessage` — a well-formed {@link JSONRPCMessage}
+ * - **Inbound (`message`).** Each decoded text frame runs through the shared
+ *   `deliverMessage` fold (parse, then narrow) — a well-formed {@link JSONRPCMessage}
  *   re-emits on this transport's `message` event; a non-text (binary) frame or a
- *   non-JSON / non-message text frame surfaces on `error` and is DROPPED (never
+ *   non-JSON / non-message text frame surfaces on `error` and is dropped (never
  *   throws on adversarial wire input).
  * - **`close()`** unsubscribes from the underlying socket, closes it, and fires `close`
  *   (idempotent); the socket's native `close` event (a server-initiated close) fires the
- *   SAME `close` exactly once total — `close()` first flips the guard, so the native event
+ *   same `close` exactly once total — `close()` first flips the guard, so the native event
  *   never double-emits, and the released socket reports its own close to nobody. Closing before
  *   the socket opens resolves the pending `start()` rather than leaving it pending, matching the
- *   Node face. A `send` issued after `close()` REJECTS (it is never queued), and the
- *   pre-open queue is DISCARDED — by `close()` and by the native `close` event alike — so a
+ *   Node face. A `send` issued after `close()` rejects (it is never queued), and the
+ *   pre-open queue is discarded — by `close()` and by the native `close` event alike — so a
  *   closed transport delivers nothing until a `start()` opens a new connection, and nothing
  *   the caller handed the abandoned connection rides that one.
- * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); every
- *   emit the emitter isolates a listener throw; `error` is a DOMAIN event (a
+ * - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); every
+ *   emit the emitter isolates a listener throw; `error` is a domain event (a
  *   transport-level fault).
  *
  * @example
@@ -575,14 +435,14 @@ export declare interface ServeMCPScopeInterface {
  * await client.connect() // the browser handshakes, then the MCP initialize runs over WS frames
  * ```
  */
-export declare class WebSocketClientTransport implements MCPClientTransportInterface {
+export declare class WebSocketClientTransport implements MCPMessageTransportInterface {
     #private;
     constructor(options: WebSocketClientTransportOptions);
-    get emitter(): EmitterInterface<MCPClientTransportEventMap>;
+    get emitter(): EmitterInterface<MCPMessageTransportEventMap>;
     get session(): string | undefined;
     get duplex(): boolean;
     start(): Promise<void>;
-    send(message: JSONRPCMessage_2): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
     close(): Promise<void>;
 }
 
@@ -593,9 +453,9 @@ export declare class WebSocketClientTransport implements MCPClientTransportInter
  * @remarks
  * - `url` — the absolute `ws://` / `wss://` (or `http://` / `https://`, accepted by
  *   the native `WebSocket` constructor the same way) URL of the remote server's
- *   WebSocket endpoint. REQUIRED.
+ *   WebSocket endpoint. Required.
  * - `protocols` — the WebSocket subprotocol(s) to request. **Defaults to
- *   {@link import('./constants.js').MCP_WEBSOCKET_SUBPROTOCOL} (`'mcp'`)**, which
+ *   {@link import('@orkestrel/mcp').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
@@ -609,7 +469,7 @@ export declare class WebSocketClientTransport implements MCPClientTransportInter
  * upgrade request header at all — there is no seam for an `Authorization` bearer to reach.
  * The Node face owns its own `node:http(s)` upgrade request and therefore can, which is why
  * only that side offers `headers`. Reach a guarded server from a page with a credential the
- * platform DOES carry: a cookie the browser attaches to the upgrade, a subprotocol token, or
+ * platform does carry: a cookie the browser attaches to the upgrade, a subprotocol token, or
  * a signed value in the URL. Adding a `headers` key here would be an option that silently
  * did nothing.
  */