@dexto/core 1.1.9 → 1.1.11

package/dist/mcp/manager.d.ts

@@ -1,70 +1,92 @@
 import { ValidatedServerConfigs, ValidatedMcpServerConfig } from './schemas.js';
-import { IMCPClient } from './types.js';
-import { ToolSet } from '../tools/types.js';
 import { GetPromptResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
-import 'zod';
-import '@modelcontextprotocol/sdk/client/index.js';
-import 'json-schema';
-
-/**
- * Centralized manager for Multiple Model Context Protocol (MCP) servers.
- *
- * The MCPManager serves as a focused interface for managing connections to MCP servers
- * and providing access to their capabilities (tools, prompts, resources).
- *
- * Key responsibilities:
- * - **Client Management**: Register, connect, disconnect, and remove MCP clients
- * - **Resource Discovery**: Cache and provide access to tools, prompts, and resources from connected clients
- * - **MCP Tool Execution**: Execute MCP tools with built-in confirmation mechanisms
- * - **Connection Handling**: Support both strict and lenient connection modes with error tracking
- * - **Caching**: Maintain efficient lookup maps for fast access to client capabilities
- *
- * The manager supports dynamic client connections, allowing servers to be added or removed at runtime.
- * It includes robust error handling and maintains connection state for debugging purposes.
- *
- * Note: This class focuses only on MCP server management. For unified tool management
- * across multiple sources (MCP + custom tools), use the ToolManager class.
- *
- * @example
- * ```typescript
- * const manager = new MCPManager();
- * await manager.initializeFromConfig(serverConfigs);
- *
- * // Execute an MCP tool
- * const result = await manager.executeTool('my_tool', { param: 'value' });
- *
- * // Get all available MCP tools
- * const tools = await manager.getAllTools();
- * ```
- */
-declare class MCPManager {
+import { IMCPClient, MCPResolvedResource } from './types.js';
+import { ToolSet } from '../tools/types.js';
+import type { PromptDefinition } from '../prompts/types.js';
+import type { ApprovalManager } from '../approval/manager.js';
+export declare class MCPManager {
     private clients;
     private connectionErrors;
-    private toolToClientMap;
-    private serverToolsMap;
+    private toolCache;
     private toolConflicts;
-    private promptToClientMap;
-    private resourceToClientMap;
+    private promptCache;
+    private resourceCache;
     private sanitizedNameToServerMap;
+    private approvalManager;
     private static readonly SERVER_DELIMITER;
     constructor();
+    /**
+     * Set the approval manager for handling elicitation requests from MCP servers
+     *
+     * TODO: Consider making ApprovalManager a required constructor parameter instead of using a setter.
+     * This would make the dependency explicit and remove the need for defensive `if (!approvalManager)` checks.
+     * Current setter pattern is useful if we want to expose MCPManager as a standalone service to end-users
+     * without requiring them to know about ApprovalManager.
+     */
+    setApprovalManager(approvalManager: ApprovalManager): void;
+    private buildQualifiedResourceKey;
+    private parseQualifiedResourceKey;
+    private removeServerResources;
+    private getResourceCacheEntry;
     /**
      * Register a client that provides tools (and potentially more)
      * @param name Unique name for the client
      * @param client The client instance, expected to be IMCPClient
      */
     registerClient(name: string, client: IMCPClient): void;
+    /**
+     * Clears all cached data for a disconnected MCP client
+     *
+     * Performs comprehensive cleanup of tool, prompt, and resource caches.
+     * Uses two-pass algorithm to detect and resolve tool name conflicts:
+     * if a conflicted tool now has only one provider, restores simple name.
+     *
+     * @param clientName - The name/identifier of the MCP server being removed
+     * @private
+     */
     private clearClientCache;
-    private rebuildToolConflicts;
     /**
      * Sanitize server name for use in tool prefixing.
      * Ensures the name is safe for LLM provider tool naming constraints.
      */
     private sanitizeServerName;
+    /**
+     * Updates internal caches for a connected MCP client
+     *
+     * This method performs initial cache population after a client connects.
+     * It fetches and caches tools, prompts, and resources from the MCP server,
+     * implementing conflict detection and resolution for tool names.
+     *
+     * @param clientName - The name/identifier of the MCP server
+     * @param client - The connected MCP client instance
+     *
+     * @remarks
+     * **Tool Caching:**
+     * - Fetches all tools and caches them with full definitions
+     * - Detects naming conflicts when multiple servers provide same tool name
+     * - On conflict: uses qualified names (`server--toolname`) for all conflicting tools
+     * - Updates toolConflicts set to track which base names have conflicts
+     *
+     * **Prompt Caching:**
+     * - Fetches all prompts and their metadata (description, arguments)
+     * - Stores full prompt definitions in promptCache for efficient access
+     * - Falls back to minimal metadata if full definition fetch fails
+     *
+     * **Resource Caching:**
+     * - Fetches all resource summaries (uri, name, mimeType)
+     * - Stores resource metadata in resourceCache for quick lookups
+     *
+     * **Error Handling:**
+     * - Tool fetch errors abort caching entirely (early return)
+     * - Prompt/resource errors log warnings but don't block other caching
+     * - Individual prompt metadata errors are caught and logged
+     *
+     * @private
+     */
     private updateClientCache;
     /**
-     * Get all available MCP tools from all connected clients, updating the cache.
-     * Conflicted tools are prefixed with server name using distinctive delimiter.
+     * Get all available MCP tools from cache (no network calls).
+     * Conflicted tools are already stored with qualified names.
      * @returns Promise resolving to a ToolSet mapping tool names to Tool definitions
      */
     getAllTools(): Promise<ToolSet>;
@@ -105,24 +127,40 @@ declare class MCPManager {
      * @param args Arguments for the prompt (optional).
      * @returns Promise resolving to the prompt definition.
      */
-    getPrompt(name: string, args?: any): Promise<GetPromptResult>;
+    getPrompt(name: string, args?: Record<string, unknown>): Promise<GetPromptResult>;
     /**
-     * Get all available resource URIs from all connected clients, updating the cache.
-     * @returns Promise resolving to an array of unique resource URIs.
+     * Get cached prompt metadata (no network calls).
+     * @param promptName Name of the prompt.
+     * @returns Cached prompt definition or undefined if not cached.
      */
-    listAllResources(): Promise<string[]>;
+    getPromptMetadata(promptName: string): PromptDefinition | undefined;
     /**
-     * Get the client that provides a specific resource from the cache.
-     * @param resourceUri URI of the resource.
-     * @returns The client instance or undefined.
+     * Get all cached prompt metadata (no network calls).
+     * @returns Array of all cached prompt definitions with server info.
+     */
+    getAllPromptMetadata(): Array<{
+        promptName: string;
+        serverName: string;
+        definition: PromptDefinition;
+    }>;
+    /**
+     * Get all cached MCP resources (no network calls).
+     */
+    listAllResources(): Promise<MCPResolvedResource[]>;
+    /**
+     * Determine if a qualified MCP resource is cached.
+     */
+    hasResource(resourceKey: string): boolean;
+    /**
+     * Get cached resource metadata by qualified key.
      */
-    getResourceClient(resourceUri: string): IMCPClient | undefined;
+    getResource(resourceKey: string): MCPResolvedResource | undefined;
     /**
-     * Read a specific resource by URI.
-     * @param uri URI of the resource.
+     * Read a specific resource by qualified URI.
+     * @param resourceKey Qualified resource key in the form mcp:server:uri.
      * @returns Promise resolving to the resource content.
      */
-    readResource(uri: string): Promise<ReadResourceResult>;
+    readResource(resourceKey: string): Promise<ReadResourceResult>;
     /**
      * Initialize clients from server configurations
      * @param serverConfigs Server configurations with individual connection modes
@@ -149,6 +187,12 @@ declare class MCPManager {
     getFailedConnections(): {
         [key: string]: string;
     };
+    /**
+     * Refresh all client caches by re-fetching capabilities from servers
+     * Useful when you want to force a full refresh of tools, prompts, and resources
+     * In normal operation, caches are automatically kept fresh via server notifications
+     */
+    refresh(): Promise<void>;
     /**
      * Disconnect and remove a specific client by name.
      * @param name The name of the client to remove.
@@ -158,6 +202,21 @@ declare class MCPManager {
      * Disconnect all clients and clear caches
      */
     disconnectAll(): Promise<void>;
+    /**
+     * Set up notification listeners for a specific client
+     */
+    private setupClientNotifications;
+    /**
+     * Handle resource updated notification
+     */
+    private handleResourceUpdated;
+    /**
+     * Handle prompts list changed notification
+     */
+    private handlePromptsListChanged;
+    /**
+     * Handle tools list changed notification
+     */
+    private handleToolsListChanged;
 }
-
-export { MCPManager };
+//# sourceMappingURL=manager.d.ts.map

package/dist/mcp/manager.d.ts.map

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