@orkestrel/mcp 0.0.4 → 0.0.6

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

@@ -5,6 +5,81 @@ import { ToolInterface } from '@orkestrel/agent';
 import { ToolManagerInterface } from '@orkestrel/agent';
 import { ToolResult } from '@orkestrel/agent';
 
+/**
+ * Pipe an {@link MCPTransportInterface} into an {@link MCPClientInterface} — every
+ * inbound message is decoded and delivered onto the client's OWN transport
+ * (`client.transport.emitter`'s `message` / `close` events), resolving/rejecting the
+ * client's correlated pending requests exactly as a direct reply would.
+ *
+ * @remarks
+ * The client's outbound writes flow through `client.transport.send` — its existing,
+ * unmodified request/response correlation — so `client` must have been constructed
+ * with a {@link import('./types.js').ClientTransportInterface} that itself carries
+ * the SAME `transport` (see {@link import('./factories.js').createDuplexClientTransport},
+ * the additive factory that adapts an {@link MCPTransportInterface} into that shape);
+ * this binder then completes the inbound half by decoding each message and pushing it
+ * onto `client.transport.emitter` (an {@link import('@orkestrel/emitter').EmitterInterface}
+ * exposes `emit`, so no client modification is needed). A malformed / non-JSON-RPC
+ * inbound message is DROPPED (§14, total — never throws); a delivery fault is routed to
+ * `client.transport.emitter`'s `error` event (never rethrown). The returned unbind
+ * DETACHES this binder (further inbound messages and the transport's `closed` signal are
+ * ignored) WITHOUT closing the transport.
+ *
+ * `listen`/`closed` are REPLACE semantics (§ port contract): the returned unbind
+ * DETACHES by replacing this binder's own handlers with no-ops, so a subsequent
+ * `bindClient` call on the SAME transport is never double-dispatched by a stale
+ * subscription left behind — an unbind→rebind cycle delivers exactly one `message`
+ * emit per inbound reply.
+ *
+ * @param client - The transport-agnostic client whose transport to deliver messages onto
+ * @param transport - The duplex channel to pipe the client over
+ * @returns Detach this binder from the transport (does not close it)
+ *
+ * @example
+ * ```ts
+ * const client = createMCPClient({ transport: createDuplexClientTransport(transport) })
+ * const unbind = bindClient(client, transport)
+ * await client.connect()
+ * // ... later, detach without closing:
+ * unbind()
+ * ```
+ */
+export declare function bindClient(client: MCPClientInterface, transport: MCPTransportInterface): () => void;
+
+/**
+ * Pipe an {@link MCPTransportInterface} into an {@link MCPServerInterface} — every
+ * inbound message runs through `server.handle`, and a defined reply is written back
+ * via `transport.send`.
+ *
+ * @remarks
+ * `server.handle` already turns a malformed message into a serialized `-32700` /
+ * `-32600` reply and a notification into `undefined` (no reply), so this binder adds
+ * no parsing of its own. A `transport.send` throw or rejection is caught and routed
+ * to `server.emitter`'s `error` event (never rethrown, never an unhandled rejection);
+ * a listener on that event that itself throws is swallowed (the end of the line —
+ * the caller's own bug, never this binder's). The returned unbind DETACHES this
+ * binder (further inbound messages and the transport's `closed` signal are ignored)
+ * WITHOUT closing the transport — closing is the caller's decision.
+ *
+ * `listen`/`closed` are REPLACE semantics (§ port contract): the returned unbind
+ * DETACHES by replacing this binder's own handlers with no-ops, so a subsequent
+ * `bindServer` call on the SAME transport is never double-dispatched by a stale
+ * subscription left behind — an unbind→rebind cycle yields exactly one reply per
+ * request.
+ *
+ * @param server - The transport-agnostic server to dispatch inbound messages over
+ * @param transport - The duplex channel to pipe the server over
+ * @returns Detach this binder from the transport (does not close it)
+ *
+ * @example
+ * ```ts
+ * const unbind = bindServer(server, transport)
+ * // ... later, detach without closing:
+ * unbind()
+ * ```
+ */
+export declare function bindServer(server: MCPServerInterface, transport: MCPTransportInterface): () => void;
+
 /**
  * Map a {@link ToolManagerInterface}'s definitions to MCP `tools/list` descriptors
  * — renaming `parameters` to the wire's `inputSchema`.
@@ -69,10 +144,10 @@ export declare type ClientTransportEventMap = {
  *
  * @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
+ * {@link MCPClientInterface} hands the transport one {@link JSONRPCMessage} 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),
+ * `start` (open the connection / arm any reader), `send` (write one message),
  * 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
@@ -90,7 +165,7 @@ export declare interface ClientTransportInterface {
      */
     start(): Promise<void>;
     /**
-     * Send one JSON-RPC message (or a batch) to the remote server.
+     * Send one JSON-RPC message to the remote server.
      *
      * @remarks
      * Each decoded reply is surfaced on the `emitter`'s `message` event — `send`
@@ -98,10 +173,10 @@ export declare interface ClientTransportInterface {
      * 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
+     * @param message - The message to write to the wire
+     * @returns Resolves once the message has been sent
      */
