@1mcp/agent 0.29.2 → 0.30.0-beta1

package/build/core/capabilities/metaToolProvider.js

@@ -0,0 +1,374 @@
+import { ConnectionResolver } from '../../core/server/connectionResolver.js';
+import logger, { debugIf, errorIf } from '../../logger/logger.js';
+import { zodToInputSchema, zodToOutputSchema } from '../../utils/schemaUtils.js';
+import { ToolInvokeInputSchema, ToolInvokeOutputSchema, ToolListInputSchema, ToolListOutputSchema, ToolSchemaInputSchema, ToolSchemaOutputSchema, } from './schemas/metaToolSchemas.js';
+/**
+ * MetaToolProvider provides meta-tools for lazy loading:
+ * 1. tool_list - List all tools (names + descriptions only)
+ * 2. tool_schema - Get full tool schema on-demand
+ * 3. tool_invoke - Invoke any tool by server and name
+ *
+ * @example
+ * ```typescript
+ * const provider = new MetaToolProvider(() => toolRegistry, schemaCache, outboundConnections, loadSchemaFn);
+ * const tools = provider.getMetaTools();
+ * const result = await provider.callMetaTool('tool_list', { server: 'filesystem' });
+ * ```
+ */
+export class MetaToolProvider {
+    getToolRegistry;
+    schemaCache;
+    outboundConnections;
+    loadSchema;
+    allowedServers;
+    connectionResolver;
+    constructor(getToolRegistry, schemaCache, outboundConnections, loadSchema, allowedServers, templateHashProvider) {
+        this.getToolRegistry = getToolRegistry;
+        this.schemaCache = schemaCache;
+        this.outboundConnections = outboundConnections;
+        this.loadSchema = loadSchema;
+        this.allowedServers = allowedServers;
+        this.connectionResolver = new ConnectionResolver(outboundConnections, templateHashProvider);
+    }
+    /**
+     * Resolve a clean server name to the actual connection key.
+     * Delegates to ConnectionResolver.findByServerName for unified resolution logic.
+     *
+     * @param cleanServerName - The clean server name (without hash suffix)
+     * @returns The actual connection key, or the original name if not found
+     */
+    resolveConnectionKey(cleanServerName) {
+        const result = this.connectionResolver.findByServerName(cleanServerName);
+        return result?.key ?? cleanServerName;
+    }
+    /**
+     * Set the allowed servers filter
+     * @param serverNames - Set of server names to allow, or undefined to allow all
+     */
+    setAllowedServers(serverNames) {
+        this.allowedServers = serverNames;
+    }
+    /**
+     * Get the current tool registry, optionally filtered by allowed servers
+     */
+    toolRegistry() {
+        const registry = this.getToolRegistry();
+        if (this.allowedServers !== undefined) {
+            return registry.filterByServers(this.allowedServers);
+        }
+        return registry;
+    }
+    /**
+     * Get all available meta-tools (3 discovery tools)
+     */
+    getMetaTools() {
+        return [this.createListToolsMetaTool(), this.createDescribeToolMetaTool(), this.createCallToolMetaTool()];
+    }
+    /**
+     * Call a meta-tool by name
+     */
+    async callMetaTool(name, args) {
+        switch (name) {
+            case 'tool_list': {
+                const parsed = ToolListInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        tools: [],
+                        totalCount: 0,
+                        servers: [],
+                        hasMore: false,
+                        error: {
+                            type: 'validation',
+                            message: `Invalid arguments for tool_list: ${parsed.error.message}`,
+                        },
+                    };
+                }
+                return this.listAvailableTools(parsed.data);
+            }
+            case 'tool_schema': {
+                const parsed = ToolSchemaInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        schema: {},
+                        error: {
+                            type: 'validation',
+                            message: `Invalid arguments for tool_schema: ${parsed.error.message}`,
+                        },
+                    };
+                }
+                return this.describeTool(parsed.data);
+            }
+            case 'tool_invoke': {
+                const parsed = ToolInvokeInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        result: {},
+                        server: '',
+                        tool: '',
+                        error: {
+                            type: 'validation',
+                            message: `Invalid arguments for tool_invoke: ${parsed.error.message}`,
+                        },
+                    };
+                }
+                return this.callTool(parsed.data);
+            }
+            default:
+                return {
+                    tools: [],
+                    totalCount: 0,
+                    servers: [],
+                    hasMore: false,
+                    error: {
+                        type: 'not_found',
+                        message: `Unknown meta-tool: ${name}. Valid meta-tools are: tool_list, tool_schema, tool_invoke`,
+                    },
+                };
+        }
+    }
+    /**
+     * Create the tool_list meta-tool
+     */
+    createListToolsMetaTool() {
+        return {
+            name: 'tool_list',
+            description: 'List all available MCP tools with names and descriptions. Use for tool discovery.',
+            inputSchema: zodToInputSchema(ToolListInputSchema),
+            outputSchema: zodToOutputSchema(ToolListOutputSchema),
+        };
+    }
+    /**
+     * Implement tool_list
+     */
+    async listAvailableTools(args) {
+        try {
+            const registry = this.toolRegistry();
+            const result = registry.listTools(args);
+            // Format tools for response
+            const tools = result.tools.map((tool) => ({
+                name: tool.name,
+                server: tool.server,
+                description: tool.description,
+                tags: tool.tags,
+            }));
+            // Get unique servers from filtered results to keep output consistent with applied filters
+            const servers = Array.from(new Set(result.tools.map((t) => t.server))).sort();
+            // Return structured result matching outputSchema
+            const response = {
+                tools,
+                totalCount: result.totalCount,
+                servers,
+                hasMore: result.hasMore,
+                ...(result.nextCursor ? { nextCursor: result.nextCursor } : {}),
+            };
+            return response;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            errorIf(() => ({
+                message: 'Error in tool_list meta-tool',
+                meta: { args, error: errorMessage },
+            }));
+            return {
+                tools: [],
+                totalCount: 0,
+                servers: [],
+                hasMore: false,
+                error: {
+                    type: 'internal',
+                    message: `Internal error listing tools: ${errorMessage}`,
+                },
+            };
+        }
+    }
+    /**
+     * Create the tool_schema meta-tool
+     */
+    createDescribeToolMetaTool() {
+        return {
+            name: 'tool_schema',
+            description: 'Get the full schema for a specific tool including input validation rules',
+            inputSchema: zodToInputSchema(ToolSchemaInputSchema),
+            outputSchema: zodToOutputSchema(ToolSchemaOutputSchema),
+        };
+    }
+    /**
+     * Implement tool_schema
+     */
+    async describeTool(args) {
+        try {
+            // Validate arguments
+            if (!args.server || !args.toolName) {
+                return {
+                    schema: {},
+                    error: {
+                        type: 'validation',
+                        message: 'Validation Error: "server" and "toolName" are required parameters',
+                    },
+                };
+            }
+            // Check if tool exists in registry
+            if (!this.toolRegistry().hasTool(args.server, args.toolName)) {
+                return {
+                    schema: {},
+                    error: {
+                        type: 'not_found',
+                        message: `Tool not found: ${args.server}:${args.toolName}. Call tool_list to see available tools.`,
+                    },
+                };
+            }
+            // Try to get from cache first
+            const cached = this.schemaCache.getIfCached(args.server, args.toolName);
+            if (cached) {
+                debugIf(() => ({ message: `Cache hit for tool schema: ${args.server}:${args.toolName}` }));
+                return {
+                    schema: cached,
+                    fromCache: true,
+                };
+            }
+            // Not in cache - load from server if SchemaLoader is available
+            if (this.loadSchema) {
+                try {
+                    debugIf(() => ({ message: `Loading schema from server: ${args.server}:${args.toolName}` }));
+                    // Resolve the clean server name to the actual connection key
+                    const connectionKey = this.resolveConnectionKey(args.server);
+                    const tool = await this.loadSchema(connectionKey, args.toolName);
+                    // Cache the loaded schema
+                    await this.schemaCache.preload([{ server: args.server, toolName: args.toolName }], async (s, t) => {
+                        if (s === args.server && t === args.toolName) {
+                            return tool;
+                        }
+                        throw new Error('Unexpected preload request');
+                    });
+                    return {
+                        schema: tool,
+                        fromCache: false,
+                    };
+                }
+                catch (loadError) {
+                    return {
+                        schema: {},
+                        error: {
+                            type: 'upstream',
+                            message: `Failed to load schema from server: ${loadError}`,
+                        },
+                    };
+                }
+            }
+            // No SchemaLoader available - return error
+            return {
+                schema: {},
+                error: {
+                    type: 'internal',
+                    message: 'Tool schema not loaded and no SchemaLoader available. Please use the tool invocation flow to load schema on first use.',
+                },
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            errorIf(() => ({
+                message: 'Error in tool_schema meta-tool',
+                meta: { server: args.server, toolName: args.toolName, error: errorMessage },
+            }));
+            return {
+                schema: {},
+                error: {
+                    type: 'internal',
+                    message: `Internal error describing tool: ${errorMessage}`,
+                },
+            };
+        }
+    }
+    /**
+     * Create the tool_invoke meta-tool
+     */
+    createCallToolMetaTool() {
+        return {
+            name: 'tool_invoke',
+            description: 'Execute any tool on any MCP server with proper argument validation',
+            inputSchema: zodToInputSchema(ToolInvokeInputSchema),
+            outputSchema: zodToOutputSchema(ToolInvokeOutputSchema),
+        };
+    }
+    /**
+     * Implement tool_invoke
+     */
+    async callTool(args) {
+        try {
+            // Validate arguments
+            if (!args.server || !args.toolName) {
+                return {
+                    result: {},
+                    server: args.server,
+                    tool: args.toolName,
+                    error: {
+                        type: 'validation',
+                        message: 'Validation Error: "server" and "toolName" are required parameters',
+                    },
+                };
+            }
+            // Check if tool exists
+            if (!this.toolRegistry().hasTool(args.server, args.toolName)) {
+                return {
+                    result: {},
+                    server: args.server,
+                    tool: args.toolName,
+                    error: {
+                        type: 'not_found',
+                        message: `Tool not found: ${args.server}:${args.toolName}. Call tool_list to see available tools.`,
+                    },
+                };
+            }
+            // Get connection - resolve clean server name to actual connection key
+            const connectionKey = this.resolveConnectionKey(args.server);
+            const connection = this.outboundConnections.get(connectionKey);
+            if (!connection || !connection.client) {
+                return {
+                    result: {},
+                    server: args.server,
+                    tool: args.toolName,
+                    error: {
+                        type: 'upstream',
+                        message: `Server not connected: ${args.server}`,
+                    },
+                };
+            }
+            // Call the tool
+            const upstreamResult = await connection.client.callTool({
+                name: args.toolName,
+                arguments: args.args,
+            });
+            // Return structured result matching outputSchema
+            return {
+                result: upstreamResult,
+                server: args.server,
+                tool: args.toolName,
+            };
+        }
+        catch (error) {
+            logger.error(`Error in tool_invoke: ${error}`);
+            // Check if it's a tool not found error from upstream
+            if (error instanceof Error && error.message.includes('not found')) {
+                return {
+                    result: {},
+                    server: args.server,
+                    tool: args.toolName,
+                    error: {
+                        type: 'not_found',
+                        message: `Tool not found: ${args.server}:${args.toolName}`,
+                    },
+                };
+            }
+            return {
+                result: {},
+                server: args.server,
+                tool: args.toolName,
+                error: {
+                    type: 'upstream',
+                    message: `Server Error: ${error}. This is an upstream server issue - please report it.`,
+                },
+            };
+        }
+    }
+}
+//# sourceMappingURL=metaToolProvider.js.map

