@orkestrel/mcp 0.0.4 → 0.0.5

package/dist/src/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["#emitter","#name","#version","#tools","#call","#emitter","#transport","#name","#version","#timeout","#pending","#receive","#connected","#request","#tool","#text","#nextId"],"sources":["../../../src/core/constants.ts","../../../src/core/validators.ts","../../../src/core/parsers.ts","../../../src/core/helpers.ts","../../../src/core/MCPServer.ts","../../../src/core/MCPClient.ts","../../../src/core/factories.ts"],"sourcesContent":["// MCP protocol revisions + the reserved JSON-RPC 2.0 error codes. The negotiated\n// protocol version is the current rev unless the client requests a SUPPORTED prior\n// one (see `initializeResult` in ./helpers.js). Transport-level header names\n// (session / version headers) belong to the HTTP transport sub-chunk, NOT here.\n\n/** The MCP protocol revision this server implements (the default negotiated version). */\nexport const MCP_PROTOCOL_VERSION = '2025-06-18'\n\n/**\n * The MCP protocol revisions this server can negotiate — the current\n * {@link MCP_PROTOCOL_VERSION} plus a prior rev a client may still request.\n *\n * @remarks\n * `initialize` echoes the client's requested `protocolVersion` when it appears in\n * this list, else falls back to {@link MCP_PROTOCOL_VERSION}. Frozen so the list is\n * an immutable contract.\n */\nexport const SUPPORTED_PROTOCOL_VERSIONS: readonly string[] = Object.freeze([\n\t'2025-06-18',\n\t'2025-03-26',\n])\n\n/** JSON-RPC 2.0 reserved error: invalid JSON was received (the message did not parse). */\nexport const JSONRPC_PARSE_ERROR = -32700\n\n/** JSON-RPC 2.0 reserved error: the payload was not a valid Request object. */\nexport const JSONRPC_INVALID_REQUEST = -32600\n\n/** JSON-RPC 2.0 reserved error: the requested method does not exist. */\nexport const JSONRPC_METHOD_NOT_FOUND = -32601\n\n/** JSON-RPC 2.0 reserved error: the method's parameters were invalid. */\nexport const JSONRPC_INVALID_PARAMS = -32602\n\n/** JSON-RPC 2.0 implementation-defined server error (the `-32000` to `-32099` range). */\nexport const JSONRPC_SERVER_ERROR = -32000\n\n// MCP CLIENT defaults — the identity an `MCPClient` reports in the `initialize`\n// handshake (`clientInfo`) and the per-request deadline, when the caller supplies\n// none. The egress mirror of the server's protocol-version constants above.\n\n/** The default client name reported in the MCP `initialize` handshake (`clientInfo.name`). */\nexport const DEFAULT_MCP_CLIENT_NAME = 'taverna'\n\n/** The default client version reported in the MCP `initialize` handshake (`clientInfo.version`). */\nexport const DEFAULT_MCP_CLIENT_VERSION = '1.0.0'\n\n/**\n * The default per-request deadline (ms) an `MCPClient` applies when `options.timeout`\n * is unset — a request the remote server does not answer within it rejects.\n */\nexport const DEFAULT_MCP_REQUEST_TIMEOUT = 30_000\n","import type { JSONRPCMessage, JSONRPCRequest, JSONRPCResponse } from './types.js'\nimport { isNumber, isRecord, isString, isUndefined } from '@orkestrel/contract'\n\n// AGENTS §14: every guard here is a TOTAL function over the already-`JSON.parse`d\n// value — adversarial input returns `false`, never throws. The raw-string\n// `JSON.parse` (which CAN throw) happens in `MCPServer.handle` inside a try/catch;\n// these guards only ever see a parsed `unknown`. Each is a flat structural test on\n// `isRecord` + field checks (no user callbacks), so totality is immediate.\n\n/**\n * Determine whether a value is a valid JSON-RPC REQUEST `id` — a string, a number,\n * or absent.\n *\n * @remarks\n * A request id is a string, a number, or `undefined` (its ABSENCE marks a\n * NOTIFICATION). `null` is NOT a valid request id — it is valid only on a RESPONSE.\n * Total (§14): any other input returns `false`.\n *\n * @param value - The already-parsed value to test\n * @returns `true` when `value` is a string, a number, or `undefined`\n *\n * @example\n * ```ts\n * isRequestId(1)         // true\n * isRequestId('abc')     // true\n * isRequestId(undefined) // true — a notification\n * isRequestId(null)      // false — valid only on a response\n * ```\n */\nexport function isRequestId(value: unknown): value is string | number | undefined {\n\treturn isUndefined(value) || isString(value) || isNumber(value)\n}\n\n/**\n * Determine whether a parsed value is a {@link JSONRPCRequest}.\n *\n * @remarks\n * A request is a record with `jsonrpc === '2.0'` and a string `method`. `id`, when\n * present, must be a string or number; its ABSENCE is valid — that marks a\n * NOTIFICATION (a fire-and-forget request that yields no response). `params`, when\n * present, must be a record. Total (§14): any other input returns `false`.\n *\n * @param value - The already-parsed value to test\n * @returns `true` when `value` is a valid JSON-RPC request\n *\n * @example\n * ```ts\n * isJSONRPCRequest({ jsonrpc: '2.0', method: 'ping', id: 1 }) // true\n * isJSONRPCRequest({ jsonrpc: '2.0', method: 'notifications/initialized' }) // true — a notification\n * isJSONRPCRequest({ jsonrpc: '1.0', method: 'ping' }) // false\n * ```\n */\nexport function isJSONRPCRequest(value: unknown): value is JSONRPCRequest {\n\tif (!isRecord(value)) {\n\t\treturn false\n\t}\n\tif (value['jsonrpc'] !== '2.0' || !isString(value['method'])) {\n\t\treturn false\n\t}\n\tif (!isRequestId(value['id'])) {\n\t\treturn false\n\t}\n\tconst params = value['params']\n\treturn isUndefined(params) || isRecord(params)\n}\n\n/**\n * Determine whether a parsed value is a {@link JSONRPCResponse}.\n *\n * @remarks\n * A response is a record with `jsonrpc === '2.0'`, an `id` that is a string,\n * number, or `null`, and EXACTLY ONE of a `result` (any value, including\n * `undefined`'s absence) or an `error` (a record with a numeric `code` and string\n * `message`). Total (§14).\n *\n * @param value - The already-parsed value to test\n * @returns `true` when `value` is a valid JSON-RPC response\n */\nexport function isJSONRPCResponse(value: unknown): value is JSONRPCResponse {\n\tif (!isRecord(value)) {\n\t\treturn false\n\t}\n\tif (value['jsonrpc'] !== '2.0') {\n\t\treturn false\n\t}\n\tconst id = value['id']\n\tif (id !== null && !isString(id) && !isNumber(id)) {\n\t\treturn false\n\t}\n\tconst hasResult = Object.hasOwn(value, 'result')\n\tconst error = value['error']\n\tconst hasError = !isUndefined(error)\n\t// Exactly one of result / error — never both, never neither.\n\tif (hasResult === hasError) {\n\t\treturn false\n\t}\n\tif (hasError) {\n\t\treturn isRecord(error) && isNumber(error['code']) && isString(error['message'])\n\t}\n\treturn true\n}\n\n/**\n * Determine whether a parsed value is a {@link JSONRPCMessage} — a request or a\n * response.\n *\n * @remarks\n * The union of {@link isJSONRPCRequest} and {@link isJSONRPCResponse}. Total (§14).\n *\n * @param value - The already-parsed value to test\n * @returns `true` when `value` is a valid JSON-RPC request or response\n */\nexport function isJSONRPCMessage(value: unknown): value is JSONRPCMessage {\n\treturn isJSONRPCRequest(value) || isJSONRPCResponse(value)\n}\n\n/**\n * Determine whether a parsed value is an MCP `initialize` request — a\n * {@link JSONRPCRequest} whose `method` is `'initialize'`.\n *\n * @param value - The already-parsed value to test\n * @returns `true` when `value` is a valid `initialize` request\n *\n * @example\n * ```ts\n * isInitializeRequest({ jsonrpc: '2.0', method: 'initialize', id: 1 }) // true\n * isInitializeRequest({ jsonrpc: '2.0', method: 'ping', id: 1 }) // false\n * ```\n */\nexport function isInitializeRequest(value: unknown): value is JSONRPCRequest {\n\treturn isJSONRPCRequest(value) && value.method === 'initialize'\n}\n","import type { JSONRPCMessage } from './types.js'\nimport { isJSONRPCMessage } from './validators.js'\n\n/**\n * Narrow an already-parsed value to a {@link JSONRPCMessage}, or `undefined` when\n * it is not one.\n *\n * @remarks\n * Total (§14) — a non-message returns `undefined`, never throws. The input must\n * ALREADY be `JSON.parse`d: the raw-string parse (which can throw on malformed\n * JSON) happens in `MCPServer.handle` inside a try/catch that maps a parse failure\n * to a `-32700` response. Sound with {@link isJSONRPCMessage}: a guard-valid input\n * is returned unchanged, and every non-`undefined` output satisfies the guard.\n *\n * @param value - The already-parsed value to narrow\n * @returns The value as a {@link JSONRPCMessage}, or `undefined`\n *\n * @example\n * ```ts\n * parseJSONRPCMessage({ jsonrpc: '2.0', method: 'ping', id: 1 }) // the request\n * parseJSONRPCMessage({ method: 'ping' }) // undefined — missing jsonrpc\n * ```\n */\nexport function parseJSONRPCMessage(value: unknown): JSONRPCMessage | undefined {\n\treturn isJSONRPCMessage(value) ? value : undefined\n}\n","import type { ToolManagerInterface, ToolResult } from '@orkestrel/agent'\nimport type { JSONRPCResponse, MCPToolDescriptor, MCPToolResult } from './types.js'\nimport { MCP_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS } from './constants.js'\n\n// Pure dispatch builders (AGENTS §5: the dispatch branches stay exported helpers,\n// not hidden privates). Each turns a piece of MCP state into the JSON-RPC `result`\n// payload (or a response envelope) the server returns — independently testable.\n\n/**\n * Build a JSON-RPC success {@link JSONRPCResponse} — the `id` echoed, the method's\n * value as `result`.\n *\n * @param id - The request's id (`null` only for a parse / invalid-request error)\n * @param result - The method's return value\n * @returns The success response envelope\n */\nexport function jsonRPCResult(id: string | number | null, result: unknown): JSONRPCResponse {\n\treturn { jsonrpc: '2.0', id, result }\n}\n\n/**\n * Build a JSON-RPC error {@link JSONRPCResponse} — the `id` echoed, the failure as\n * an `error` object.\n *\n * @param id - The request's id (`null` for a parse / invalid-request error)\n * @param code - One of the reserved JSON-RPC codes (see `./constants.js`)\n * @param message - A short human description of the failure\n * @param data - An OPTIONAL machine-readable payload (omitted from the envelope when absent)\n * @returns The error response envelope\n */\nexport function jsonRPCError(\n\tid: string | number | null,\n\tcode: number,\n\tmessage: string,\n\tdata?: unknown,\n): JSONRPCResponse {\n\treturn {\n\t\tjsonrpc: '2.0',\n\t\tid,\n\t\terror: data === undefined ? { code, message } : { code, message, data },\n\t}\n}\n\n/**\n * Map a {@link ToolManagerInterface}'s definitions to MCP `tools/list` descriptors\n * — renaming `parameters` to the wire's `inputSchema`.\n *\n * @remarks\n * Each {@link import('@orkestrel/agent').ToolDefinition} carries through its\n * `name` and (when present) `description`; its open JSON-Schema `parameters`\n * becomes `inputSchema`, defaulting to an empty object schema (`{ type: 'object' }`)\n * when a tool declares none (MCP requires an `inputSchema`).\n *\n * @param manager - The tool registry to describe\n * @returns One {@link MCPToolDescriptor} per registered tool, in registry order\n */\nexport function buildToolDescriptors(manager: ToolManagerInterface): readonly MCPToolDescriptor[] {\n\treturn manager.definitions().map((definition) => {\n\t\tconst descriptor: {\n\t\t\tname: string\n\t\t\tdescription?: string\n\t\t\tinputSchema: Readonly<Record<string, unknown>>\n\t\t} = {\n\t\t\tname: definition.name,\n\t\t\tinputSchema: definition.parameters ?? { type: 'object' },\n\t\t}\n\t\tif (definition.description !== undefined) descriptor.description = definition.description\n\t\treturn descriptor\n\t})\n}\n\n/**\n * Map an executed tool's {@link ToolResult} to an MCP {@link MCPToolResult} — the\n * value (or error) as a `text` content block.\n *\n * @remarks\n * The {@link ToolManagerInterface} already isolates a thrown tool into\n * `result.error` (so the server adds NO try/catch around `execute`): when `error`\n * is present, this builds an `isError: true` result carrying the error text, so the\n * model sees the failure as a tool result it can react to rather than a protocol\n * error; otherwise it serializes `result.value` (via `JSON.stringify`) into one\n * `text` block.\n *\n * @param result - The tool's execution outcome\n * @returns The MCP tool-call result\n */\nexport function buildToolResult(result: ToolResult): MCPToolResult {\n\tif (result.error !== undefined) {\n\t\treturn { content: [{ type: 'text', text: result.error }], isError: true }\n\t}\n\t// A content block must carry a string `text`; `JSON.stringify(undefined)` is the value\n\t// `undefined` (which serializes away), so a value-less result becomes an empty text block.\n\tconst text = result.value === undefined ? '' : JSON.stringify(result.value)\n\treturn { content: [{ type: 'text', text }] }\n}\n\n/**\n * Build the MCP `initialize` result — the negotiated protocol version, the\n * advertised capabilities, and the server identity.\n *\n * @remarks\n * Version negotiation echoes the client's `requested` version when it is one of the\n * {@link SUPPORTED_PROTOCOL_VERSIONS}, else falls back to {@link MCP_PROTOCOL_VERSION}.\n * `capabilities.tools` is an empty object — this server advertises the tools\n * capability with no sub-options (no list-changed notification yet).\n *\n * @param name - The server name (echoed in `serverInfo`)\n * @param version - The server version (echoed in `serverInfo`)\n * @param requested - The client's requested protocol version (negotiated when supported)\n * @returns The `initialize` result payload\n */\nexport function initializeResult(\n\tname: string,\n\tversion: string,\n\trequested?: string,\n): Readonly<Record<string, unknown>> {\n\tconst protocolVersion =\n\t\trequested !== undefined && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)\n\t\t\t? requested\n\t\t\t: MCP_PROTOCOL_VERSION\n\treturn {\n\t\tprotocolVersion,\n\t\tcapabilities: { tools: {} },\n\t\tserverInfo: { name, version },\n\t}\n}\n","import type { EmitterInterface } from '@orkestrel/emitter'\nimport type { ToolManagerInterface } from '@orkestrel/agent'\nimport type {\n\tJSONRPCRequest,\n\tJSONRPCResponse,\n\tMCPServerEventMap,\n\tMCPServerInterface,\n\tMCPServerOptions,\n} from './types.js'\nimport { Emitter } from '@orkestrel/emitter'\nimport { isRecord, isString } from '@orkestrel/contract'\nimport {\n\tJSONRPC_INVALID_PARAMS,\n\tJSONRPC_INVALID_REQUEST,\n\tJSONRPC_METHOD_NOT_FOUND,\n\tJSONRPC_PARSE_ERROR,\n} from './constants.js'\nimport {\n\tbuildToolDescriptors,\n\tbuildToolResult,\n\tinitializeResult,\n\tjsonRPCError,\n\tjsonRPCResult,\n} from './helpers.js'\nimport { parseJSONRPCMessage } from './parsers.js'\n\n/**\n * A transport-agnostic Model Context Protocol server — dispatches JSON-RPC 2.0\n * requests over a live {@link ToolManagerInterface}, with NO transport coupling.\n *\n * @remarks\n * - **Two entry points.** `dispatch(request)` runs an already-parsed request and\n *   resolves a {@link JSONRPCResponse} — or `undefined` for a NOTIFICATION (a\n *   request with no `id`). `handle(message)` is the string boundary: it\n *   `JSON.parse`s the raw message (a failure → a `-32700` response), narrows it to\n *   a request (a non-request → a `-32600` response), dispatches, and serializes the\n *   response back to a string (`undefined` for a notification).\n * - **The method switch.** `initialize` negotiates the protocol version + advertises\n *   the tools capability; `notifications/initialized` is a notification (no\n *   response); `ping` returns `{}`; `tools/list` lists the registry's tools (its\n *   `parameters` renamed to `inputSchema`); `tools/call` runs a tool by name (the\n *   {@link ToolManagerInterface} isolates a tool throw into the result `error`, which\n *   maps to an `isError: true` tool result — so the server adds NO try/catch). An\n *   unknown method → `-32601`; a `tools/call` with a missing / non-string `name` →\n *   `-32602`.\n * - **Provider-agnostic.** Imports only core siblings — JSON-RPC + the tool registry,\n *   no HTTP, no model. Wire fields are narrowed via the contracts guards (no `as`).\n * - **Observable (§13).** The owned `emitter` fires `request` at the top of every\n *   dispatch; the emitter isolates a listener throw and routes it to its `error` handler\n *   (the `error` option), so a listener throw can never escape the dispatch.\n *\n * @example\n * ```ts\n * const tools = createToolManager()\n * tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))\n * const server = new MCPServer({ name: 'demo', version: '1.0.0', tools })\n * await server.handle('{\"jsonrpc\":\"2.0\",\"method\":\"ping\",\"id\":1}') // '{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{}}'\n * ```\n */\nexport class MCPServer implements MCPServerInterface {\n\treadonly #emitter: Emitter<MCPServerEventMap>\n\treadonly #name: string\n\treadonly #version: string\n\treadonly #tools: ToolManagerInterface\n\n\tconstructor(options: MCPServerOptions) {\n\t\tthis.#emitter = new Emitter<MCPServerEventMap>({ on: options.on, error: options.error })\n\t\tthis.#name = options.name\n\t\tthis.#version = options.version\n\t\tthis.#tools = options.tools\n\t}\n\n\tget emitter(): EmitterInterface<MCPServerEventMap> {\n\t\treturn this.#emitter\n\t}\n\n\tget name(): string {\n\t\treturn this.#name\n\t}\n\n\tget version(): string {\n\t\treturn this.#version\n\t}\n\n\tasync dispatch(request: JSONRPCRequest): Promise<JSONRPCResponse | undefined> {\n\t\tconst id = request.id ?? null\n\t\tthis.#emitter.emit('request', request.method, id)\n\t\t// JSON-RPC: a request with NO `id` is a NOTIFICATION — it is handled (the\n\t\t// `request` event already fired) but NEVER produces a response, whatever its\n\t\t// method (`notifications/initialized`, a fire-and-forget `ping`, an unknown\n\t\t// method — all silent). So short-circuit here, and the switch below only ever\n\t\t// runs for an id-bearing request that expects a reply.\n\t\tif (request.id === undefined) {\n\t\t\treturn undefined\n\t\t}\n\t\tswitch (request.method) {\n\t\t\tcase 'initialize': {\n\t\t\t\tconst requested = request.params?.['protocolVersion']\n\t\t\t\treturn jsonRPCResult(\n\t\t\t\t\tid,\n\t\t\t\t\tinitializeResult(this.#name, this.#version, isString(requested) ? requested : undefined),\n\t\t\t\t)\n\t\t\t}\n\t\t\tcase 'ping':\n\t\t\t\treturn jsonRPCResult(id, {})\n\t\t\tcase 'tools/list':\n\t\t\t\treturn jsonRPCResult(id, { tools: buildToolDescriptors(this.#tools) })\n\t\t\tcase 'tools/call':\n\t\t\t\treturn this.#call(request, id)\n\t\t\tdefault:\n\t\t\t\treturn jsonRPCError(id, JSONRPC_METHOD_NOT_FOUND, `Method not found: ${request.method}`)\n\t\t}\n\t}\n\n\tasync handle(message: string): Promise<string | undefined> {\n\t\tlet parsed: unknown\n\t\ttry {\n\t\t\tparsed = JSON.parse(message)\n\t\t} catch {\n\t\t\treturn JSON.stringify(jsonRPCError(null, JSONRPC_PARSE_ERROR, 'Parse error'))\n\t\t}\n\t\tconst decoded = parseJSONRPCMessage(parsed)\n\t\t// Only a REQUEST is dispatchable — a response (or any non-message) is invalid input.\n\t\tif (decoded === undefined || !('method' in decoded)) {\n\t\t\treturn JSON.stringify(jsonRPCError(null, JSONRPC_INVALID_REQUEST, 'Invalid Request'))\n\t\t}\n\t\tconst response = await this.dispatch(decoded)\n\t\treturn response === undefined ? undefined : JSON.stringify(response)\n\t}\n\n\t// Run a `tools/call`: narrow `params.name` (string) + `params.arguments` (record,\n\t// default `{}`) with no `as`, execute the tool (the manager isolates a throw into\n\t// `result.error`), and map the result to an MCP tool-call result.\n\tasync #call(request: JSONRPCRequest, id: string | number | null): Promise<JSONRPCResponse> {\n\t\tconst params = request.params\n\t\tconst name = params?.['name']\n\t\tif (!isString(name)) {\n\t\t\treturn jsonRPCError(id, JSONRPC_INVALID_PARAMS, 'Invalid params: a string `name` is required')\n\t\t}\n\t\tconst rawArguments = params?.['arguments']\n\t\tconst args = isRecord(rawArguments) ? rawArguments : {}\n\t\tconst callId = request.id === undefined ? crypto.randomUUID() : String(request.id)\n\t\tconst result = await this.#tools.execute({ id: callId, name, arguments: args })\n\t\treturn jsonRPCResult(id, buildToolResult(result))\n\t}\n}\n","import type { EmitterInterface } from '@orkestrel/emitter'\nimport type { ToolInterface } from '@orkestrel/agent'\nimport type {\n\tClientTransportInterface,\n\tJSONRPCMessage,\n\tJSONRPCRequest,\n\tMCPClientEventMap,\n\tMCPClientInterface,\n\tMCPClientOptions,\n} from './types.js'\nimport { Emitter } from '@orkestrel/emitter'\nimport { Tool } from '@orkestrel/agent'\nimport { isArray, isRecord, isString } from '@orkestrel/contract'\nimport {\n\tDEFAULT_MCP_CLIENT_NAME,\n\tDEFAULT_MCP_CLIENT_VERSION,\n\tDEFAULT_MCP_REQUEST_TIMEOUT,\n\tMCP_PROTOCOL_VERSION,\n} from './constants.js'\nimport { isJSONRPCResponse, isRequestId } from './validators.js'\n\n/**\n * A transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE MCP server\n * over an injected {@link ClientTransportInterface}, runs the `initialize` handshake,\n * and exposes the server's tools as local {@link ToolInterface}s an agent can run.\n *\n * @remarks\n * - **The mirror of `MCPServer`.** The server DISPATCHES requests over a tool registry;\n *   this client ISSUES them over a transport. `connect` runs `initialize` then sends\n *   `notifications/initialized`; `tools()` lists the remote tools and wraps each as a\n *   local {@link ToolInterface} whose `execute` calls back through `call`; `call` runs a\n *   remote `tools/call` and returns the tool's value (a remote `isError: true` throws\n *   locally, so an agent's {@link import('@orkestrel/agent').ToolManagerInterface}\n *   isolates it into a result `error` just like a local throw).\n * - **Request↔response correlation.** Each request is tagged with a monotonic numeric\n *   `id` ({@link #nextId}); a single transport `message` subscription resolves / rejects\n *   the matching {@link #pending} entry by `id`. A message that is NOT a response to a\n *   pending request is a server NOTIFICATION — re-surfaced on the `notification` event.\n * - **Per-request deadline.** `#request` races `AbortSignal.timeout(this.#timeout)` (the\n *   taverna idiom — never a raw `setTimeout`): a server that never replies REJECTS the\n *   pending request once the deadline fires, never hanging.\n * - **Transport-agnostic.** Imports only core siblings (JSON-RPC + the tool vocabulary);\n *   the concrete transport is injected. Wire fields are narrowed via the contracts\n *   guards (no `as`).\n * - **Observable (§13).** The owned `emitter` fires `connect` / `disconnect` /\n *   `notification` / `error`; the emitter isolates a listener throw and routes it to its\n *   `error` handler (the `error` option), so a listener throw can never escape.\n *\n * @example\n * ```ts\n * const client = new MCPClient({ transport, name: 'agent', version: '1.0.0' })\n * await client.connect()\n * const tools = await client.tools()\n * agent.context.tools.add(tools) // the remote tools are now the agent's\n * const value = await client.call('search', { query: 'mcp' })\n * ```\n */\nexport class MCPClient implements MCPClientInterface {\n\treadonly #emitter: Emitter<MCPClientEventMap>\n\treadonly #transport: ClientTransportInterface\n\treadonly #name: string\n\treadonly #version: string\n\treadonly #timeout: number\n\t// The in-flight requests, keyed by JSON-RPC id, each holding its promise settlers —\n\t// resolved on the matching response, rejected on an error response, the deadline, or\n\t// `disconnect`. Genuinely private glue (§5): the settler shape lives inline here.\n\treadonly #pending = new Map<\n\t\tstring | number,\n\t\t{ resolve: (value: unknown) => void; reject: (error: Error) => void }\n\t>()\n\t#nextId = 0\n\t#connected = false\n\n\tconstructor(options: MCPClientOptions) {\n\t\tthis.#emitter = new Emitter<MCPClientEventMap>({ on: options.on, error: options.error })\n\t\tthis.#transport = options.transport\n\t\tthis.#name = options.name ?? DEFAULT_MCP_CLIENT_NAME\n\t\tthis.#version = options.version ?? DEFAULT_MCP_CLIENT_VERSION\n\t\tthis.#timeout = options.timeout ?? DEFAULT_MCP_REQUEST_TIMEOUT\n\t\t// One message subscription for the client's whole life: a response settles its\n\t\t// pending request by id; anything else is a server notification.\n\t\tthis.#transport.emitter.on('message', (message) => this.#receive(message))\n\t}\n\n\tget emitter(): EmitterInterface<MCPClientEventMap> {\n\t\treturn this.#emitter\n\t}\n\n\tget connected(): boolean {\n\t\treturn this.#connected\n\t}\n\n\tget transport(): ClientTransportInterface {\n\t\treturn this.#transport\n\t}\n\n\ton<K extends keyof MCPClientEventMap>(\n\t\tevent: K,\n\t\thandler: (...args: MCPClientEventMap[K]) => void,\n\t): void {\n\t\tthis.#emitter.on(event, handler)\n\t}\n\n\tasync connect(): Promise<void> {\n\t\tif (this.#connected) return\n\t\tawait this.#transport.start()\n\t\t// The MCP handshake: negotiate the protocol version + advertise (empty) client\n\t\t// capabilities + identify ourselves, then mark connected and fire the no-args\n\t\t// `notifications/initialized` (a notification — no id, no response).\n\t\tawait this.#request('initialize', {\n\t\t\tprotocolVersion: MCP_PROTOCOL_VERSION,\n\t\t\tcapabilities: {},\n\t\t\tclientInfo: { name: this.#name, version: this.#version },\n\t\t})\n\t\tthis.#connected = true\n\t\tawait this.#transport.send({ jsonrpc: '2.0', method: 'notifications/initialized' })\n\t\tthis.#emitter.emit('connect')\n\t}\n\n\tasync disconnect(): Promise<void> {\n\t\tif (!this.#connected) return\n\t\tthis.#connected = false\n\t\t// Reject every still-pending request so no caller hangs past a disconnect, then\n\t\t// clear the map and tear the transport down.\n\t\tfor (const pending of this.#pending.values()) {\n\t\t\tpending.reject(new Error('MCP client disconnected'))\n\t\t}\n\t\tthis.#pending.clear()\n\t\tawait this.#transport.close()\n\t\tthis.#emitter.emit('disconnect')\n\t}\n\n\tasync tools(): Promise<readonly ToolInterface[]> {\n\t\tconst result = await this.#request('tools/list')\n\t\t// The wire shape is `{ tools: MCPToolDescriptor[] }` — narrow it (§14): a\n\t\t// non-record / non-array `tools` yields no tools rather than throwing.\n\t\tif (!isRecord(result) || !isArray(result['tools'])) return []\n\t\tconst tools: ToolInterface[] = []\n\t\tfor (const descriptor of result['tools']) {\n\t\t\tif (!isRecord(descriptor) || !isString(descriptor['name'])) continue\n\t\t\tconst name = descriptor['name']\n\t\t\ttools.push(this.#tool(name, descriptor))\n\t\t}\n\t\treturn tools\n\t}\n\n\tasync call(name: string, args: Readonly<Record<string, unknown>>): Promise<unknown> {\n\t\tconst result = await this.#request('tools/call', { name, arguments: args })\n\t\t// The inverse of the server's `buildToolResult`: concat the result's text blocks,\n\t\t// then either throw (a remote `isError`) or parse the JSON value.\n\t\tconst text = this.#text(result)\n\t\tif (isRecord(result) && result['isError'] === true) {\n\t\t\tthrow new Error(text.length > 0 ? text : `MCP tool '${name}' failed`)\n\t\t}\n\t\t// A success carries the value JSON-serialized into the text block(s); parse it,\n\t\t// falling back to the raw string when it is not JSON (the inverse of the server's\n\t\t// `JSON.stringify`, whose value-less result is an empty text block).\n\t\tif (text.length === 0) return undefined\n\t\ttry {\n\t\t\treturn JSON.parse(text)\n\t\t} catch {\n\t\t\treturn text\n\t\t}\n\t}\n\n\t// Issue a request and await its correlated response, bounded by the per-request\n\t// deadline. A monotonic numeric id keys the pending settlers; `AbortSignal.timeout`\n\t// (the taverna idiom — never a raw setTimeout) rejects the pending request if the\n\t// server never answers. The transport `send` is awaited so a write failure rejects\n\t// here rather than leaving a pending request to time out.\n\t#request(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown> {\n\t\tthis.#nextId += 1\n\t\tconst id = this.#nextId\n\t\tconst request: JSONRPCRequest = {\n\t\t\tjsonrpc: '2.0',\n\t\t\tid,\n\t\t\tmethod,\n\t\t\t...(params === undefined ? {} : { params }),\n\t\t}\n\t\treturn new Promise<unknown>((resolve, reject) => {\n\t\t\tconst deadline = AbortSignal.timeout(this.#timeout)\n\t\t\t// Settle once: clear the pending entry + detach the deadline listener, whichever\n\t\t\t// of (response | deadline | send-failure) fires first.\n\t\t\tconst settle = (): void => {\n\t\t\t\tthis.#pending.delete(id)\n\t\t\t\tdeadline.removeEventListener('abort', onDeadline)\n\t\t\t}\n\t\t\tconst onDeadline = (): void => {\n\t\t\t\tsettle()\n\t\t\t\treject(new Error(`MCP request '${method}' timed out after ${this.#timeout}ms`))\n\t\t\t}\n\t\t\tdeadline.addEventListener('abort', onDeadline, { once: true })\n\t\t\tthis.#pending.set(id, {\n\t\t\t\tresolve: (value) => {\n\t\t\t\t\tsettle()\n\t\t\t\t\tresolve(value)\n\t\t\t\t},\n\t\t\t\treject: (error) => {\n\t\t\t\t\tsettle()\n\t\t\t\t\treject(error)\n\t\t\t\t},\n\t\t\t})\n\t\t\tthis.#transport.send(request).catch((error: unknown) => {\n\t\t\t\tconst pending = this.#pending.get(id)\n\t\t\t\tif (pending === undefined) return\n\t\t\t\tpending.reject(error instanceof Error ? error : new Error(String(error)))\n\t\t\t})\n\t\t})\n\t}\n\n\t// Handle one inbound transport message: a response settles its pending request by\n\t// id (an error response rejects, a result resolves); anything else (a message with\n\t// no matching pending id) is a server-initiated notification, re-surfaced on the\n\t// `notification` event.\n\t#receive(message: JSONRPCMessage): void {\n\t\tif (isJSONRPCResponse(message) && isRequestId(message.id)) {\n\t\t\tconst pending = this.#pending.get(message.id)\n\t\t\tif (pending !== undefined) {\n\t\t\t\tif (message.error !== undefined) {\n\t\t\t\t\tpending.reject(new Error(`MCP error ${message.error.code}: ${message.error.message}`))\n\t\t\t\t} else {\n\t\t\t\t\tpending.resolve(message.result)\n\t\t\t\t}\n\t\t\t\treturn\n\t\t\t}\n\t\t}\n\t\t// Not a correlated response — a server notification (or an unsolicited response).\n\t\tthis.#emitter.emit('notification', message)\n\t}\n\n\t// Wrap one remote tool descriptor as a local tool: map `inputSchema` → `parameters`\n\t// (the inverse of the server's rename, no `as`), carry `description` when present,\n\t// and bind `execute` to a remote `tools/call` via `call`.\n\t#tool(name: string, descriptor: Readonly<Record<string, unknown>>): ToolInterface {\n\t\tconst inputSchema = descriptor['inputSchema']\n\t\tconst description = descriptor['description']\n\t\tconst options: {\n\t\t\tname: string\n\t\t\tdescription?: string\n\t\t\tparameters?: Readonly<Record<string, unknown>>\n\t\t\texecute: (args: Readonly<Record<string, unknown>>) => Promise<unknown>\n\t\t} = {\n\t\t\tname,\n\t\t\texecute: (args) => this.call(name, args),\n\t\t}\n\t\tif (isString(description)) options.description = description\n\t\tif (isRecord(inputSchema)) options.parameters = inputSchema\n\t\treturn new Tool(options)\n\t}\n\n\t// Concatenate an MCP tool-call result's text content blocks into one string — the\n\t// inverse of the server splitting a value into text block(s). Total (§14): a\n\t// non-record result, a non-array `content`, or a non-string `text` contributes\n\t// nothing rather than throwing.\n\t#text(result: unknown): string {\n\t\tif (!isRecord(result) || !isArray(result['content'])) return ''\n\t\tconst parts: string[] = []\n\t\tfor (const block of result['content']) {\n\t\t\tif (isRecord(block) && isString(block['text'])) parts.push(block['text'])\n\t\t}\n\t\treturn parts.join('\\n')\n\t}\n}\n","import type {\n\tMCPClientInterface,\n\tMCPClientOptions,\n\tMCPServerInterface,\n\tMCPServerOptions,\n} from './types.js'\nimport { MCPClient } from './MCPClient.js'\nimport { MCPServer } from './MCPServer.js'\n\n/**\n * Create a transport-agnostic Model Context Protocol server — exposes a live\n * {@link import('@orkestrel/agent').ToolManagerInterface} over JSON-RPC 2.0\n * (`initialize` / `ping` / `tools/list` / `tools/call`).\n *\n * @remarks\n * Pump raw message strings through `handle` (parse → dispatch → serialize) from a\n * transport, or call the typed `dispatch` directly with an already-parsed request.\n * The server is provider-agnostic — JSON-RPC plus the tool registry, with no HTTP\n * and no model. The {@link import('@orkestrel/agent').ToolManagerInterface} already\n * isolates a thrown tool into a result error (surfaced as an MCP `isError: true`\n * tool result), so a misbehaving tool never crashes a dispatch. Subscribe to the\n * `request` event via `server.emitter.on('request', …)` for tracing.\n *\n * @param options - `name` / `version` (the server identity), `tools` (the live\n *   registry to expose), an optional `description`, and the reserved `on`\n *   {@link import('@orkestrel/emitter').EmitterHooks} (see {@link MCPServerOptions})\n * @returns A working {@link MCPServerInterface}\n *\n * @example\n * ```ts\n * import { createMCPServer, createTool, createToolManager } from '@src/core'\n *\n * const tools = createToolManager()\n * tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))\n *\n * const server = createMCPServer({ name: 'calculator', version: '1.0.0', tools })\n * server.emitter.on('request', (method, id) => log(method, id))\n *\n * // A transport pumps message strings through `handle`:\n * const reply = await server.handle('{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}')\n * // reply → '{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"tools\":[{\"name\":\"add\",\"inputSchema\":{\"type\":\"object\"}}]}}'\n * ```\n */\nexport function createMCPServer(options: MCPServerOptions): MCPServerInterface {\n\treturn new MCPServer(options)\n}\n\n/**\n * Create a transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE\n * MCP server over an injected {@link import('./types.js').ClientTransportInterface},\n * runs the `initialize` handshake, and exposes the server's tools as local\n * {@link import('@orkestrel/agent').ToolInterface}s an agent can run.\n *\n * @remarks\n * The egress mirror of {@link createMCPServer}: where the server exposes a local tool\n * registry over MCP, the client USES a remote server's tools. `connect()` handshakes,\n * `tools()` lists + wraps the remote tools (each `execute` calls back over the wire),\n * and `call(name, args)` runs a remote `tools/call` (a remote tool failure throws\n * locally, so an agent's {@link import('@orkestrel/agent').ToolManagerInterface}\n * isolates it). The transport is injected — a concrete one (the HTTP transport over\n * `fetch`) lives in `@src/server`; the client itself is provider-agnostic. Subscribe\n * to `connect` / `disconnect` / `notification` via `client.on(...)` (or\n * `client.emitter.on(...)`).\n *\n * @param options - `transport` (the carrier; REQUIRED), `name` / `version` (the client\n *   identity), `timeout` (the per-request deadline), and the reserved `on`\n *   {@link import('@orkestrel/emitter').EmitterHooks} (see {@link MCPClientOptions})\n * @returns A working {@link MCPClientInterface}\n *\n * @example\n * ```ts\n * import { createMCPClient } from '@src/core'\n * import { createHTTPClientTransport } from '@src/server'\n *\n * const client = createMCPClient({\n * \ttransport: createHTTPClientTransport({ url: 'http://localhost:3000/mcp' }),\n * })\n * await client.connect()\n * agent.context.tools.add(await client.tools()) // give the agent the remote tools\n * const value = await client.call('search', { query: 'mcp' })\n * ```\n */\nexport function createMCPClient(options: MCPClientOptions): MCPClientInterface {\n\treturn new MCPClient(options)\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["#emitter","#name","#version","#tools","#call","#emitter","#transport","#name","#version","#timeout","#pending","#receive","#connected","#request","#tool","#text","#nextId"],"sources":["../../../src/core/constants.ts","../../../src/core/validators.ts","../../../src/core/parsers.ts","../../../src/core/helpers.ts","../../../src/core/MCPServer.ts","../../../src/core/MCPClient.ts","../../../src/core/factories.ts"],"sourcesContent":["// MCP protocol revisions + the reserved JSON-RPC 2.0 error codes. The negotiated\n// protocol version is the current rev unless the client requests a SUPPORTED prior\n// one (see `initializeResult` in ./helpers.js). Transport-level header names\n// (session / version headers) belong to the HTTP transport sub-chunk, NOT here.\n\n/** The MCP protocol revision this server implements (the default negotiated version). */\nexport const MCP_PROTOCOL_VERSION = '2025-06-18'\n\n/**\n * The MCP protocol revisions this server can negotiate — the current\n * {@link MCP_PROTOCOL_VERSION} plus a prior rev a client may still request.\n *\n * @remarks\n * `initialize` echoes the client's requested `protocolVersion` when it appears in\n * this list, else falls back to {@link MCP_PROTOCOL_VERSION}. Frozen so the list is\n * an immutable contract.\n */\nexport const SUPPORTED_PROTOCOL_VERSIONS: readonly string[] = Object.freeze([\n\t'2025-06-18',\n\t'2025-03-26',\n])\n\n/** JSON-RPC 2.0 reserved error: invalid JSON was received (the message did not parse). */\nexport const JSONRPC_PARSE_ERROR = -32700\n\n/** JSON-RPC 2.0 reserved error: the payload was not a valid Request object. */\nexport const JSONRPC_INVALID_REQUEST = -32600\n\n/** JSON-RPC 2.0 reserved error: the requested method does not exist. */\nexport const JSONRPC_METHOD_NOT_FOUND = -32601\n\n/** JSON-RPC 2.0 reserved error: the method's parameters were invalid. */\nexport const JSONRPC_INVALID_PARAMS = -32602\n\n/** JSON-RPC 2.0 implementation-defined server error (the `-32000` to `-32099` range). */\nexport const JSONRPC_SERVER_ERROR = -32000\n\n// MCP CLIENT defaults — the identity an `MCPClient` reports in the `initialize`\n// handshake (`clientInfo`) and the per-request deadline, when the caller supplies\n// none. The egress mirror of the server's protocol-version constants above.\n\n/** The default client name reported in the MCP `initialize` handshake (`clientInfo.name`). */\nexport const DEFAULT_MCP_CLIENT_NAME = 'taverna'\n\n/** The default client version reported in the MCP `initialize` handshake (`clientInfo.version`). */\nexport const DEFAULT_MCP_CLIENT_VERSION = '1.0.0'\n\n/**\n * The default per-request deadline (ms) an `MCPClient` applies when `options.timeout`\n * is unset — a request the remote server does not answer within it rejects.\n */\nexport const DEFAULT_MCP_REQUEST_TIMEOUT = 30_000\n","import type { JSONRPCMessage, JSONRPCRequest, JSONRPCResponse } from './types.js'\nimport { isNumber, isRecord, isString, isUndefined } from '@orkestrel/contract'\n\n// AGENTS §14: every guard here is a TOTAL function over the already-`JSON.parse`d\n// value — adversarial input returns `false`, never throws. The raw-string\n// `JSON.parse` (which CAN throw) happens in `MCPServer.handle` inside a try/catch;\n// these guards only ever see a parsed `unknown`. Each is a flat structural test on\n// `isRecord` + field checks (no user callbacks), so totality is immediate.\n\n/**\n * Determine whether a value is a valid JSON-RPC REQUEST `id` — a string, a number,\n * or absent.\n *\n * @remarks\n * A request id is a string, a number, or `undefined` (its ABSENCE marks a\n * NOTIFICATION). `null` is NOT a valid request id — it is valid only on a RESPONSE.\n * Total (§14): any other input returns `false`.\n *\n * @param value - The already-parsed value to test\n * @returns `true` when `value` is a string, a number, or `undefined`\n *\n * @example\n * ```ts\n * isRequestId(1)         // true\n * isRequestId('abc')     // true\n * isRequestId(undefined) // true — a notification\n * isRequestId(null)      // false — valid only on a response\n * ```\n */\nexport function isRequestId(value: unknown): value is string | number | undefined {\n\treturn isUndefined(value) || isString(value) || isNumber(value)\n}\n\n/**\n * Determine whether a parsed value is a {@link JSONRPCRequest}.\n *\n * @remarks\n * A request is a record with `jsonrpc === '2.0'` and a string `method`. `id`, when\n * present, must be a string or number; its ABSENCE is valid — that marks a\n * NOTIFICATION (a fire-and-forget request that yields no response). `params`, when\n * present, must be a record. Total (§14): any other input returns `false`.\n *\n * @param value - The already-parsed value to test\n * @returns `true` when `value` is a valid JSON-RPC request\n *\n * @example\n * ```ts\n * isJSONRPCRequest({ jsonrpc: '2.0', method: 'ping', id: 1 }) // true\n * isJSONRPCRequest({ jsonrpc: '2.0', method: 'notifications/initialized' }) // true — a notification\n * isJSONRPCRequest({ jsonrpc: '1.0', method: 'ping' }) // false\n * ```\n */\nexport function isJSONRPCRequest(value: unknown): value is JSONRPCRequest {\n\tif (!isRecord(value)) {\n\t\treturn false\n\t}\n\tif (value['jsonrpc'] !== '2.0' || !isString(value['method'])) {\n\t\treturn false\n\t}\n\tif (!isRequestId(value['id'])) {\n\t\treturn false\n\t}\n\tconst params = value['params']\n\treturn isUndefined(params) || isRecord(params)\n}\n\n/**\n * Determine whether a parsed value is a {@link JSONRPCResponse}.\n *\n * @remarks\n * A response is a record with `jsonrpc === '2.0'`, an `id` that is a string,\n * number, or `null`, and EXACTLY ONE of a `result` (any value, including\n * `undefined`'s absence) or an `error` (a record with a numeric `code` and string\n * `message`). Total (§14).\n *\n * @param value - The already-parsed value to test\n * @returns `true` when `value` is a valid JSON-RPC response\n */\nexport function isJSONRPCResponse(value: unknown): value is JSONRPCResponse {\n\tif (!isRecord(value)) {\n\t\treturn false\n\t}\n\tif (value['jsonrpc'] !== '2.0') {\n\t\treturn false\n\t}\n\tconst id = value['id']\n\tif (id !== null && !isString(id) && !isNumber(id)) {\n\t\treturn false\n\t}\n\tconst hasResult = Object.hasOwn(value, 'result')\n\tconst error = value['error']\n\tconst hasError = !isUndefined(error)\n\t// Exactly one of result / error — never both, never neither.\n\tif (hasResult === hasError) {\n\t\treturn false\n\t}\n\tif (hasError) {\n\t\treturn isRecord(error) && isNumber(error['code']) && isString(error['message'])\n\t}\n\treturn true\n}\n\n/**\n * Determine whether a parsed value is a {@link JSONRPCMessage} — a request or a\n * response.\n *\n * @remarks\n * The union of {@link isJSONRPCRequest} and {@link isJSONRPCResponse}. Total (§14).\n *\n * @param value - The already-parsed value to test\n * @returns `true` when `value` is a valid JSON-RPC request or response\n */\nexport function isJSONRPCMessage(value: unknown): value is JSONRPCMessage {\n\treturn isJSONRPCRequest(value) || isJSONRPCResponse(value)\n}\n\n/**\n * Determine whether a parsed value is an MCP `initialize` request — a\n * {@link JSONRPCRequest} whose `method` is `'initialize'`.\n *\n * @param value - The already-parsed value to test\n * @returns `true` when `value` is a valid `initialize` request\n *\n * @example\n * ```ts\n * isInitializeRequest({ jsonrpc: '2.0', method: 'initialize', id: 1 }) // true\n * isInitializeRequest({ jsonrpc: '2.0', method: 'ping', id: 1 }) // false\n * ```\n */\nexport function isInitializeRequest(value: unknown): value is JSONRPCRequest {\n\treturn isJSONRPCRequest(value) && value.method === 'initialize'\n}\n","import type { JSONRPCMessage } from './types.js'\nimport { isJSONRPCMessage } from './validators.js'\n\n/**\n * Narrow an already-parsed value to a {@link JSONRPCMessage}, or `undefined` when\n * it is not one.\n *\n * @remarks\n * Total (§14) — a non-message returns `undefined`, never throws. The input must\n * ALREADY be `JSON.parse`d: the raw-string parse (which can throw on malformed\n * JSON) happens in `MCPServer.handle` inside a try/catch that maps a parse failure\n * to a `-32700` response. Sound with {@link isJSONRPCMessage}: a guard-valid input\n * is returned unchanged, and every non-`undefined` output satisfies the guard.\n *\n * @param value - The already-parsed value to narrow\n * @returns The value as a {@link JSONRPCMessage}, or `undefined`\n *\n * @example\n * ```ts\n * parseJSONRPCMessage({ jsonrpc: '2.0', method: 'ping', id: 1 }) // the request\n * parseJSONRPCMessage({ method: 'ping' }) // undefined — missing jsonrpc\n * ```\n */\nexport function parseJSONRPCMessage(value: unknown): JSONRPCMessage | undefined {\n\treturn isJSONRPCMessage(value) ? value : undefined\n}\n","import type { ToolManagerInterface, ToolResult } from '@orkestrel/agent'\nimport type {\n\tJSONRPCResponse,\n\tMCPClientInterface,\n\tMCPServerInterface,\n\tMCPToolDescriptor,\n\tMCPToolResult,\n\tMCPTransportInterface,\n} from './types.js'\nimport { MCP_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS } from './constants.js'\nimport { parseJSONRPCMessage } from './parsers.js'\n\n// Pure dispatch builders (AGENTS §5: the dispatch branches stay exported helpers,\n// not hidden privates). Each turns a piece of MCP state into the JSON-RPC `result`\n// payload (or a response envelope) the server returns — independently testable.\n\n/**\n * Build a JSON-RPC success {@link JSONRPCResponse} — the `id` echoed, the method's\n * value as `result`.\n *\n * @param id - The request's id (`null` only for a parse / invalid-request error)\n * @param result - The method's return value\n * @returns The success response envelope\n */\nexport function jsonRPCResult(id: string | number | null, result: unknown): JSONRPCResponse {\n\treturn { jsonrpc: '2.0', id, result }\n}\n\n/**\n * Build a JSON-RPC error {@link JSONRPCResponse} — the `id` echoed, the failure as\n * an `error` object.\n *\n * @param id - The request's id (`null` for a parse / invalid-request error)\n * @param code - One of the reserved JSON-RPC codes (see `./constants.js`)\n * @param message - A short human description of the failure\n * @param data - An OPTIONAL machine-readable payload (omitted from the envelope when absent)\n * @returns The error response envelope\n */\nexport function jsonRPCError(\n\tid: string | number | null,\n\tcode: number,\n\tmessage: string,\n\tdata?: unknown,\n): JSONRPCResponse {\n\treturn {\n\t\tjsonrpc: '2.0',\n\t\tid,\n\t\terror: data === undefined ? { code, message } : { code, message, data },\n\t}\n}\n\n/**\n * Map a {@link ToolManagerInterface}'s definitions to MCP `tools/list` descriptors\n * — renaming `parameters` to the wire's `inputSchema`.\n *\n * @remarks\n * Each {@link import('@orkestrel/agent').ToolDefinition} carries through its\n * `name` and (when present) `description`; its open JSON-Schema `parameters`\n * becomes `inputSchema`, defaulting to an empty object schema (`{ type: 'object' }`)\n * when a tool declares none (MCP requires an `inputSchema`).\n *\n * @param manager - The tool registry to describe\n * @returns One {@link MCPToolDescriptor} per registered tool, in registry order\n */\nexport function buildToolDescriptors(manager: ToolManagerInterface): readonly MCPToolDescriptor[] {\n\treturn manager.definitions().map((definition) => {\n\t\tconst descriptor: {\n\t\t\tname: string\n\t\t\tdescription?: string\n\t\t\tinputSchema: Readonly<Record<string, unknown>>\n\t\t} = {\n\t\t\tname: definition.name,\n\t\t\tinputSchema: definition.parameters ?? { type: 'object' },\n\t\t}\n\t\tif (definition.description !== undefined) descriptor.description = definition.description\n\t\treturn descriptor\n\t})\n}\n\n/**\n * Map an executed tool's {@link ToolResult} to an MCP {@link MCPToolResult} — the\n * value (or error) as a `text` content block.\n *\n * @remarks\n * The {@link ToolManagerInterface} already isolates a thrown tool into\n * `result.error` (so the server adds NO try/catch around `execute`): when `error`\n * is present, this builds an `isError: true` result carrying the error text, so the\n * model sees the failure as a tool result it can react to rather than a protocol\n * error; otherwise it serializes `result.value` (via `JSON.stringify`) into one\n * `text` block.\n *\n * @param result - The tool's execution outcome\n * @returns The MCP tool-call result\n */\nexport function buildToolResult(result: ToolResult): MCPToolResult {\n\tif (result.error !== undefined) {\n\t\treturn { content: [{ type: 'text', text: result.error }], isError: true }\n\t}\n\t// A content block must carry a string `text`; `JSON.stringify(undefined)` is the value\n\t// `undefined` (which serializes away), so a value-less result becomes an empty text block.\n\tconst text = result.value === undefined ? '' : JSON.stringify(result.value)\n\treturn { content: [{ type: 'text', text }] }\n}\n\n/**\n * Build the MCP `initialize` result — the negotiated protocol version, the\n * advertised capabilities, and the server identity.\n *\n * @remarks\n * Version negotiation echoes the client's `requested` version when it is one of the\n * {@link SUPPORTED_PROTOCOL_VERSIONS}, else falls back to {@link MCP_PROTOCOL_VERSION}.\n * `capabilities.tools` is an empty object — this server advertises the tools\n * capability with no sub-options (no list-changed notification yet).\n *\n * @param name - The server name (echoed in `serverInfo`)\n * @param version - The server version (echoed in `serverInfo`)\n * @param requested - The client's requested protocol version (negotiated when supported)\n * @returns The `initialize` result payload\n */\nexport function initializeResult(\n\tname: string,\n\tversion: string,\n\trequested?: string,\n): Readonly<Record<string, unknown>> {\n\tconst protocolVersion =\n\t\trequested !== undefined && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)\n\t\t\t? requested\n\t\t\t: MCP_PROTOCOL_VERSION\n\treturn {\n\t\tprotocolVersion,\n\t\tcapabilities: { tools: {} },\n\t\tserverInfo: { name, version },\n\t}\n}\n\n// The environment-agnostic PORT binders — the keystone that lets an\n// {@link MCPServerInterface} / {@link MCPClientInterface} run over ANY\n// {@link MCPTransportInterface} (a Node stdio pair, a browser MessagePort, a Web\n// Worker `self`) with no per-environment dispatch/correlation wiring duplicated at\n// each face. Both are TOTAL: a `send` throw or rejection is caught and never\n// escapes as an unhandled rejection.\n\n/**\n * Pipe an {@link MCPTransportInterface} into an {@link MCPServerInterface} — every\n * inbound message runs through `server.handle`, and a defined reply is written back\n * via `transport.send`.\n *\n * @remarks\n * `server.handle` already turns a malformed message into a serialized `-32700` /\n * `-32600` reply and a notification into `undefined` (no reply), so this binder adds\n * no parsing of its own. A `transport.send` throw or rejection is caught and routed\n * to `server.emitter`'s `error` event (never rethrown, never an unhandled rejection);\n * a listener on that event that itself throws is swallowed (the end of the line —\n * the caller's own bug, never this binder's). The returned unbind DETACHES this\n * binder (further inbound messages and the transport's `closed` signal are ignored)\n * WITHOUT closing the transport — closing is the caller's decision.\n *\n * `listen`/`closed` are REPLACE semantics (§ port contract): the returned unbind\n * DETACHES by replacing this binder's own handlers with no-ops, so a subsequent\n * `bindServer` call on the SAME transport is never double-dispatched by a stale\n * subscription left behind — an unbind→rebind cycle yields exactly one reply per\n * request.\n *\n * @param server - The transport-agnostic server to dispatch inbound messages over\n * @param transport - The duplex channel to pipe the server over\n * @returns Detach this binder from the transport (does not close it)\n *\n * @example\n * ```ts\n * const unbind = bindServer(server, transport)\n * // ... later, detach without closing:\n * unbind()\n * ```\n */\nexport function bindServer(\n\tserver: MCPServerInterface,\n\ttransport: MCPTransportInterface,\n): () => void {\n\tlet active = true\n\ttransport.listen((message) => {\n\t\tif (!active) return\n\t\tvoid (async () => {\n\t\t\ttry {\n\t\t\t\tconst response = await server.handle(message)\n\t\t\t\tif (response !== undefined) await transport.send(response)\n\t\t\t} catch (error) {\n\t\t\t\ttry {\n\t\t\t\t\tserver.emitter.emit('error', error)\n\t\t\t\t} catch {\n\t\t\t\t\t// A throwing `error` listener is the caller's own bug — the end of the line.\n\t\t\t\t}\n\t\t\t}\n\t\t})()\n\t})\n\ttransport.closed(() => {\n\t\tactive = false\n\t})\n\treturn () => {\n\t\tactive = false\n\t\ttransport.listen(() => {})\n\t\ttransport.closed(() => {})\n\t}\n}\n\n/**\n * Pipe an {@link MCPTransportInterface} into an {@link MCPClientInterface} — every\n * inbound message is decoded and delivered onto the client's OWN transport\n * (`client.transport.emitter`'s `message` / `close` events), resolving/rejecting the\n * client's correlated pending requests exactly as a direct reply would.\n *\n * @remarks\n * The client's outbound writes flow through `client.transport.send` — its existing,\n * unmodified request/response correlation — so `client` must have been constructed\n * with a {@link import('./types.js').ClientTransportInterface} that itself carries\n * the SAME `transport` (see {@link import('./factories.js').createDuplexClientTransport},\n * the additive factory that adapts an {@link MCPTransportInterface} into that shape);\n * this binder then completes the inbound half by decoding each message and pushing it\n * onto `client.transport.emitter` (an {@link import('@orkestrel/emitter').EmitterInterface}\n * exposes `emit`, so no client modification is needed). A malformed / non-JSON-RPC\n * inbound message is DROPPED (§14, total — never throws); a delivery fault is routed to\n * `client.transport.emitter`'s `error` event (never rethrown). The returned unbind\n * DETACHES this binder (further inbound messages and the transport's `closed` signal are\n * ignored) WITHOUT closing the transport.\n *\n * `listen`/`closed` are REPLACE semantics (§ port contract): the returned unbind\n * DETACHES by replacing this binder's own handlers with no-ops, so a subsequent\n * `bindClient` call on the SAME transport is never double-dispatched by a stale\n * subscription left behind — an unbind→rebind cycle delivers exactly one `message`\n * emit per inbound reply.\n *\n * @param client - The transport-agnostic client whose transport to deliver messages onto\n * @param transport - The duplex channel to pipe the client over\n * @returns Detach this binder from the transport (does not close it)\n *\n * @example\n * ```ts\n * const client = createMCPClient({ transport: createDuplexClientTransport(transport) })\n * const unbind = bindClient(client, transport)\n * await client.connect()\n * // ... later, detach without closing:\n * unbind()\n * ```\n */\nexport function bindClient(\n\tclient: MCPClientInterface,\n\ttransport: MCPTransportInterface,\n): () => void {\n\tlet active = true\n\ttransport.listen((message) => {\n\t\tif (!active) return\n\t\tlet parsed: unknown\n\t\ttry {\n\t\t\tparsed = JSON.parse(message)\n\t\t} catch {\n\t\t\treturn\n\t\t}\n\t\tconst decoded = parseJSONRPCMessage(parsed)\n\t\tif (decoded === undefined) return\n\t\ttry {\n\t\t\tclient.transport.emitter.emit('message', decoded)\n\t\t} catch (error) {\n\t\t\ttry {\n\t\t\t\tclient.transport.emitter.emit('error', error)\n\t\t\t} catch {\n\t\t\t\t// A throwing `error` listener is the caller's own bug — the end of the line.\n\t\t\t}\n\t\t}\n\t})\n\ttransport.closed(() => {\n\t\tif (!active) return\n\t\tactive = false\n\t\ttry {\n\t\t\tclient.transport.emitter.emit('close')\n\t\t} catch {\n\t\t\t// A throwing `close` listener is the caller's own bug — the end of the line.\n\t\t}\n\t})\n\treturn () => {\n\t\tactive = false\n\t\ttransport.listen(() => {})\n\t\ttransport.closed(() => {})\n\t}\n}\n","import type { EmitterInterface } from '@orkestrel/emitter'\nimport type { ToolManagerInterface } from '@orkestrel/agent'\nimport type {\n\tJSONRPCRequest,\n\tJSONRPCResponse,\n\tMCPServerEventMap,\n\tMCPServerInterface,\n\tMCPServerOptions,\n} from './types.js'\nimport { Emitter } from '@orkestrel/emitter'\nimport { isRecord, isString } from '@orkestrel/contract'\nimport {\n\tJSONRPC_INVALID_PARAMS,\n\tJSONRPC_INVALID_REQUEST,\n\tJSONRPC_METHOD_NOT_FOUND,\n\tJSONRPC_PARSE_ERROR,\n} from './constants.js'\nimport {\n\tbuildToolDescriptors,\n\tbuildToolResult,\n\tinitializeResult,\n\tjsonRPCError,\n\tjsonRPCResult,\n} from './helpers.js'\nimport { parseJSONRPCMessage } from './parsers.js'\n\n/**\n * A transport-agnostic Model Context Protocol server — dispatches JSON-RPC 2.0\n * requests over a live {@link ToolManagerInterface}, with NO transport coupling.\n *\n * @remarks\n * - **Two entry points.** `dispatch(request)` runs an already-parsed request and\n *   resolves a {@link JSONRPCResponse} — or `undefined` for a NOTIFICATION (a\n *   request with no `id`). `handle(message)` is the string boundary: it\n *   `JSON.parse`s the raw message (a failure → a `-32700` response), narrows it to\n *   a request (a non-request → a `-32600` response), dispatches, and serializes the\n *   response back to a string (`undefined` for a notification).\n * - **The method switch.** `initialize` negotiates the protocol version + advertises\n *   the tools capability; `notifications/initialized` is a notification (no\n *   response); `ping` returns `{}`; `tools/list` lists the registry's tools (its\n *   `parameters` renamed to `inputSchema`); `tools/call` runs a tool by name (the\n *   {@link ToolManagerInterface} isolates a tool throw into the result `error`, which\n *   maps to an `isError: true` tool result — so the server adds NO try/catch). An\n *   unknown method → `-32601`; a `tools/call` with a missing / non-string `name` →\n *   `-32602`.\n * - **Provider-agnostic.** Imports only core siblings — JSON-RPC + the tool registry,\n *   no HTTP, no model. Wire fields are narrowed via the contracts guards (no `as`).\n * - **Observable (§13).** The owned `emitter` fires `request` at the top of every\n *   dispatch; the emitter isolates a listener throw and routes it to its `error` handler\n *   (the `error` option), so a listener throw can never escape the dispatch.\n *\n * @example\n * ```ts\n * const tools = createToolManager()\n * tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))\n * const server = new MCPServer({ name: 'demo', version: '1.0.0', tools })\n * await server.handle('{\"jsonrpc\":\"2.0\",\"method\":\"ping\",\"id\":1}') // '{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{}}'\n * ```\n */\nexport class MCPServer implements MCPServerInterface {\n\treadonly #emitter: Emitter<MCPServerEventMap>\n\treadonly #name: string\n\treadonly #version: string\n\treadonly #tools: ToolManagerInterface\n\n\tconstructor(options: MCPServerOptions) {\n\t\tthis.#emitter = new Emitter<MCPServerEventMap>({ on: options.on, error: options.error })\n\t\tthis.#name = options.name\n\t\tthis.#version = options.version\n\t\tthis.#tools = options.tools\n\t}\n\n\tget emitter(): EmitterInterface<MCPServerEventMap> {\n\t\treturn this.#emitter\n\t}\n\n\tget name(): string {\n\t\treturn this.#name\n\t}\n\n\tget version(): string {\n\t\treturn this.#version\n\t}\n\n\tasync dispatch(request: JSONRPCRequest): Promise<JSONRPCResponse | undefined> {\n\t\tconst id = request.id ?? null\n\t\tthis.#emitter.emit('request', request.method, id)\n\t\t// JSON-RPC: a request with NO `id` is a NOTIFICATION — it is handled (the\n\t\t// `request` event already fired) but NEVER produces a response, whatever its\n\t\t// method (`notifications/initialized`, a fire-and-forget `ping`, an unknown\n\t\t// method — all silent). So short-circuit here, and the switch below only ever\n\t\t// runs for an id-bearing request that expects a reply.\n\t\tif (request.id === undefined) {\n\t\t\treturn undefined\n\t\t}\n\t\tswitch (request.method) {\n\t\t\tcase 'initialize': {\n\t\t\t\tconst requested = request.params?.['protocolVersion']\n\t\t\t\treturn jsonRPCResult(\n\t\t\t\t\tid,\n\t\t\t\t\tinitializeResult(this.#name, this.#version, isString(requested) ? requested : undefined),\n\t\t\t\t)\n\t\t\t}\n\t\t\tcase 'ping':\n\t\t\t\treturn jsonRPCResult(id, {})\n\t\t\tcase 'tools/list':\n\t\t\t\treturn jsonRPCResult(id, { tools: buildToolDescriptors(this.#tools) })\n\t\t\tcase 'tools/call':\n\t\t\t\treturn this.#call(request, id)\n\t\t\tdefault:\n\t\t\t\treturn jsonRPCError(id, JSONRPC_METHOD_NOT_FOUND, `Method not found: ${request.method}`)\n\t\t}\n\t}\n\n\tasync handle(message: string): Promise<string | undefined> {\n\t\tlet parsed: unknown\n\t\ttry {\n\t\t\tparsed = JSON.parse(message)\n\t\t} catch {\n\t\t\treturn JSON.stringify(jsonRPCError(null, JSONRPC_PARSE_ERROR, 'Parse error'))\n\t\t}\n\t\tconst decoded = parseJSONRPCMessage(parsed)\n\t\t// Only a REQUEST is dispatchable — a response (or any non-message) is invalid input.\n\t\tif (decoded === undefined || !('method' in decoded)) {\n\t\t\treturn JSON.stringify(jsonRPCError(null, JSONRPC_INVALID_REQUEST, 'Invalid Request'))\n\t\t}\n\t\tconst response = await this.dispatch(decoded)\n\t\treturn response === undefined ? undefined : JSON.stringify(response)\n\t}\n\n\t// Run a `tools/call`: narrow `params.name` (string) + `params.arguments` (record,\n\t// default `{}`) with no `as`, execute the tool (the manager isolates a throw into\n\t// `result.error`), and map the result to an MCP tool-call result.\n\tasync #call(request: JSONRPCRequest, id: string | number | null): Promise<JSONRPCResponse> {\n\t\tconst params = request.params\n\t\tconst name = params?.['name']\n\t\tif (!isString(name)) {\n\t\t\treturn jsonRPCError(id, JSONRPC_INVALID_PARAMS, 'Invalid params: a string `name` is required')\n\t\t}\n\t\tconst rawArguments = params?.['arguments']\n\t\tconst args = isRecord(rawArguments) ? rawArguments : {}\n\t\tconst callId = request.id === undefined ? crypto.randomUUID() : String(request.id)\n\t\tconst result = await this.#tools.execute({ id: callId, name, arguments: args })\n\t\treturn jsonRPCResult(id, buildToolResult(result))\n\t}\n}\n","import type { EmitterInterface } from '@orkestrel/emitter'\nimport type { ToolInterface } from '@orkestrel/agent'\nimport type {\n\tClientTransportInterface,\n\tJSONRPCMessage,\n\tJSONRPCRequest,\n\tMCPClientEventMap,\n\tMCPClientInterface,\n\tMCPClientOptions,\n} from './types.js'\nimport { Emitter } from '@orkestrel/emitter'\nimport { Tool } from '@orkestrel/agent'\nimport { isArray, isRecord, isString } from '@orkestrel/contract'\nimport {\n\tDEFAULT_MCP_CLIENT_NAME,\n\tDEFAULT_MCP_CLIENT_VERSION,\n\tDEFAULT_MCP_REQUEST_TIMEOUT,\n\tMCP_PROTOCOL_VERSION,\n} from './constants.js'\nimport { isJSONRPCResponse, isRequestId } from './validators.js'\n\n/**\n * A transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE MCP server\n * over an injected {@link ClientTransportInterface}, runs the `initialize` handshake,\n * and exposes the server's tools as local {@link ToolInterface}s an agent can run.\n *\n * @remarks\n * - **The mirror of `MCPServer`.** The server DISPATCHES requests over a tool registry;\n *   this client ISSUES them over a transport. `connect` runs `initialize` then sends\n *   `notifications/initialized`; `tools()` lists the remote tools and wraps each as a\n *   local {@link ToolInterface} whose `execute` calls back through `call`; `call` runs a\n *   remote `tools/call` and returns the tool's value (a remote `isError: true` throws\n *   locally, so an agent's {@link import('@orkestrel/agent').ToolManagerInterface}\n *   isolates it into a result `error` just like a local throw).\n * - **Request↔response correlation.** Each request is tagged with a monotonic numeric\n *   `id` ({@link #nextId}); a single transport `message` subscription resolves / rejects\n *   the matching {@link #pending} entry by `id`. A message that is NOT a response to a\n *   pending request is a server NOTIFICATION — re-surfaced on the `notification` event.\n * - **Per-request deadline.** `#request` races `AbortSignal.timeout(this.#timeout)` (the\n *   taverna idiom — never a raw `setTimeout`): a server that never replies REJECTS the\n *   pending request once the deadline fires, never hanging.\n * - **Transport-agnostic.** Imports only core siblings (JSON-RPC + the tool vocabulary);\n *   the concrete transport is injected. Wire fields are narrowed via the contracts\n *   guards (no `as`).\n * - **Observable (§13).** The owned `emitter` fires `connect` / `disconnect` /\n *   `notification` / `error`; the emitter isolates a listener throw and routes it to its\n *   `error` handler (the `error` option), so a listener throw can never escape.\n *\n * @example\n * ```ts\n * const client = new MCPClient({ transport, name: 'agent', version: '1.0.0' })\n * await client.connect()\n * const tools = await client.tools()\n * agent.context.tools.add(tools) // the remote tools are now the agent's\n * const value = await client.call('search', { query: 'mcp' })\n * ```\n */\nexport class MCPClient implements MCPClientInterface {\n\treadonly #emitter: Emitter<MCPClientEventMap>\n\treadonly #transport: ClientTransportInterface\n\treadonly #name: string\n\treadonly #version: string\n\treadonly #timeout: number\n\t// The in-flight requests, keyed by JSON-RPC id, each holding its promise settlers —\n\t// resolved on the matching response, rejected on an error response, the deadline, or\n\t// `disconnect`. Genuinely private glue (§5): the settler shape lives inline here.\n\treadonly #pending = new Map<\n\t\tstring | number,\n\t\t{ resolve: (value: unknown) => void; reject: (error: Error) => void }\n\t>()\n\t#nextId = 0\n\t#connected = false\n\n\tconstructor(options: MCPClientOptions) {\n\t\tthis.#emitter = new Emitter<MCPClientEventMap>({ on: options.on, error: options.error })\n\t\tthis.#transport = options.transport\n\t\tthis.#name = options.name ?? DEFAULT_MCP_CLIENT_NAME\n\t\tthis.#version = options.version ?? DEFAULT_MCP_CLIENT_VERSION\n\t\tthis.#timeout = options.timeout ?? DEFAULT_MCP_REQUEST_TIMEOUT\n\t\t// One message subscription for the client's whole life: a response settles its\n\t\t// pending request by id; anything else is a server notification.\n\t\tthis.#transport.emitter.on('message', (message) => this.#receive(message))\n\t}\n\n\tget emitter(): EmitterInterface<MCPClientEventMap> {\n\t\treturn this.#emitter\n\t}\n\n\tget connected(): boolean {\n\t\treturn this.#connected\n\t}\n\n\tget transport(): ClientTransportInterface {\n\t\treturn this.#transport\n\t}\n\n\ton<K extends keyof MCPClientEventMap>(\n\t\tevent: K,\n\t\thandler: (...args: MCPClientEventMap[K]) => void,\n\t): void {\n\t\tthis.#emitter.on(event, handler)\n\t}\n\n\tasync connect(): Promise<void> {\n\t\tif (this.#connected) return\n\t\tawait this.#transport.start()\n\t\t// The MCP handshake: negotiate the protocol version + advertise (empty) client\n\t\t// capabilities + identify ourselves, then mark connected and fire the no-args\n\t\t// `notifications/initialized` (a notification — no id, no response).\n\t\tawait this.#request('initialize', {\n\t\t\tprotocolVersion: MCP_PROTOCOL_VERSION,\n\t\t\tcapabilities: {},\n\t\t\tclientInfo: { name: this.#name, version: this.#version },\n\t\t})\n\t\tthis.#connected = true\n\t\tawait this.#transport.send({ jsonrpc: '2.0', method: 'notifications/initialized' })\n\t\tthis.#emitter.emit('connect')\n\t}\n\n\tasync disconnect(): Promise<void> {\n\t\tif (!this.#connected) return\n\t\tthis.#connected = false\n\t\t// Reject every still-pending request so no caller hangs past a disconnect, then\n\t\t// clear the map and tear the transport down.\n\t\tfor (const pending of this.#pending.values()) {\n\t\t\tpending.reject(new Error('MCP client disconnected'))\n\t\t}\n\t\tthis.#pending.clear()\n\t\tawait this.#transport.close()\n\t\tthis.#emitter.emit('disconnect')\n\t}\n\n\tasync tools(): Promise<readonly ToolInterface[]> {\n\t\tconst result = await this.#request('tools/list')\n\t\t// The wire shape is `{ tools: MCPToolDescriptor[] }` — narrow it (§14): a\n\t\t// non-record / non-array `tools` yields no tools rather than throwing.\n\t\tif (!isRecord(result) || !isArray(result['tools'])) return []\n\t\tconst tools: ToolInterface[] = []\n\t\tfor (const descriptor of result['tools']) {\n\t\t\tif (!isRecord(descriptor) || !isString(descriptor['name'])) continue\n\t\t\tconst name = descriptor['name']\n\t\t\ttools.push(this.#tool(name, descriptor))\n\t\t}\n\t\treturn tools\n\t}\n\n\tasync call(name: string, args: Readonly<Record<string, unknown>>): Promise<unknown> {\n\t\tconst result = await this.#request('tools/call', { name, arguments: args })\n\t\t// The inverse of the server's `buildToolResult`: concat the result's text blocks,\n\t\t// then either throw (a remote `isError`) or parse the JSON value.\n\t\tconst text = this.#text(result)\n\t\tif (isRecord(result) && result['isError'] === true) {\n\t\t\tthrow new Error(text.length > 0 ? text : `MCP tool '${name}' failed`)\n\t\t}\n\t\t// A success carries the value JSON-serialized into the text block(s); parse it,\n\t\t// falling back to the raw string when it is not JSON (the inverse of the server's\n\t\t// `JSON.stringify`, whose value-less result is an empty text block).\n\t\tif (text.length === 0) return undefined\n\t\ttry {\n\t\t\treturn JSON.parse(text)\n\t\t} catch {\n\t\t\treturn text\n\t\t}\n\t}\n\n\t// Issue a request and await its correlated response, bounded by the per-request\n\t// deadline. A monotonic numeric id keys the pending settlers; `AbortSignal.timeout`\n\t// (the taverna idiom — never a raw setTimeout) rejects the pending request if the\n\t// server never answers. The transport `send` is awaited so a write failure rejects\n\t// here rather than leaving a pending request to time out.\n\t#request(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown> {\n\t\tthis.#nextId += 1\n\t\tconst id = this.#nextId\n\t\tconst request: JSONRPCRequest = {\n\t\t\tjsonrpc: '2.0',\n\t\t\tid,\n\t\t\tmethod,\n\t\t\t...(params === undefined ? {} : { params }),\n\t\t}\n\t\treturn new Promise<unknown>((resolve, reject) => {\n\t\t\tconst deadline = AbortSignal.timeout(this.#timeout)\n\t\t\t// Settle once: clear the pending entry + detach the deadline listener, whichever\n\t\t\t// of (response | deadline | send-failure) fires first.\n\t\t\tconst settle = (): void => {\n\t\t\t\tthis.#pending.delete(id)\n\t\t\t\tdeadline.removeEventListener('abort', onDeadline)\n\t\t\t}\n\t\t\tconst onDeadline = (): void => {\n\t\t\t\tsettle()\n\t\t\t\treject(new Error(`MCP request '${method}' timed out after ${this.#timeout}ms`))\n\t\t\t}\n\t\t\tdeadline.addEventListener('abort', onDeadline, { once: true })\n\t\t\tthis.#pending.set(id, {\n\t\t\t\tresolve: (value) => {\n\t\t\t\t\tsettle()\n\t\t\t\t\tresolve(value)\n\t\t\t\t},\n\t\t\t\treject: (error) => {\n\t\t\t\t\tsettle()\n\t\t\t\t\treject(error)\n\t\t\t\t},\n\t\t\t})\n\t\t\tthis.#transport.send(request).catch((error: unknown) => {\n\t\t\t\tconst pending = this.#pending.get(id)\n\t\t\t\tif (pending === undefined) return\n\t\t\t\tpending.reject(error instanceof Error ? error : new Error(String(error)))\n\t\t\t})\n\t\t})\n\t}\n\n\t// Handle one inbound transport message: a response settles its pending request by\n\t// id (an error response rejects, a result resolves); anything else (a message with\n\t// no matching pending id) is a server-initiated notification, re-surfaced on the\n\t// `notification` event.\n\t#receive(message: JSONRPCMessage): void {\n\t\tif (isJSONRPCResponse(message) && isRequestId(message.id)) {\n\t\t\tconst pending = this.#pending.get(message.id)\n\t\t\tif (pending !== undefined) {\n\t\t\t\tif (message.error !== undefined) {\n\t\t\t\t\tpending.reject(new Error(`MCP error ${message.error.code}: ${message.error.message}`))\n\t\t\t\t} else {\n\t\t\t\t\tpending.resolve(message.result)\n\t\t\t\t}\n\t\t\t\treturn\n\t\t\t}\n\t\t}\n\t\t// Not a correlated response — a server notification (or an unsolicited response).\n\t\tthis.#emitter.emit('notification', message)\n\t}\n\n\t// Wrap one remote tool descriptor as a local tool: map `inputSchema` → `parameters`\n\t// (the inverse of the server's rename, no `as`), carry `description` when present,\n\t// and bind `execute` to a remote `tools/call` via `call`.\n\t#tool(name: string, descriptor: Readonly<Record<string, unknown>>): ToolInterface {\n\t\tconst inputSchema = descriptor['inputSchema']\n\t\tconst description = descriptor['description']\n\t\tconst options: {\n\t\t\tname: string\n\t\t\tdescription?: string\n\t\t\tparameters?: Readonly<Record<string, unknown>>\n\t\t\texecute: (args: Readonly<Record<string, unknown>>) => Promise<unknown>\n\t\t} = {\n\t\t\tname,\n\t\t\texecute: (args) => this.call(name, args),\n\t\t}\n\t\tif (isString(description)) options.description = description\n\t\tif (isRecord(inputSchema)) options.parameters = inputSchema\n\t\treturn new Tool(options)\n\t}\n\n\t// Concatenate an MCP tool-call result's text content blocks into one string — the\n\t// inverse of the server splitting a value into text block(s). Total (§14): a\n\t// non-record result, a non-array `content`, or a non-string `text` contributes\n\t// nothing rather than throwing.\n\t#text(result: unknown): string {\n\t\tif (!isRecord(result) || !isArray(result['content'])) return ''\n\t\tconst parts: string[] = []\n\t\tfor (const block of result['content']) {\n\t\t\tif (isRecord(block) && isString(block['text'])) parts.push(block['text'])\n\t\t}\n\t\treturn parts.join('\\n')\n\t}\n}\n","import type {\n\tClientTransportEventMap,\n\tClientTransportInterface,\n\tJSONRPCMessage,\n\tMCPClientInterface,\n\tMCPClientOptions,\n\tMCPServerInterface,\n\tMCPServerOptions,\n\tMCPTransportInterface,\n} from './types.js'\nimport { Emitter } from '@orkestrel/emitter'\nimport { MCPClient } from './MCPClient.js'\nimport { MCPServer } from './MCPServer.js'\n\n/**\n * Create a transport-agnostic Model Context Protocol server — exposes a live\n * {@link import('@orkestrel/agent').ToolManagerInterface} over JSON-RPC 2.0\n * (`initialize` / `ping` / `tools/list` / `tools/call`).\n *\n * @remarks\n * Pump raw message strings through `handle` (parse → dispatch → serialize) from a\n * transport, or call the typed `dispatch` directly with an already-parsed request.\n * The server is provider-agnostic — JSON-RPC plus the tool registry, with no HTTP\n * and no model. The {@link import('@orkestrel/agent').ToolManagerInterface} already\n * isolates a thrown tool into a result error (surfaced as an MCP `isError: true`\n * tool result), so a misbehaving tool never crashes a dispatch. Subscribe to the\n * `request` event via `server.emitter.on('request', …)` for tracing.\n *\n * @param options - `name` / `version` (the server identity), `tools` (the live\n *   registry to expose), an optional `description`, and the reserved `on`\n *   {@link import('@orkestrel/emitter').EmitterHooks} (see {@link MCPServerOptions})\n * @returns A working {@link MCPServerInterface}\n *\n * @example\n * ```ts\n * import { createMCPServer, createTool, createToolManager } from '@src/core'\n *\n * const tools = createToolManager()\n * tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))\n *\n * const server = createMCPServer({ name: 'calculator', version: '1.0.0', tools })\n * server.emitter.on('request', (method, id) => log(method, id))\n *\n * // A transport pumps message strings through `handle`:\n * const reply = await server.handle('{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}')\n * // reply → '{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"tools\":[{\"name\":\"add\",\"inputSchema\":{\"type\":\"object\"}}]}}'\n * ```\n */\nexport function createMCPServer(options: MCPServerOptions): MCPServerInterface {\n\treturn new MCPServer(options)\n}\n\n/**\n * Create a transport-agnostic Model Context Protocol CLIENT — connects to a REMOTE\n * MCP server over an injected {@link import('./types.js').ClientTransportInterface},\n * runs the `initialize` handshake, and exposes the server's tools as local\n * {@link import('@orkestrel/agent').ToolInterface}s an agent can run.\n *\n * @remarks\n * The egress mirror of {@link createMCPServer}: where the server exposes a local tool\n * registry over MCP, the client USES a remote server's tools. `connect()` handshakes,\n * `tools()` lists + wraps the remote tools (each `execute` calls back over the wire),\n * and `call(name, args)` runs a remote `tools/call` (a remote tool failure throws\n * locally, so an agent's {@link import('@orkestrel/agent').ToolManagerInterface}\n * isolates it). The transport is injected — a concrete one (the HTTP transport over\n * `fetch`) lives in `@src/server`; the client itself is provider-agnostic. Subscribe\n * to `connect` / `disconnect` / `notification` via `client.on(...)` (or\n * `client.emitter.on(...)`).\n *\n * @param options - `transport` (the carrier; REQUIRED), `name` / `version` (the client\n *   identity), `timeout` (the per-request deadline), and the reserved `on`\n *   {@link import('@orkestrel/emitter').EmitterHooks} (see {@link MCPClientOptions})\n * @returns A working {@link MCPClientInterface}\n *\n * @example\n * ```ts\n * import { createMCPClient } from '@src/core'\n * import { createHTTPClientTransport } from '@src/server'\n *\n * const client = createMCPClient({\n * \ttransport: createHTTPClientTransport({ url: 'http://localhost:3000/mcp' }),\n * })\n * await client.connect()\n * agent.context.tools.add(await client.tools()) // give the agent the remote tools\n * const value = await client.call('search', { query: 'mcp' })\n * ```\n */\nexport function createMCPClient(options: MCPClientOptions): MCPClientInterface {\n\treturn new MCPClient(options)\n}\n\n/**\n * Adapt an {@link MCPTransportInterface} (the environment-agnostic duplex message\n * channel) into a {@link ClientTransportInterface} — the additive bridge that lets\n * `createMCPClient` run over the new port without any change to `MCPClient`'s\n * existing shape.\n *\n * @remarks\n * Hand the RESULT to `createMCPClient({ transport })`, then pass the SAME\n * `transport` to {@link import('./helpers.js').bindClient} to complete the inbound\n * wiring: `send` serializes each outbound {@link JSONRPCMessage} (or batch, one per\n * message) and writes it via `transport.send`; `close` closes the underlying\n * `transport`; `start` is a no-op (the duplex channel is already open by the time\n * it is handed in — there is no separate connect step at this layer); `session` is\n * always `undefined` (session correlation is a higher-level concern the duplex port\n * does not carry). Inbound delivery (`emitter`'s `message` / `close` events) is\n * `bindClient`'s job, not this factory's — the returned object exposes a `message`-\n * capable emitter for `bindClient` to push onto.\n *\n * @param transport - The duplex channel to adapt\n * @returns A {@link ClientTransportInterface} `createMCPClient` can drive\n *\n * @example\n * ```ts\n * const client = createMCPClient({ transport: createDuplexClientTransport(transport) })\n * const unbind = bindClient(client, transport)\n * await client.connect()\n * ```\n */\nexport function createDuplexClientTransport(\n\ttransport: MCPTransportInterface,\n): ClientTransportInterface {\n\tconst emitter = new Emitter<ClientTransportEventMap>()\n\treturn {\n\t\temitter,\n\t\tsession: undefined,\n\t\tasync start(): Promise<void> {\n\t\t\t// The duplex channel is already open by the time it is handed in — no separate\n\t\t\t// connect step at this layer.\n\t\t},\n\t\tasync send(message: JSONRPCMessage | readonly JSONRPCMessage[]): Promise<void> {\n\t\t\tconst messages = Array.isArray(message) ? message : [message]\n\t\t\tfor (const one of messages) await transport.send(JSON.stringify(one))\n\t\t},\n\t\tasync close(): Promise<void> {\n\t\t\tawait transport.close()\n\t\t},\n\t}\n}\n"],"mappings":"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"}

package/dist/src/server/index.cjs

@@ -264,6 +264,81 @@ function dispatchLines(emitter, lines) {
 		emitter.emit("message", message);
 	}
 }
