@orkestrel/mcp 0.0.27 → 0.0.28

package/README.md

@@ -57,7 +57,7 @@ const client = createMCPClient({
 })
 await client.connect()
 const tools = await client.tools()
-const value = await client.call('add', { x: 2, y: 5 })
+const outcome = await client.call('add', { x: 2, y: 5 })
 ```
 
 The SAME `MCPClient` drives a `createWebSocketClientTransport` or

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

@@ -1,19 +1,24 @@
 import { EmitterInterface } from '@orkestrel/emitter';
+import { HTTPClientTransportOptions } from '@orkestrel/mcp';
 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 { MCPMessageTransportEventMap } from '@orkestrel/mcp';
+import { MCPMessageTransportInterface } from '@orkestrel/mcp';
+import { MCPMessageTransportInterface as MCPMessageTransportInterface_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';
 
 /**
- * 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
@@ -34,7 +39,7 @@ import { ToolManagerInterface } from '@orkestrel/tool';
  *   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,7 +53,7 @@ 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_2;
 
 /**
  * Creates the browser-face `MessagePort` transport — a
@@ -80,9 +85,9 @@ 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
@@ -94,10 +99,10 @@ export declare function createMessagePortTransport(options: MessagePortTransport
  * replies), so a repeat is silently dropped.
  *
  * The key is what makes `teardowns` the ONLY place an accepted port is remembered. A separate
- * seen-port set would be a second collection over the same lifetime, and the caller's disposer
- * would have to remember to empty both — so a long-lived scope such as a Service Worker would
- * retain every port it ever accepted, closed and unbound ones included. Membership answers
- * "already bound?" and `clear()` drops the binding and the dedup together.
+ * seen-port set would be a second collection over the same lifetime, and the scope server's
+ * `stop` would have to remember to empty both — so a long-lived scope such as a Service Worker
+ * would retain every port it ever accepted, closed and unbound ones included. Membership
+ * answers "already bound?" and `clear()` drops the binding and the dedup together.
  *
  * This branch fires on EITHER a Service-Worker-shaped scope (its normal per-client
  * channel) or a dedicated-worker-shaped one that happens to receive a port-bearing event
@@ -108,8 +113,8 @@ export declare function createMessagePortTransport(options: MessagePortTransport
  *
  * @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 +126,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)`
+ * 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,11 +187,11 @@ 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}
+ * {@link import('@orkestrel/mcp').MCPClientInterface} — a {@link MCPMessageTransportInterface}
  * that drives a REMOTE MCP server over the native `WebSocket` global, the browser
  * sibling of the Node face's `createWebSocketClientTransport` (`@orkestrel/mcp/server`).
  *
@@ -167,7 +206,7 @@ export declare function createScopeTransport(scope: ServeMCPScopeInterface): Sco
  * @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,168 +220,23 @@ 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_2;
 
-/**
- * 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
+ *   / {@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
@@ -353,7 +247,7 @@ export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
  *   `MCPTransportInterface` has no separate open/connect step for the caller to hook
  *   a start into, so the constructor calls `port.start()` immediately: the port
  *   begins dispatching QUEUED messages the moment the transport exists. This is safe
- *   inside `serveMCP`'s flow (the transport is synchronously handed to `bindServer`
+ *   inside `createScopeServer`'s flow (the transport is synchronously handed to `bindServer`
  *   before control returns to the event loop), but is a **footgun for direct use**:
  *   if you construct `new MessagePortTransport({ port })` and then `await` anything
  *   before calling `listen`, messages that arrived in the gap are DROPPED. **Bind
@@ -365,16 +259,17 @@ export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
  *   non-string `event.data` (a host or a misbehaving peer posting a structured
  *   object) is IGNORED — dropped silently, never forwarded, never thrown —
  *   because `MCPTransportInterface` carries no `error` channel for this port to
- *   surface a non-string frame on (unlike `MCPClientTransportInterface`'s `emitter`);
+ *   surface a non-string frame on (unlike `MCPMessageTransportInterface`'s `emitter`);
  *   silently ignoring is the total, contract-shaped choice.
  * - **`messageerror` is IGNORED, not routed to `closed`.** A `messageerror` event
  *   (the structured-clone deserialization of an inbound message threw) reports one
  *   BAD FRAME, not a dead channel — the port itself keeps working and later, well-
- *   formed messages still arrive. Routing it to `closed` would tear down the
+ *   formed messages still arrive. This transport registers no listener for it: an
+ *   unhandled `messageerror` on a `MessagePort` neither throws, closes the port, nor
+ *   reaches this transport, so one bad frame costs exactly that frame and nothing
+ *   tears the binding down. Routing it to `closed` would tear down the
  *   `bindServer`/`bindClient` wiring (and, transitively, every session it carries)
- *   over a single malformed frame, which is far more destructive than dropping that
- *   one frame — so this transport registers a `messageerror` listener that does
- *   nothing, deliberately.
+ *   over a single malformed frame.
  * - **`close()`** is idempotent: it closes the underlying `port` (`MessagePort.close()`
  *   disconnects it — further `postMessage` calls on EITHER end are silently
  *   undelivered, per the platform contract) and fires the registered `closed`
@@ -420,55 +315,46 @@ 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
@@ -476,16 +362,16 @@ export declare function serveMCP(options: ServeMCPOptions): () => void;
  *   event is accepted; return `false` to drop the event (no binding, no reply).
  *   **`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
  *   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,45 +379,21 @@ 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
+ * Drives a REMOTE MCP server over the native `WebSocket` global from the browser face — a
+ * CLIENT {@link MCPMessageTransportInterface}, the browser sibling of the Node face's
  * {@link import('@orkestrel/mcp/server').WebSocketClientTransport}.
  *
  * @remarks
@@ -550,8 +412,8 @@ export declare interface ServeMCPScopeInterface {
  *   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
  *   throws on adversarial wire input).
@@ -564,7 +426,7 @@ export declare interface ServeMCPScopeInterface {
  *   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
+ * - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); every
  *   emit the emitter isolates a listener throw; `error` is a DOMAIN event (a
  *   transport-level fault).
  *
@@ -575,14 +437,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>;
 }
 
@@ -595,7 +457,7 @@ 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'`)**, 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