package/build/core/capabilities/metaToolProvider.js.map

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

package/build/core/capabilities/schemaCache.d.ts

@@ -0,0 +1,124 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Statistics for schema cache operations
+ */
+export interface SchemaCacheStats {
+    hits: number;
+    misses: number;
+    coalesced: number;
+    evictions: number;
+    get hitRate(): number;
+}
+/**
+ * Configuration for SchemaCache
+ */
+export interface SchemaCacheConfig {
+    maxEntries: number;
+    ttlMs?: number;
+}
+/**
+ * SchemaCache provides LRU caching for tool schemas with optional TTL and request coalescing.
+ *
+ * This cache reduces redundant upstream server calls by storing loaded tool schemas
+ * and coalescing parallel requests for the same tool.
+ *
+ * @example
+ * ```typescript
+ * const cache = new SchemaCache({ maxEntries: 1000, ttlMs: 3600000 });
+ *
+ * // Load tool schema (with coalescing for parallel calls)
+ * const tool = await cache.getOrLoad('filesystem', 'read_file', async () => {
+ *   return await fetchSchemaFromServer('filesystem', 'read_file');
+ * });
+ * ```
+ */
+export declare class SchemaCache {
+    private cache;
+    private inflightRequests;
+    private config;
+    private stats;
+    constructor(config: SchemaCacheConfig);
+    /**
+     * Generate cache key from server and tool name
+     */
+    private getCacheKey;
+    /**
+     * Check if a cache entry has expired (TTL)
+     */
+    private isExpired;
+    /**
+     * Evict oldest entry when cache is full (FIFO eviction by insertion time)
+     * Note: This is not true LRU - for that we'd need to track access order
+     */
+    private evictOldest;
+    /**
+     * Get tool schema from cache or load it using the provided loader function
+     * Implements request coalescing for parallel requests to the same tool
+     *
+     * @param server - Server name
+     * @param toolName - Tool name
+     * @param loader - Async function to load the tool schema from upstream server
+     * @returns Promise resolving to the Tool schema
+     */
+    getOrLoad(server: string, toolName: string, loader: (server: string, toolName: string) => Promise<Tool>): Promise<Tool>;
+    /**
+     * Check if a tool schema is currently cached (and not expired)
+     */
+    has(server: string, toolName: string): boolean;
+    /**
+     * Get cached tool schema without loading (returns null if not cached)
+     */
+    getIfCached(server: string, toolName: string): Tool | null;
+    /**
+     * Manually add a tool schema to the cache
+     */
+    set(server: string, toolName: string, tool: Tool): void;
+    /**
+     * Remove a tool schema from the cache
+     */
+    delete(server: string, toolName: string): boolean;
+    /**
+     * Clear all cached schemas
+     */
+    clear(): void;
+    /**
+     * Get current cache statistics
+     */
+    getStats(): Readonly<SchemaCacheStats>;
+    /**
+     * Get current cache size
+     */
+    size(): number;
+    /**
+     * Get all cached tool identifiers
+     */
+    getCachedTools(): Array<{
+        server: string;
+        toolName: string;
+    }>;
+    /**
+     * Reset statistics counters
+     */
+    resetStats(): void;
+    /**
+     * Log current cache statistics (for monitoring and observability)
+     * @param forceLog - Force logging even if debug mode is off
+     */
+    logStats(forceLog?: boolean): void;
+    /**
+     * Preload tool schemas in batch
+     * @returns Object with loaded count and array of failures
+     */
+    preload(tools: Array<{
+        server: string;
+        toolName: string;
+    }>, loader: (server: string, toolName: string) => Promise<Tool>): Promise<{
+        loaded: number;
+        failed: Array<{
+            server: string;
+            toolName: string;
+            error: string;
+        }>;
+    }>;
+}
+//# sourceMappingURL=schemaCache.d.ts.map