+/**
+* Bridge a message-channel {@link ClientTransportInterface} (the shape the stdio and
+* WebSocket SERVER transports already implement) into the environment-agnostic
+* {@link import('@src/core').MCPTransportInterface} port — the adapter
+* {@link import('./factories.js').createStdioServer} and {@link
+* import('./factories.js').createWebSocketServer} pipe through `bindServer`, so the
+* request/reply/error pump those two factories used to hand-roll identically now
+* lives ONCE in the core binder.
+*
+* @remarks
+* `send` decodes the already-serialized reply string back to a {@link JSONRPCMessage}
+* and writes it via `transport.send` (the SAME `JSON.stringify` the underlying
+* transport already performs, so the wire bytes are unchanged). `listen` filters
+* `transport`'s `message` event to REQUESTS ONLY — a stray response is ignored,
+* exactly as the prior hand-rolled pumps did — and re-serializes each one back to a
+* string for `bindServer`. `closed` bridges `transport`'s `close` event. `close`
+* closes the underlying `transport`.
+*
+* @remarks Per {@link import('@src/core').MCPTransportInterface}, `listen`/`closed`
+* each hold THE SINGLE current handler (a second call REPLACES the first, never adds).
+* Since the underlying `transport.emitter` is ADD-based (`on` subscribes, never
+* replaces), this bridge installs ONE stable emitter listener per event on first use
+* and re-routes it to whichever handler is CURRENTLY registered (`undefined` while
+* none is), so rebinding never double-dispatches.
+*
+* @remarks A response whose `result` serializes away (e.g. `undefined`) is dropped by
+* the message validators on the wire's decode side — an asymmetry the stdio/WS carrier
+* shares with the streamable-HTTP face, since both round-trip through `JSON.stringify`
+* / `JSON.parse` before re-validation.
+*
+* @param transport - The message-channel transport to bridge (stdio or WebSocket)
+* @returns An {@link import('@src/core').MCPTransportInterface} `bindServer` can drive
+*
+* @example
+* ```ts
+* import { bindServer } from '@src/core'
+*
+* const transport = new StdioServerTransport(process.stdin, process.stdout)
+* bindServer(mcp, bridgeMessageTransport(transport))
+* ```
+*/
+function bridgeMessageTransport(transport) {
+	let onMessage;
+	let onClosed;
+	let subscribed = false;
+	function subscribe() {
+		if (subscribed) return;
+		subscribed = true;
+		transport.emitter.on("message", (message) => {
+			if (!(0, _src_core.isJSONRPCRequest)(message)) return;
+			onMessage?.(JSON.stringify(message));
+		});
+		transport.emitter.on("close", () => {
+			onClosed?.();
+		});
+	}
+	return {
+		async send(message) {
+			const decoded = decodeEvent(message);
+			if (decoded === void 0) return;
+			await transport.send(decoded);
+		},
+		listen(handler) {
+			subscribe();
+			onMessage = handler;
+		},
+		closed(handler) {
+			subscribe();
+			onClosed = handler;
+		},
+		async close() {
+			await transport.close();
+		}
+	};
+}
 //#endregion
 //#region src/server/transports/HTTPClientTransport.ts
 /**
@@ -1031,12 +1106,13 @@ function createHTTPClientTransport(options) {
 * - **Claims (returns `true`)** otherwise: it builds `createNodeWebSocket({ socket, key, head,
 *   protocol })` (SERVER mode → writes the `101` handshake, echoing the `subprotocol`, default
 *   {@link MCP_WEBSOCKET_SUBPROTOCOL} `'mcp'`, and sends UNMASKED frames), wraps it in a
-*   {@link WebSocketServerTransport}, and PUMPS: each inbound {@link
-*   import('@src/core').JSONRPCMessage} that is a REQUEST runs through `mcp.dispatch`, and a
-*   defined response is written back as a frame — a NOTIFICATION (`dispatch` → `undefined`)
-*   sends nothing. A non-request message (a stray response) is ignored. The dispatch is
-*   guarded so a `dispatch` / `send` fault surfaces on the transport's `error` event rather
-*   than escaping the (async) message listener.
+*   {@link WebSocketServerTransport}, and pipes it through the core {@link
+*   import('@src/core').MCPTransportInterface} port via {@link
+*   import('./helpers.js').bridgeMessageTransport} + {@link import('@src/core').bindServer}:
+*   each inbound REQUEST runs through `mcp.dispatch`, and a defined response is written back
+*   as a frame — a NOTIFICATION sends nothing, and a non-request message (a stray response) is
+*   ignored. A `dispatch` / `send` fault surfaces on `mcp.emitter`'s `error` event rather than
+*   escaping the (async) message pump.
 *
 * It is MECHANISM, not policy: compose an auth guard IN FRONT by registering an upgrade
 * handler BEFORE this one — that handler can claim (decline + destroy) an unauthenticated
@@ -1073,19 +1149,7 @@ function createWebSocketServer(mcp, options) {
 			head,
 			protocol: subprotocol
 		}));
-		transport.emitter.on("message", (message) => {
-			if (!(0, _src_core.isJSONRPCRequest)(message)) return;
-			(async () => {
-				try {
-					const response = await mcp.dispatch(message);
-					if (response !== void 0) await transport.send(response);
-				} catch (error) {
-					try {
-						transport.emitter.emit("error", error);
-					} catch {}
-				}
-			})();
-		});
+		(0, _src_core.bindServer)(mcp, bridgeMessageTransport(transport));
 		transport.start();
 		return true;
 	};
@@ -1167,12 +1231,13 @@ function createStdioClientTransport(options) {
 * @remarks
 * Wraps `options.input` (default `process.stdin`) / `options.output` (default
 * `process.stdout`) in a {@link import('./transports/StdioServerTransport.js').StdioServerTransport}
-* and PUMPS: each inbound {@link import('@src/core').JSONRPCMessage} that is a
-* REQUEST runs through `mcp.dispatch`, and a defined response is written back as a
-* newline-terminated line — a NOTIFICATION (`dispatch` → `undefined`) writes
-* nothing. A non-request message is ignored. The dispatch is guarded so a
-* `dispatch` / `send` fault surfaces on the transport's `error` event rather than
-* escaping the (async) message listener.
+* and pipes it through the core {@link import('@src/core').MCPTransportInterface} port
+* via {@link import('./helpers.js').bridgeMessageTransport} + {@link
+* import('@src/core').bindServer}: each inbound REQUEST runs through `mcp.dispatch`, and
+* a defined response is written back as a newline-terminated line — a NOTIFICATION
+* writes nothing, and a non-request message is ignored. A `dispatch` / `send` fault
+* surfaces on `mcp.emitter`'s `error` event rather than escaping the (async) message
+* pump.
 *
 * @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over stdio
 * @param options - Optional injectable `input` / `output` streams; see
@@ -1190,19 +1255,7 @@ function createStdioClientTransport(options) {
 */
 function createStdioServer(mcp, options) {
 	const transport = new StdioServerTransport(options?.input ?? process.stdin, options?.output ?? process.stdout);
-	transport.emitter.on("message", (message) => {
-		if (!(0, _src_core.isJSONRPCRequest)(message)) return;
-		(async () => {
-			try {
-				const response = await mcp.dispatch(message);
-				if (response !== void 0) await transport.send(response);
-			} catch (error) {
-				try {
-					transport.emitter.emit("error", error);
-				} catch {}
-			}
-		})();
-	});
+	(0, _src_core.bindServer)(mcp, bridgeMessageTransport(transport));
 	return {
 		start() {
 			transport.start();
@@ -1353,6 +1406,7 @@ exports.StdioServerTransport = StdioServerTransport;
 exports.WebSocketClientTransport = WebSocketClientTransport;
 exports.WebSocketServerTransport = WebSocketServerTransport;
 exports.acceptsEventStream = acceptsEventStream;
+exports.bridgeMessageTransport = bridgeMessageTransport;
 exports.createHTTPClientTransport = createHTTPClientTransport;
 exports.createMCPRoutes = createMCPRoutes;
 exports.createMCPSession = createMCPSession;