@yuaone/core 0.1.0

package/dist/mcp-client.d.ts

@@ -0,0 +1,232 @@
+/**
+ * @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 { EventEmitter } from "node:events";
+import type { ToolDefinition, ToolResult } from "./types.js";
+/** Configuration for a single MCP server connection. */
+export interface MCPServerConfig {
+    /** Unique server name (e.g., "github", "postgres", "slack") */
+    name: string;
+    /** Transport type — only "stdio" supported currently */
+    transport: "stdio";
+    /** Command to spawn (e.g., "npx", "node") */
+    command: string;
+    /** Arguments for the command (e.g., ["-y", "@modelcontextprotocol/server-github"]) */
+    args: string[];
+    /** Additional environment variables for the child process */
+    env?: Record<string, string>;
+    /** Connection timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Auto-restart on crash (default: true) */
+    retryOnCrash?: boolean;
+}
+/** Top-level MCP client configuration. */
+export interface MCPClientConfig {
+    /** Server configurations */
+    servers: MCPServerConfig[];
+    /** Connect all servers on init (default: true) */
+    autoConnect: boolean;
+    /** Prefix tool names with server name, e.g., "github_search_repos" (default: true) */
+    toolPrefix: boolean;
+    /** Max parallel tool calls across all servers (default: 5) */
+    maxConcurrentCalls: number;
+}
+/** A tool discovered from an MCP server. */
+export interface MCPTool {
+    /** Original tool name from the server */
+    name: string;
+    /** Prefixed name: "serverName_toolName" */
+    prefixedName: string;
+    /** Which server this tool belongs to */
+    serverName: string;
+    /** Human-readable description */
+    description: string;
+    /** JSON Schema for the tool's input */
+    inputSchema: Record<string, unknown>;
+}
+/** Result of an MCP tool invocation. */
+export interface MCPCallResult {
+    /** Content blocks returned by the tool */
+    content: Array<{
+        type: "text" | "image" | "resource";
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    /** Whether the tool returned an error */
+    isError?: boolean;
+}
+/** Observable state of a single MCP server. */
+export interface MCPServerState {
+    /** Server name */
+    name: string;
+    /** Connection status */
+    status: "disconnected" | "connecting" | "ready" | "error" | "crashed";
+    /** Discovered tools */
+    tools: MCPTool[];
+    /** Child process PID */
+    pid?: number;
+    /** Error message if status is "error" or "crashed" */
+    error?: string;
+    /** Epoch ms of last successful connection */
+    lastConnected?: number;
+    /** Total tool calls made on this server */
+    callCount: number;
+}
+/**
+ * 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 declare class MCPClient extends EventEmitter {
+    private config;
+    private servers;
+    private allTools;
+    private activeCalls;
+    private callQueue;
+    constructor(config?: Partial<MCPClientConfig>);
+    /**
+     * Connect to all configured servers.
+     * @returns Map of server name → state after connection attempt
+     */
+    connectAll(): Promise<Map<string, MCPServerState>>;
+    /**
+     * Connect to a single MCP server.
+     * @param serverConfig - Server configuration
+     * @returns Server state after connection
+     */
+    connect(serverConfig: MCPServerConfig): Promise<MCPServerState>;
+    /**
+     * Disconnect a specific server by name.
+     * @param serverName - Server to disconnect
+     */
+    disconnect(serverName: string): Promise<void>;
+    /**
+     * Disconnect all servers and clean up.
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * Add a server configuration at runtime (does not auto-connect).
+     * @param config - Server configuration to add
+     */
+    addServer(config: MCPServerConfig): void;
+    /**
+     * Remove a server configuration and disconnect if connected.
+     * @param name - Server name to remove
+     */
+    removeServer(name: string): void;
+    /**
+     * Get all available tools from all connected servers.
+     * @returns Array of all discovered MCP tools
+     */
+    getAvailableTools(): MCPTool[];
+    /**
+     * Get tools from a specific server.
+     * @param serverName - Server to get tools from
+     * @returns Array of tools from the specified server
+     */
+    getServerTools(serverName: string): MCPTool[];
+    /**
+     * 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: string): MCPTool | 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(): ToolDefinition[];
+    /**
+     * 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
+     */
+    callTool(toolName: string, args: Record<string, unknown>): Promise<MCPCallResult>;
+    /**
+     * 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
+     */
+    callToolAsYuan(toolName: string, args: Record<string, unknown>, callId: string): Promise<ToolResult>;
+    /**
+     * Get states of all registered servers.
+     * @returns Array of server states
+     */
+    getServerStates(): MCPServerState[];
+    /**
+     * Get state of a specific server.
+     * @param name - Server name
+     * @returns Server state or undefined if not registered
+     */
+    getServerState(name: string): MCPServerState | undefined;
+    /**
+     * Check if any servers are connected and ready.
+     * @returns True if at least one server is in "ready" status
+     */
+    hasConnections(): boolean;
+    /**
+     * Extract text content from an MCP call result.
+     * Concatenates all text blocks, includes base64 image markers, and resource URIs.
+     */
+    private extractTextContent;
+    /**
+     * Acquire a concurrency slot, or wait in queue.
+     */
+    private acquireCallSlot;
+    /**
+     * Release a concurrency slot and dequeue the next waiter.
+     */
+    private releaseCallSlot;
+    /**
+     * Attempt to reconnect a crashed server after a brief delay.
+     */
+    private reconnectServer;
+}
+//# sourceMappingURL=mcp-client.d.ts.map

package/dist/mcp-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.d.ts","sourceRoot":"","sources":["../src/mcp-client.ts"],"names":[],"mappings":"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"}