@juspay/neurolink 7.13.0 → 7.14.1

package/dist/neurolink.js

@@ -21,7 +21,7 @@ import { toolRegistry } from "./mcp/toolRegistry.js";
 import { logger } from "./utils/logger.js";
 import { getBestProvider } from "./utils/providerUtils.js";
 import { ProviderRegistry } from "./factories/providerRegistry.js";
-import { validateTool, createMCPServerFromTools, } from "./sdk/toolRegistration.js";
+import { createCustomToolServerInfo, detectCategory, } from "./utils/mcpDefaults.js";
 // Factory processing imports
 import { processFactoryOptions, enhanceTextGenerationOptions, validateFactoryConfig, processStreamingFactoryOptions, createCleanStreamOptions, } from "./utils/factoryProcessing.js";
 // Enhanced error handling imports
@@ -29,6 +29,7 @@ import { ErrorFactory, NeuroLinkError, withTimeout, withRetry, isRetriableError,
 import { EventEmitter } from "events";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import { applyConversationMemoryDefaults, getConversationMessages, storeConversationTurn, } from "./utils/conversationMemoryUtils.js";
+import { ExternalServerManager } from "./mcp/externalServerManager.js";
 import { ContextManager } from "./context/ContextManager.js";
 import { defaultContextConfig } from "./context/config.js";
 // Core types imported from core/types.js
@@ -36,9 +37,9 @@ export class NeuroLink {
     mcpInitialized = false;
     emitter = new EventEmitter();
     contextManager = null;
-    // Tool registration support
-    customTools = new Map();
-    inMemoryServers = new Map();
+    autoDiscoveredServerInfos = [];
+    // External MCP server management
+    externalServerManager;
     // Enhanced error handling support
     toolCircuitBreakers = new Map();
     toolExecutionMetrics = new Map();
@@ -73,6 +74,34 @@ export class NeuroLink {
                 maxTurnsPerSession: memoryConfig.maxTurnsPerSession,
             });
         }
