@orkestrel/mcp 0.0.4 → 0.0.5

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

@@ -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`.
@@ -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} (or batch, one per
+ * message) 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},
@@ -657,6 +762,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 +880,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.

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`.
@@ -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} (or batch, one per
+ * message) 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},
@@ -657,6 +762,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 +880,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.

package/dist/src/core/index.js

@@ -279,6 +279,134 @@ function initializeResult(name, version, requested) {
 		}
 	};
 }
+/**
+* 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()
+* ```
+*/
+function bindServer(server, transport) {
+	let active = true;
+	transport.listen((message) => {
+		if (!active) return;
+		(async () => {
+			try {
+				const response = await server.handle(message);
+				if (response !== void 0) await transport.send(response);
+			} catch (error) {
+				try {
+					server.emitter.emit("error", error);
+				} catch {}
+			}
+		})();
+	});
+	transport.closed(() => {
+		active = false;
+	});
+	return () => {
+		active = false;
+		transport.listen(() => {});
+		transport.closed(() => {});
+	};
+}
+/**
+* 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()
+* ```
+*/
+function bindClient(client, transport) {
+	let active = true;
+	transport.listen((message) => {
+		if (!active) return;
+		let parsed;
+		try {
+			parsed = JSON.parse(message);
+		} catch {
+			return;
+		}
+		const decoded = parseJSONRPCMessage(parsed);
+		if (decoded === void 0) return;
+		try {
+			client.transport.emitter.emit("message", decoded);
+		} catch (error) {
+			try {
+				client.transport.emitter.emit("error", error);
+			} catch {}
+		}
+	});
+	transport.closed(() => {
+		if (!active) return;
+		active = false;
+		try {
+			client.transport.emitter.emit("close");
+		} catch {}
+	});
+	return () => {
+		active = false;
+		transport.listen(() => {});
+		transport.closed(() => {});
+	};
+}
 //#endregion
 //#region src/core/MCPServer.ts
 /**
@@ -642,7 +770,49 @@ function createMCPServer(options) {
 function createMCPClient(options) {
 	return new MCPClient(options);
 }
+/**
+* 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} (or batch, one per
+* message) 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()
+* ```
+*/
+function createDuplexClientTransport(transport) {
+	return {
+		emitter: new Emitter(),
+		session: void 0,
+		async start() {},
+		async send(message) {
+			const messages = Array.isArray(message) ? message : [message];
+			for (const one of messages) await transport.send(JSON.stringify(one));
+		},
+		async close() {
+			await transport.close();
+		}
+	};
+}
 //#endregion
-export { DEFAULT_MCP_CLIENT_NAME, DEFAULT_MCP_CLIENT_VERSION, DEFAULT_MCP_REQUEST_TIMEOUT, JSONRPC_INVALID_PARAMS, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_PARSE_ERROR, JSONRPC_SERVER_ERROR, MCPClient, MCPServer, MCP_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, buildToolDescriptors, buildToolResult, createMCPClient, createMCPServer, initializeResult, isInitializeRequest, isJSONRPCMessage, isJSONRPCRequest, isJSONRPCResponse, isRequestId, jsonRPCError, jsonRPCResult, parseJSONRPCMessage };
+export { DEFAULT_MCP_CLIENT_NAME, DEFAULT_MCP_CLIENT_VERSION, DEFAULT_MCP_REQUEST_TIMEOUT, JSONRPC_INVALID_PARAMS, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_PARSE_ERROR, JSONRPC_SERVER_ERROR, MCPClient, MCPServer, MCP_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, bindClient, bindServer, buildToolDescriptors, buildToolResult, createDuplexClientTransport, createMCPClient, createMCPServer, initializeResult, isInitializeRequest, isJSONRPCMessage, isJSONRPCRequest, isJSONRPCResponse, isRequestId, jsonRPCError, jsonRPCResult, parseJSONRPCMessage };
 
 //# sourceMappingURL=index.js.map