@orkestrel/mcp 0.0.5 → 0.0.7

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

@@ -144,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
@@ -165,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`
@@ -173,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.
      *
@@ -194,8 +194,8 @@ export declare interface ClientTransportInterface {
  * @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
+ * 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
@@ -224,7 +224,8 @@ export declare function createDuplexClientTransport(transport: MCPTransportInter
  * @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
@@ -379,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.
@@ -502,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}
@@ -536,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>;
@@ -580,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,
@@ -604,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;
     /**
@@ -616,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
      */
@@ -631,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
      */
@@ -703,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.
@@ -928,13 +985,14 @@ export declare interface MCPTransportInterface {
 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[];
 

package/dist/src/core/index.js

@@ -5,15 +5,16 @@ import { Tool } from "@orkestrel/agent";
 /** The MCP protocol revision this server implements (the default negotiated version). */
 var MCP_PROTOCOL_VERSION = "2025-06-18";
 /**
-* 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.
 */
-var SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(["2025-06-18", "2025-03-26"]);
+var SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(["2025-06-18"]);
 /** JSON-RPC 2.0 reserved error: invalid JSON was received (the message did not parse). */
 var JSONRPC_PARSE_ERROR = -32700;
 /** JSON-RPC 2.0 reserved error: the payload was not a valid Request object. */
@@ -34,6 +35,61 @@ var DEFAULT_MCP_CLIENT_VERSION = "1.0.0";
 */
 var DEFAULT_MCP_REQUEST_TIMEOUT = 3e4;
 //#endregion
+//#region src/core/errors.ts
+/**
+* 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' }
+* ```
+*/
+var MCPError = class extends Error {
+	name = "MCPError";
+	code;
+	context;
+	/**
+	* 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, code, context) {
+		super(message);
+		this.code = code;
+		this.context = context;
+	}
+};
+/**
+* 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
+* ```
+*/
+function isMCPError(value) {
+	try {
+		return value instanceof MCPError;
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/core/validators.ts
 /**
 * Determine whether a value is a valid JSON-RPC REQUEST `id` — a string, a number,
@@ -313,18 +369,16 @@ function initializeResult(name, version, requested) {
 */
 function bindServer(server, transport) {
 	let active = true;
-	transport.listen((message) => {
+	transport.listen(async (message) => {
 		if (!active) return;
-		(async () => {
+		try {
+			const response = await server.handle(message);
+			if (response !== void 0) await transport.send(response);
+		} catch (error) {
 			try {
-				const response = await server.handle(message);
-				if (response !== void 0) await transport.send(response);
-			} catch (error) {
-				try {
-					server.emitter.emit("error", error);
-				} catch {}
-			}
-		})();
+				server.emitter.emit("error", error);
+			} catch {}
+		}
 	});
 	transport.closed(() => {
 		active = false;
@@ -449,8 +503,8 @@ var MCPServer = class {
 	#tools;
 	constructor(options) {
 		this.#emitter = new Emitter({
-			on: options.on,
-			error: options.error
+			...options.on !== void 0 ? { on: options.on } : {},
+			...options.error !== void 0 ? { error: options.error } : {}
 		});
 		this.#name = options.name;
 		this.#version = options.version;
@@ -515,8 +569,9 @@ var MCPServer = class {
 *
 * @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}
@@ -553,10 +608,11 @@ var MCPClient = class {
 	#pending = /* @__PURE__ */ new Map();
 	#nextId = 0;
 	#connected = false;
+	#protocol = void 0;
 	constructor(options) {
 		this.#emitter = new Emitter({
-			on: options.on,
-			error: options.error
+			...options.on !== void 0 ? { on: options.on } : {},
+			...options.error !== void 0 ? { error: options.error } : {}
 		});
 		this.#transport = options.transport;
 		this.#name = options.name ?? "taverna";
@@ -570,6 +626,9 @@ var MCPClient = class {
 	get connected() {
 		return this.#connected;
 	}
+	get protocol() {
+		return this.#protocol;
+	}
 	get transport() {
 		return this.#transport;
 	}
@@ -579,7 +638,7 @@ var MCPClient = class {
 	async connect() {
 		if (this.#connected) return;
 		await this.#transport.start();
-		await this.#request("initialize", {
+		const result = await this.#request("initialize", {
 			protocolVersion: MCP_PROTOCOL_VERSION,
 			capabilities: {},
 			clientInfo: {
@@ -587,6 +646,13 @@ var MCPClient = class {
 				version: this.#version
 			}
 		});
+		const protocol = isRecord(result) ? result["protocolVersion"] : void 0;
+		if (!isString(protocol) || !SUPPORTED_PROTOCOL_VERSIONS.includes(protocol)) {
+			await this.#transport.close();
+			if (isString(protocol)) throw new Error(`MCP server negotiated unsupported protocol version '${protocol}'`);
+			throw new Error("MCP server returned a non-string protocol version");
+		}
+		this.#protocol = protocol;
 		this.#connected = true;
 		await this.#transport.send({
 			jsonrpc: "2.0",
@@ -597,8 +663,8 @@ var MCPClient = class {
 	async disconnect() {
 		if (!this.#connected) return;
 		this.#connected = false;
-		for (const pending of this.#pending.values()) pending.reject(/* @__PURE__ */ new Error("MCP client disconnected"));
-		this.#pending.clear();
+		this.#protocol = void 0;
+		for (const id of this.#pending.keys()) this.#settle(id, /* @__PURE__ */ new Error("MCP client disconnected"), true);
 		await this.#transport.close();
 		this.#emitter.emit("disconnect");
 	}
@@ -638,38 +704,24 @@ var MCPClient = class {
 		};
 		return new Promise((resolve, reject) => {
 			const deadline = AbortSignal.timeout(this.#timeout);
-			const settle = () => {
-				this.#pending.delete(id);
-				deadline.removeEventListener("abort", onDeadline);
-			};
-			const onDeadline = () => {
-				settle();
-				reject(/* @__PURE__ */ new Error(`MCP request '${method}' timed out after ${this.#timeout}ms`));
-			};
-			deadline.addEventListener("abort", onDeadline, { once: true });
+			const timeout = this.#timeoutRequest.bind(this, id, method);
+			deadline.addEventListener("abort", timeout, { once: true });
 			this.#pending.set(id, {
-				resolve: (value) => {
-					settle();
-					resolve(value);
-				},
-				reject: (error) => {
-					settle();
-					reject(error);
-				}
+				resolve,
+				reject,
+				deadline,
+				timeout
 			});
 			this.#transport.send(request).catch((error) => {
-				const pending = this.#pending.get(id);
-				if (pending === void 0) return;
-				pending.reject(error instanceof Error ? error : new Error(String(error)));
+				this.#settle(id, error instanceof Error ? error : new Error(String(error)), true);
 			});
 		});
 	}
 	#receive(message) {
 		if (isJSONRPCResponse(message) && isRequestId(message.id)) {
-			const pending = this.#pending.get(message.id);
-			if (pending !== void 0) {
-				if (message.error !== void 0) pending.reject(/* @__PURE__ */ new Error(`MCP error ${message.error.code}: ${message.error.message}`));
-				else pending.resolve(message.result);
+			if (this.#pending.has(message.id)) {
+				if (message.error !== void 0) this.#settle(message.id, new MCPError(message.error.message, message.error.code, message.error.data), true);
+				else this.#settle(message.id, message.result, false);
 				return;
 			}
 		}
@@ -680,7 +732,7 @@ var MCPClient = class {
 		const description = descriptor["description"];
 		const options = {
 			name,
-			execute: (args) => this.call(name, args)
+			execute: this.call.bind(this, name)
 		};
 		if (isString(description)) options.description = description;
 		if (isRecord(inputSchema)) options.parameters = inputSchema;
@@ -692,6 +744,17 @@ var MCPClient = class {
 		for (const block of result["content"]) if (isRecord(block) && isString(block["text"])) parts.push(block["text"]);
 		return parts.join("\n");
 	}
+	#timeoutRequest(id, method) {
+		this.#settle(id, /* @__PURE__ */ new Error(`MCP request '${method}' timed out after ${this.#timeout}ms`), true);
+	}
+	#settle(id, value, failed) {
+		const pending = this.#pending.get(id);
+		if (pending === void 0) return;
+		this.#pending.delete(id);
+		pending.deadline.removeEventListener("abort", pending.timeout);
+		if (failed) pending.reject(value);
+		else pending.resolve(value);
+	}
 };
 //#endregion
 //#region src/core/factories.ts
@@ -741,7 +804,8 @@ function createMCPServer(options) {
 * @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
@@ -779,8 +843,8 @@ function createMCPClient(options) {
 * @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
+* 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
@@ -804,8 +868,7 @@ function createDuplexClientTransport(transport) {
 		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));
+			await transport.send(JSON.stringify(message));
 		},
 		async close() {
 			await transport.close();
@@ -813,6 +876,6 @@ function createDuplexClientTransport(transport) {
 	};
 }
 //#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, bindClient, bindServer, buildToolDescriptors, buildToolResult, createDuplexClientTransport, 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, MCPError, MCPServer, MCP_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, bindClient, bindServer, buildToolDescriptors, buildToolResult, createDuplexClientTransport, createMCPClient, createMCPServer, initializeResult, isInitializeRequest, isJSONRPCMessage, isJSONRPCRequest, isJSONRPCResponse, isMCPError, isRequestId, jsonRPCError, jsonRPCResult, parseJSONRPCMessage };
 
 //# sourceMappingURL=index.js.map