+        // Initialize external server manager with main registry integration
+        this.externalServerManager = new ExternalServerManager({
+            maxServers: 20,
+            defaultTimeout: 15000,
+            enableAutoRestart: true,
+            enablePerformanceMonitoring: true,
+        }, {
+            enableMainRegistryIntegration: true, // Enable integration with main toolRegistry
+        });
+        // Forward external server events
+        this.externalServerManager.on("connected", (event) => {
+            this.emitter.emit("externalMCP:serverConnected", event);
+        });
+        this.externalServerManager.on("disconnected", (event) => {
+            this.emitter.emit("externalMCP:serverDisconnected", event);
+        });
+        this.externalServerManager.on("failed", (event) => {
+            this.emitter.emit("externalMCP:serverFailed", event);
+        });
+        this.externalServerManager.on("toolDiscovered", (event) => {
+            this.emitter.emit("externalMCP:toolDiscovered", event);
+            // Tools are already registered on server connection, no need to duplicate here
+        });
+        this.externalServerManager.on("toolRemoved", (event) => {
+            this.emitter.emit("externalMCP:toolRemoved", event);
+            // Unregister removed tools from main tool registry
+            this.unregisterExternalMCPToolFromRegistry(event.toolName);
+        });
     }
     /**
      * Initialize MCP registry with enhanced error handling and resource cleanup
@@ -98,6 +127,26 @@ export class NeuroLink {
             ]);
             // Register all providers with lazy loading support
             await ProviderRegistry.registerAllProviders();
+            // Load MCP configuration from .mcp-config.json using ExternalServerManager
+            try {
+                const configResult = await this.externalServerManager.loadMCPConfiguration();
+                mcpLogger.debug("[NeuroLink] MCP configuration loaded successfully", {
+                    serversLoaded: configResult.serversLoaded,
+                    errors: configResult.errors.length,
+                });
+                if (configResult.errors.length > 0) {
+                    mcpLogger.warn("[NeuroLink] Some MCP servers failed to load", {
+                        errors: configResult.errors,
+                    });
+                }
+            }
+            catch (configError) {
+                mcpLogger.warn("[NeuroLink] MCP configuration loading failed", {
+                    error: configError instanceof Error
+                        ? configError.message
+                        : String(configError),
+                });
+            }
             this.mcpInitialized = true;
             // Monitor memory usage and provide cleanup suggestions
             const endMemory = MemoryManager.getMemoryUsageMB();
@@ -131,7 +180,9 @@ export class NeuroLink {
      * @returns The original prompt text as a string.
      */
     _extractOriginalPrompt(optionsOrPrompt) {
-        return typeof optionsOrPrompt === 'string' ? optionsOrPrompt : optionsOrPrompt.input.text;
+        return typeof optionsOrPrompt === "string"
+            ? optionsOrPrompt
+            : optionsOrPrompt.input.text;
     }
     /**
      * Enables automatic context summarization for the NeuroLink instance.
@@ -321,6 +372,7 @@ export class NeuroLink {
             // Try MCP-enhanced generation first (if not explicitly disabled)
             if (!options.disableTools) {
                 try {
+                    logger.debug(`[${functionTag}] Attempting MCP generation...`);
                     const mcpResult = await this.tryMCPGeneration(options);
                     if (mcpResult && mcpResult.content) {
                         logger.debug(`[${functionTag}] MCP generation successful`);
@@ -328,6 +380,13 @@ export class NeuroLink {
                         await storeConversationTurn(this.conversationMemory, options, mcpResult);
                         return mcpResult;
                     }
+                    else {
+                        logger.debug(`[${functionTag}] MCP generation returned empty result:`, {
+                            hasResult: !!mcpResult,
+                            hasContent: !!(mcpResult && mcpResult.content),
+                            contentLength: mcpResult?.content?.length || 0,
+                        });
+                    }
                 }
                 catch (error) {
                     logger.debug(`[${functionTag}] MCP generation failed, falling back`, {
@@ -367,34 +426,7 @@ export class NeuroLink {
                 ? await getBestProvider()
                 : options.provider;
             // Get available tools
-            let availableTools = [];
-            try {
-                // 1. Get MCP server tools (existing functionality)
-                const mcpTools = await toolRegistry.listTools();
-                const mappedMcpTools = mcpTools.map((tool) => ({
-                    name: tool.name || "Unknown",
-                    description: tool.description || "No description available",
-                    server: tool.serverId || "Unknown", // Fix: use serverId instead of server
-                    category: tool.category,
-                }));
-                // 2. ✅ NEW: Get custom tools from this NeuroLink instance
-                const customTools = Array.from(this.customTools.entries()).map(([name, tool]) => ({
-                    name,
-                    description: tool.description || "Custom tool",
-                    server: "custom",
-                    category: "user-defined",
-                }));
-                // 3. ✅ NEW: Combine all tools for AI generation
-                availableTools = [...mappedMcpTools, ...customTools];
-                logger.debug(`[${functionTag}] Available tools for AI generation:`, {
-                    mcpTools: mappedMcpTools.length,
-                    customTools: customTools.length,
-                    total: availableTools.length,
-                });
-            }
-            catch (error) {
-                mcpLogger.warn(`[${functionTag}] Failed to get tools`, { error });
-            }
+            const availableTools = await this.getAllAvailableTools();
             // Create tool-aware system prompt
             const enhancedSystemPrompt = this.createToolAwareSystemPrompt(options.systemPrompt, availableTools);
             // Get conversation messages for context
@@ -404,7 +436,7 @@ export class NeuroLink {
             this);
             // Enable tool execution for the provider using BaseProvider method
             provider.setupToolExecutor({
-                customTools: this.customTools,
+                customTools: this.getCustomTools(),
                 executeTool: this.executeTool.bind(this),
             }, functionTag);
             const result = await provider.generate({
@@ -417,7 +449,7 @@ export class NeuroLink {
             if (!result || !result.content || result.content.trim().length === 0) {
                 return null; // Let caller fall back to direct generation
             }
-            // Return enhanced result
+            // Return enhanced result with external tool information
             return {
                 content: result.content,
                 provider: providerName,
@@ -432,9 +464,14 @@ export class NeuroLink {
                         success: true, // Assume success if tool executed (AI providers handle failures differently)
                         serverId: teRecord.serverId || undefined,
                     };
-                }) || [], // ✅ NEW: Add missing toolExecutions with proper format
+                }) || [],
                 enhancedWithTools: true,
-                availableTools: availableTools.length > 0 ? availableTools : undefined,
+                availableTools: availableTools.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    server: tool.server,
+                    category: tool.category,
+                })),
                 // Include analytics and evaluation from BaseProvider
                 analytics: result.analytics,
                 evaluation: result.evaluation,
@@ -485,7 +522,7 @@ export class NeuroLink {
                 this);
                 // Enable tool execution for direct provider generation using BaseProvider method
                 provider.setupToolExecutor({
-                    customTools: this.customTools,
+                    customTools: this.getCustomTools(),
                     executeTool: this.executeTool.bind(this),
                 }, functionTag);
                 const result = await provider.generate({
@@ -537,8 +574,23 @@ export class NeuroLink {
             return originalSystemPrompt || "";
         }
         const toolDescriptions = availableTools
-            .map((tool) => `- ${tool.name}: ${tool.description} (from ${tool.server})`)
-            .join("\n");
+            .map((tool) => {
+            const toolWithSchema = tool;
+            const schema = (toolWithSchema.inputSchema ||
+                toolWithSchema.parameters);
+            let params = "";
+            if (schema && schema.properties) {
+                const requiredParams = new Set(schema.required || []);
+                params = Object.entries(schema.properties)
+                    .map(([key, value]) => {
+                    const required = requiredParams.has(key) ? " (required)" : "";
+                    return `  - ${key}: ${value.type}${required}`;
+                })
+                    .join("\n");
+            }
+            return `- ${tool.name}: ${tool.description} (from ${tool.server})\n${params}`;
+        })
+            .join("\n\n");
         const toolPrompt = `\n\nYou have access to these additional tools if needed:\n${toolDescriptions}\n\nIMPORTANT: You are a general-purpose AI assistant. Answer all requests directly and creatively. These tools are optional helpers - use them only when they would genuinely improve your response. For creative tasks like storytelling, writing, or general conversation, respond naturally without requiring tools.`;
         return (originalSystemPrompt || "") + toolPrompt;
     }
@@ -572,7 +624,7 @@ export class NeuroLink {
         for (const result of toolResults) {
             if (result && typeof result === "object") {
                 enhancedPrompt += `\n\nTool Results:\n`;
-                // Handle any structured result generically
+                // Handle structured result generically
                 try {
                     const resultStr = typeof result === "string"
                         ? result
@@ -682,7 +734,7 @@ export class NeuroLink {
             const provider = await AIProviderFactory.createBestProvider(providerName, options.model, true, this);
             // Enable tool execution for streaming using BaseProvider method
             provider.setupToolExecutor({
-                customTools: this.customTools,
+                customTools: this.getCustomTools(),
                 executeTool: this.executeTool.bind(this),
             }, functionTag);
             // Create clean options for provider (remove factoryConfig)
@@ -738,7 +790,7 @@ export class NeuroLink {
             this);
             // Enable tool execution for fallback streaming using BaseProvider method
             provider.setupToolExecutor({
-                customTools: this.customTools,
+                customTools: this.getCustomTools(),
                 executeTool: this.executeTool.bind(this),
             }, functionTag);
             // Create clean options for fallback provider (remove factoryConfig)
@@ -792,7 +844,7 @@ export class NeuroLink {
     /**
      * Register a custom tool that will be available to all AI providers
      * @param name - Unique name for the tool
-     * @param tool - Tool configuration
+     * @param tool - Tool in MCPExecutableTool format (unified MCP protocol type)
      */
     registerTool(name, tool) {
         // Emit tool registration start event
@@ -801,18 +853,10 @@ export class NeuroLink {
             timestamp: Date.now(),
         });
         try {
-            // Validate tool configuration
-            validateTool(name, tool);
-            // Store the tool
-            this.customTools.set(name, tool);
-            // Convert to MCP server format for integration
-            const serverId = `custom-tool-${name}`;
-            const mcpServer = createMCPServerFromTools(serverId, { [name]: tool }, {
-                title: `Custom Tool: ${name}`,
-                category: "custom",
-            });
-            // Store as in-memory server
-            this.inMemoryServers.set(serverId, mcpServer);
+            // SMART DEFAULTS: Use utility to eliminate boilerplate creation
+            const mcpServerInfo = createCustomToolServerInfo(name, tool);
+            // Register with toolRegistry using MCPServerInfo directly
+            toolRegistry.registerServer(mcpServerInfo);
             logger.info(`Registered custom tool: ${name}`);
             // Emit tool registration success event
             this.emitter.emit("tools-register:end", {
@@ -828,10 +872,10 @@ export class NeuroLink {
     }
     /**
      * Register multiple tools at once - Supports both object and array formats
-     * @param tools - Object mapping tool names to configurations OR Array of tools with names
+     * @param tools - Object mapping tool names to MCPExecutableTool format OR Array of tools with names
      *
-     * Object format (existing): { toolName: SimpleTool, ... }
-     * Array format (Lighthouse compatible): [{ name: string, tool: SimpleTool }, ...]
+     * Object format (existing): { toolName: MCPExecutableTool, ... }
+     * Array format (Lighthouse compatible): [{ name: string, tool: MCPExecutableTool }, ...]
      */
     registerTools(tools) {
         if (Array.isArray(tools)) {
@@ -853,40 +897,57 @@ export class NeuroLink {
      * @returns true if the tool was removed, false if it didn't exist
      */
     unregisterTool(name) {
-        const removed = this.customTools.delete(name);
+        const serverId = `custom-tool-${name}`;
+        const removed = toolRegistry.unregisterServer(serverId);
         if (removed) {
-            const serverId = `custom-tool-${name}`;
-            this.inMemoryServers.delete(serverId);
             logger.info(`Unregistered custom tool: ${name}`);
         }
         return removed;
     }
     /**
      * Get all registered custom tools
-     * @returns Map of tool names to configurations
+     * @returns Map of tool names to MCPExecutableTool format
      */
     getCustomTools() {
-        return new Map(this.customTools);
+        // Get tools from toolRegistry with smart category detection
+        const customTools = toolRegistry.getToolsByCategory(detectCategory({ isCustomTool: true }));
+        const toolMap = new Map();
+        for (const tool of customTools) {
+            // Return MCPServerInfo.tools format directly - no conversion needed
+            toolMap.set(tool.name, {
+                name: tool.name,
+                description: tool.description || "",
+                inputSchema: {},
+                execute: async (args, context) => {
+                    // Type guard to ensure context is compatible with ExecutionContext
+                    const executionContext = context && typeof context === "object" && context !== null
+                        ? context
+                        : undefined;
+                    return await toolRegistry.executeTool(tool.name, args, executionContext);
+                },
+            });
+        }
+        return toolMap;
     }
     /**
      * Add an in-memory MCP server (from git diff)
      * Allows registration of pre-instantiated server objects
      * @param serverId - Unique identifier for the server
-     * @param config - Server configuration
+     * @param serverInfo - Server configuration
      */
-    async addInMemoryMCPServer(serverId, config) {
+    async addInMemoryMCPServer(serverId, serverInfo) {
         try {
             mcpLogger.debug(`[NeuroLink] Registering in-memory MCP server: ${serverId}`);
-            // Validate server configuration
-            if (!config.server) {
-                throw new Error(`Server object is required for ${serverId}`);
+            // Initialize tools array if not provided
+            if (!serverInfo.tools) {
+                serverInfo.tools = [];
             }
-            // Store in registry
-            this.inMemoryServers.set(serverId, config);
+            // ZERO CONVERSIONS: Pass MCPServerInfo directly to toolRegistry
+            await toolRegistry.registerServer(serverInfo);
             mcpLogger.info(`[NeuroLink] Successfully registered in-memory server: ${serverId}`, {
-                category: config.category,
-                provider: config.metadata?.provider,
-                version: config.metadata?.version,
+                category: serverInfo.metadata?.category,
+                provider: serverInfo.metadata?.provider,
+                version: serverInfo.metadata?.version,
             });
         }
         catch (error) {
@@ -896,10 +957,41 @@ export class NeuroLink {
     }
     /**
      * Get all registered in-memory servers
-     * @returns Map of server IDs to configurations
+     * @returns Map of server IDs to MCPServerInfo
      */
     getInMemoryServers() {
-        return new Map(this.inMemoryServers);
+        // Get in-memory servers from toolRegistry
+        const serverInfos = toolRegistry.getBuiltInServerInfos();
+        const serverMap = new Map();
+        for (const serverInfo of serverInfos) {
+            if (detectCategory({
+                existingCategory: serverInfo.metadata?.category,
+                serverId: serverInfo.id,
+            }) === "in-memory") {
+                serverMap.set(serverInfo.id, serverInfo);
+            }
+        }
+        return serverMap;
+    }
+    /**
+     * Get in-memory servers as MCPServerInfo - ZERO conversion needed
+     * Now fetches from centralized tool registry instead of local duplication
+     * @returns Array of MCPServerInfo
+     */
+    getInMemoryServerInfos() {
+        // Get in-memory servers from centralized tool registry
+        const allServers = toolRegistry.getBuiltInServerInfos();
+        return allServers.filter((server) => detectCategory({
+            existingCategory: server.metadata?.category,
+            serverId: server.id,
+        }) === "in-memory");
+    }
+    /**
+     * Get auto-discovered servers as MCPServerInfo - ZERO conversion needed
+     * @returns Array of MCPServerInfo
+     */
+    getAutoDiscoveredServerInfos() {
+        return this.autoDiscoveredServerInfos;
     }
     /**
      * Execute a specific tool by name with robust error handling
@@ -912,6 +1004,14 @@ export class NeuroLink {
     async executeTool(toolName, params = {}, options) {
         const functionTag = "NeuroLink.executeTool";
         const executionStartTime = Date.now();
+        // Debug: Log tool execution attempt
+        logger.debug(`[${functionTag}] Tool execution requested:`, {
+            toolName,
+            params: typeof params === "object"
+                ? Object.keys(params).length + " params"
+                : params,
+            hasExternalManager: !!this.externalServerManager,
+        });
         // Emit tool start event
         this.emitter.emit("tool:start", {
             toolName,
@@ -1010,8 +1110,8 @@ export class NeuroLink {
                     structuredError = ErrorFactory.toolTimeout(toolName, finalOptions.timeout);
                 }
                 else if (error.message.includes("not found")) {
-                    const availableTools = Array.from(this.customTools.keys());
-                    structuredError = ErrorFactory.toolNotFound(toolName, availableTools);
+                    const availableTools = await this.getAllAvailableTools();
+                    structuredError = ErrorFactory.toolNotFound(toolName, availableTools.map((t) => t.name));
                 }
                 else if (error.message.includes("validation") ||
                     error.message.includes("parameter")) {
@@ -1053,58 +1153,37 @@ export class NeuroLink {
      */
     async executeToolInternal(toolName, params, options) {
         const functionTag = "NeuroLink.executeToolInternal";
-        // First check custom tools
-        if (this.customTools.has(toolName)) {
-            const tool = this.customTools.get(toolName);
-            // Validate parameters if schema is available
-            if (tool.parameters) {
-                try {
-                    tool.parameters.parse(params);
-                }
-                catch (validationError) {
-                    throw ErrorFactory.invalidParameters(toolName, validationError, params);
-                }
-            }
-            const context = {
-                sessionId: `direct-execution-${Date.now()}`,
-                logger,
-            };
+        // Check external MCP servers
+        const externalTools = this.externalServerManager.getAllTools();
+        const externalTool = externalTools.find((tool) => tool.name === toolName);
+        logger.debug(`[${functionTag}] External MCP tool search:`, {
+            toolName,
+            externalToolsCount: externalTools.length,
+            foundTool: !!externalTool,
+            isAvailable: externalTool?.isAvailable,
+            serverId: externalTool?.serverId,
+        });
+        if (externalTool && externalTool.isAvailable) {
             try {
-                const result = await tool.execute(params, context);
+                mcpLogger.debug(`[${functionTag}] Executing external MCP tool: ${toolName} from ${externalTool.serverId}`);
+                const result = await this.externalServerManager.executeTool(externalTool.serverId, toolName, params, { timeout: options.timeout });
+                logger.debug(`[${functionTag}] External MCP tool execution successful:`, {
+                    toolName,
+                    serverId: externalTool.serverId,
+                    resultType: typeof result,
+                });
                 return result;
             }
             catch (error) {
-                throw ErrorFactory.toolExecutionFailed(toolName, error instanceof Error ? error : new Error(String(error)));
-            }
-        }
-        // Then check in-memory servers
-        for (const [serverId, serverConfig] of this.inMemoryServers.entries()) {
-            const server = serverConfig.server;
-            if (server && server.tools) {
-                const tool = server.tools instanceof Map
-                    ? server.tools.get(toolName)
-                    : server.tools[toolName];
-                if (tool && typeof tool.execute === "function") {
-                    try {
-                        const result = await tool.execute(params);
-                        // Handle MCP-style results
-                        if (result && typeof result === "object" && "success" in result) {
-                            if (result.success) {
-                                return result.data;
-                            }
-                            else {
-                                throw ErrorFactory.toolExecutionFailed(toolName, new Error(result.error || "Tool execution failed"), serverId);
-                            }
-                        }
-                        return result;
-                    }
-                    catch (error) {
-                        throw ErrorFactory.toolExecutionFailed(toolName, error instanceof Error ? error : new Error(String(error)), serverId);
-                    }
-                }
+                logger.error(`[${functionTag}] External MCP tool execution failed:`, {
+                    toolName,
+                    serverId: externalTool.serverId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw ErrorFactory.toolExecutionFailed(toolName, error instanceof Error ? error : new Error(String(error)), externalTool.serverId);
             }
         }
-        // If not found in custom tools or in-memory servers, try unified registry
+        // If not found in custom tools, in-memory servers, or external servers, try unified registry
         try {
             const context = {
                 sessionId: `neurolink-tool-${Date.now()}`,
@@ -1139,42 +1218,71 @@ export class NeuroLink {
                 serverId: tool.serverId === "direct" ? "neurolink-direct" : tool.serverId, // Update serverId for test compatibility
             }));
             // 2. Get custom tools from this NeuroLink instance
-            const customTools = Array.from(this.customTools.entries()).map(([name, tool]) => ({
-                name,
-                toolName: name, // Add toolName property for compatibility with tests
+            const customTools = toolRegistry
+                .getToolsByCategory(detectCategory({ isCustomTool: true }))
+                .map((tool) => ({
+                name: tool.name,
+                toolName: tool.name, // Add toolName property for compatibility with tests
                 description: tool.description || "Custom tool",
-                serverId: `custom-tool-${name}`, // Match the serverId pattern used in registerTool
-                category: "user-defined",
-                inputSchema: {},
+                serverId: tool.serverId || `custom-tool-${tool.name}`,
+                category: detectCategory({
+                    isCustomTool: true,
+                    serverId: tool.serverId,
+                }),
+                inputSchema: tool.inputSchema || {},
             }));
             // 3. Get tools from in-memory MCP servers
-            const inMemoryTools = [];
-            for (const [serverId, serverConfig] of this.inMemoryServers.entries()) {
-                const server = serverConfig.server;
-                if (server && server.tools) {
-                    const tools = server.tools instanceof Map
-                        ? Object.fromEntries(server.tools)
-                        : server.tools;
-                    for (const [toolName, toolDef] of Object.entries(tools)) {
-                        const toolRecord = toolDef;
-                        inMemoryTools.push({
-                            name: toolName,
-                            toolName, // Add toolName property for compatibility with tests
-                            description: toolRecord.description || "In-memory MCP tool",
-                            serverId,
-                            category: serverConfig.category || "mcp-server",
-                            inputSchema: {},
-                        });
-                    }
+            const inMemoryTools = toolRegistry
+                .getToolsByCategory("in-memory")
+                .map((tool) => ({
+                name: tool.name,
+                toolName: tool.name, // Add toolName property for compatibility with tests
+                description: tool.description || "In-memory MCP tool",
+                serverId: tool.serverId || "unknown",
+                category: tool.category || "in-memory",
+                inputSchema: {},
+            }));
+            // 4. Get external MCP tools
+            const externalMCPTools = this.externalServerManager
+                .getAllTools()
+                .map((tool) => ({
+                name: tool.name,
+                toolName: tool.name,
+                description: tool.description,
+                serverId: tool.serverId,
+                category: detectCategory({
+                    existingCategory: typeof tool.metadata?.category === "string"
+                        ? tool.metadata.category
+                        : undefined,
+                    isExternal: true,
+                    serverId: tool.serverId,
+                }),
+                inputSchema: tool.inputSchema || {},
+                isAvailable: tool.isAvailable,
+                stats: tool.stats,
+            }));
+            // 5. Combine all tools with deduplication by name
+            const combinedTools = [
+                ...mcpTools,
+                ...customTools,
+                ...inMemoryTools,
+                ...externalMCPTools,
+            ];
+            const uniqueTools = Array.from(combinedTools
+                .reduce((map, tool) => {
+                const key = tool.name;
+                if (!map.has(key)) {
+                    map.set(key, tool);
                 }
-            }
-            // 4. Combine all tools
-            const allTools = [...mcpTools, ...customTools, ...inMemoryTools];
+                return map;
+            }, new Map())
+                .values());
             mcpLogger.debug("Tool discovery results", {
                 mcpTools: mcpTools.length,
                 customTools: customTools.length,
                 inMemoryTools: inMemoryTools.length,
-                total: allTools.length,
+                externalMCPTools: externalMCPTools.length,
+                total: uniqueTools.length,
             });
             // Check memory usage after tool enumeration
             const endMemory = MemoryManager.getMemoryUsageMB();
@@ -1182,11 +1290,11 @@ export class NeuroLink {
             if (memoryDelta > 10) {
                 mcpLogger.debug(`🔍 Tool listing used ${memoryDelta}MB memory (large tool registry detected)`);
                 // Suggest periodic cleanup for large tool registries
-                if (allTools.length > 100) {
+                if (uniqueTools.length > 100) {
                     mcpLogger.debug("💡 Suggestion: Consider using tool categories or lazy loading for large tool sets");
                 }
             }
-            return allTools;
+            return uniqueTools;
         }
         catch (error) {
             mcpLogger.error("Failed to list available tools", { error });
@@ -1394,17 +1502,39 @@ export class NeuroLink {
      */
     async getMCPStatus() {
         try {
-            // Simplified MCP status - unified registry removed
+            // Initialize MCP if not already initialized (loads external servers from config)
+            await this.initializeMCP();
+            // Get built-in tools
             const allTools = await toolRegistry.listTools();
+            // Get external MCP server statistics
+            const externalStats = this.externalServerManager.getStatistics();
+            // DIRECT RETURNS - ZERO conversion
+            const externalMCPServers = this.externalServerManager.listServers();
+            const inMemoryServerInfos = this.getInMemoryServerInfos();
+            const builtInServerInfos = toolRegistry.getBuiltInServerInfos();
+            const autoDiscoveredServerInfos = this.getAutoDiscoveredServerInfos();
+            // Calculate totals
+            const totalServers = externalMCPServers.length +
+                inMemoryServerInfos.length +
+                builtInServerInfos.length +
+                autoDiscoveredServerInfos.length;
+            const availableServers = externalStats.connectedServers +
+                inMemoryServerInfos.length +
+                builtInServerInfos.length; // in-memory and built-in always available
+            const totalTools = allTools.length + externalStats.totalTools;
             return {
                 mcpInitialized: this.mcpInitialized,
-                totalServers: 1, // Only tool registry now
-                availableServers: 1,
-                autoDiscoveredCount: 0, // No auto-discovery
-                totalTools: allTools.length,
-                autoDiscoveredServers: [], // No auto-discovery
-                customToolsCount: this.customTools.size,
-                inMemoryServersCount: this.inMemoryServers.size,
+                totalServers,
+                availableServers,
+                autoDiscoveredCount: autoDiscoveredServerInfos.length,
+                totalTools,
+                autoDiscoveredServers: autoDiscoveredServerInfos,
+                customToolsCount: toolRegistry.getToolsByCategory(detectCategory({ isCustomTool: true })).length,
+                inMemoryServersCount: inMemoryServerInfos.length,
+                externalMCPServersCount: externalMCPServers.length,
+                externalMCPConnectedCount: externalStats.connectedServers,
+                externalMCPFailedCount: externalStats.failedServers,
+                externalMCPServers,
             };
         }
         catch (error) {
@@ -1415,8 +1545,12 @@ export class NeuroLink {
                 autoDiscoveredCount: 0,
                 totalTools: 0,
                 autoDiscoveredServers: [],
-                customToolsCount: this.customTools.size,
-                inMemoryServersCount: this.inMemoryServers.size,
+                customToolsCount: toolRegistry.getToolsByCategory(detectCategory({ isCustomTool: true })).length,
+                inMemoryServersCount: 0,
+                externalMCPServersCount: 0,
+                externalMCPConnectedCount: 0,
+                externalMCPFailedCount: 0,
+                externalMCPServers: [],
                 error: error instanceof Error ? error.message : String(error),
             };
         }
@@ -1426,8 +1560,13 @@ export class NeuroLink {
      * @returns Promise resolving to array of MCP server information
      */
     async listMCPServers() {
-        // Simplified MCP servers listing - unified registry removed
-        return [];
+        // DIRECT RETURNS - ZERO conversion logic
+        return [
+            ...this.externalServerManager.listServers(), // Direct return
+            ...this.getInMemoryServerInfos(), // Direct return
+            ...toolRegistry.getBuiltInServerInfos(), // Direct return
+            ...this.getAutoDiscoveredServerInfos(), // Direct return
+        ];
     }
     /**
      * Test connectivity to a specific MCP server
@@ -1435,8 +1574,30 @@ export class NeuroLink {
      * @returns Promise resolving to true if server is reachable
      */
     async testMCPServer(serverId) {
-        // Simplified MCP server testing - unified registry removed
-        return false; // No auto-discovery servers available
+        try {
+            // Test built-in tools
+            if (serverId === "neurolink-direct") {
+                const tools = await toolRegistry.listTools();
+                return tools.length > 0;
+            }
+            // Test in-memory servers
+            const inMemoryServers = this.getInMemoryServers();
+            if (inMemoryServers.has(serverId)) {
+                const serverInfo = inMemoryServers.get(serverId);
+                return !!(serverInfo.tools && serverInfo.tools.length > 0);
+            }
+            // Test external MCP servers
+            const externalServer = this.externalServerManager.getServer(serverId);
+            if (externalServer) {
+                return (externalServer.status === "connected" &&
+                    externalServer.client !== null);
+            }
+            return false;
+        }
+        catch (error) {
+            mcpLogger.error(`[NeuroLink] Error testing MCP server ${serverId}:`, error);
+            return false;
+        }
     }
     // ==================== PROVIDER HEALTH CHECKING ====================
     /**
@@ -1589,14 +1750,12 @@ export class NeuroLink {
      * Get comprehensive tool health report
      * @returns Detailed health report for all tools
      */
-    getToolHealthReport() {
+    async getToolHealthReport() {
         const tools = {};
         let healthyCount = 0;
-        // Get all tool names from all sources
-        const allToolNames = new Set([
-            ...this.customTools.keys(),
-            ...Array.from(this.inMemoryServers.values()).flatMap((server) => server.server?.tools ? Object.keys(server.server.tools) : []),
-        ]);
+        // Get all tool names from toolRegistry
+        const allTools = await toolRegistry.listTools();
+        const allToolNames = new Set(allTools.map((tool) => tool.name));
         for (const toolName of allToolNames) {
             const metrics = this.toolExecutionMetrics.get(toolName);
             const circuitBreaker = this.toolCircuitBreakers.get(toolName);
@@ -1678,6 +1837,277 @@ export class NeuroLink {
         }
         await this.conversationMemory.clearAllSessions();
     }
+    // ===== EXTERNAL MCP SERVER METHODS =====
+    /**
+     * Add an external MCP server
+     * Automatically discovers and registers tools from the server
+     * @param serverId - Unique identifier for the server
+     * @param config - External MCP server configuration
+     * @returns Operation result with server instance
+     */
+    async addExternalMCPServer(serverId, config) {
+        try {
+            mcpLogger.info(`[NeuroLink] Adding external MCP server: ${serverId}`, {
+                command: config.command,
+                transport: config.transport,
+            });
+            const result = await this.externalServerManager.addServer(serverId, config);
+            if (result.success) {
+                mcpLogger.info(`[NeuroLink] External MCP server added successfully: ${serverId}`, {
+                    toolsDiscovered: result.metadata?.toolsDiscovered || 0,
+                    duration: result.duration,
+                });
+                // Emit server added event
+                this.emitter.emit("externalMCP:serverAdded", {
+                    serverId,
+                    config,
+                    toolCount: result.metadata?.toolsDiscovered || 0,
+                    timestamp: Date.now(),
+                });
+            }
+            else {
+                mcpLogger.error(`[NeuroLink] Failed to add external MCP server: ${serverId}`, {
+                    error: result.error,
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            mcpLogger.error(`[NeuroLink] Error adding external MCP server: ${serverId}`, error);
+            throw error;
+        }
+    }
+    /**
+     * Remove an external MCP server
+     * Stops the server and removes all its tools
+     * @param serverId - ID of the server to remove
+     * @returns Operation result
+     */
+    async removeExternalMCPServer(serverId) {
+        try {
+            mcpLogger.info(`[NeuroLink] Removing external MCP server: ${serverId}`);
+            const result = await this.externalServerManager.removeServer(serverId);
+            if (result.success) {
+                mcpLogger.info(`[NeuroLink] External MCP server removed successfully: ${serverId}`);
+                // Emit server removed event
+                this.emitter.emit("externalMCP:serverRemoved", {
+                    serverId,
+                    timestamp: Date.now(),
+                });
+            }
+            else {
+                mcpLogger.error(`[NeuroLink] Failed to remove external MCP server: ${serverId}`, {
+                    error: result.error,
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            mcpLogger.error(`[NeuroLink] Error removing external MCP server: ${serverId}`, error);
+            throw error;
+        }
+    }
+    /**
+     * List all external MCP servers
+     * @returns Array of server health information
+     */
+    listExternalMCPServers() {
+        const serverStatuses = this.externalServerManager.getServerStatuses();
+        const allServers = this.externalServerManager.listServers();
+        return serverStatuses.map((health) => {
+            const server = allServers.find((s) => s.id === health.serverId);
+            return {
+                serverId: health.serverId,
+                status: health.status,
+                toolCount: health.toolCount,
+                uptime: health.performance.uptime,
+                isHealthy: health.isHealthy,
+                config: server || {},
+            };
+        });
+    }
+    /**
+     * Get external MCP server status
+     * @param serverId - ID of the server
+     * @returns Server instance or undefined if not found
+     */
+    getExternalMCPServer(serverId) {
+        return this.externalServerManager.getServer(serverId);
+    }
+    /**
+     * Execute a tool from an external MCP server
+     * @param serverId - ID of the server
+     * @param toolName - Name of the tool
+     * @param parameters - Tool parameters
+     * @param options - Execution options
+     * @returns Tool execution result
+     */
+    async executeExternalMCPTool(serverId, toolName, parameters, options) {
+        try {
+            mcpLogger.debug(`[NeuroLink] Executing external MCP tool: ${toolName} on ${serverId}`);
+            const result = await this.externalServerManager.executeTool(serverId, toolName, parameters, options);
+            mcpLogger.debug(`[NeuroLink] External MCP tool executed successfully: ${toolName}`);
+            return result;
+        }
+        catch (error) {
+            mcpLogger.error(`[NeuroLink] External MCP tool execution failed: ${toolName}`, error);
+            throw error;
+        }
+    }
+    /**
+     * Get all tools from external MCP servers
+     * @returns Array of external tool information
+     */
+    getExternalMCPTools() {
+        return this.externalServerManager.getAllTools();
+    }
+    /**
+     * Get tools from a specific external MCP server
+     * @param serverId - ID of the server
+     * @returns Array of tool information for the server
+     */
+    getExternalMCPServerTools(serverId) {
+        return this.externalServerManager.getServerTools(serverId);
+    }
+    /**
+     * Test connection to an external MCP server
+     * @param config - Server configuration to test
+     * @returns Test result with connection status
+     */
+    async testExternalMCPConnection(config) {
+        try {
+            const { MCPClientFactory } = await import("./mcp/mcpClientFactory.js");
+            const testResult = await MCPClientFactory.testConnection(config, 10000);
+            return {
+                success: testResult.success,
+                error: testResult.error,
+                toolCount: testResult.capabilities ? 1 : 0, // Basic indication
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Get external MCP server manager statistics
+     * @returns Statistics about external servers and tools
+     */
+    getExternalMCPStatistics() {
+        return this.externalServerManager.getStatistics();
+    }
+    /**
+     * Shutdown all external MCP servers
+     * Called automatically on process exit
+     */
+    async shutdownExternalMCPServers() {
+        try {
+            mcpLogger.info("[NeuroLink] Shutting down all external MCP servers...");
+            // First, unregister all external MCP tools from the main tool registry
+            this.unregisterAllExternalMCPToolsFromRegistry();
+            // Then shutdown the external server manager
+            await this.externalServerManager.shutdown();
+            mcpLogger.info("[NeuroLink] All external MCP servers shut down successfully");
+        }
+        catch (error) {
+            mcpLogger.error("[NeuroLink] Error shutting down external MCP servers:", error);
+            throw error;
+        }
+    }
+    /**
+     * Convert external MCP tools to Vercel AI SDK tool format
+     * This allows AI providers to use external tools directly
+     */
+    convertExternalMCPToolsToAISDKFormat() {
+        const externalTools = this.externalServerManager.getAllTools();
+        const aiSDKTools = {};
+        for (const tool of externalTools) {
+            if (tool.isAvailable) {
+                // Create tool definition without parameters schema to avoid Zod issues
+                // The AI provider will handle parameters dynamically based on the tool description
+                const toolDefinition = {
+                    description: tool.description,
+                    execute: async (args) => {
+                        try {
+                            mcpLogger.debug(`[NeuroLink] Executing external MCP tool via AI SDK: ${tool.name}`, { args });
+                            const result = await this.externalServerManager.executeTool(tool.serverId, tool.name, args, { timeout: 30000 });
+                            mcpLogger.debug(`[NeuroLink] External MCP tool execution result: ${tool.name}`, {
+                                success: !!result,
+                                hasData: !!(result &&
+                                    typeof result === "object" &&
+                                    "content" in result),
+                            });
+                            return result;
+                        }
+                        catch (error) {
+                            mcpLogger.error(`[NeuroLink] External MCP tool execution failed: ${tool.name}`, error);
+                            throw error;
+                        }
+                    },
+                };
+                // Only add parameters if we have a valid schema - otherwise omit it entirely
+                // This prevents Zod schema parsing errors
+                aiSDKTools[tool.name] = toolDefinition;
+                mcpLogger.debug(`[NeuroLink] Converted external MCP tool to AI SDK format: ${tool.name} from server ${tool.serverId}`);
+            }
+        }
+        mcpLogger.info(`[NeuroLink] Converted ${Object.keys(aiSDKTools).length} external MCP tools to AI SDK format`);
+        return aiSDKTools;
+    }
+    /**
+     * Convert JSON Schema to AI SDK compatible format
+     * For now, we'll skip schema validation and let the AI SDK handle parameters dynamically
+     */
+    convertJSONSchemaToAISDKFormat(inputSchema) {
+        // The simplest approach: don't provide parameters schema
+        // This lets the AI SDK handle the tool without schema validation
+        // Tools will still work, they just won't have strict parameter validation
+        return undefined;
+    }
+    /**
+     * Unregister external MCP tools from a specific server
+     */
+    unregisterExternalMCPToolsFromRegistry(serverId) {
+        try {
+            const externalTools = this.externalServerManager.getServerTools(serverId);
+            for (const tool of externalTools) {
+                toolRegistry.removeTool(tool.name);
+                mcpLogger.debug(`[NeuroLink] Unregistered external MCP tool from main registry: ${tool.name}`);
+            }
+        }
+        catch (error) {
+            mcpLogger.error(`[NeuroLink] Failed to unregister external MCP tools from registry for server ${serverId}:`, error);
+        }
+    }
+    /**
+     * Unregister a specific external MCP tool from the main registry
+     */
+    unregisterExternalMCPToolFromRegistry(toolName) {
+        try {
+            toolRegistry.removeTool(toolName);
+            mcpLogger.debug(`[NeuroLink] Unregistered external MCP tool from main registry: ${toolName}`);
+        }
+        catch (error) {
+            mcpLogger.error(`[NeuroLink] Failed to unregister external MCP tool ${toolName} from registry:`, error);
+        }
+    }
+    /**
+     * Unregister all external MCP tools from the main registry
+     */
+    unregisterAllExternalMCPToolsFromRegistry() {
+        try {
+            const externalTools = this.externalServerManager.getAllTools();
+            for (const tool of externalTools) {
+                toolRegistry.removeTool(tool.name);
+            }
+            mcpLogger.debug(`[NeuroLink] Unregistered ${externalTools.length} external MCP tools from main registry`);
+        }
+        catch (error) {
+            mcpLogger.error("[NeuroLink] Failed to unregister all external MCP tools from registry:", error);
+        }
+    }
 }
 // Create default instance
 export const neurolink = new NeuroLink();