@orkestrel/mcp 0.0.4 → 0.0.6

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,
@@ -279,6 +335,132 @@ 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(async (message) => {
+		if (!active) return;
+		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
 /**
@@ -321,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;
@@ -387,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}
@@ -425,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";
@@ -442,6 +626,9 @@ var MCPClient = class {
 	get connected() {
 		return this.#connected;
 	}
+	get protocol() {
+		return this.#protocol;
+	}
 	get transport() {
 		return this.#transport;
 	}
@@ -451,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: {
@@ -459,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",
@@ -469,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");
 	}
@@ -510,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;
 			}
 		}
@@ -552,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;
@@ -564,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
@@ -613,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
@@ -642,7 +834,48 @@ 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} 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) {
+			await transport.send(JSON.stringify(message));
+		},
+		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, 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