@juspay/neurolink 4.1.0 → 4.2.0

package/dist/mcp/unified-registry.js

@@ -8,6 +8,8 @@ import { MCPToolRegistry, } from "./tool-registry.js";
 import { TransportManager, TransportConfigSchema, } from "./transport-manager.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { ErrorManager } from "./error-manager.js";
+import * as fs from "fs";
+import * as path from "path";
 /**
  * Unified registry combining multiple sources
  */
@@ -25,10 +27,12 @@ export class UnifiedMCPRegistry extends MCPToolRegistry {
         this.transportManager = new TransportManager(this.errorManager);
     }
     /**
-     * Initialize with auto-discovery
+     * Initialize with auto-discovery and manual config
      */
     async initialize(options = {}) {
         unifiedRegistryLogger.info("Initializing unified MCP registry...");
+        // Load manual configuration first
+        await this.loadManualConfig();
         if (this.autoDiscoveryEnabled) {
             const result = await autoRegisterMCPServers(options);
             unifiedRegistryLogger.info(`Auto-discovery complete: ${result.registered} registered, ${result.failed} failed`);
@@ -40,6 +44,58 @@ export class UnifiedMCPRegistry extends MCPToolRegistry {
             }
         }
     }
+    /**
+     * Load servers from .mcp-config.json
+     */
+    async loadManualConfig() {
+        const configPath = path.join(process.cwd(), ".mcp-config.json");
+        try {
+            await fs.promises.access(configPath, fs.constants.F_OK);
+        }
+        catch {
+            unifiedRegistryLogger.debug("No .mcp-config.json found");
+            return;
+        }
+        try {
+            const configContent = await fs.promises.readFile(configPath, "utf-8");
+            const config = JSON.parse(configContent);
+            if (!config.mcpServers) {
+                unifiedRegistryLogger.debug("No mcpServers section in config");
+                return;
+            }
+            unifiedRegistryLogger.info(`Loading ${Object.keys(config.mcpServers).length} servers from .mcp-config.json`);
+            for (const [serverId, serverConfig] of Object.entries(config.mcpServers)) {
+                try {
+                    // Convert server config to DiscoveredMCP format
+                    const discoveredMcp = {
+                        metadata: {
+                            name: serverId,
+                            version: "1.0.0",
+                            main: "index.js",
+                            engine: { neurolink: ">=4.0.0" },
+                            description: `MCP server: ${serverId}`,
+                            permissions: ["filesystem", "network"],
+                        },
+                        entryPath: serverConfig.command || "npx",
+                        source: "project",
+                        constructor: undefined,
+                    };
+                    // Register the server
+                    this.register(discoveredMcp);
+                    this.manualServers.set(serverId, serverConfig);
+                    this.availableServers.add(serverId);
+                    unifiedRegistryLogger.debug(`Registered manual server: ${serverId}`);
+                }
+                catch (error) {
+                    unifiedRegistryLogger.error(`Failed to register server ${serverId}:`, error instanceof Error ? error.message : String(error));
+                }
+            }
+            unifiedRegistryLogger.info(`Manual config loaded: ${this.manualServers.size} servers registered`);
+        }
+        catch (error) {
+            unifiedRegistryLogger.error("Failed to load manual config:", error instanceof Error ? error.message : String(error));
+        }
+    }
     /**
      * Enable or disable auto-discovery
      */