-    send(message: JSONRPCMessage | readonly JSONRPCMessage[]): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
     /**
      * Close the transport — end the connection and release resources.
      *
@@ -110,6 +185,36 @@ export declare interface ClientTransportInterface {
     close(): Promise<void>;
 }
 
+/**
+ * Adapt an {@link MCPTransportInterface} (the environment-agnostic duplex message
+ * channel) into a {@link ClientTransportInterface} — the additive bridge that lets
+ * `createMCPClient` run over the new port without any change to `MCPClient`'s
+ * existing shape.
+ *
+ * @remarks
+ * Hand the RESULT to `createMCPClient({ transport })`, then pass the SAME
+ * `transport` to {@link import('./helpers.js').bindClient} to complete the inbound
+ * wiring: `send` serializes each outbound {@link JSONRPCMessage} and writes it via
+ * `transport.send`; `close` closes the underlying
+ * `transport`; `start` is a no-op (the duplex channel is already open by the time
+ * it is handed in — there is no separate connect step at this layer); `session` is
+ * always `undefined` (session correlation is a higher-level concern the duplex port
+ * does not carry). Inbound delivery (`emitter`'s `message` / `close` events) is
+ * `bindClient`'s job, not this factory's — the returned object exposes a `message`-
+ * capable emitter for `bindClient` to push onto.
+ *
+ * @param transport - The duplex channel to adapt
+ * @returns A {@link ClientTransportInterface} `createMCPClient` can drive
+ *
+ * @example
+ * ```ts
+ * const client = createMCPClient({ transport: createDuplexClientTransport(transport) })
+ * const unbind = bindClient(client, transport)
+ * await client.connect()
+ * ```
+ */
+export declare function createDuplexClientTransport(transport: MCPTransportInterface): ClientTransportInterface;
+
 /**
  * Create a transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE
  * MCP server over an injected {@link import('./types.js').ClientTransportInterface},
@@ -119,7 +224,8 @@ export declare interface ClientTransportInterface {
  * @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),
+ * validates and exposes the negotiated protocol, `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
@@ -274,6 +380,20 @@ export declare function isJSONRPCRequest(value: unknown): value is JSONRPCReques
  */
 export declare function isJSONRPCResponse(value: unknown): value is JSONRPCResponse;
 
+/**
+ * Determine whether an unknown value is an {@link MCPError}.
+ *
+ * @param value - The unknown value to inspect
+ * @returns `true` only when the value is an `MCPError`
+ *
+ * @example
+ * ```ts
+ * isMCPError(new MCPError('Method not found', -32601)) // true
+ * isMCPError(new Error('Method not found')) // false
+ * ```
+ */
+export declare function isMCPError(value: unknown): value is MCPError;
+
 /**
  * Determine whether a value is a valid JSON-RPC REQUEST `id` — a string, a number,
  * or absent.
@@ -397,8 +517,9 @@ export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
  *
  * @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
+ *   this client ISSUES them over a transport. `connect` runs `initialize`, validates and
+ *   exposes the negotiated `protocol`, 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}
@@ -431,6 +552,7 @@ export declare class MCPClient implements MCPClientInterface {
     constructor(options: MCPClientOptions);
     get emitter(): EmitterInterface<MCPClientEventMap>;
     get connected(): boolean;
+    get protocol(): string | undefined;
     get transport(): ClientTransportInterface;
     on<K extends keyof MCPClientEventMap>(event: K, handler: (...args: MCPClientEventMap[K]) => void): void;
     connect(): Promise<void>;
@@ -475,7 +597,8 @@ export declare type MCPClientEventMap = {
  * @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
+ *   `initialize` handshake, validates and exposes the negotiated `protocol` (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,
@@ -499,6 +622,11 @@ export declare interface MCPClientInterface {
     readonly emitter: EmitterInterface<MCPClientEventMap>;
     /** Whether the `initialize` handshake has completed and the client is connected. */
     readonly connected: boolean;
