@juspay/neurolink 3.0.1 → 4.1.0

package/dist/lib/mcp/unified-registry.js

@@ -4,14 +4,25 @@
 import { autoRegisterMCPServers, } from "./auto-discovery.js";
 import { unifiedRegistryLogger } from "./logging.js";
 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";
 /**
  * Unified registry combining multiple sources
  */
 export class UnifiedMCPRegistry extends MCPToolRegistry {
+    errorManager;
     autoDiscoveryEnabled = true;
     autoDiscoveredServers = [];
     manualServers = new Map();
     availableServers = new Set();
+    transportManager;
+    activeConnections = new Map();
+    constructor(errorManager = new ErrorManager()) {
+        super();
+        this.errorManager = errorManager;
+        this.transportManager = new TransportManager(this.errorManager);
+    }
     /**
      * Initialize with auto-discovery
      */
@@ -78,7 +89,12 @@ export class UnifiedMCPRegistry extends MCPToolRegistry {
             try {
                 // Get tools from plugin metadata if available
                 const tools = await this.listTools();
-                allTools.push(...tools);
+                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);
@@ -124,14 +140,22 @@ export class UnifiedMCPRegistry extends MCPToolRegistry {
         this.availableServers.add(id);
     }
     /**
-     * Get registry statistics
+     * Get registry statistics (override parent method)
      */
-    async getStats() {
+    getStats() {
+        // Return execution stats in the expected format
+        return super.getStats();
+    }
+    /**
+     * Get detailed registry statistics
+     */
+    async getDetailedStats() {
         const plugins = this.list();
         const bySource = {};
         const byType = {};
         for (const plugin of plugins) {
-            bySource[plugin.source] = (bySource[plugin.source] || 0) + 1;
+            const source = plugin.source || "unknown";
+            bySource[source] = (bySource[source] || 0) + 1;
             // Extract type from name or metadata
             const type = plugin.metadata.name.split("/")[1]?.split("-")[0] || "unknown";
             byType[type] = (byType[type] || 0) + 1;
@@ -146,14 +170,123 @@ export class UnifiedMCPRegistry extends MCPToolRegistry {
         };
     }
     /**
-     * Clear all registries
+     * Add external MCP server programmatically
+     *
+     * @param serverId - Unique server identifier
+     * @param config - Server configuration (stdio, sse, or http)
      */
-    clear() {
+    async addExternalServer(serverId, config) {
+        unifiedRegistryLogger.info(`Adding external server: ${serverId} (${config.type})`);
+        // Create server metadata
+        const serverMeta = {
+            metadata: {
+                name: serverId,
+                version: "1.0.0",
+                main: "index.js",
+                engine: { neurolink: ">=4.0.0" },
+                description: `External ${config.type} server: ${serverId}`,
+                permissions: ["network", "filesystem"],
+            },
+            entryPath: "",
+            source: "installed",
+            constructor: undefined,
+        };
+        // Register in internal registry
+        this.register(serverMeta);
+        this.manualServers.set(serverId, config);
+        this.availableServers.add(serverId);
+        // Establish actual connection to make server immediately reachable
+        try {
+            // Validate config for stdio transport (most common case)
+            if (config.type === "stdio" && !config.command) {
+                throw new Error("Command is required for stdio transport");
+            }
+            // Create transport with proper type validation
+            // Validate config shape before creating transport
+            const validatedConfig = TransportConfigSchema.parse(config);
+            const transport = await this.transportManager.createTransport(validatedConfig);
+            const client = new Client({
+                name: "neurolink-client",
+                version: "4.1.0",
+            }, {
+                capabilities: {
+                    tools: {},
+                    logging: {},
+                },
+            });
+            // Connect the client
+            await client.connect(transport);
+            this.activeConnections.set(serverId, client);
+            unifiedRegistryLogger.info(`Successfully connected to external server: ${serverId}`);
+            unifiedRegistryLogger.info(`Successfully added external server: ${serverId}`);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            unifiedRegistryLogger.warn(`Failed to establish connection to ${serverId}: ${errorMessage}. Server registered but not connected.`);
+            unifiedRegistryLogger.info(`Successfully registered external server: ${serverId} but connection failed.`);
+        }
+    }
+    /**
+     * Get active connection for a server
+     */
+    getConnection(serverId) {
+        return this.activeConnections.get(serverId);
+    }
+    /**
+     * Check if server is actively connected
+     */
+    isConnected(serverId) {
+        return this.activeConnections.has(serverId);
+    }
+    /**
+     * Clear all registries and active connections (synchronous, preserves base API contract)
+     */
+    /**
+     * Clear registries without closing connections (internal use)
+     */
+    clearRegistriesOnly() {
         super.clear();
         this.autoDiscoveredServers = [];
         this.manualServers.clear();
         this.availableServers.clear();
     }
+    /**
+     * Clear all registries and initiate async connection cleanup
+     */
+    clear() {
+        // Close all active connections before clearing registries to prevent resource leaks
+        const closePromises = [];
+        for (const [serverId, client] of this.activeConnections) {
+            closePromises.push(client.close().catch((error) => {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                unifiedRegistryLogger.warn(`Failed to close connection for ${serverId}: ${errorMessage}`);
+            }));
+        }
+        // Handle async cleanup without blocking synchronous clear()
+        Promise.allSettled(closePromises).then(() => {
+            this.activeConnections.clear();
+        });
+        // Clear registries after initiating connection cleanup
+        this.clearRegistriesOnly();
+    }
+    /**
+     * Clear all registries and close active connections asynchronously
+     */
+    async clearAsync() {
+        // Close all active connections first
+        for (const [serverId, client] of this.activeConnections) {
+            try {
+                await client.close();
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                unifiedRegistryLogger.warn(`Failed to close connection for ${serverId}: ${errorMessage}`);
+            }
+        }
+        this.activeConnections.clear();
+        // Clear registries without attempting to close connections again
+        this.clearRegistriesOnly();
+    }
 }
 /**
  * Default unified registry instance

package/dist/lib/neurolink.d.ts

@@ -15,6 +15,15 @@ export interface TextGenerationOptions {
     schema?: any;
     timeout?: number | string;
     disableTools?: boolean;
+    enableAnalytics?: boolean;
+    enableEvaluation?: boolean;
+    context?: Record<string, any>;
+    evaluationDomain?: string;
+    toolUsageContext?: string;
+    conversationHistory?: Array<{
+        role: string;
+        content: string;
+    }>;
 }
 export interface StreamTextOptions {
     prompt: string;
@@ -23,7 +32,12 @@ export interface StreamTextOptions {
     temperature?: number;
     maxTokens?: number;
     systemPrompt?: string;
+    schema?: any;
     timeout?: number | string;
+    disableTools?: boolean;
+    enableAnalytics?: boolean;
+    enableEvaluation?: boolean;
+    context?: Record<string, any>;
 }
 export interface TextGenerationResult {
     content: string;
@@ -115,4 +129,91 @@ export declare class NeuroLink {
             hasServer: boolean;
         }[];
     }>;
+    /**
+     * Add a new MCP server programmatically
+     *
+     * Allows dynamic registration of MCP servers at runtime for enhanced
+     * tool ecosystem management. Perfect for integrating external services
+     * like Bitbucket, Slack, databases, etc.
+     *
+     * @param serverId - Unique identifier for the server (e.g., 'bitbucket', 'slack-api')
+     * @param config - Server configuration with command and execution parameters
+     * @returns Promise that resolves when server is successfully added and connected
+     *
+     * @example
+     * ```typescript
+     * // Add Bitbucket MCP server
+     * await neurolink.addMCPServer('bitbucket', {
+     *   command: 'npx',
+     *   args: ['-y', '@nexus2520/bitbucket-mcp-server'],
+     *   env: {
+     *     BITBUCKET_USERNAME: 'your-username',
+     *     BITBUCKET_APP_PASSWORD: 'your-app-password'
+     *   }
+     * });
+     *
+     * // Add custom database connector
+     * await neurolink.addMCPServer('database', {
+     *   command: 'node',
+     *   args: ['./custom-db-mcp-server.js'],
+     *   env: { DB_CONNECTION_STRING: 'postgresql://...' }
+     * });
+     * ```
+     */
+    addMCPServer(serverId: string, config: {
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+        cwd?: string;
+        type?: "stdio" | "sse" | "http";
+        url?: string;
+        headers?: Record<string, string>;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Alias for generateText() - CLI-SDK consistency
+     * @param options - Text generation options
+     * @returns Promise resolving to text generation result
+     */
+    generate(options: TextGenerationOptions): Promise<TextGenerationResult>;
+    /**
+     * Short alias for generateText() - CLI-SDK consistency
+     * @param options - Text generation options
+     * @returns Promise resolving to text generation result
+     */
+    gen(options: TextGenerationOptions): Promise<TextGenerationResult>;
+    /**
+     * Get the connection client for a specific MCP server
+     * @param serverId - The ID of the server to get connection for
+     * @returns Client connection object or undefined if not connected
+     */
+    getConnection(serverId: string): import("@modelcontextprotocol/sdk/client/index.js").Client<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    }> | undefined;
+    /**
+     * Check if a specific MCP server is currently connected
+     * @param serverId - The ID of the server to check
+     * @returns True if server is connected, false otherwise
+     */
+    isConnected(serverId: string): boolean;
 }

package/dist/lib/neurolink.js

@@ -135,6 +135,14 @@ export class NeuroLink {
                 maxTokens: options.maxTokens,
                 systemPrompt: enhancedSystemPrompt,
                 timeout: options.timeout,
+                // NEW: Pass enhancement options
+                enableAnalytics: options.enableAnalytics,
+                enableEvaluation: options.enableEvaluation,
+                context: options.context,
+                // NEW: Lighthouse-compatible domain-aware evaluation
+                evaluationDomain: options.evaluationDomain,
+                toolUsageContext: options.toolUsageContext,
+                conversationHistory: options.conversationHistory,
             }, options.schema);
             if (!result) {
                 throw new Error("No response received from AI provider");
@@ -166,6 +174,9 @@ export class NeuroLink {
                 toolsUsed: metadata.toolsUsed || [],
                 enhancedWithTools: metadata.enhancedWithTools || false,
                 availableTools: availableTools.length > 0 ? availableTools : undefined,
+                // NEW: Preserve enhancement data from provider
+                ...(result.analytics && { analytics: result.analytics }),
+                ...(result.evaluation && { evaluation: result.evaluation }),
             };
         }
         catch (error) {
@@ -225,6 +236,14 @@ export class NeuroLink {
                     maxTokens: options.maxTokens,
                     systemPrompt: options.systemPrompt,
                     timeout: options.timeout,
+                    // NEW: Pass enhancement options
+                    enableAnalytics: options.enableAnalytics,
+                    enableEvaluation: options.enableEvaluation,
+                    context: options.context,
+                    // NEW: Lighthouse-compatible domain-aware evaluation
+                    evaluationDomain: options.evaluationDomain,
+                    toolUsageContext: options.toolUsageContext,
+                    conversationHistory: options.conversationHistory,
                 }, options.schema);
                 if (!result) {
                     throw new Error("No response received from AI provider");
@@ -250,6 +269,9 @@ export class NeuroLink {
                     provider: providerName,
                     usage: result.usage,
                     responseTime,
+                    // NEW: Preserve enhancement data from provider
+                    ...(result.analytics && { analytics: result.analytics }),
+                    ...(result.evaluation && { evaluation: result.evaluation }),
                 };
             }
             catch (error) {
@@ -409,7 +431,11 @@ Note: Tool integration is currently in development. Please provide helpful respo
     async testProvider(providerName, testPrompt = "test") {
         try {
             const provider = await AIProviderFactory.createProvider(providerName);
-            await provider.generateText(testPrompt);
+            await provider.generateText({
+                prompt: testPrompt,
+                enableAnalytics: false,
+                enableEvaluation: false,
+            });
             return true;
         }
         catch (error) {
@@ -446,4 +472,124 @@ Note: Tool integration is currently in development. Please provide helpful respo
             })),
         };
     }
+    /**
+     * Add a new MCP server programmatically
+     *
+     * Allows dynamic registration of MCP servers at runtime for enhanced
+     * tool ecosystem management. Perfect for integrating external services
+     * like Bitbucket, Slack, databases, etc.
+     *
+     * @param serverId - Unique identifier for the server (e.g., 'bitbucket', 'slack-api')
+     * @param config - Server configuration with command and execution parameters
+     * @returns Promise that resolves when server is successfully added and connected
+     *
+     * @example
+     * ```typescript
+     * // Add Bitbucket MCP server
+     * await neurolink.addMCPServer('bitbucket', {
+     *   command: 'npx',
+     *   args: ['-y', '@nexus2520/bitbucket-mcp-server'],
+     *   env: {
+     *     BITBUCKET_USERNAME: 'your-username',
+     *     BITBUCKET_APP_PASSWORD: 'your-app-password'
+     *   }
+     * });
+     *
+     * // Add custom database connector
+     * await neurolink.addMCPServer('database', {
+     *   command: 'node',
+     *   args: ['./custom-db-mcp-server.js'],
+     *   env: { DB_CONNECTION_STRING: 'postgresql://...' }
+     * });
+     * ```
+     */
+    async addMCPServer(serverId, config) {
+        const functionTag = "NeuroLink.addMCPServer";
+        mcpLogger.info(`[${functionTag}] Adding MCP server: ${serverId}`, {
+            command: config.command,
+            argsCount: config.args?.length || 0,
+            hasEnv: Object.keys(config.env || {}).length > 0,
+        });
+        try {
+            // Ensure MCP is initialized
+            await this.initializeMCP();
+            // Add server to unified registry with configurable transport type
+            const transportType = config.type || "stdio";
+            // Validate URL requirement for non-stdio transports
+            if ((transportType === "sse" || transportType === "http") &&
+                !config.url) {
+                throw new Error(`URL is required for ${transportType} transport. Please provide config.url for server '${serverId}'.`);
+            }
+            const transportConfig = {
+                type: transportType,
+                ...(transportType === "stdio" && {
+                    command: config.command,
+                    args: config.args || [],
+                    env: config.env || {},
+                    cwd: config.cwd,
+                }),
+                ...(transportType === "sse" && {
+                    url: config.url,
+                    headers: config.headers,
+                    timeout: config.timeout,
+                }),
+                ...(transportType === "http" && {
+                    url: config.url,
+                    headers: config.headers,
+                    timeout: config.timeout,
+                }),
+            };
+            await unifiedRegistry.addExternalServer(serverId, transportConfig);
+            // Check if server is actually connected vs just registered
+            const isConnected = unifiedRegistry.isConnected(serverId);
+            if (isConnected) {
+                mcpLogger.info(`[${functionTag}] Successfully connected to MCP server: ${serverId}`);
+            }
+            else {
+                mcpLogger.info(`[${functionTag}] MCP server registered: ${serverId} (connection failed, but server available for retry)`);
+            }
+        }
+        catch (error) {
+            mcpLogger.error(`[${functionTag}] Failed to add MCP server: ${serverId}`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            const newError = new Error(`Failed to add MCP server '${serverId}': ${error instanceof Error ? error.message : String(error)}`);
+            if (error instanceof Error && error.stack) {
+                newError.stack = `${newError.stack}\nCaused by: ${error.stack}`;
+            }
+            throw newError;
+        }
+    }
+    /**
+     * Alias for generateText() - CLI-SDK consistency
+     * @param options - Text generation options
+     * @returns Promise resolving to text generation result
+     */
+    async generate(options) {
+        return this.generateText(options);
+    }
+    /**
+     * Short alias for generateText() - CLI-SDK consistency
+     * @param options - Text generation options
+     * @returns Promise resolving to text generation result
+     */
+    async gen(options) {
+        return this.generateText(options);
+    }
+    /**
+     * Get the connection client for a specific MCP server
+     * @param serverId - The ID of the server to get connection for
+     * @returns Client connection object or undefined if not connected
+     */
+    getConnection(serverId) {
+        return unifiedRegistry.getConnection(serverId);
+    }
+    /**
+     * Check if a specific MCP server is currently connected
+     * @param serverId - The ID of the server to check
+     * @returns True if server is connected, false otherwise
+     */
+    isConnected(serverId) {
+        return unifiedRegistry.isConnected(serverId);
+    }
 }

package/dist/lib/providers/agent-enhanced-provider.d.ts

@@ -3,7 +3,7 @@
  * Integrates direct tools with AI providers for true agent functionality
  */
 import { type GenerateTextResult, type StreamTextResult, type ToolSet } from "ai";
-import type { AIProvider, TextGenerationOptions, StreamTextOptions } from "../core/types.js";
+import type { AIProvider, TextGenerationOptions, EnhancedGenerateTextResult, EnhancedStreamTextOptions } from "../core/types.js";
 /**
  * Agent configuration options
  */
@@ -30,6 +30,7 @@ interface AgentConfig {
 export declare class AgentEnhancedProvider implements AIProvider {
     private config;
     private model;
+    private resolvedModelName;
     private mcpSystem;
     private mcpInitialized;
     private mcpInitializing;
@@ -45,7 +46,7 @@ export declare class AgentEnhancedProvider implements AIProvider {
      */
     private getCombinedTools;
     generateText(optionsOrPrompt: TextGenerationOptions | string): Promise<GenerateTextResult<ToolSet, unknown> | null>;
-    streamText(optionsOrPrompt: StreamTextOptions | string): Promise<StreamTextResult<ToolSet, unknown> | null>;
+    streamText(optionsOrPrompt: EnhancedStreamTextOptions | string): Promise<StreamTextResult<ToolSet, unknown> | null>;
     /**
      * Determine if we should force tool usage based on prompt patterns
      */
@@ -68,6 +69,14 @@ export declare class AgentEnhancedProvider implements AIProvider {
      * Create multiple agent providers for comparison
      */
     static createMultiProviderAgents(): Record<string, AgentEnhancedProvider>;
+    /**
+     * Alias for generateText() - CLI-SDK consistency
+     */
+    generate(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: any): Promise<EnhancedGenerateTextResult | null>;
+    /**
+     * Short alias for generateText() - CLI-SDK consistency
+     */
+    gen(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: any): Promise<EnhancedGenerateTextResult | null>;
 }
 /**
  * Helper function to create agent provider