package/build/core/capabilities/schemaCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaCache.d.ts","sourceRoot":"","sources":["../../../src/core/capabilities/schemaCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAI1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,OAAO,IAAI,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAUD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,gBAAgB,CAAyC;IACjE,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,KAAK,CASX;gBAEU,MAAM,EAAE,iBAAiB;IAIrC;;OAEG;IACH,OAAO,CAAC,WAAW;IAInB;;OAEG;IACH,OAAO,CAAC,SAAS;IASjB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAkBnB;;;;;;;;OAQG;IACU,SAAS,CACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAC1D,OAAO,CAAC,IAAI,CAAC;IAmDhB;;OAEG;IACI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAMrD;;OAEG;IACI,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAgBjE;;OAEG;IACI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI;IAe9D;;OAEG;IACI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKxD;;OAEG;IACI,KAAK,IAAI,IAAI;IAOpB;;OAEG;IACI,QAAQ,IAAI,QAAQ,CAAC,gBAAgB,CAAC;IAI7C;;OAEG;IACI,IAAI,IAAI,MAAM;IAIrB;;OAEG;IACI,cAAc,IAAI,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAiBpE;;OAEG;IACI,UAAU,IAAI,IAAI;IAOzB;;;OAGG;IACI,QAAQ,CAAC,QAAQ,UAAQ,GAAG,IAAI;IAWvC;;;OAGG;IACU,OAAO,CAClB,KAAK,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,EAClD,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAC1D,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;CA0BnG"}