@yuaone/core 0.1.0

package/dist/mcp-client.js

@@ -0,0 +1,718 @@
+/**
+ * @module mcp-client
+ * @description MCP (Model Context Protocol) Client Bridge
+ *
+ * Connects to external MCP servers (GitHub, Postgres, Slack, etc.) via stdio
+ * transport, discovers their tools, and invokes them. This extends YUAN's
+ * tool ecosystem dynamically at runtime.
+ *
+ * Protocol: JSON-RPC 2.0 over newline-delimited stdio
+ * Spec: https://modelcontextprotocol.io/specification/2024-11-05
+ *
+ * Pure TypeScript — no @modelcontextprotocol/sdk dependency.
+ * Uses only Node.js builtins: child_process, events, readline, crypto.
+ */
+import { spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { createInterface } from "node:readline";
+// ─── Defaults ───
+const DEFAULT_CONFIG = {
+    servers: [],
+    autoConnect: true,
+    toolPrefix: true,
+    maxConcurrentCalls: 5,
+};
+const DEFAULT_TIMEOUT = 30_000;
+const REQUEST_TIMEOUT = 60_000;
+const MCP_PROTOCOL_VERSION = "2024-11-05";
+const CLIENT_INFO = { name: "yuan", version: "0.1.0" };
+// ─── MCPServerConnection (internal) ───
+/**
+ * Manages the lifecycle of a single MCP server process.
+ * Not exported — internal to MCPClient.
+ */
+class MCPServerConnection {
+    process = null;
+    readline = null;
+    state;
+    pendingRequests = new Map();
+    requestIdCounter = 0;
+    config;
+    toolPrefix;
+    constructor(config, toolPrefix) {
+        this.config = config;
+        this.toolPrefix = toolPrefix;
+        this.state = {
+            name: config.name,
+            status: "disconnected",
+            tools: [],
+            callCount: 0,
+        };
+    }
+    /** Current server state (immutable snapshot). */
+    getState() {
+        return { ...this.state, tools: [...this.state.tools] };
+    }
+    /**
+     * Spawn the child process, perform MCP handshake, and discover tools.
+     * @throws {Error} On connection/initialization failure
+     */
+    async connect() {
+        if (this.state.status === "ready")
+            return;
+        this.state.status = "connecting";
+        this.state.error = undefined;
+        const timeout = this.config.timeout ?? DEFAULT_TIMEOUT;
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.killProcess();
+                const err = new Error(`MCP server "${this.config.name}" connection timed out after ${timeout}ms`);
+                this.state.status = "error";
+                this.state.error = err.message;
+                reject(err);
+            }, timeout);
+            try {
+                // Merge env: inherit process.env + server-specific env
+                const env = { ...process.env, ...this.config.env };
+                this.process = spawn(this.config.command, this.config.args, {
+                    stdio: ["pipe", "pipe", "pipe"],
+                    env,
+                    // Don't let the child keep our event loop alive
+                    detached: false,
+                });
+                this.state.pid = this.process.pid;
+                // Handle spawn errors
+                this.process.on("error", (err) => {
+                    clearTimeout(timer);
+                    this.handleProcessError(err);
+                    reject(err);
+                });
+                // Handle unexpected exit during init
+                this.process.on("exit", (code) => {
+                    if (this.state.status === "connecting") {
+                        clearTimeout(timer);
+                        const err = new Error(`MCP server "${this.config.name}" exited during init with code ${code}`);
+                        this.state.status = "error";
+                        this.state.error = err.message;
+                        reject(err);
+                    }
+                    else {
+                        this.handleProcessExit(code ?? 1);
+                    }
+                });
+                // Set up stdout line reader for JSON-RPC messages
+                if (!this.process.stdout) {
+                    clearTimeout(timer);
+                    const err = new Error(`MCP server "${this.config.name}": stdout not available`);
+                    this.state.status = "error";
+                    this.state.error = err.message;
+                    reject(err);
+                    return;
+                }
+                this.readline = createInterface({ input: this.process.stdout });
+                this.readline.on("line", (line) => {
+                    this.handleStdoutLine(line);
+                });
+                // Stderr → log (not part of protocol)
+                if (this.process.stderr) {
+                    this.process.stderr.on("data", (data) => {
+                        // Silently consume stderr; could add debug logging here
+                        void data;
+                    });
+                }
+                // Perform MCP handshake
+                this.initialize()
+                    .then(() => this.listTools())
+                    .then((tools) => {
+                    clearTimeout(timer);
+                    this.state.tools = tools;
+                    this.state.status = "ready";
+                    this.state.lastConnected = Date.now();
+                    resolve();
+                })
+                    .catch((err) => {
+                    clearTimeout(timer);
+                    this.state.status = "error";
+                    this.state.error = err.message;
+                    this.killProcess();
+                    reject(err);
+                });
+            }
+            catch (err) {
+                clearTimeout(timer);
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.state.status = "error";
+                this.state.error = error.message;
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Gracefully disconnect the server.
+     */
+    async disconnect() {
+        this.rejectAllPending(new Error("Disconnecting"));
+        this.killProcess();
+        this.state.status = "disconnected";
+        this.state.pid = undefined;
+        this.state.tools = [];
+    }
+    /**
+     * Invoke a tool on this MCP server.
+     */
+    async callTool(name, args) {
+        if (this.state.status !== "ready") {
+            throw new Error(`MCP server "${this.config.name}" is not ready (status: ${this.state.status})`);
+        }
+        this.state.callCount++;
+        const result = (await this.sendRequest("tools/call", {
+            name,
+            arguments: args,
+        }));
+        return result;
+    }
+    // ─── MCP Protocol Methods ───
+    /**
+     * Send the MCP `initialize` request and the `notifications/initialized` notification.
+     */
+    async initialize() {
+        const result = (await this.sendRequest("initialize", {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: CLIENT_INFO,
+        }));
+        // After successful init, send the initialized notification
+        this.sendNotification("notifications/initialized");
+        void result;
+    }
+    /**
+     * Request the tool list from the server.
+     */
+    async listTools() {
+        const result = (await this.sendRequest("tools/list"));
+        return (result.tools ?? []).map((t) => ({
+            name: t.name,
+            prefixedName: this.toolPrefix
+                ? `${this.config.name}_${t.name}`
+                : t.name,
+            serverName: this.config.name,
+            description: t.description ?? "",
+            inputSchema: t.inputSchema ?? { type: "object", properties: {} },
+        }));
+    }
+    // ─── JSON-RPC Transport ───
+    /**
+     * Send a JSON-RPC request and wait for the response.
+     */
+    sendRequest(method, params) {
+        return new Promise((resolve, reject) => {
+            if (!this.process?.stdin || this.process.stdin.destroyed) {
+                reject(new Error(`MCP server "${this.config.name}": stdin not available`));
+                return;
+            }
+            const id = ++this.requestIdCounter;
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`MCP request "${method}" timed out after ${REQUEST_TIMEOUT}ms`));
+            }, REQUEST_TIMEOUT);
+            this.pendingRequests.set(id, { resolve, reject, timer });
+            const message = {
+                jsonrpc: "2.0",
+                id,
+                method,
+                params,
+            };
+            const line = JSON.stringify(message) + "\n";
+            this.process.stdin.write(line);
+        });
+    }
+    /**
+     * Send a JSON-RPC notification (no response expected).
+     */
+    sendNotification(method, params) {
+        if (!this.process?.stdin || this.process.stdin.destroyed)
+            return;
+        const message = {
+            jsonrpc: "2.0",
+            method,
+            params,
+        };
+        const line = JSON.stringify(message) + "\n";
+        this.process.stdin.write(line);
+    }
+    /**
+     * Handle a single line from stdout (newline-delimited JSON-RPC).
+     */
+    handleStdoutLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let message;
+        try {
+            message = JSON.parse(trimmed);
+        }
+        catch {
+            // Not valid JSON — skip (could be debug output)
+            return;
+        }
+        if (message.jsonrpc !== "2.0")
+            return;
+        this.handleMessage(message);
+    }
+    /**
+     * Route a parsed JSON-RPC message to the appropriate handler.
+     */
+    handleMessage(message) {
+        // Response to a pending request
+        if (message.id !== undefined) {
+            const pending = this.pendingRequests.get(message.id);
+            if (!pending)
+                return; // Orphan response — ignore
+            this.pendingRequests.delete(message.id);
+            clearTimeout(pending.timer);
+            if (message.error) {
+                pending.reject(new Error(`MCP error ${message.error.code}: ${message.error.message}`));
+            }
+            else {
+                pending.resolve(message.result);
+            }
+            return;
+        }
+        // Server-initiated notification — currently ignored
+        // Future: handle tools/list_changed, resources/updated, etc.
+    }
+    /**
+     * Handle child process unexpected exit.
+     */
+    handleProcessExit(code) {
+        this.rejectAllPending(new Error(`MCP server "${this.config.name}" exited with code ${code}`));
+        this.state.status = "crashed";
+        this.state.error = `Process exited with code ${code}`;
+        this.state.pid = undefined;
+        this.process = null;
+        this.readline = null;
+    }
+    /**
+     * Handle child process error event.
+     */
+    handleProcessError(err) {
+        this.rejectAllPending(err);
+        this.state.status = "error";
+        this.state.error = err.message;
+        this.state.pid = undefined;
+        this.process = null;
+        this.readline = null;
+    }
+    /**
+     * Kill the child process if alive.
+     */
+    killProcess() {
+        if (this.readline) {
+            this.readline.close();
+            this.readline = null;
+        }
+        if (this.process) {
+            try {
+                this.process.kill("SIGTERM");
+            }
+            catch {
+                // Already dead
+            }
+            this.process = null;
+        }
+    }
+    /**
+     * Reject all pending requests (used on disconnect/crash).
+     */
+    rejectAllPending(err) {
+        for (const [id, pending] of this.pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(err);
+            this.pendingRequests.delete(id);
+        }
+    }
+}
+// ─── MCPClient (exported) ───
+/**
+ * MCP Client Bridge — connects to external MCP servers, discovers their tools,
+ * and invokes them. Extends YUAN's tool ecosystem dynamically.
+ *
+ * @example
+ * ```ts
+ * const client = new MCPClient({
+ *   servers: [
+ *     {
+ *       name: "github",
+ *       transport: "stdio",
+ *       command: "npx",
+ *       args: ["-y", "@modelcontextprotocol/server-github"],
+ *       env: { GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx" },
+ *     },
+ *   ],
+ * });
+ *
+ * await client.connectAll();
+ * const tools = client.getAvailableTools();
+ * const result = await client.callTool("github_search_repositories", { query: "yuan" });
+ * ```
+ *
+ * @fires MCPClient#server:connected
+ * @fires MCPClient#server:disconnected
+ * @fires MCPClient#server:error
+ * @fires MCPClient#server:crashed
+ * @fires MCPClient#tools:discovered
+ * @fires MCPClient#tool:called
+ * @fires MCPClient#tool:result
+ */
+export class MCPClient extends EventEmitter {
+    config;
+    servers = new Map();
+    allTools = new Map();
+    activeCalls = 0;
+    callQueue = [];
+    constructor(config) {
+        super();
+        this.config = {
+            ...DEFAULT_CONFIG,
+            ...config,
+            servers: config?.servers ? [...config.servers] : [],
+        };
+    }
+    // ─── Lifecycle ───
+    /**
+     * Connect to all configured servers.
+     * @returns Map of server name → state after connection attempt
+     */
+    async connectAll() {
+        const results = new Map();
+        const promises = this.config.servers.map(async (serverConfig) => {
+            try {
+                const state = await this.connect(serverConfig);
+                results.set(serverConfig.name, state);
+            }
+            catch {
+                results.set(serverConfig.name, this.getServerState(serverConfig.name) ?? {
+                    name: serverConfig.name,
+                    status: "error",
+                    tools: [],
+                    error: "Connection failed",
+                    callCount: 0,
+                });
+            }
+        });
+        await Promise.allSettled(promises);
+        return results;
+    }
+    /**
+     * Connect to a single MCP server.
+     * @param serverConfig - Server configuration
+     * @returns Server state after connection
+     */
+    async connect(serverConfig) {
+        // Disconnect existing connection with same name
+        if (this.servers.has(serverConfig.name)) {
+            await this.disconnect(serverConfig.name);
+        }
+        const connection = new MCPServerConnection(serverConfig, this.config.toolPrefix);
+        this.servers.set(serverConfig.name, connection);
+        try {
+            await connection.connect();
+            const state = connection.getState();
+            // Register discovered tools
+            for (const tool of state.tools) {
+                this.allTools.set(tool.prefixedName, tool);
+            }
+            this.emit("server:connected", { name: serverConfig.name, toolCount: state.tools.length });
+            this.emit("tools:discovered", { serverName: serverConfig.name, tools: state.tools });
+            return state;
+        }
+        catch (err) {
+            const state = connection.getState();
+            this.emit("server:error", {
+                name: serverConfig.name,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return state;
+        }
+    }
+    /**
+     * Disconnect a specific server by name.
+     * @param serverName - Server to disconnect
+     */
+    async disconnect(serverName) {
+        const connection = this.servers.get(serverName);
+        if (!connection)
+            return;
+        // Remove this server's tools
+        for (const [key, tool] of this.allTools) {
+            if (tool.serverName === serverName) {
+                this.allTools.delete(key);
+            }
+        }
+        await connection.disconnect();
+        this.servers.delete(serverName);
+        this.emit("server:disconnected", { name: serverName });
+    }
+    /**
+     * Disconnect all servers and clean up.
+     */
+    async disconnectAll() {
+        const names = [...this.servers.keys()];
+        await Promise.allSettled(names.map((name) => this.disconnect(name)));
+        this.allTools.clear();
+        this.callQueue = [];
+        this.activeCalls = 0;
+    }
+    /**
+     * Add a server configuration at runtime (does not auto-connect).
+     * @param config - Server configuration to add
+     */
+    addServer(config) {
+        // Prevent duplicates
+        this.config.servers = this.config.servers.filter((s) => s.name !== config.name);
+        this.config.servers.push(config);
+    }
+    /**
+     * Remove a server configuration and disconnect if connected.
+     * @param name - Server name to remove
+     */
+    removeServer(name) {
+        this.config.servers = this.config.servers.filter((s) => s.name !== name);
+        // Fire-and-forget disconnect
+        void this.disconnect(name);
+    }
+    // ─── Tool Discovery ───
+    /**
+     * Get all available tools from all connected servers.
+     * @returns Array of all discovered MCP tools
+     */
+    getAvailableTools() {
+        return [...this.allTools.values()];
+    }
+    /**
+     * Get tools from a specific server.
+     * @param serverName - Server to get tools from
+     * @returns Array of tools from the specified server
+     */
+    getServerTools(serverName) {
+        return [...this.allTools.values()].filter((t) => t.serverName === serverName);
+    }
+    /**
+     * Find a tool by name (searches both prefixed and original names).
+     * @param name - Tool name to search for
+     * @returns The matching tool, or undefined if not found
+     */
+    findTool(name) {
+        // Direct lookup by prefixed name
+        const direct = this.allTools.get(name);
+        if (direct)
+            return direct;
+        // Search by original name (returns first match)
+        for (const tool of this.allTools.values()) {
+            if (tool.name === name)
+                return tool;
+        }
+        return undefined;
+    }
+    /**
+     * Convert all discovered MCP tools to YUAN ToolDefinition format.
+     * Allows seamless integration with the AgentLoop tool system.
+     * @returns Array of YUAN-compatible tool definitions
+     */
+    toToolDefinitions() {
+        return [...this.allTools.values()].map((tool) => ({
+            name: tool.prefixedName,
+            description: `[MCP:${tool.serverName}] ${tool.description}`,
+            parameters: {
+                type: "object",
+                properties: tool.inputSchema.properties ?? {},
+                required: tool.inputSchema.required ?? [],
+            },
+        }));
+    }
+    // ─── Tool Invocation ───
+    /**
+     * Call a tool on an MCP server.
+     * Respects maxConcurrentCalls — excess calls are queued.
+     *
+     * @param toolName - Tool name (prefixed or original)
+     * @param args - Tool arguments
+     * @returns Tool result
+     * @throws {Error} If tool not found or server not ready
+     */
+    async callTool(toolName, args) {
+        const tool = this.findTool(toolName);
+        if (!tool) {
+            throw new Error(`MCP tool "${toolName}" not found`);
+        }
+        const connection = this.servers.get(tool.serverName);
+        if (!connection) {
+            throw new Error(`MCP server "${tool.serverName}" not connected`);
+        }
+        // Concurrency control
+        await this.acquireCallSlot();
+        this.emit("tool:called", {
+            tool: tool.prefixedName,
+            serverName: tool.serverName,
+            args,
+        });
+        const startTime = Date.now();
+        try {
+            const result = await connection.callTool(tool.name, args);
+            this.emit("tool:result", {
+                tool: tool.prefixedName,
+                serverName: tool.serverName,
+                durationMs: Date.now() - startTime,
+                isError: result.isError ?? false,
+            });
+            return result;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            // Check if server crashed
+            const state = connection.getState();
+            if (state.status === "crashed") {
+                this.emit("server:crashed", { name: tool.serverName, error: error.message });
+                // Auto-restart if configured
+                const serverConfig = this.config.servers.find((s) => s.name === tool.serverName);
+                if (serverConfig?.retryOnCrash !== false) {
+                    void this.reconnectServer(serverConfig);
+                }
+            }
+            throw error;
+        }
+        finally {
+            this.releaseCallSlot();
+        }
+    }
+    /**
+     * Call a tool and convert the result to YUAN's ToolResult format.
+     * Suitable for direct use in the AgentLoop.
+     *
+     * @param toolName - Tool name (prefixed or original)
+     * @param args - Tool arguments
+     * @param callId - Unique call ID for correlation
+     * @returns YUAN-format ToolResult
+     */
+    async callToolAsYuan(toolName, args, callId) {
+        const startTime = Date.now();
+        try {
+            const result = await this.callTool(toolName, args);
+            const output = this.extractTextContent(result);
+            return {
+                tool_call_id: callId,
+                name: toolName,
+                output,
+                success: !result.isError,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        catch (err) {
+            return {
+                tool_call_id: callId,
+                name: toolName,
+                output: `MCP tool error: ${err instanceof Error ? err.message : String(err)}`,
+                success: false,
+                durationMs: Date.now() - startTime,
+            };
+        }
+    }
+    // ─── Status ───
+    /**
+     * Get states of all registered servers.
+     * @returns Array of server states
+     */
+    getServerStates() {
+        return [...this.servers.values()].map((conn) => conn.getState());
+    }
+    /**
+     * Get state of a specific server.
+     * @param name - Server name
+     * @returns Server state or undefined if not registered
+     */
+    getServerState(name) {
+        return this.servers.get(name)?.getState();
+    }
+    /**
+     * Check if any servers are connected and ready.
+     * @returns True if at least one server is in "ready" status
+     */
+    hasConnections() {
+        for (const conn of this.servers.values()) {
+            if (conn.getState().status === "ready")
+                return true;
+        }
+        return false;
+    }
+    // ─── Private Helpers ───
+    /**
+     * Extract text content from an MCP call result.
+     * Concatenates all text blocks, includes base64 image markers, and resource URIs.
+     */
+    extractTextContent(result) {
+        const parts = [];
+        for (const block of result.content) {
+            switch (block.type) {
+                case "text":
+                    if (block.text)
+                        parts.push(block.text);
+                    break;
+                case "image":
+                    parts.push(`[image: ${block.mimeType ?? "unknown"}, ${(block.data?.length ?? 0)} bytes base64]`);
+                    break;
+                case "resource":
+                    if (block.text)
+                        parts.push(block.text);
+                    else
+                        parts.push(`[resource: ${block.mimeType ?? "unknown"}]`);
+                    break;
+            }
+        }
+        return parts.join("\n") || "(empty response)";
+    }
+    /**
+     * Acquire a concurrency slot, or wait in queue.
+     */
+    acquireCallSlot() {
+        if (this.activeCalls < this.config.maxConcurrentCalls) {
+            this.activeCalls++;
+            return Promise.resolve();
+        }
+        // Bound queue size to prevent unbounded memory growth
+        const MAX_QUEUE_SIZE = 100;
+        if (this.callQueue.length >= MAX_QUEUE_SIZE) {
+            return Promise.reject(new Error(`MCP call queue is full (max ${MAX_QUEUE_SIZE}). Try again later.`));
+        }
+        return new Promise((resolve) => {
+            this.callQueue.push(() => {
+                this.activeCalls++;
+                resolve();
+            });
+        });
+    }
+    /**
+     * Release a concurrency slot and dequeue the next waiter.
+     */
+    releaseCallSlot() {
+        this.activeCalls--;
+        const next = this.callQueue.shift();
+        if (next)
+            next();
+    }
+    /**
+     * Attempt to reconnect a crashed server after a brief delay.
+     */
+    async reconnectServer(config) {
+        if (!config)
+            return;
+        // Brief delay before reconnect
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        try {
+            await this.connect(config);
+        }
+        catch {
+            // Reconnect failed — server remains in error/crashed state
+        }
+    }
+}
+//# sourceMappingURL=mcp-client.js.map