@@ -85,30 +141,136 @@ export class UnifiedMCPRegistry extends MCPToolRegistry {
      */
     async listAllTools() {
         const allTools = [];
-        const plugins = this.list();
+        try {
+            // FIXED: Get built-in tools from base registry
+            const builtInTools = await super.listTools();
+            allTools.push(...builtInTools.map((tool) => ({
+                ...tool,
+                id: tool.name,
+                serverId: tool.serverId || "built-in",
+                source: "built-in",
+                isExternal: false,
+            })));
+            unifiedRegistryLogger.debug(`Found ${builtInTools.length} built-in tools`);
+        }
+        catch (error) {
+            unifiedRegistryLogger.warn("Failed to get built-in tools:", error);
+        }
+        // FIXED: Get tools from external servers with proper error handling
+        // Use the internal plugin registry for accurate server listing
+        const plugins = Array.from(this.plugins.values());
+        const externalToolPromises = [];
         for (const plugin of plugins) {
-            try {
-                // Get tools from plugin metadata if available
-                const tools = await this.listTools();
-                allTools.push(...tools.map((tool) => ({
-                    ...tool,
-                    id: tool.name,
-                    serverId: tool.serverId || plugin.metadata.name,
-                    source: "unified",
-                })));
-            }
-            catch (error) {
-                unifiedRegistryLogger.warn(`Failed to get tools from ${plugin.metadata.name}:`, error);
+            if (plugin.metadata?.name &&
+                this.availableServers.has(plugin.metadata.name)) {
+                const connection = this.activeConnections.get(plugin.metadata.name);
+                if (connection) {
+                    externalToolPromises.push(connection
+                        .listTools()
+                        .then((response) => {
+                        const serverTools = response.tools || [];
+                        allTools.push(...serverTools.map((tool) => ({
+                            name: tool.name,
+                            description: tool.description,
+                            inputSchema: tool.inputSchema,
+                            serverId: plugin.metadata.name,
+                            id: `${plugin.metadata.name}.${tool.name}`,
+                            source: "external",
+                            isExternal: true,
+                        })));
+                        unifiedRegistryLogger.debug(`Found ${serverTools.length} tools from ${plugin.metadata.name}`);
+                    })
+                        .catch((error) => {
+                        unifiedRegistryLogger.warn(`Failed to get tools from ${plugin.metadata.name}:`, error);
+                    }));
+                }
             }
         }
+        await Promise.all(externalToolPromises);
+        unifiedRegistryLogger.info(`Total tools available: ${allTools.length}`);
         return allTools;
     }
     /**
-     * Execute a tool through the registry
+     * Execute a tool through the registry with fallback to direct MCP execution
      */
     async executeTool(toolName, args, context) {
         unifiedRegistryLogger.info(`Executing tool: ${toolName}`);
-        return super.executeTool(toolName, args, context);
+        // STEP 1: Try built-in tools first
+        try {
+            const result = await super.executeTool(toolName, args, context);
+            unifiedRegistryLogger.info(`Tool ${toolName} executed successfully via built-in registry`);
+            return result;
+        }
+        catch (builtInError) {
+            unifiedRegistryLogger.debug(`Built-in tool execution failed: ${builtInError.message}`);
+        }
+        // STEP 2: Try external MCP servers
+        try {
+            const result = await this.executeToolViaMCPServer(toolName, args, context);
+            unifiedRegistryLogger.info(`Tool ${toolName} executed successfully via external MCP server`);
+            return result;
+        }
+        catch (externalError) {
+            unifiedRegistryLogger.debug(`External MCP execution failed: ${externalError.message}`);
+        }
+        // STEP 3: Comprehensive error with available tools
+        const availableTools = await this.listAllTools();
+        const toolNames = availableTools.map((t) => t.name).join(", ");
+        const builtInTools = availableTools
+            .filter((t) => !t.isExternal)
+            .map((t) => t.name)
+            .join(", ");
+        const externalTools = availableTools
+            .filter((t) => t.isExternal)
+            .map((t) => `${t.serverId}.${t.name}`)
+            .join(", ");
+        const errorMessage = [
+            `Tool '${toolName}' not found in any registry.`,
+            `Available built-in tools: ${builtInTools || "none"}`,
+            `Available external tools: ${externalTools || "none"}`,
+            `Connected servers: ${Array.from(this.availableServers).join(", ") || "none"}`,
+        ].join("\n");
+        throw new Error(errorMessage);
+    }
+    /**
+     * Execute tool via direct MCP server connection (fallback)
+     */
+    async executeToolViaMCPServer(toolName, args, context) {
+        const configPath = path.join(process.cwd(), ".mcp-config.json");
+        if (!fs.existsSync(configPath)) {
+            throw new Error(`Tool '${toolName}' not found and no .mcp-config.json for fallback`);
+        }
+        const configContent = fs.readFileSync(configPath, "utf-8");
+        const config = JSON.parse(configContent);
+        if (!config.mcpServers) {
+            throw new Error(`Tool '${toolName}' not found and no servers configured`);
+        }
+        // Try each configured server
+        const errors = [];
+        for (const [serverId, serverConfig] of Object.entries(config.mcpServers)) {
+            try {
+                unifiedRegistryLogger.debug(`Trying tool ${toolName} on server ${serverId}`);
+                // Import the executeMCPTool function
+                const { executeMCPTool } = await import("../../cli/commands/mcp.js");
+                const result = await executeMCPTool(serverConfig, toolName, args || {});
+                // Convert to ToolResult format
+                const toolResult = {
+                    success: true,
+                    data: result,
+                    metadata: { toolName, serverId, sessionId: context?.sessionId },
+                };
+                unifiedRegistryLogger.info(`Tool ${toolName} executed successfully via server ${serverId}`);
+                return toolResult;
+            }
+            catch (serverError) {
+                const errorMsg = serverError instanceof Error
+                    ? serverError.message
+                    : String(serverError);
+                errors.push(`${serverId}: ${errorMsg}`);
+                unifiedRegistryLogger.debug(`Tool ${toolName} failed on server ${serverId}: ${errorMsg}`);
+            }
+        }
+        throw new Error(`Tool '${toolName}' not found on any configured MCP server. Errors: ${errors.join("; ")}`);
     }
     /**
      * Lazily activate a server by ID
@@ -144,7 +306,7 @@ export class UnifiedMCPRegistry extends MCPToolRegistry {
      * Get registry statistics (override parent method)
      */
     getStats() {
-        // Return execution stats in the expected format
+        // Return full stats interface as expected by MCPOrchestrator
         return super.getStats();
     }
     /**

package/dist/neurolink.js

@@ -73,6 +73,12 @@ export class NeuroLink {
      * Tools are ENABLED BY DEFAULT for natural AI behavior
      */
     async generateText(options) {
+        // 🔧 FIX: Add input validation
+        if (!options ||
+            typeof options.prompt !== "string" ||
+            options.prompt.trim() === "") {
+            throw new Error("options.prompt is required and must be a non-empty string");
+        }
         // Tools are DEFAULT behavior unless explicitly disabled
         if (options.disableTools === true) {
             return this.generateTextRegular(options);
@@ -101,7 +107,7 @@ export class NeuroLink {
         try {
             mcpLogger.debug(`[${functionTag}] Starting MCP-enabled generation`, {
                 provider: providerName,
-                prompt: options.prompt.substring(0, 100) + "...",
+                prompt: (options.prompt?.substring(0, 100) || "No prompt") + "...",
                 contextId: context.sessionId,
             });
             // Get available tools from tool registry (simplified approach)
@@ -205,22 +211,15 @@ export class NeuroLink {
             "ollama",
         ];
         const requestedProvider = options.provider === "auto" ? undefined : options.provider;
-        // Local providers that should not fall back when explicitly requested
-        const localProviders = ["ollama"];
-        // If specific provider requested, check if we should allow fallback
+        // If specific provider requested, only use that provider (no fallback)
         const tryProviders = requestedProvider
-            ? localProviders.includes(requestedProvider)
-                ? [requestedProvider] // No fallback for local providers
-                : [
-                    requestedProvider,
-                    ...providerPriority.filter((p) => p !== requestedProvider),
-                ]
+            ? [requestedProvider] // Only use the requested provider, no fallback
             : providerPriority;
         logger.debug(`[${functionTag}] Starting text generation`, {
             requestedProvider: requestedProvider || "auto",
             tryProviders,
-            allowFallback: !requestedProvider || !localProviders.includes(requestedProvider),
-            promptLength: options.prompt.length,
+            allowFallback: !requestedProvider,
+            promptLength: options.prompt?.length || 0,
         });
         let lastError = null;
         for (const providerName of tryProviders) {
@@ -228,7 +227,7 @@ export class NeuroLink {
                 logger.debug(`[${functionTag}] Attempting provider`, {
                     provider: providerName,
                 });
-                const provider = await AIProviderFactory.createProvider(providerName, options.model);
+                const provider = await AIProviderFactory.createProvider(providerName, options.model, false);
                 const result = await provider.generateText({
                     prompt: options.prompt,
                     model: options.model,
@@ -343,21 +342,14 @@ Note: Tool integration is currently in development. Please provide helpful respo
             "ollama",
         ];
         const requestedProvider = options.provider === "auto" ? undefined : options.provider;
-        // Local providers that should not fall back when explicitly requested
-        const localProviders = ["ollama"];
-        // If specific provider requested, check if we should allow fallback
+        // If specific provider requested, only use that provider (no fallback)
         const tryProviders = requestedProvider
-            ? localProviders.includes(requestedProvider)
-                ? [requestedProvider] // No fallback for local providers
-                : [
-                    requestedProvider,
-                    ...providerPriority.filter((p) => p !== requestedProvider),
-                ]
+            ? [requestedProvider] // Only use the requested provider, no fallback
             : providerPriority;
         logger.debug(`[${functionTag}] Starting stream generation`, {
             requestedProvider: requestedProvider || "auto",
             tryProviders,
-            allowFallback: !requestedProvider || !localProviders.includes(requestedProvider),
+            allowFallback: !requestedProvider,
             promptLength: options.prompt.length,
         });
         let lastError = null;
@@ -366,7 +358,7 @@ Note: Tool integration is currently in development. Please provide helpful respo
                 logger.debug(`[${functionTag}] Attempting provider`, {
                     provider: providerName,
                 });
-                const provider = await AIProviderFactory.createProvider(providerName, options.model);
+                const provider = await AIProviderFactory.createProvider(providerName, options.model, false);
                 const result = await provider.streamText({
                     prompt: options.prompt,
                     model: options.model,
@@ -430,7 +422,7 @@ Note: Tool integration is currently in development. Please provide helpful respo
      */
     async testProvider(providerName, testPrompt = "test") {
         try {
-            const provider = await AIProviderFactory.createProvider(providerName);
+            const provider = await AIProviderFactory.createProvider(providerName, null, false); // Disable MCP for simple testing
             await provider.generateText({
                 prompt: testPrompt,
                 enableAnalytics: false,

package/dist/providers/googleVertexAI.js

@@ -35,7 +35,25 @@ const DEFAULT_SYSTEM_CONTEXT = {
 const getGCPVertexBreezeProjectId = () => {
     const projectId = process.env.GOOGLE_VERTEX_PROJECT;
     if (!projectId) {
-        throw new Error("GOOGLE_VERTEX_PROJECT environment variable is not set");
+        // 🔧 FIX: Enhanced error message with setup instructions
+        throw new Error(`❌ VERTEX Provider Configuration Error
+
+Missing required environment variables: GOOGLE_VERTEX_PROJECT
+
+🔧 Step 1: Get Credentials
+Set up Google Cloud project and download service account JSON
+
+💡 Step 2: Add to your .env file (or export in CLI):
+GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
+GOOGLE_VERTEX_PROJECT="your-gcp-project-id"
+GOOGLE_VERTEX_LOCATION="us-central1"
+# Optional:
+VERTEX_MODEL="gemini-2.5-pro"
+
+🚀 Step 3: Test the setup:
+npx neurolink generate "Hello" --provider vertex
+
+📖 Full setup guide: https://docs.neurolink.ai/providers/vertex`);
     }
     return projectId;
 };

package/dist/providers/openAI.js

@@ -13,7 +13,24 @@ const DEFAULT_SYSTEM_CONTEXT = {
 const getOpenAIApiKey = () => {
     const apiKey = process.env.OPENAI_API_KEY;
     if (!apiKey) {
-        throw new Error("OPENAI_API_KEY environment variable is not set");
+        // 🔧 FIX: Enhanced error message with setup instructions
+        throw new Error(`❌ OPENAI Provider Configuration Error
+
+Missing required environment variables: OPENAI_API_KEY
+
+🔧 Step 1: Get Credentials
+Get your API key from https://platform.openai.com/api-keys
+
+💡 Step 2: Add to your .env file (or export in CLI):
+OPENAI_API_KEY="sk-proj-your-openai-api-key"
+# Optional:
+OPENAI_MODEL="gpt-4o"
+OPENAI_BASE_URL="https://api.openai.com"
+
+🚀 Step 3: Test the setup:
+npx neurolink generate "Hello" --provider openai
+
+📖 Full setup guide: https://docs.neurolink.ai/providers/openai`);
     }
     return apiKey;
 };

package/dist/utils/provider-setup-messages.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Enhanced Provider Setup Messages
+ * Provides detailed setup instructions for AI providers
+ */
+/**
+ * Generate enhanced error message with setup instructions
+ */
+export declare function getProviderSetupMessage(provider: string, missingVars: string[]): string;

package/dist/utils/provider-setup-messages.js

@@ -0,0 +1,120 @@
+/**
+ * Enhanced Provider Setup Messages
+ * Provides detailed setup instructions for AI providers
+ */
+/**
+ * Generate enhanced error message with setup instructions
+ */
+export function getProviderSetupMessage(provider, missingVars) {
+    const providerSetup = {
+        openai: {
+            guide: "Get your API key from https://platform.openai.com/api-keys",
+            envVars: [
+                'OPENAI_API_KEY="sk-proj-your-openai-api-key"',
+                "# Optional:",
+                'OPENAI_MODEL="gpt-4o"',
+                'OPENAI_BASE_URL="https://api.openai.com"',
+            ],
+        },
+        anthropic: {
+            guide: "Get your API key from https://console.anthropic.com/",
+            envVars: [
+                'ANTHROPIC_API_KEY="sk-ant-api03-your-anthropic-key"',
+                "# Optional:",
+                'ANTHROPIC_MODEL="claude-3-5-sonnet-20241022"',
+            ],
+        },
+        "google-ai": {
+            guide: "Get your API key from https://aistudio.google.com/app/apikey",
+            envVars: [
+                'GOOGLE_AI_API_KEY="AIza-your-google-ai-api-key"',
+                "# Optional:",
+                'GOOGLE_AI_MODEL="gemini-2.5-pro"',
+            ],
+        },
+        vertex: {
+            guide: "Set up Google Cloud project and download service account JSON",
+            envVars: [
+                'GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"',
+                'GOOGLE_VERTEX_PROJECT="your-gcp-project-id"',
+                'GOOGLE_VERTEX_LOCATION="us-central1"',
+                "# Optional:",
+                'VERTEX_MODEL="gemini-2.5-pro"',
+            ],
+        },
+        bedrock: {
+            guide: "Set up AWS credentials and request model access in Bedrock console",
+            envVars: [
+                'AWS_ACCESS_KEY_ID="AKIA..."',
+                'AWS_SECRET_ACCESS_KEY="your-aws-secret-key"',
+                'AWS_REGION="us-east-1"',
+                "# Use full inference profile ARN for Anthropic models:",
+                'BEDROCK_MODEL="arn:aws:bedrock:us-east-1:123456789:inference-profile/us.anthropic.claude-3-5-sonnet-20241022-v2:0"',
+                "# Or simple name for Amazon models:",
+                '# BEDROCK_MODEL="amazon.titan-text-express-v1"',
+            ],
+        },
+        azure: {
+            guide: "Set up Azure OpenAI resource and create deployment",
+            envVars: [
+                'AZURE_OPENAI_API_KEY="your-azure-openai-key"',
+                'AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"',
+                'AZURE_OPENAI_DEPLOYMENT_ID="your-deployment-name"',
+                "# Optional:",
+                'AZURE_MODEL="gpt-4o"',
+                'AZURE_API_VERSION="2024-02-15-preview"',
+            ],
+        },
+        huggingface: {
+            guide: "Get your API token from https://huggingface.co/settings/tokens",
+            envVars: [
+                'HUGGINGFACE_API_KEY="hf_your_huggingface_token"',
+                "# Optional:",
+                'HUGGINGFACE_MODEL="microsoft/DialoGPT-medium"',
+                'HUGGINGFACE_ENDPOINT="https://api-inference.huggingface.co"',
+            ],
+        },
+        mistral: {
+            guide: "Get your API key from https://mistral.ai/platform",
+            envVars: [
+                'MISTRAL_API_KEY="your_mistral_api_key"',
+                "# Optional:",
+                'MISTRAL_MODEL="mistral-small"',
+                'MISTRAL_ENDPOINT="https://api.mistral.ai"',
+            ],
+        },
+        ollama: {
+            guide: "Install Ollama and pull models locally",
+            envVars: [
+                "# Ollama runs locally - no API key needed",
+                'OLLAMA_BASE_URL="http://localhost:11434"',
+                'OLLAMA_MODEL="llama2"',
+                "",
+                "# First install and start Ollama:",
+                "# macOS: brew install ollama",
+                "# Linux: curl -fsSL https://ollama.ai/install.sh | sh",
+                "# Then pull a model: ollama pull llama2",
+            ],
+        },
+    };
+    const setup = providerSetup[provider];
+    if (!setup) {
+        return `❌ ${provider.toUpperCase()} Provider Configuration Error\nMissing variables: ${missingVars.join(", ")}\nCheck provider documentation for setup instructions.`;
+    }
+    return `
+❌ ${provider.toUpperCase()} Provider Configuration Error
+
+Missing required environment variables: ${missingVars.join(", ")}
+
+🔧 Step 1: Get Credentials
+${setup.guide}
+
+💡 Step 2: Add to your .env file (or export in CLI):
+${setup.envVars.join("\n")}
+
+🚀 Step 3: Test the setup:
+npx neurolink generate "Hello" --provider ${provider}
+
+📖 Full setup guide: https://docs.neurolink.ai/providers/${provider}
+`;
+}

package/dist/utils/provider-validation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Enhanced Provider Validation Utilities
+ *
+ * Fixes false positives in provider status checking by implementing:
+ * - API key format validation
+ * - Lightweight authentication checks
+ * - Proper error classification
+ * - Rate-limit friendly validation
+ */
+export interface ProviderValidationResult {
+    configured: boolean;
+    formatValid: boolean;
+    authenticated: boolean;
+    available: boolean;
+    error?: string;
+    errorType?: "config" | "format" | "auth" | "network" | "quota" | "unknown";
+    responseTime?: number;
+    details?: Record<string, any>;
+}
+/**
+ * Validate API key format for a specific provider
+ */
+export declare function validateApiKeyFormat(provider: string, apiKey: string): boolean;
+/**
+ * Comprehensive provider validation that prevents false positives
+ */
+export declare function validateProvider(provider: string): Promise<ProviderValidationResult>;
+/**
+ * Batch validate multiple providers efficiently
+ */
+export declare function validateProviders(providers: string[]): Promise<Record<string, ProviderValidationResult>>;
+/**
+ * Check if provider validation should be cached (to avoid rate limits)
+ */
+export declare function shouldCacheValidation(result: ProviderValidationResult): boolean;