@orkestrel/mcp 0.0.3 → 0.0.5

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

@@ -0,0 +1,631 @@
+import { ClientTransportEventMap } from '../../core/index.ts';
+import { ClientTransportInterface } from '../../core/index.ts';
+import { ClientTransportInterface as ClientTransportInterface_2 } from '../core/index.ts';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { JSONRPCMessage } from '../core/index.ts';
+import { JSONRPCMessage as JSONRPCMessage_2 } from '../../core/index.ts';
+import { MCPServerInterface } from '../core/index.ts';
+import { MCPTransportInterface } from '../core/index.ts';
+import { MCPTransportInterface as MCPTransportInterface_2 } from '../../core/index.ts';
+import { ToolManagerInterface } from '@orkestrel/agent';
+
+/**
+ * Create the browser-face HTTP CLIENT transport for an
+ * {@link import('@src/core').MCPClientInterface} — a {@link ClientTransportInterface}
+ * that drives a REMOTE Streamable-HTTP MCP server over the native `fetch`, the
+ * browser sibling of the Node face's `createHTTPClientTransport` (`@src/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
+ * `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, so the same `MCPClient` passes
+ * session validation (a stateless server sends none).
+ *
+ * @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
+ *   {@link HTTPClientTransportOptions}
+ * @returns A working {@link ClientTransportInterface} over the native `fetch`
+ *
+ * @example
+ * ```ts
+ * import { createMCPClient } from '@orkestrel/mcp'
+ * import { createHTTPClientTransport } from '@orkestrel/mcp/browser'
+ *
+ * const client = createMCPClient({
+ * 	transport: createHTTPClientTransport({ url: 'http://localhost:3000/mcp' }),
+ * })
+ * await client.connect()
+ * const tools = await client.tools()
+ * ```
+ */
+export declare function createHTTPClientTransport(options: HTTPClientTransportOptions): ClientTransportInterface_2;
+
+/**
+ * Create the browser-face `MessagePort` transport — a
+ * {@link import('@src/core').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.
+ *
+ * @remarks
+ * `port.start()` runs at construction (see {@link MessagePortTransport}'s doc for
+ * why); inbound payloads are string-only (a non-string `postMessage` payload is
+ * 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
+ *   {@link MessagePortTransportOptions}
+ * @returns A working {@link import('@src/core').MCPTransportInterface} over the port
+ *
+ * @example
+ * ```ts
+ * import { bindServer, createMCPServer } from '@orkestrel/mcp'
+ * import { createMessagePortTransport } from '@orkestrel/mcp/browser'
+ *
+ * const { port1, port2 } = new MessageChannel()
+ * bindServer(createMCPServer({ name: 's', version: '1.0.0', tools }), createMessagePortTransport({ port: port1 }))
+ * ```
+ */
+export declare function createMessagePortTransport(options: MessagePortTransportOptions): MCPTransportInterface;
+
+/**
+ * Build `serveMCPScope`'s (`serve.ts`) `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
+ * — 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.
+ *
+ * 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.
+ *
+ * @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 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 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;
+
+/**
+ * Adapt 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` (`serve.ts`) binds for the
+ * dedicated-worker shape.
+ *
+ * @remarks
+ * `send` writes each outbound string via `scope.postMessage`. `listen`/`closed`
+ * register the SINGLE handler `deliver` / the underlying close path route through —
+ * `serveMCPScope`'s own `scope` `message`-event listener calls `deliver(event.data)`
+ * for every portless, string-payload event (there is no native registration point on
+ * the scope itself for `serveMCPScope` to hand a `listen` handler to, so `deliver` is
+ * the bridge). `close()` fires the registered `closed` handler — a scope has nothing
+ * physically closable, so this is the only teardown signal available.
+ *
+ * @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`
+ *
+ * @example
+ * ```ts
+ * const scopeTransport = createScopeTransport(self)
+ * const unbind = bindServer(server, scopeTransport)
+ * ```
+ */
+export declare function createScopeTransport(scope: ServeMCPScopeInterface): ScopeTransportInterface;
+
+/**
+ * Create the browser-face WebSocket CLIENT transport for an
+ * {@link import('@src/core').MCPClientInterface} — a {@link ClientTransportInterface}
+ * that drives a REMOTE MCP server over the native `WebSocket` global, the browser
+ * sibling of the Node face's `createWebSocketClientTransport` (`@src/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,
+ * 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
+ *   `protocols` (the WebSocket subprotocol(s) to request); see
+ *   {@link WebSocketClientTransportOptions}
+ * @returns A working {@link ClientTransportInterface} over the native `WebSocket`
+ *
+ * @example
+ * ```ts
+ * import { createMCPClient } from '@orkestrel/mcp'
+ * import { createWebSocketClientTransport } from '@orkestrel/mcp/browser'
+ *
+ * const client = createMCPClient({
+ * 	transport: createWebSocketClientTransport({ url: 'ws://localhost:3000/mcp' }),
+ * })
+ * await client.connect()
+ * const tools = await client.tools()
+ * ```
+ */
+export declare function createWebSocketClientTransport(options: WebSocketClientTransportOptions): ClientTransportInterface_2;
+
+/**
+ * Decode 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
+ * `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";
+
+/** The default server version `serveMCPScope` 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 ClientTransportInterface} 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
+ * `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 (or batch) 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
+ *   `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.
+ * - **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
+ *   `@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 echo.** `start()` / `close()` are no-ops (a request/response transport
+ *   holds 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. Before `initialize`
+ *   returns an id, `session` is `undefined` and no header is sent (safe against a
+ *   stateless server, which neither sends nor expects one).
+ * - **Total at the boundary (§14).** 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 ClientTransportEventMap}); 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 ClientTransportInterface {
+    #private;
+    constructor(options: HTTPClientTransportOptions);
+    get emitter(): EmitterInterface<ClientTransportEventMap>;
+    get session(): string | undefined;
+    start(): Promise<void>;
+    send(message: JSONRPCMessage_2 | readonly 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` (e.g. 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.
+ */
+export declare interface HTTPClientTransportOptions {
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly fetch?: typeof fetch;
+    readonly timeout?: number;
+}
+
+/**
+ * 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'`, matching `createWebSocketServer`'s unconditional `Sec-WebSocket-Protocol:
+ * mcp` echo. 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`.
+ *
+ * @remarks
+ * - **Symmetric.** Unlike {@link import('./WebSocketClientTransport.js').WebSocketClientTransport}
+ *   / {@link import('./HTTPClientTransport.js').HTTPClientTransport} (CLIENT-only
+ *   carriers of `@src/core`'s `ClientTransportInterface`), a `MessagePort` is a
+ *   plain duplex channel — the SAME class implements `@src/core`'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`
+ *   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`
+ *   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
+ *   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 (§14) —
+ *   because `MCPTransportInterface` carries no `error` channel for this port to
+ *   surface a non-string frame on (unlike `ClientTransportInterface`'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
+ *   `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.
+ * - **`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`
+ *   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
+ *   second call REPLACES the first rather than adding a second subscriber.
+ *
+ * @example
+ * ```ts
+ * const { port1, port2 } = new MessageChannel()
+ * const serverTransport = new MessagePortTransport({ port: port1 })
+ * bindServer(server, serverTransport) // port1 side dispatches inbound requests
+ *
+ * const clientTransport = new MessagePortTransport({ port: port2 })
+ * const client = createMCPClient({ transport: createDuplexClientTransport(clientTransport) })
+ * bindClient(client, clientTransport) // port2 side is the client's carrier
+ * ```
+ */
+export declare class MessagePortTransport implements MCPTransportInterface_2 {
+    #private;
+    constructor(options: MessagePortTransportOptions);
+    send(message: string): void;
+    listen(handler: (message: string) => void): void;
+    closed(handler: () => void): void;
+    close(): void;
+}
+
+/**
+ * Options for `createMessagePortTransport` — the native `MessagePort` a
+ * {@link MessagePortTransport} sends and listens on.
+ *
+ * @remarks
+ * `port` — the channel half to drive (e.g. 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`).
+ */
+export declare interface MessagePortTransportOptions {
+    readonly port: MessagePort;
+}
+
+/**
+ * Decode a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it
+ * carried — the CLIENT-side inverse of the server's Streamable-HTTP SSE response.
+ *
+ * @remarks
+ * Reads the whole `response.body` stream chunk-by-chunk through a `TextDecoder({
+ * stream: true })` (handling a multi-byte char split across reads) and
+ * `@orkestrel/sse`'s {@link SSEParserInterface} (handling a partial line / in-progress
+ * event split across reads), then narrows each dispatched event's `data` to a
+ * {@link JSONRPCMessage} via {@link decodeEvent} (so a non-message / non-JSON `data:`
+ * event is DROPPED, never thrown — total, §14). 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, via this `deliver`).
+ */
+export declare interface ScopeTransportInterface extends MCPTransportInterface {
+    /** Push one inbound message string into the currently registered `listen` handler. */
+    deliver(message: string): void;
+}
+
+/**
+ * Boot an `MCPServer` inside the CURRENT hostable scope (`globalThis` — a dedicated
+ * Web Worker or a Service Worker) and wire its message events to it.
+ *
+ * @remarks
+ * A one-liner over {@link serveMCPScope}: `serveMCP(options)` is exactly
+ * `serveMCPScope(globalThis, options)`. Kept as its own export so the scope-facing
+ * wiring stays independently testable (AGENTS §5) — drive {@link serveMCPScope}
+ * directly with a scope double for a test, and this thin wrapper for real deploys.
+ *
+ * **Trust boundary and lifecycle** — see {@link serveMCPScope}'s `@remarks`. The same
+ * considerations apply: ENTIRE tool registry exposed to every accepted port-bearing
+ * event; use `accept` to gate; per-client bindings accumulate for the scope's lifetime.
+ *
+ * @param options - `tools` (the live registry to expose; REQUIRED), optional
+ *   `name`/`version`, optional `accept` (origin/identity gate); see {@link ServeMCPOptions}
+ * @returns A dispose function — see {@link serveMCPScope}
+ *
+ * @example
+ * ```ts
+ * // Inside a dedicated Web Worker's entry module:
+ * import { serveMCP } from '@orkestrel/mcp/browser'
+ * import { createToolManager, createTool } from '@orkestrel/agent'
+ *
+ * const tools = createToolManager()
+ * tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
+ * const dispose = serveMCP({ tools, name: 'worker-mcp', version: '1.0.0' })
+ * // ... later, on teardown:
+ * dispose()
+ * ```
+ */
+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
+ * {@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
+ *   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
+ *   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.
+ */
+export declare interface ServeMCPOptions {
+    readonly tools: ToolManagerInterface;
+    readonly name?: string;
+    readonly version?: string;
+    readonly accept?: (event: MessageEvent) => boolean;
+}
+
+/**
+ * Boot an `MCPServer` inside a hostable scope (a dedicated Web Worker's `self`, or a
+ * Service Worker's `self`) and wire its message events to it.
+ *
+ * @remarks
+ * **Trust boundary — mechanism, not policy.** `serveMCPScope` exposes the ENTIRE
+ * supplied `tools` registry to EVERY client the scope accepts a port from, with NO
+ * built-in origin or identity check. In a Service Worker that means every same-origin
+ * context the SW controls (any window, worker, or iframe can
+ * `controller.postMessage(msg, [port])` and get a fully-bound server with complete
+ * tool-call access). Origin allow-listing, handshake tokens, and any other gating are
+ * the embedding application's responsibility — compose a guard in front. Use the
+ * `accept` option to gate port-bearing events before binding: return `false` to drop
+ * the event entirely (no binding, no reply).
+ *
+ * **Lifetime / per-client binding accumulation.** Each accepted port-bearing event
+ * creates a fresh `MessagePortTransport` + `bindServer` binding that lives for the
+ * scope's lifetime — there is NO per-client reaping, because `MessagePort` provides
+ * no "peer closed" signal. For bounded, long-lived client sets this is fine; embedders
+ * with high client churn must track and invoke the dispose function themselves to
+ * avoid unbounded accumulation.
+ *
+ * **Portless events and the implicit scope channel.** A portless `message` event
+ * (e.g. `controller.postMessage('<json-rpc>')` in a Service Worker) delivers its
+ * string directly to the implicit scope transport — **the tool EXECUTES** — even
+ * though no reply can reach the caller. In a `ServiceWorkerGlobalScope` the reply
+ * path (`scopeTransport.send` → `scope.postMessage`) throws (no `self.postMessage`),
+ * and `bindServer` routes the throw to the server emitter's `error` event (see
+ * `@src/core bindServer`), so the un-repliable reply is dropped. The net effect is
+ * **blind side-effecting ingress**: the tool runs but the caller gets no result.
+ * Crucially, **`accept` does NOT gate this channel** — it is consulted only for
+ * port-bearing events. In a Service Worker, if `accept` is your sole guard, ensure
+ * all clients connect through transferred `MessagePort`s (port-bearing messages), or
+ * restrict the exposed tools to side-effect-free operations, or validate a token
+ * inside the tools themselves.
+ *
+ * Binds the implicit scope channel EAGERLY (at call time, not lazily on first use) —
+ * `bindServer` is called once against a {@link import('./types.js').ScopeTransportInterface}
+ * wrapping `scope` for the whole lifetime of the returned dispose, so a dedicated
+ * worker's very first portless message is served with no first-use setup cost or
+ * ordering hazard.
+ *
+ * Every inbound `message` event is inspected structurally: `event.ports.length > 0`
+ * spawns a fresh {@link import('./factories.js').createMessagePortTransport} +
+ * `bindServer` for THAT port (tracked for teardown) — this holds even on a
+ * dedicated-worker-shaped scope, the unified design's deliberate cross-case. An
+ * event with NO ports and a STRING `event.data` is delivered onto the implicit scope
+ * channel; any other event (no ports, non-string data) is dropped.
+ *
+ * @param scope - The hostable scope to wire (structurally, `self` inside a worker)
+ * @param options - `tools` (the live registry to expose; REQUIRED), optional
+ *   `name`/`version` (default {@link import('./constants.js').DEFAULT_MCP_SERVER_NAME} /
+ *   {@link import('./constants.js').DEFAULT_MCP_SERVER_VERSION}), optional `accept`
+ *   (origin/identity gate for port-bearing events); see {@link ServeMCPOptions}
+ * @returns A dispose function — unbinds every binding, closes every accepted
+ *   `MessagePort`, and removes the scope's `message` listener. Idempotent.
+ *
+ * @example
+ * ```ts
+ * const scope = { postMessage() {}, addEventListener() {}, removeEventListener() {} }
+ * const dispose = serveMCPScope(scope, {
+ *   tools: createToolManager(),
+ *   // Prefer token-in-data — event.origin is empty for same-origin worker messages.
+ *   accept: (event) => event.data === 'my-secret-token',
+ * })
+ * // ... later:
+ * dispose()
+ * ```
+ */
+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 three 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 `serve.ts`). A real `self` / `globalThis` inside a worker satisfies this
+ * structurally (it exposes far more, which this narrower shape ignores).
+ */
+export declare interface ServeMCPScopeInterface {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+}
+
+/**
+ * The browser-face WebSocket CLIENT transport for the Model Context Protocol — a
+ * {@link ClientTransportInterface} that drives a REMOTE MCP server over the native
+ * `WebSocket` global, the browser sibling of the Node face's
+ * {@link import('@src/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()`.
+ * - **Queued sends.** `send` writes each message as one text frame immediately once
+ *   the socket is `OPEN`; a `send` issued before `'open'` fires (or before `start()`
+ *   is even called) is QUEUED and flushed, IN ORDER, the moment the socket opens —
+ *   so a caller need not await `start()` before calling `send`.
+ * - **Inbound (`message`).** Each decoded text frame is `JSON.parse`d (guarded) and
+ *   narrowed with `parseJSONRPCMessage` — a well-formed {@link JSONRPCMessage}
+ *   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
+ *   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 ClientTransportEventMap}); every
+ *   emit the emitter isolates a listener throw; `error` is a DOMAIN event (a
+ *   transport-level fault).
+ *
+ * @example
+ * ```ts
+ * const transport = new WebSocketClientTransport({ url: 'ws://localhost:3000/mcp' })
+ * const client = new MCPClient({ transport })
+ * await client.connect() // the browser handshakes, then the MCP initialize runs over WS frames
+ * ```
+ */
+export declare class WebSocketClientTransport implements ClientTransportInterface {
+    #private;
+    constructor(options: WebSocketClientTransportOptions);
+    get emitter(): EmitterInterface<ClientTransportEventMap>;
+    get session(): string | undefined;
+    start(): Promise<void>;
+    send(message: JSONRPCMessage_2 | readonly JSONRPCMessage_2[]): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * Options for `createWebSocketClientTransport` (browser face) — the remote MCP
+ * WebSocket endpoint and any negotiated subprotocols.
+ *
+ * @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.
+ * - `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
+ *   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
+ *   targeting a foreign server that speaks a different (or no) subprotocol — pass `[]`
+ *   to request no subprotocol at all.
+ */
+export declare interface WebSocketClientTransportOptions {
+    readonly url: string;
+    readonly protocols?: string | readonly string[];
+}
+
+export { }