@orkestrel/mcp 0.0.1

package/dist/src/core/index.d.cts

@@ -0,0 +1,805 @@
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { ToolInterface } from '@orkestrel/agent';
+import { ToolManagerInterface } from '@orkestrel/agent';
+import { ToolResult } from '@orkestrel/agent';
+
+/**
+ * Map a {@link ToolManagerInterface}'s definitions to MCP `tools/list` descriptors
+ * — renaming `parameters` to the wire's `inputSchema`.
+ *
+ * @remarks
+ * Each {@link import('@orkestrel/agent').ToolDefinition} carries through its
+ * `name` and (when present) `description`; its open JSON-Schema `parameters`
+ * becomes `inputSchema`, defaulting to an empty object schema (`{ type: 'object' }`)
+ * when a tool declares none (MCP requires an `inputSchema`).
+ *
+ * @param manager - The tool registry to describe
+ * @returns One {@link MCPToolDescriptor} per registered tool, in registry order
+ */
+export declare function buildToolDescriptors(manager: ToolManagerInterface): readonly MCPToolDescriptor[];
+
+/**
+ * Map an executed tool's {@link ToolResult} to an MCP {@link MCPToolResult} — the
+ * value (or error) as a `text` content block.
+ *
+ * @remarks
+ * The {@link ToolManagerInterface} already isolates a thrown tool into
+ * `result.error` (so the server adds NO try/catch around `execute`): when `error`
+ * is present, this builds an `isError: true` result carrying the error text, so the
+ * model sees the failure as a tool result it can react to rather than a protocol
+ * error; otherwise it serializes `result.value` (via `JSON.stringify`) into one
+ * `text` block.
+ *
+ * @param result - The tool's execution outcome
+ * @returns The MCP tool-call result
+ */
+export declare function buildToolResult(result: ToolResult): MCPToolResult;
+
+/**
+ * The observable events of a {@link ClientTransportInterface} (§13) — the moments the
+ * {@link MCPClientInterface} (and any tracer) subscribes to via `transport.emitter.on`.
+ *
+ * @remarks
+ * - `message` — a JSON-RPC message ARRIVED from the remote server (a response the
+ *   client correlates to a pending request by `id`, or a server-initiated
+ *   notification). The transport decodes the wire bytes (a JSON body or an SSE
+ *   `data:` event) and emits the parsed {@link JSONRPCMessage}.
+ * - `close` — the transport's connection ended (a stream closed, `close()` ran).
+ * - `error` — a transport-level fault (a malformed message, a network error); the
+ *   payload is typed `unknown` (§13). This is a DOMAIN event, distinct from the emitter's
+ *   own listener-error channel: a listener throw is routed to the emitter's `error` handler
+ *   (the `error` option), never onto this map. Declared as a `type` alias (§4.5) so the
+ *   type-literal satisfies `EventMap` structurally.
+ */
+export declare type ClientTransportEventMap = {
+    /** A JSON-RPC message arrived from the remote server (a response, or a notification). */
+    readonly message: readonly [message: JSONRPCMessage];
+    /** The transport's connection ended. */
+    readonly close: readonly [];
+    /** A transport-level fault — the caught error (typed `unknown`, §13). */
+    readonly error: readonly [error: unknown];
+};
+
+/**
+ * A transport-agnostic carrier for the MCP CLIENT — pumps JSON-RPC messages to a
+ * remote server and surfaces the server's replies on its `emitter`'s `message`
+ * event, with NO knowledge of the protocol it carries.
+ *
+ * @remarks
+ * The mirror of the server's "a transport pumps strings through `handle`": here the
+ * {@link MCPClientInterface} hands the transport a {@link JSONRPCMessage} (or a batch)
+ * via `send`, and the transport delivers each decoded reply back through the
+ * `message` event the client subscribed to. The minimal carrier surface (§21): a
+ * `start` (open the connection / arm any reader), `send` (write a message or batch),
+ * and `close` (tear down). `session` exposes a server-assigned session id once a
+ * stateful transport has one (`undefined` for the stateless v1) — reserved for the
+ * later sessions tier. Concrete transports (the HTTP transport over `fetch`, a future
+ * WebSocket one) live in `src/server/mcp`; the in-process loopback transport in the
+ * tests is one too.
+ */
+export declare interface ClientTransportInterface {
+    readonly emitter: EmitterInterface<ClientTransportEventMap>;
+    /** A server-assigned session id once a stateful transport has one; `undefined` otherwise. */
+    readonly session: string | undefined;
+    /**
+     * Open the transport — establish the connection and arm any reply reader.
+     *
+     * @returns Resolves once the transport is ready to `send`
+     */
+    start(): Promise<void>;
+    /**
+     * Send one JSON-RPC message (or a batch) to the remote server.
+     *
+     * @remarks
+     * Each decoded reply is surfaced on the `emitter`'s `message` event — `send`
+     * itself resolves once the message has been written (and, for a request/response
+     * transport, its synchronous reply emitted), not when a logical response arrives;
+     * the {@link MCPClientInterface} awaits the response through its `id` correlation.
+     *
+     * @param message - One message, or a batch of them, to write to the wire
+     * @returns Resolves once the message(s) have been sent
+     */
+    send(message: JSONRPCMessage | readonly JSONRPCMessage[]): Promise<void>;
+    /**
+     * Close the transport — end the connection and release resources.
+     *
+     * @returns Resolves once the transport is closed
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Create a transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE
+ * MCP server over an injected {@link import('./types.js').ClientTransportInterface},
+ * runs the `initialize` handshake, and exposes the server's tools as local
+ * {@link import('@orkestrel/agent').ToolInterface}s an agent can run.
+ *
+ * @remarks
+ * The egress mirror of {@link createMCPServer}: where the server exposes a local tool
+ * registry over MCP, the client USES a remote server's tools. `connect()` handshakes,
+ * `tools()` lists + wraps the remote tools (each `execute` calls back over the wire),
+ * and `call(name, args)` runs a remote `tools/call` (a remote tool failure throws
+ * locally, so an agent's {@link import('@orkestrel/agent').ToolManagerInterface}
+ * isolates it). The transport is injected — a concrete one (the HTTP transport over
+ * `fetch`) lives in `@src/server`; the client itself is provider-agnostic. Subscribe
+ * to `connect` / `disconnect` / `notification` via `client.on(...)` (or
+ * `client.emitter.on(...)`).
+ *
+ * @param options - `transport` (the carrier; REQUIRED), `name` / `version` (the client
+ *   identity), `timeout` (the per-request deadline), and the reserved `on`
+ *   {@link import('@orkestrel/emitter').EmitterHooks} (see {@link MCPClientOptions})
+ * @returns A working {@link MCPClientInterface}
+ *
+ * @example
+ * ```ts
+ * import { createMCPClient } from '@src/core'
+ * import { createHTTPClientTransport } from '@src/server'
+ *
+ * const client = createMCPClient({
+ * 	transport: createHTTPClientTransport({ url: 'http://localhost:3000/mcp' }),
+ * })
+ * await client.connect()
+ * agent.context.tools.add(await client.tools()) // give the agent the remote tools
+ * const value = await client.call('search', { query: 'mcp' })
+ * ```
+ */
+export declare function createMCPClient(options: MCPClientOptions): MCPClientInterface;
+
+/**
+ * Create a transport-agnostic Model Context Protocol server — exposes a live
+ * {@link import('@orkestrel/agent').ToolManagerInterface} over JSON-RPC 2.0
+ * (`initialize` / `ping` / `tools/list` / `tools/call`).
+ *
+ * @remarks
+ * Pump raw message strings through `handle` (parse → dispatch → serialize) from a
+ * transport, or call the typed `dispatch` directly with an already-parsed request.
+ * The server is provider-agnostic — JSON-RPC plus the tool registry, with no HTTP
+ * and no model. The {@link import('@orkestrel/agent').ToolManagerInterface} already
+ * isolates a thrown tool into a result error (surfaced as an MCP `isError: true`
+ * tool result), so a misbehaving tool never crashes a dispatch. Subscribe to the
+ * `request` event via `server.emitter.on('request', …)` for tracing.
+ *
+ * @param options - `name` / `version` (the server identity), `tools` (the live
+ *   registry to expose), an optional `description`, and the reserved `on`
+ *   {@link import('@orkestrel/emitter').EmitterHooks} (see {@link MCPServerOptions})
+ * @returns A working {@link MCPServerInterface}
+ *
+ * @example
+ * ```ts
+ * import { createMCPServer, createTool, createToolManager } from '@src/core'
+ *
+ * const tools = createToolManager()
+ * tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
+ *
+ * const server = createMCPServer({ name: 'calculator', version: '1.0.0', tools })
+ * server.emitter.on('request', (method, id) => log(method, id))
+ *
+ * // A transport pumps message strings through `handle`:
+ * const reply = await server.handle('{"jsonrpc":"2.0","method":"tools/list","id":1}')
+ * // reply → '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"add","inputSchema":{"type":"object"}}]}}'
+ * ```
+ */
+export declare function createMCPServer(options: MCPServerOptions): MCPServerInterface;
+
+/** The default client name reported in the MCP `initialize` handshake (`clientInfo.name`). */
+export declare const DEFAULT_MCP_CLIENT_NAME = "taverna";
+
+/** The default client version reported in the MCP `initialize` handshake (`clientInfo.version`). */
+export declare const DEFAULT_MCP_CLIENT_VERSION = "1.0.0";
+
+/**
+ * The default per-request deadline (ms) an `MCPClient` applies when `options.timeout`
+ * is unset — a request the remote server does not answer within it rejects.
+ */
+export declare const DEFAULT_MCP_REQUEST_TIMEOUT = 30000;
+
+/**
+ * Build the MCP `initialize` result — the negotiated protocol version, the
+ * advertised capabilities, and the server identity.
+ *
+ * @remarks
+ * Version negotiation echoes the client's `requested` version when it is one of the
+ * {@link SUPPORTED_PROTOCOL_VERSIONS}, else falls back to {@link MCP_PROTOCOL_VERSION}.
+ * `capabilities.tools` is an empty object — this server advertises the tools
+ * capability with no sub-options (no list-changed notification yet).
+ *
+ * @param name - The server name (echoed in `serverInfo`)
+ * @param version - The server version (echoed in `serverInfo`)
+ * @param requested - The client's requested protocol version (negotiated when supported)
+ * @returns The `initialize` result payload
+ */
+export declare function initializeResult(name: string, version: string, requested?: string): Readonly<Record<string, unknown>>;
+
+/**
+ * Determine whether a parsed value is an MCP `initialize` request — a
+ * {@link JSONRPCRequest} whose `method` is `'initialize'`.
+ *
+ * @param value - The already-parsed value to test
+ * @returns `true` when `value` is a valid `initialize` request
+ *
+ * @example
+ * ```ts
+ * isInitializeRequest({ jsonrpc: '2.0', method: 'initialize', id: 1 }) // true
+ * isInitializeRequest({ jsonrpc: '2.0', method: 'ping', id: 1 }) // false
+ * ```
+ */
+export declare function isInitializeRequest(value: unknown): value is JSONRPCRequest;
+
+/**
+ * Determine whether a parsed value is a {@link JSONRPCMessage} — a request or a
+ * response.
+ *
+ * @remarks
+ * The union of {@link isJSONRPCRequest} and {@link isJSONRPCResponse}. Total (§14).
+ *
+ * @param value - The already-parsed value to test
+ * @returns `true` when `value` is a valid JSON-RPC request or response
+ */
+export declare function isJSONRPCMessage(value: unknown): value is JSONRPCMessage;
+
+/**
+ * Determine whether a parsed value is a {@link JSONRPCRequest}.
+ *
+ * @remarks
+ * A request is a record with `jsonrpc === '2.0'` and a string `method`. `id`, when
+ * present, must be a string or number; its ABSENCE is valid — that marks a
+ * NOTIFICATION (a fire-and-forget request that yields no response). `params`, when
+ * present, must be a record. Total (§14): any other input returns `false`.
+ *
+ * @param value - The already-parsed value to test
+ * @returns `true` when `value` is a valid JSON-RPC request
+ *
+ * @example
+ * ```ts
+ * isJSONRPCRequest({ jsonrpc: '2.0', method: 'ping', id: 1 }) // true
+ * isJSONRPCRequest({ jsonrpc: '2.0', method: 'notifications/initialized' }) // true — a notification
+ * isJSONRPCRequest({ jsonrpc: '1.0', method: 'ping' }) // false
+ * ```
+ */
+export declare function isJSONRPCRequest(value: unknown): value is JSONRPCRequest;
+
+/**
+ * Determine whether a parsed value is a {@link JSONRPCResponse}.
+ *
+ * @remarks
+ * A response is a record with `jsonrpc === '2.0'`, an `id` that is a string,
+ * number, or `null`, and EXACTLY ONE of a `result` (any value, including
+ * `undefined`'s absence) or an `error` (a record with a numeric `code` and string
+ * `message`). Total (§14).
+ *
+ * @param value - The already-parsed value to test
+ * @returns `true` when `value` is a valid JSON-RPC response
+ */
+export declare function isJSONRPCResponse(value: unknown): value is JSONRPCResponse;
+
+/**
+ * Determine whether a value is a valid JSON-RPC REQUEST `id` — a string, a number,
+ * or absent.
+ *
+ * @remarks
+ * A request id is a string, a number, or `undefined` (its ABSENCE marks a
+ * NOTIFICATION). `null` is NOT a valid request id — it is valid only on a RESPONSE.
+ * Total (§14): any other input returns `false`.
+ *
+ * @param value - The already-parsed value to test
+ * @returns `true` when `value` is a string, a number, or `undefined`
+ *
+ * @example
+ * ```ts
+ * isRequestId(1)         // true
+ * isRequestId('abc')     // true
+ * isRequestId(undefined) // true — a notification
+ * isRequestId(null)      // false — valid only on a response
+ * ```
+ */
+export declare function isRequestId(value: unknown): value is string | number | undefined;
+
+/** JSON-RPC 2.0 reserved error: the method's parameters were invalid. */
+export declare const JSONRPC_INVALID_PARAMS = -32602;
+
+/** JSON-RPC 2.0 reserved error: the payload was not a valid Request object. */
+export declare const JSONRPC_INVALID_REQUEST = -32600;
+
+/** JSON-RPC 2.0 reserved error: the requested method does not exist. */
+export declare const JSONRPC_METHOD_NOT_FOUND = -32601;
+
+/** JSON-RPC 2.0 reserved error: invalid JSON was received (the message did not parse). */
+export declare const JSONRPC_PARSE_ERROR = -32700;
+
+/** JSON-RPC 2.0 implementation-defined server error (the `-32000` to `-32099` range). */
+export declare const JSONRPC_SERVER_ERROR = -32000;
+
+/**
+ * Build a JSON-RPC error {@link JSONRPCResponse} — the `id` echoed, the failure as
+ * an `error` object.
+ *
+ * @param id - The request's id (`null` for a parse / invalid-request error)
+ * @param code - One of the reserved JSON-RPC codes (see `./constants.js`)
+ * @param message - A short human description of the failure
+ * @param data - An OPTIONAL machine-readable payload (omitted from the envelope when absent)
+ * @returns The error response envelope
+ */
+export declare function jsonRPCError(id: string | number | null, code: number, message: string, data?: unknown): JSONRPCResponse;
+
+/**
+ * A JSON-RPC 2.0 error object — the `error` member of a failed
+ * {@link JSONRPCResponse}.
+ *
+ * @remarks
+ * `code` is one of the reserved JSON-RPC codes (see `./constants.js`); `message`
+ * is a short human description; `data` is an OPTIONAL machine-readable payload
+ * carrying extra detail.
+ */
+export declare interface JSONRPCErrorData {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+}
+
+/** A JSON-RPC 2.0 message on the wire — a {@link JSONRPCRequest} or a {@link JSONRPCResponse}. */
+export declare type JSONRPCMessage = JSONRPCRequest | JSONRPCResponse;
+
+/**
+ * A JSON-RPC 2.0 request — a `method` call with optional `params`, correlated to
+ * its response by `id`.
+ *
+ * @remarks
+ * `jsonrpc` is the literal `'2.0'`. An ABSENT `id` marks a NOTIFICATION — a
+ * fire-and-forget call the server handles WITHOUT producing a response (e.g.
+ * `notifications/initialized`). `params` is an open record forwarded to the
+ * method handler (the handler narrows the fields it reads, §14).
+ */
+export declare interface JSONRPCRequest {
+    readonly jsonrpc: '2.0';
+    readonly method: string;
+    /** Correlates the request with its response; ABSENT ⇒ a notification (no response). */
+    readonly id?: string | number;
+    /** The method's open argument record (narrowed by the handler, §14). */
+    readonly params?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A JSON-RPC 2.0 response — the same `id` as its request, carrying EITHER a
+ * `result` (success) OR an `error` (failure), never both.
+ *
+ * @remarks
+ * `id` is `null` only when the request could not be parsed or its id read (a
+ * parse / invalid-request error), per the spec; otherwise it echoes the
+ * request's id. `result` is the method's return value (an open `unknown`);
+ * `error` is a {@link JSONRPCErrorData}.
+ */
+export declare interface JSONRPCResponse {
+    readonly jsonrpc: '2.0';
+    readonly id: string | number | null;
+    readonly result?: unknown;
+    readonly error?: JSONRPCErrorData;
+}
+
+/**
+ * Build a JSON-RPC success {@link JSONRPCResponse} — the `id` echoed, the method's
+ * value as `result`.
+ *
+ * @param id - The request's id (`null` only for a parse / invalid-request error)
+ * @param result - The method's return value
+ * @returns The success response envelope
+ */
+export declare function jsonRPCResult(id: string | number | null, result: unknown): JSONRPCResponse;
+
+/** The MCP protocol revision this server implements (the default negotiated version). */
+export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+
+/**
+ * A transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE MCP server
+ * over an injected {@link ClientTransportInterface}, runs the `initialize` handshake,
+ * and exposes the server's tools as local {@link ToolInterface}s an agent can run.
+ *
+ * @remarks
+ * - **The mirror of `MCPServer`.** The server DISPATCHES requests over a tool registry;
+ *   this client ISSUES them over a transport. `connect` runs `initialize` then sends
+ *   `notifications/initialized`; `tools()` lists the remote tools and wraps each as a
+ *   local {@link ToolInterface} whose `execute` calls back through `call`; `call` runs a
+ *   remote `tools/call` and returns the tool's value (a remote `isError: true` throws
+ *   locally, so an agent's {@link import('@orkestrel/agent').ToolManagerInterface}
+ *   isolates it into a result `error` just like a local throw).
+ * - **Request↔response correlation.** Each request is tagged with a monotonic numeric
+ *   `id` ({@link #nextId}); a single transport `message` subscription resolves / rejects
+ *   the matching {@link #pending} entry by `id`. A message that is NOT a response to a
+ *   pending request is a server NOTIFICATION — re-surfaced on the `notification` event.
+ * - **Per-request deadline.** `#request` races `AbortSignal.timeout(this.#timeout)` (the
+ *   taverna idiom — never a raw `setTimeout`): a server that never replies REJECTS the
+ *   pending request once the deadline fires, never hanging.
+ * - **Transport-agnostic.** Imports only core siblings (JSON-RPC + the tool vocabulary);
+ *   the concrete transport is injected. Wire fields are narrowed via the contracts
+ *   guards (no `as`).
+ * - **Observable (§13).** The owned `emitter` fires `connect` / `disconnect` /
+ *   `notification` / `error`; the emitter isolates a listener throw and routes it to its
+ *   `error` handler (the `error` option), so a listener throw can never escape.
+ *
+ * @example
+ * ```ts
+ * const client = new MCPClient({ transport, name: 'agent', version: '1.0.0' })
+ * await client.connect()
+ * const tools = await client.tools()
+ * agent.context.tools.add(tools) // the remote tools are now the agent's
+ * const value = await client.call('search', { query: 'mcp' })
+ * ```
+ */
+export declare class MCPClient implements MCPClientInterface {
+    #private;
+    constructor(options: MCPClientOptions);
+    get emitter(): EmitterInterface<MCPClientEventMap>;
+    get connected(): boolean;
+    get transport(): ClientTransportInterface;
+    on<K extends keyof MCPClientEventMap>(event: K, handler: (...args: MCPClientEventMap[K]) => void): void;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    tools(): Promise<readonly ToolInterface[]>;
+    call(name: string, args: Readonly<Record<string, unknown>>): Promise<unknown>;
+}
+
+/**
+ * The push observation surface (§13) of an {@link MCPClientInterface} — the moments a
+ * fire-and-forget observer (logging, tracing) subscribes to via `client.emitter.on`.
+ *
+ * @remarks
+ * - `connect` — the `initialize` handshake completed (the client is connected).
+ * - `disconnect` — the client disconnected (every pending request rejected, the
+ *   transport closed).
+ * - `notification` — a server-initiated JSON-RPC NOTIFICATION arrived (a `message`
+ *   that is not a response to a pending request) — forwarded for the consumer to
+ *   react to (e.g. a `notifications/tools/list_changed`).
+ * - `error` — a client-level fault surfaced for observation (typed `unknown`, §13). This is
+ *   a DOMAIN event, distinct from the emitter's own listener-error channel: a listener throw
+ *   is routed to the emitter's `error` handler (the `error` option), never onto this map.
+ *   Declared as a `type` alias (§4.5) so the literal satisfies `EventMap`.
+ */
+export declare type MCPClientEventMap = {
+    /** The `initialize` handshake completed — the client is connected. */
+    readonly connect: readonly [];
+    /** The client disconnected — pending requests rejected, the transport closed. */
+    readonly disconnect: readonly [];
+    /** A server-initiated notification arrived (not a response to a pending request). */
+    readonly notification: readonly [message: JSONRPCMessage];
+    /** A client-level fault surfaced for observation (typed `unknown`, §13). */
+    readonly error: readonly [error: unknown];
+};
+
+/**
+ * A transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE MCP
+ * server over an injected {@link ClientTransportInterface}, performs the
+ * `initialize` handshake, and exposes the server's tools as local
+ * {@link ToolInterface}s an agent can run.
+ *
+ * @remarks
+ * - **The mirror of {@link MCPServerInterface}.** Where the server DISPATCHES requests
+ *   over a tool registry, the client ISSUES them over a transport: `connect` runs the
+ *   `initialize` handshake (then sends `notifications/initialized`); `tools()` lists
+ *   the remote tools and wraps each as a local {@link ToolInterface} whose `execute`
+ *   calls back through `call`; `call(name, args)` runs a remote `tools/call` and
+ *   returns the tool's value (a remote tool FAILURE — `isError: true` — throws locally,
+ *   so the agent's {@link ToolManagerInterface} isolates it into a result `error` just
+ *   like a local throw).
+ * - **Request↔response correlation.** Every request is tagged with a monotonic numeric
+ *   `id`; the client subscribes to the transport's `message` event and resolves /
+ *   rejects the matching pending request by that `id`. A message that is NOT a response
+ *   to a pending request is a server NOTIFICATION — surfaced on `notification`.
+ * - **Per-request deadline.** Each request races an `AbortSignal.timeout(timeout)`
+ *   deadline: a server that never replies REJECTS the pending request once the
+ *   deadline fires, never hanging.
+ * - **Transport-agnostic.** Imports only core siblings — JSON-RPC + the tool vocabulary
+ *   + the timeout primitive — with no HTTP and no model; the concrete transport is
+ *   injected. Wire fields are narrowed via the contracts guards (no `as`).
+ * - **Observable (§13).** The owned `emitter` fires `connect` / `disconnect` /
+ *   `notification` / `error`; the emitter isolates a listener throw and routes it to its
+ *   `error` handler (the `error` option, §13), never the client.
+ */
+export declare interface MCPClientInterface {
+    readonly emitter: EmitterInterface<MCPClientEventMap>;
+    /** Whether the `initialize` handshake has completed and the client is connected. */
+    readonly connected: boolean;
+    /** The injected transport the client drives the remote server over. */
+    readonly transport: ClientTransportInterface;
+    /**
+     * Subscribe a listener to one of the client's {@link MCPClientEventMap} events —
+     * the convenience forward to `emitter.on` (§13).
+     *
+     * @param event - The event name to subscribe to
+     * @param handler - The listener for that event's argument tuple
+     */
+    on<K extends keyof MCPClientEventMap>(event: K, handler: (...args: MCPClientEventMap[K]) => void): void;
+    /**
+     * Connect to the remote server — open the transport and run the `initialize`
+     * handshake (then send `notifications/initialized`).
+     *
+     * @remarks
+     * Idempotent — a second `connect` while already connected is a no-op. On success
+     * the `connect` event fires.
+     *
+     * @returns Resolves once the handshake completes and the client is connected
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the remote server — reject every pending request and close the
+     * transport.
+     *
+     * @remarks
+     * Idempotent — a second `disconnect` while already disconnected is a no-op. The
+     * `disconnect` event fires.
+     *
+     * @returns Resolves once the transport is closed
+     */
+    disconnect(): Promise<void>;
+    /**
+     * List the remote server's tools, each wrapped as a local {@link ToolInterface}
+     * whose `execute` runs the remote `tools/call` via {@link call}.
+     *
+     * @remarks
+     * Runs `tools/list` and maps each descriptor: `name` (narrowed to a string),
+     * `description`, and `inputSchema` → `parameters` (the inverse of the server's
+     * `parameters` → `inputSchema` rename). Add the returned tools to an agent's
+     * {@link ToolManagerInterface} to give it the remote tools.
+     *
+     * @returns The remote tools as local {@link ToolInterface}s, in server order
+     */
+    tools(): Promise<readonly ToolInterface[]>;
+    /**
+     * Call a remote tool by name and return its value — runs `tools/call`, concats the
+     * result's `text` content blocks, and either parses the JSON value or throws.
+     *
+     * @remarks
+     * The inverse of the server's `buildToolResult`: a SUCCESS parses the concatenated
+     * `text` as JSON (falling back to the raw string when it is not JSON); a remote tool
+     * FAILURE (`isError: true`) THROWS an `Error` carrying the error text — so an agent's
+     * {@link ToolManagerInterface} isolates the remote failure into a result `error`
+     * exactly as it would a local tool throw.
+     *
+     * @param name - The remote tool's name
+     * @param args - The arguments record forwarded as the call's `arguments`
+     * @returns The remote tool's value (parsed JSON, or the raw text)
+     */
+    call(name: string, args: Readonly<Record<string, unknown>>): Promise<unknown>;
+}
+
+/**
+ * Options for `createMCPClient` — the {@link ClientTransportInterface} to drive, the
+ * client identity (`name` / `version`), the per-request `timeout`, and the reserved
+ * `on` hooks (§8).
+ *
+ * @remarks
+ * - `transport` — the carrier the client drives a remote MCP server over (REQUIRED;
+ *   a concrete one from `src/server/mcp`, or an in-process loopback).
+ * - `name` / `version` — identify the client in the `initialize` handshake
+ *   (`clientInfo`); default to {@link import('./constants.js').DEFAULT_MCP_CLIENT_NAME}
+ *   / {@link import('./constants.js').DEFAULT_MCP_CLIENT_VERSION}.
+ * - `timeout` — the per-request deadline in milliseconds: a `tools/list` / `tools/call`
+ *   / `initialize` that the server does not answer within it REJECTS (the pending
+ *   request is settled by an `AbortSignal.timeout(timeout)` deadline — never a raw
+ *   `setTimeout`). Defaults to {@link
+ *   import('./constants.js').DEFAULT_MCP_REQUEST_TIMEOUT}.
+ * - `on` — the §8 reserved key: initial listeners for the client's
+ *   {@link MCPClientEventMap}, wired at construction.
+ */
+export declare interface MCPClientOptions {
+    readonly on?: EmitterHooks<MCPClientEventMap>;
+    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    readonly error?: EmitterErrorHandler;
+    readonly transport: ClientTransportInterface;
+    readonly name?: string;
+    readonly version?: string;
+    /** The per-request deadline in milliseconds (default {@link import('./constants.js').DEFAULT_MCP_REQUEST_TIMEOUT}). */
+    readonly timeout?: number;
+}
+
+/** One content item of an MCP {@link MCPToolResult} — a `text` block carrying the tool's output. */
+export declare interface MCPContent {
+    readonly type: 'text';
+    readonly text: string;
+}
+
+/**
+ * A transport-agnostic Model Context Protocol server — dispatches JSON-RPC 2.0
+ * requests over a live {@link ToolManagerInterface}, with NO transport coupling.
+ *
+ * @remarks
+ * - **Two entry points.** `dispatch(request)` runs an already-parsed request and
+ *   resolves a {@link JSONRPCResponse} — or `undefined` for a NOTIFICATION (a
+ *   request with no `id`). `handle(message)` is the string boundary: it
+ *   `JSON.parse`s the raw message (a failure → a `-32700` response), narrows it to
+ *   a request (a non-request → a `-32600` response), dispatches, and serializes the
+ *   response back to a string (`undefined` for a notification).
+ * - **The method switch.** `initialize` negotiates the protocol version + advertises
+ *   the tools capability; `notifications/initialized` is a notification (no
+ *   response); `ping` returns `{}`; `tools/list` lists the registry's tools (its
+ *   `parameters` renamed to `inputSchema`); `tools/call` runs a tool by name (the
+ *   {@link ToolManagerInterface} isolates a tool throw into the result `error`, which
+ *   maps to an `isError: true` tool result — so the server adds NO try/catch). An
+ *   unknown method → `-32601`; a `tools/call` with a missing / non-string `name` →
+ *   `-32602`.
+ * - **Provider-agnostic.** Imports only core siblings — JSON-RPC + the tool registry,
+ *   no HTTP, no model. Wire fields are narrowed via the contracts guards (no `as`).
+ * - **Observable (§13).** The owned `emitter` fires `request` at the top of every
+ *   dispatch; the emitter isolates a listener throw and routes it to its `error` handler
+ *   (the `error` option), so a listener throw can never escape the dispatch.
+ *
+ * @example
+ * ```ts
+ * const tools = createToolManager()
+ * tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
+ * const server = new MCPServer({ name: 'demo', version: '1.0.0', tools })
+ * await server.handle('{"jsonrpc":"2.0","method":"ping","id":1}') // '{"jsonrpc":"2.0","id":1,"result":{}}'
+ * ```
+ */
+export declare class MCPServer implements MCPServerInterface {
+    #private;
+    constructor(options: MCPServerOptions);
+    get emitter(): EmitterInterface<MCPServerEventMap>;
+    get name(): string;
+    get version(): string;
+    dispatch(request: JSONRPCRequest): Promise<JSONRPCResponse | undefined>;
+    handle(message: string): Promise<string | undefined>;
+}
+
+/**
+ * The push observation surface (§13) of an {@link MCPServerInterface} — the
+ * dispatch moments a fire-and-forget observer (logging, tracing) subscribes to
+ * via `server.emitter.on`.
+ *
+ * @remarks
+ * `request` fires at the TOP of every `dispatch` with the method and the
+ * correlating id (`null` for a notification), BEFORE the method runs — so an
+ * observer sees every inbound call. Listener isolation is the emitter's (§13): a
+ * listener throw is routed to the emitter's `error` handler (the `error` option),
+ * never onto this map, so a buggy observer can never corrupt a dispatch. Declared as
+ * a `type` alias (§4.5) so the type-literal satisfies `EventMap` structurally.
+ */
+export declare type MCPServerEventMap = {
+    /** A request is being dispatched — its `method` and correlating `id` (`null` for a notification). */
+    readonly request: readonly [method: string, id: string | number | null];
+};
+
+/** The server identity echoed in the MCP `initialize` result's `serverInfo`. */
+export declare interface MCPServerInfo {
+    readonly name: string;
+    readonly version: string;
+}
+
+/**
+ * A transport-agnostic Model Context Protocol server — dispatches JSON-RPC 2.0
+ * requests (`initialize` / `ping` / `tools/list` / `tools/call`) over a live
+ * {@link ToolManagerInterface}, with NO transport coupling (a transport layer
+ * pumps strings through `handle`).
+ *
+ * @remarks
+ * - **Two entry points.** `dispatch(request)` is the TYPED core: it takes an
+ *   already-parsed {@link JSONRPCRequest}, runs the method, and resolves a
+ *   {@link JSONRPCResponse} — or `undefined` for a NOTIFICATION (a request with no
+ *   `id`). `handle(message)` is the STRING boundary: it `JSON.parse`s the raw
+ *   message, narrows it to a request, dispatches, and serializes the response back
+ *   to a string — turning a parse failure into a `-32700` response and a non-request
+ *   into a `-32600` response, and returning `undefined` for a notification.
+ * - **Provider-agnostic.** Imports only core siblings; it speaks JSON-RPC + the
+ *   tool registry, with no HTTP, no model, and no backend coupling.
+ * - **Observable (§13).** The owned `emitter` ({@link MCPServerEventMap}) fires
+ *   `request` per dispatch; the emitter isolates a listener throw and routes it to its
+ *   `error` handler (the `error` option, §13), never the dispatch.
+ */
+export declare interface MCPServerInterface {
+    readonly emitter: EmitterInterface<MCPServerEventMap>;
+    readonly name: string;
+    readonly version: string;
+    /**
+     * Dispatch an already-parsed request — run its method and resolve the response,
+     * or `undefined` for a notification (a request with no `id`).
+     *
+     * @param request - The parsed JSON-RPC request to dispatch
+     * @returns The response, or `undefined` when the request was a notification
+     */
+    dispatch(request: JSONRPCRequest): Promise<JSONRPCResponse | undefined>;
+    /**
+     * Handle a raw message string — parse it, dispatch, and serialize the response.
+     *
+     * @remarks
+     * A `JSON.parse` failure resolves a serialized `-32700` (Parse error) response;
+     * a parsed value that is not a valid request resolves a serialized `-32600`
+     * (Invalid Request) response; a notification resolves `undefined` (no response).
+     *
+     * @param message - The raw JSON-RPC message string
+     * @returns The serialized response string, or `undefined` for a notification
+     */
+    handle(message: string): Promise<string | undefined>;
+}
+
+/**
+ * Options for `createMCPServer` — the server identity (`name` / `version`), the
+ * live {@link ToolManagerInterface} it exposes, an optional `description`, and the
+ * reserved `on` hooks (§8).
+ *
+ * @remarks
+ * `name` / `version` identify the server in the `initialize` handshake
+ * (`serverInfo`). `tools` is the live registry the server dispatches `tools/list`
+ * / `tools/call` over — its `definitions()` advertise the tools and its
+ * `execute()` runs a call (the manager already isolates a tool throw into a
+ * result `error`, so the server adds none). `description` is a human label for
+ * the server (reserved for a future `instructions` capability — unused by the
+ * current dispatch). `on` is the §8 reserved key: initial listeners for the
+ * server's {@link MCPServerEventMap}, wired at construction.
+ */
+export declare interface MCPServerOptions {
+    readonly on?: EmitterHooks<MCPServerEventMap>;
+    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    readonly error?: EmitterErrorHandler;
+    readonly name: string;
+    readonly version: string;
+    /** The live tool registry the server exposes over `tools/list` / `tools/call`. */
+    readonly tools: ToolManagerInterface;
+    /** A human label for the server (reserved for a future capability; unused by dispatch). */
+    readonly description?: string;
+}
+
+/**
+ * One entry of the MCP `tools/list` result — a tool's `name`, optional
+ * `description`, and its JSON-Schema `inputSchema`.
+ *
+ * @remarks
+ * The wire renaming of a `ToolDefinition`: `name` / `description` carry through,
+ * and `parameters` becomes `inputSchema` (the MCP field name), defaulting to an
+ * empty object schema (`{ type: 'object' }`) when a tool declares none.
+ */
+export declare interface MCPToolDescriptor {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * The MCP `tools/call` result — the executed tool's output as `content` blocks,
+ * with `isError` flagging a tool failure.
+ *
+ * @remarks
+ * A success carries the tool's value serialized into one `text` content block; a
+ * tool FAILURE (the `ToolResult.error` the registry isolated) carries the error
+ * text in `content` AND sets `isError: true`, so the model sees the failure as a
+ * tool result it can react to rather than a protocol error.
+ */
+export declare interface MCPToolResult {
+    readonly content: readonly MCPContent[];
+    /** `true` when the tool failed — its error text is in `content`. */
+    readonly isError?: boolean;
+}
+
+/**
+ * Narrow an already-parsed value to a {@link JSONRPCMessage}, or `undefined` when
+ * it is not one.
+ *
+ * @remarks
+ * Total (§14) — a non-message returns `undefined`, never throws. The input must
+ * ALREADY be `JSON.parse`d: the raw-string parse (which can throw on malformed
+ * JSON) happens in `MCPServer.handle` inside a try/catch that maps a parse failure
+ * to a `-32700` response. Sound with {@link isJSONRPCMessage}: a guard-valid input
+ * is returned unchanged, and every non-`undefined` output satisfies the guard.
+ *
+ * @param value - The already-parsed value to narrow
+ * @returns The value as a {@link JSONRPCMessage}, or `undefined`
+ *
+ * @example
+ * ```ts
+ * parseJSONRPCMessage({ jsonrpc: '2.0', method: 'ping', id: 1 }) // the request
+ * parseJSONRPCMessage({ method: 'ping' }) // undefined — missing jsonrpc
+ * ```
+ */
+export declare function parseJSONRPCMessage(value: unknown): JSONRPCMessage | undefined;
+
+/**
+ * The MCP protocol revisions this server can negotiate — the current
+ * {@link MCP_PROTOCOL_VERSION} plus a prior rev a client may still request.
+ *
+ * @remarks
+ * `initialize` echoes the client's requested `protocolVersion` when it appears in
+ * this list, else falls back to {@link MCP_PROTOCOL_VERSION}. Frozen so the list is
+ * an immutable contract.
+ */
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+
+export { }