attocode 0.2.4 → 0.2.5

package/dist/src/integrations/mcp/mcp-client.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Lesson 25: MCP Client
+ *
+ * Connects to Model Context Protocol (MCP) servers to extend agent capabilities.
+ * Supports stdio-based servers (spawned as child processes).
+ */
+import type { ToolDefinition } from '../../types.js';
+import type { DeadLetterQueue } from '../quality/dead-letter-queue.js';
+/**
+ * MCP server configuration.
+ */
+export interface MCPServerConfig {
+    /** Command to run */
+    command: string;
+    /** Command arguments */
+    args?: string[];
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Working directory */
+    cwd?: string;
+}
+/**
+ * Lightweight tool summary - always in context (low token cost).
+ * ~50 tokens per tool vs ~200-500 tokens for full definitions.
+ */
+export interface MCPToolSummary {
+    /** Full tool name (e.g., "mcp_playwright_browser_click") */
+    name: string;
+    /** Truncated description */
+    description: string;
+    /** Server name (e.g., "playwright") */
+    serverName: string;
+    /** Original MCP tool name (e.g., "browser_click") */
+    originalName: string;
+}
+/**
+ * MCP config file structure.
+ */
+export interface MCPConfigFile {
+    servers: Record<string, MCPServerConfig>;
+}
+/**
+ * MCP tool definition from server.
+ */
+interface MCPToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema?: {
+        type: string;
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * MCP client configuration.
+ */
+export interface MCPClientConfig {
+    /** Config file path (default: .mcp.json in cwd) */
+    configPath?: string;
+    /**
+     * Multiple config paths loaded in order (later overrides earlier).
+     * Example: ['/path/to/global.mcp.json', './.mcp.json']
+     * If provided, takes precedence over configPath.
+     */
+    configPaths?: string[];
+    /** Timeout for requests in ms (default: 30000) */
+    requestTimeout?: number;
+    /** Auto-connect on load (default: true) */
+    autoConnect?: boolean;
+    /** Enable lazy loading of tool schemas (default: false) */
+    lazyLoading?: boolean;
+    /** Tools to always load fully (bypass lazy loading) */
+    alwaysLoadTools?: string[];
+    /** Max chars for summary descriptions (default: 100) */
+    summaryDescriptionLimit?: number;
+    /** Max results per search query (default: 5) */
+    maxToolsPerSearch?: number;
+}
+/**
+ * Context statistics for MCP tools.
+ */
+export interface MCPContextStats {
+    /** Estimated tokens for tool summaries */
+    summaryTokens: number;
+    /** Estimated tokens for loaded full definitions */
+    definitionTokens: number;
+    /** Number of tools as summaries only */
+    summaryCount: number;
+    /** Number of fully loaded tools */
+    loadedCount: number;
+    /** Total tools available */
+    totalTools: number;
+}
+/**
+ * Server info for display.
+ */
+export interface MCPServerInfo {
+    name: string;
+    status: 'disconnected' | 'connecting' | 'connected' | 'error';
+    toolCount: number;
+    error?: string;
+}
+/**
+ * MCP events.
+ */
+export type MCPEvent = {
+    type: 'server.connecting';
+    name: string;
+} | {
+    type: 'server.connected';
+    name: string;
+    toolCount: number;
+} | {
+    type: 'server.disconnected';
+    name: string;
+} | {
+    type: 'server.error';
+    name: string;
+    error: string;
+} | {
+    type: 'tool.call';
+    server: string;
+    tool: string;
+} | {
+    type: 'tool.result';
+    server: string;
+    tool: string;
+    success: boolean;
+} | {
+    type: 'tool.dynamicLoad';
+    name: string;
+    serverName: string;
+} | {
+    type: 'tool.search';
+    query: string;
+    resultCount: number;
+};
+export type MCPEventListener = (event: MCPEvent) => void;
+/**
+ * MCP Client manages connections to MCP servers.
+ */
+export declare class MCPClient {
+    private config;
+    private servers;
+    private listeners;
+    private dlq;
+    private sessionId?;
+    constructor(config?: MCPClientConfig);
+    /**
+     * Load servers from config file.
+     */
+    loadFromConfig(configPath?: string): Promise<void>;
+    /**
+     * Load servers from multiple config files (hierarchical).
+     * Later configs override earlier ones for the same server name.
+     * Servers from all configs are merged together.
+     */
+    loadFromHierarchicalConfigs(configPaths: string[]): Promise<void>;
+    /**
+     * Expand environment variables in config.
+     */
+    private expandEnvVars;
+    /**
+     * Register a server (without connecting).
+     */
+    registerServer(name: string, config: MCPServerConfig): void;
+    /**
+     * Connect to a registered server.
+     */
+    connectServer(name: string): Promise<void>;
+    /**
+     * Initialize MCP protocol with server.
+     */
+    private initializeServer;
+    /**
+     * Send a JSON-RPC request and wait for response.
+     */
+    private sendRequest;
+    /**
+     * Send a JSON-RPC notification (no response expected).
+     */
+    private sendNotification;
+    /**
+     * Handle incoming message from server.
+     */
+    private handleServerMessage;
+    /**
+     * Disconnect from a server.
+     */
+    disconnectServer(name: string): Promise<void>;
+    /**
+     * Call a tool on a specific server.
+     * Includes automatic retry for transient failures (timeouts, connection resets).
+     */
+    callTool(serverName: string, toolName: string, args: unknown): Promise<unknown>;
+    /**
+     * List all servers and their status.
+     */
+    listServers(): MCPServerInfo[];
+    /**
+     * Get tools from a specific server.
+     */
+    getServerTools(serverName: string): MCPToolDefinition[];
+    /**
+     * Get lightweight summaries for all tools (low token cost).
+     * Use this for initial context, then load full definitions on-demand.
+     */
+    getAllToolSummaries(): MCPToolSummary[];
+    /**
+     * Search tools by name or description with BM25-style scoring.
+     * Returns matching tool summaries sorted by relevance.
+     */
+    searchTools(query: string, options?: {
+        limit?: number;
+        regex?: boolean;
+    }): MCPToolSummary[];
+    /**
+     * Get full tool definition for a specific tool.
+     * Marks the tool as loaded for context tracking.
+     */
+    getFullToolDefinition(toolName: string): ToolDefinition | null;
+    /**
+     * Batch load multiple tools by name.
+     * Returns array of loaded ToolDefinitions.
+     */
+    loadTools(toolNames: string[]): ToolDefinition[];
+    /**
+     * Get context statistics for MCP tools.
+     * Useful for monitoring token usage with lazy loading.
+     */
+    getContextStats(): MCPContextStats;
+    /**
+     * Check if a tool is fully loaded (has schema in context).
+     */
+    isToolLoaded(toolName: string): boolean;
+    /**
+     * Get all tools with lazy loading support.
+     * When lazyMode is true, only returns always-loaded tools + previously loaded tools.
+     * When lazyMode is false (default), returns all tools with full definitions.
+     */
+    getAllTools(options?: {
+        lazyMode?: boolean;
+    }): ToolDefinition[];
+    /**
+     * Check if a server is connected.
+     */
+    isConnected(serverName: string): boolean;
+    /**
+     * Subscribe to events.
+     */
+    on(listener: MCPEventListener): () => void;
+    /**
+     * Set the dead letter queue for failed operation tracking.
+     * When set, permanent failures will be logged to the DLQ for later retry.
+     */
+    setDeadLetterQueue(dlq: DeadLetterQueue | null, sessionId?: string): void;
+    /**
+     * Emit an event.
+     */
+    private emit;
+    /**
+     * Cleanup - disconnect all servers.
+     */
+    cleanup(): Promise<void>;
+}
+/**
+ * Create and initialize an MCP client.
+ */
+export declare function createMCPClient(config?: MCPClientConfig): Promise<MCPClient>;
+/**
+ * Format server list for display.
+ */
+export declare function formatServerList(servers: MCPServerInfo[]): string;
+/**
+ * Create a sample .mcp.json config file content.
+ */
+export declare function getSampleMCPConfig(): string;
+export {};
+//# sourceMappingURL=mcp-client.d.ts.map

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

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