@orkestrel/mcp 0.0.4 → 0.0.6

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

@@ -0,0 +1,564 @@
+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. It also captures the initialize
+ * result's `protocolVersion` and sends `mcp-protocol-version` on every subsequent
+ * request, so the same `MCPClient` passes the session and 2025-06-18 protocol
+ * gates without caller wiring.
+ *
+ * @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 `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` 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 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 and protocol echo.** `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` on
+ *   every subsequent request, as required by the 2025-06-18 Streamable-HTTP
+ *   transport. Before initialize returns, neither captured header is sent.
+ *   `close()` clears the captured protocol so a reconnect's `initialize`
+ *   POST is headerless; the captured `session` persists across `close()`.
+ * - **Total at the boundary (§14).** Every reply is narrowed (`parseJSONRPCMessage`,
+ *   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): 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 carrying the negotiated MCP protocol version
+ * on every post-initialize request. The browser HTTP client captures the initialize
+ * result's `protocolVersion` and sends this header 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'`, 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 worker scope.
+ *
+ * @param options - The tools, optional identity, and optional port-event gate
+ * @returns The disposer returned by {@link serveMCPScope}
+ */
+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 worker scope and wire its message events to it.
+ *
+ * @remarks
+ * Port-bearing events are gated by `options.accept`, deduplicated by port, and receive
+ * their own `MessagePortTransport` binding. Portless string events use the scope's
+ * implicit channel. The returned disposer removes the listener, unbinds the implicit
+ * channel, and closes every accepted port binding.
+ *
+ * @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 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 the bootstrap factories). 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): 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 { }