+    /**
+     * The MCP protocol revision negotiated by {@link connect}, or `undefined` before
+     * connecting and after {@link disconnect}.
+     */
+    readonly protocol: string | undefined;
     /** The injected transport the client drives the remote server over. */
     readonly transport: ClientTransportInterface;
     /**
@@ -511,11 +639,14 @@ export declare interface MCPClientInterface {
     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`).
+     * handshake, validate its negotiated protocol, then send
+     * `notifications/initialized`.
      *
      * @remarks
      * Idempotent — a second `connect` while already connected is a no-op. On success
-     * the `connect` event fires.
+     * {@link protocol} contains a supported revision and the `connect` event fires. A
+     * non-string or unsupported revision closes the transport and rejects without
+     * connecting or sending the initialized notification.
      *
      * @returns Resolves once the handshake completes and the client is connected
      */
@@ -526,7 +657,7 @@ export declare interface MCPClientInterface {
      *
      * @remarks
      * Idempotent — a second `disconnect` while already disconnected is a no-op. The
-     * `disconnect` event fires.
+     * `disconnect` event fires and {@link protocol} becomes `undefined`.
      *
      * @returns Resolves once the transport is closed
      */
@@ -598,6 +729,37 @@ export declare interface MCPContent {
     readonly text: string;
 }
 
+/**
+ * A remote Model Context Protocol JSON-RPC error, preserving its machine-readable
+ * numeric code and optional structured context.
+ *
+ * @remarks
+ * {@link MCPClient} throws this error only for a remote JSON-RPC `error` response.
+ * Local lifecycle and transport conditions such as disconnects and request timeouts
+ * remain plain `Error`s. `context` carries the response's optional `error.data`
+ * unchanged and is `undefined` when the peer omitted it.
+ *
+ * @example
+ * ```ts
+ * const error = new MCPError('Method not found', -32601, { method: 'missing' })
+ * error.code // -32601
+ * error.context // { method: 'missing' }
+ * ```
+ */
+export declare class MCPError extends Error {
+    readonly name = "MCPError";
+    readonly code: number;
+    readonly context: unknown;
+    /**
+     * Create a remote MCP protocol error.
+     *
+     * @param message - The human-readable JSON-RPC error message
+     * @param code - The machine-readable numeric JSON-RPC error code
+     * @param context - The optional JSON-RPC `error.data` payload
+     */
+    constructor(message: string, code: number, context?: unknown);
+}
+
 /**
  * A transport-agnostic Model Context Protocol server — dispatches JSON-RPC 2.0
  * requests over a live {@link ToolManagerInterface}, with NO transport coupling.
@@ -657,6 +819,12 @@ export declare class MCPServer implements MCPServerInterface {
 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];
+    /**
+     * A transport-level fault surfaced while a bound {@link MCPTransportInterface} was
+     * piping a reply out (a `send` throw or rejection from {@link bindServer}). A DOMAIN
+     * event (a genuine I/O fault), distinct from the emitter's own listener-error channel.
+     */
+    readonly error: readonly [error: unknown];
 };
 
 /** The server identity echoed in the MCP `initialize` result's `serverInfo`. */
@@ -769,6 +937,31 @@ export declare interface MCPToolResult {
     readonly isError?: boolean;
 }
 
+/**
+ * A duplex message channel an environment face provides to the pure engine — the
+ * one port `bindServer` and `bindClient` (`./helpers.js`) pipe an
+ * {@link MCPServerInterface} / {@link MCPClientInterface} over.
+ *
+ * @remarks
+ * Messages are already-serialized JSON-RPC strings; the transport owns framing
+ * (a WS text frame, an SSE `data:` event, a newline-terminated stdio line, a
+ * `postMessage` payload) and never parses the string itself. `listen` and
+ * `closed` each register THE SINGLE handler for their event — a second call
+ * REPLACES the first (matching the emitter-free, minimal-surface carrier idiom
+ * `bindServer` / `bindClient` themselves rely on), not an additive subscription
+ * list.
+ */
+export declare interface MCPTransportInterface {
+    /** Deliver one outbound JSON-RPC message (already serialized). */
+    readonly send: (message: string) => void | Promise<void>;
+    /** Register the single inbound-message handler — a second call REPLACES the first. */
+    readonly listen: (handler: (message: string) => void) => void;
+    /** Register the single closed handler — a second call REPLACES the first. */
+    readonly closed: (handler: () => void) => void;
+    /** Close the underlying channel. */
+    readonly close: () => void | Promise<void>;
+}
+
 /**
  * Narrow an already-parsed value to a {@link JSONRPCMessage}, or `undefined` when
  * it is not one.
@@ -792,13 +985,14 @@ export declare interface MCPToolResult {
 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.
+ * The MCP protocol revisions this server can negotiate.
  *
  * @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.
+ * an immutable contract. The package does not advertise `2025-03-26` because that
+ * revision mandates JSON-RPC batching, while this package accepts only individual
+ * JSON-RPC messages.
  */
 export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];