@orkestrel/mcp 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,648 @@
+import { isArray, isNumber, isRecord, isString, isUndefined } from "@orkestrel/contract";
+import { Emitter } from "@orkestrel/emitter";
+import { Tool } from "@orkestrel/agent";
+//#region src/core/constants.ts
+/** 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.
+*
+* @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.
+*/
+var SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(["2025-06-18", "2025-03-26"]);
+/** 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. */
+var JSONRPC_INVALID_REQUEST = -32600;
+/** JSON-RPC 2.0 reserved error: the requested method does not exist. */
+var JSONRPC_METHOD_NOT_FOUND = -32601;
+/** JSON-RPC 2.0 reserved error: the method's parameters were invalid. */
+var JSONRPC_INVALID_PARAMS = -32602;
+/** JSON-RPC 2.0 implementation-defined server error (the `-32000` to `-32099` range). */
+var JSONRPC_SERVER_ERROR = -32e3;
+/** The default client name reported in the MCP `initialize` handshake (`clientInfo.name`). */
+var DEFAULT_MCP_CLIENT_NAME = "taverna";
+/** The default client version reported in the MCP `initialize` handshake (`clientInfo.version`). */
+var 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.
+*/
+var DEFAULT_MCP_REQUEST_TIMEOUT = 3e4;
+//#endregion
+//#region src/core/validators.ts
+/**
+* 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
+* ```
+*/
+function isRequestId(value) {
+	return isUndefined(value) || isString(value) || isNumber(value);
+}
+/**
+* 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
+* ```
+*/
+function isJSONRPCRequest(value) {
+	if (!isRecord(value)) return false;
+	if (value["jsonrpc"] !== "2.0" || !isString(value["method"])) return false;
+	if (!isRequestId(value["id"])) return false;
+	const params = value["params"];
+	return isUndefined(params) || isRecord(params);
+}
+/**
+* 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
+*/
+function isJSONRPCResponse(value) {
+	if (!isRecord(value)) return false;
+	if (value["jsonrpc"] !== "2.0") return false;
+	const id = value["id"];
+	if (id !== null && !isString(id) && !isNumber(id)) return false;
+	const hasResult = Object.hasOwn(value, "result");
+	const error = value["error"];
+	const hasError = !isUndefined(error);
+	if (hasResult === hasError) return false;
+	if (hasError) return isRecord(error) && isNumber(error["code"]) && isString(error["message"]);
+	return true;
+}
+/**
+* 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
+*/
+function isJSONRPCMessage(value) {
+	return isJSONRPCRequest(value) || isJSONRPCResponse(value);
+}
+/**
+* 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
+* ```
+*/
+function isInitializeRequest(value) {
+	return isJSONRPCRequest(value) && value.method === "initialize";
+}
+//#endregion
+//#region src/core/parsers.ts
+/**
+* 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
+* ```
+*/
+function parseJSONRPCMessage(value) {
+	return isJSONRPCMessage(value) ? value : void 0;
+}
+//#endregion
+//#region src/core/helpers.ts
+/**
+* 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
+*/
+function jsonRPCResult(id, result) {
+	return {
+		jsonrpc: "2.0",
+		id,
+		result
+	};
+}
+/**
+* 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
+*/
+function jsonRPCError(id, code, message, data) {
+	return {
+		jsonrpc: "2.0",
+		id,
+		error: data === void 0 ? {
+			code,
+			message
+		} : {
+			code,
+			message,
+			data
+		}
+	};
+}
+/**
+* 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
+*/
+function buildToolDescriptors(manager) {
+	return manager.definitions().map((definition) => {
+		const descriptor = {
+			name: definition.name,
+			inputSchema: definition.parameters ?? { type: "object" }
+		};
+		if (definition.description !== void 0) descriptor.description = definition.description;
+		return descriptor;
+	});
+}
+/**
+* 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
+*/
+function buildToolResult(result) {
+	if (result.error !== void 0) return {
+		content: [{
+			type: "text",
+			text: result.error
+		}],
+		isError: true
+	};
+	return { content: [{
+		type: "text",
+		text: result.value === void 0 ? "" : JSON.stringify(result.value)
+	}] };
+}
+/**
+* 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
+*/
+function initializeResult(name, version, requested) {
+	return {
+		protocolVersion: requested !== void 0 && SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : MCP_PROTOCOL_VERSION,
+		capabilities: { tools: {} },
+		serverInfo: {
+			name,
+			version
+		}
+	};
+}
+//#endregion
+//#region src/core/MCPServer.ts
+/**
+* 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":{}}'
+* ```
+*/
+var MCPServer = class {
+	#emitter;
+	#name;
+	#version;
+	#tools;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options.on,
+			error: options.error
+		});
+		this.#name = options.name;
+		this.#version = options.version;
+		this.#tools = options.tools;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get name() {
+		return this.#name;
+	}
+	get version() {
+		return this.#version;
+	}
+	async dispatch(request) {
+		const id = request.id ?? null;
+		this.#emitter.emit("request", request.method, id);
+		if (request.id === void 0) return;
+		switch (request.method) {
+			case "initialize": {
+				const requested = request.params?.["protocolVersion"];
+				return jsonRPCResult(id, initializeResult(this.#name, this.#version, isString(requested) ? requested : void 0));
+			}
+			case "ping": return jsonRPCResult(id, {});
+			case "tools/list": return jsonRPCResult(id, { tools: buildToolDescriptors(this.#tools) });
+			case "tools/call": return this.#call(request, id);
+			default: return jsonRPCError(id, JSONRPC_METHOD_NOT_FOUND, `Method not found: ${request.method}`);
+		}
+	}
+	async handle(message) {
+		let parsed;
+		try {
+			parsed = JSON.parse(message);
+		} catch {
+			return JSON.stringify(jsonRPCError(null, JSONRPC_PARSE_ERROR, "Parse error"));
+		}
+		const decoded = parseJSONRPCMessage(parsed);
+		if (decoded === void 0 || !("method" in decoded)) return JSON.stringify(jsonRPCError(null, JSONRPC_INVALID_REQUEST, "Invalid Request"));
+		const response = await this.dispatch(decoded);
+		return response === void 0 ? void 0 : JSON.stringify(response);
+	}
+	async #call(request, id) {
+		const params = request.params;
+		const name = params?.["name"];
+		if (!isString(name)) return jsonRPCError(id, JSONRPC_INVALID_PARAMS, "Invalid params: a string `name` is required");
+		const rawArguments = params?.["arguments"];
+		const args = isRecord(rawArguments) ? rawArguments : {};
+		const callId = request.id === void 0 ? crypto.randomUUID() : String(request.id);
+		return jsonRPCResult(id, buildToolResult(await this.#tools.execute({
+			id: callId,
+			name,
+			arguments: args
+		})));
+	}
+};
+//#endregion
+//#region src/core/MCPClient.ts
+/**
+* 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' })
+* ```
+*/
+var MCPClient = class {
+	#emitter;
+	#transport;
+	#name;
+	#version;
+	#timeout;
+	#pending = /* @__PURE__ */ new Map();
+	#nextId = 0;
+	#connected = false;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options.on,
+			error: options.error
+		});
+		this.#transport = options.transport;
+		this.#name = options.name ?? "taverna";
+		this.#version = options.version ?? "1.0.0";
+		this.#timeout = options.timeout ?? 3e4;
+		this.#transport.emitter.on("message", (message) => this.#receive(message));
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get connected() {
+		return this.#connected;
+	}
+	get transport() {
+		return this.#transport;
+	}
+	on(event, handler) {
+		this.#emitter.on(event, handler);
+	}
+	async connect() {
+		if (this.#connected) return;
+		await this.#transport.start();
+		await this.#request("initialize", {
+			protocolVersion: MCP_PROTOCOL_VERSION,
+			capabilities: {},
+			clientInfo: {
+				name: this.#name,
+				version: this.#version
+			}
+		});
+		this.#connected = true;
+		await this.#transport.send({
+			jsonrpc: "2.0",
+			method: "notifications/initialized"
+		});
+		this.#emitter.emit("connect");
+	}
+	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();
+		await this.#transport.close();
+		this.#emitter.emit("disconnect");
+	}
+	async tools() {
+		const result = await this.#request("tools/list");
+		if (!isRecord(result) || !isArray(result["tools"])) return [];
+		const tools = [];
+		for (const descriptor of result["tools"]) {
+			if (!isRecord(descriptor) || !isString(descriptor["name"])) continue;
+			const name = descriptor["name"];
+			tools.push(this.#tool(name, descriptor));
+		}
+		return tools;
+	}
+	async call(name, args) {
+		const result = await this.#request("tools/call", {
+			name,
+			arguments: args
+		});
+		const text = this.#text(result);
+		if (isRecord(result) && result["isError"] === true) throw new Error(text.length > 0 ? text : `MCP tool '${name}' failed`);
+		if (text.length === 0) return void 0;
+		try {
+			return JSON.parse(text);
+		} catch {
+			return text;
+		}
+	}
+	#request(method, params) {
+		this.#nextId += 1;
+		const id = this.#nextId;
+		const request = {
+			jsonrpc: "2.0",
+			id,
+			method,
+			...params === void 0 ? {} : { params }
+		};
+		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 });
+			this.#pending.set(id, {
+				resolve: (value) => {
+					settle();
+					resolve(value);
+				},
+				reject: (error) => {
+					settle();
+					reject(error);
+				}
+			});
+			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)));
+			});
+		});
+	}
+	#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);
+				return;
+			}
+		}
+		this.#emitter.emit("notification", message);
+	}
+	#tool(name, descriptor) {
+		const inputSchema = descriptor["inputSchema"];
+		const description = descriptor["description"];
+		const options = {
+			name,
+			execute: (args) => this.call(name, args)
+		};
+		if (isString(description)) options.description = description;
+		if (isRecord(inputSchema)) options.parameters = inputSchema;
+		return new Tool(options);
+	}
+	#text(result) {
+		if (!isRecord(result) || !isArray(result["content"])) return "";
+		const parts = [];
+		for (const block of result["content"]) if (isRecord(block) && isString(block["text"])) parts.push(block["text"]);
+		return parts.join("\n");
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* 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"}}]}}'
+* ```
+*/
+function createMCPServer(options) {
+	return new MCPServer(options);
+}
+/**
+* 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' })
+* ```
+*/
+function createMCPClient(options) {
+	return new MCPClient(options);
+}
+//#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 };
+
+//# sourceMappingURL=index.js.map