@juspay/neurolink 4.0.0 → 4.1.1

package/dist/lib/mcp/transport-manager.js

@@ -0,0 +1,330 @@
+/**
+ * Transport Manager for MCP connections
+ * Supports stdio, SSE, and HTTP transports with reconnection logic
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { z } from "zod";
+import { ErrorCategory, ErrorSeverity } from "./error-manager.js";
+// Transport configuration schemas
+export const TransportConfigSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("stdio"),
+        command: z.string(),
+        args: z.array(z.string()).optional(),
+        cwd: z.string().optional(),
+        env: z.record(z.string()).optional(),
+    }),
+    z.object({
+        type: z.literal("sse"),
+        url: z.string().url(),
+        headers: z.record(z.string()).optional(),
+        timeout: z.number().min(5).default(30),
+        maxRetryTime: z.number().default(5000),
+        withCredentials: z.boolean().default(false),
+    }),
+    z.object({
+        type: z.literal("http"),
+        url: z.string().url(),
+        headers: z.record(z.string()).optional(),
+        timeout: z.number().min(5).default(30),
+    }),
+]);
+/**
+ * Manages MCP transport connections with automatic reconnection and health monitoring
+ */
+export class TransportManager {
+    errorManager;
+    options;
+    client;
+    config;
+    status;
+    reconnectTimer;
+    healthCheckTimer;
+    reconnectPromise;
+    constructor(errorManager, options = {}) {
+        this.errorManager = errorManager;
+        this.options = options;
+        // Initialize default options
+        this.options = {
+            jitterEnabled: true,
+            maxJitter: 1000,
+            ...this.options,
+        };
+        this.status = {
+            connected: false,
+            type: "stdio",
+            reconnectAttempts: 0,
+        };
+        // Apply defaults
+        this.options = {
+            autoReconnect: true,
+            maxReconnectAttempts: 5,
+            reconnectDelay: 1000,
+            healthCheckInterval: 30000,
+            ...options,
+        };
+    }
+    /**
+     * Connect to MCP server using specified transport
+     */
+    async connect(config) {
+        try {
+            // Validate configuration
+            const validatedConfig = TransportConfigSchema.parse(config);
+            this.config = validatedConfig;
+            this.status.type = validatedConfig.type;
+            // Disconnect existing client if any
+            if (this.client) {
+                await this.disconnect();
+            }
+            // Create transport based on type
+            const transport = await this.createTransport(validatedConfig);
+            // Create MCP client
+            this.client = new Client({
+                name: "neurolink-mcp-client",
+                version: "1.0.0",
+            }, {
+                capabilities: {},
+            });
+            // Connect client
+            await this.client.connect(transport);
+            // Update status
+            this.status.connected = true;
+            this.status.lastConnected = new Date();
+            this.status.reconnectAttempts = 0;
+            // Set up health monitoring if enabled
+            if (this.options.healthCheckInterval &&
+                this.options.healthCheckInterval > 0) {
+                this.setupHealthMonitoring();
+            }
+            return this.client;
+        }
+        catch (error) {
+            this.handleConnectionError(error);
+            throw error;
+        }
+    }
+    /**
+     * Create transport based on configuration
+     */
+    async createTransport(config) {
+        switch (config.type) {
+            case "stdio":
+                return this.createStdioTransport(config);
+            case "sse":
+                return this.createSSETransport(config);
+            case "http":
+                return this.createHTTPTransport(config);
+            default:
+                throw new Error(`Unsupported transport type: ${config.type}`);
+        }
+    }
+    /**
+     * Create stdio transport
+     */
+    createStdioTransport(config) {
+        // Filter out undefined values from process.env
+        const envWithoutUndefined = Object.fromEntries(Object.entries(process.env).filter(([_, value]) => value !== undefined));
+        // StdioClientTransport handles process creation internally
+        return new StdioClientTransport({
+            command: config.command,
+            args: config.args ?? [],
+            env: { ...envWithoutUndefined, ...config.env },
+            cwd: config.cwd,
+        });
+    }
+    /**
+     * Create SSE transport with reconnection support
+     */
+    async createSSETransport(config) {
+        // Dynamically import SSE transport
+        const { SSEClientTransport } = await import("@modelcontextprotocol/sdk/client/sse.js");
+        // Use ReconnectingEventSource for reliability
+        const ReconnectingEventSource = await import("reconnecting-eventsource").then((m) => m.default);
+        return new SSEClientTransport(new URL(config.url), {
+            requestInit: {
+                headers: config.headers,
+                ...(config.timeout && { timeout: config.timeout }),
+            },
+            eventSourceInit: {
+                eventSource: ReconnectingEventSource,
+                max_retry_time: config.maxRetryTime,
+                withCredentials: config.withCredentials,
+            },
+        });
+    }
+    /**
+     * Create HTTP transport
+     */
+    async createHTTPTransport(config) {
+        // Dynamically import HTTP transport
+        const httpModule = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+        const HTTPClientTransport = httpModule.default || httpModule.HTTPClientTransport;
+        return new HTTPClientTransport(new URL(config.url), {
+            requestInit: {
+                headers: config.headers,
+                timeout: config.timeout * 1000, // Convert seconds to milliseconds
+            },
+        });
+    }
+    /**
+     * Set up health monitoring
+     */
+    setupHealthMonitoring() {
+        if (!this.client) {
+            return;
+        }
+        // Clear any existing health check timer
+        if (this.healthCheckTimer) {
+            clearInterval(this.healthCheckTimer);
+        }
+        // Set up periodic health checks
+        this.healthCheckTimer = setInterval(async () => {
+            if (!this.client) {
+                return;
+            }
+            try {
+                // Simple health check - list tools
+                await this.client.request({ method: "tools/list" }, z.object({ tools: z.array(z.any()) }));
+            }
+            catch (error) {
+                // Health check failed, trigger reconnection if enabled
+                if (this.options.autoReconnect && this.config) {
+                    this.handleConnectionError(error);
+                }
+            }
+        }, this.options.healthCheckInterval);
+    }
+    /**
+     * Handle connection errors
+     */
+    handleConnectionError(error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        this.status.connected = false;
+        this.status.lastError = err;
+        // Record error
+        this.errorManager.recordError(err, {
+            category: ErrorCategory.CONNECTION_ERROR,
+            severity: ErrorSeverity.HIGH,
+            toolName: "transport-manager",
+            parameters: {
+                transport: this.status.type,
+                reconnectAttempts: this.status.reconnectAttempts,
+            },
+        });
+        // Attempt reconnection if enabled
+        if (this.options.autoReconnect &&
+            this.status.reconnectAttempts < this.options.maxReconnectAttempts) {
+            // Schedule reconnection attempt
+            this.scheduleReconnect();
+        }
+    }
+    /**
+     * Schedule reconnection attempt
+     */
+    scheduleReconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+        }
+        // Increment attempts BEFORE calculating delay (uses updated attempt count)
+        this.status.reconnectAttempts++;
+        const delay = this.calculateReconnectDelay();
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnect().catch((error) => {
+                console.error("Reconnection failed:", error);
+            });
+        }, delay);
+    }
+    /**
+     * Calculate reconnect delay with exponential backoff
+     */
+    calculateReconnectDelay() {
+        const baseDelay = this.options.reconnectDelay || 1000;
+        const maxDelay = 30000; // 30 seconds max
+        const delay = Math.min(baseDelay * Math.pow(2, this.status.reconnectAttempts), maxDelay);
+        // Add configurable jitter to prevent thundering herd
+        if (this.options.jitterEnabled === true) {
+            const maxJitter = this.options.maxJitter || 1000;
+            return delay + Math.random() * maxJitter;
+        }
+        return delay;
+    }
+    /**
+     * Reconnect to server
+     */
+    async reconnect() {
+        // Prevent concurrent reconnection attempts
+        if (this.reconnectPromise) {
+            return this.reconnectPromise;
+        }
+        this.reconnectPromise = this._reconnect();
+        try {
+            await this.reconnectPromise;
+        }
+        finally {
+            this.reconnectPromise = undefined;
+        }
+    }
+    async _reconnect() {
+        if (!this.config) {
+            throw new Error("No configuration available for reconnection");
+        }
+        try {
+            await this.connect(this.config);
+            console.log(`Reconnected successfully after ${this.status.reconnectAttempts} attempts`);
+        }
+        catch (error) {
+            if (this.status.reconnectAttempts >= this.options.maxReconnectAttempts) {
+                throw new Error(`Max reconnection attempts (${this.options.maxReconnectAttempts}) reached`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Disconnect from server
+     */
+    async disconnect() {
+        // Clear reconnection timer
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+        // Stop health monitoring
+        if (this.healthCheckTimer) {
+            clearInterval(this.healthCheckTimer);
+            this.healthCheckTimer = undefined;
+        }
+        // Close client connection
+        if (this.client) {
+            await this.client.close();
+            this.client = undefined;
+        }
+        // Update status
+        this.status.connected = false;
+    }
+    /**
+     * Get current transport status
+     */
+    getStatus() {
+        return { ...this.status };
+    }
+    /**
+     * Get connected client
+     */
+    getClient() {
+        return this.client;
+    }
+    /**
+     * Check if connected
+     */
+    isConnected() {
+        return this.status.connected && this.client !== undefined;
+    }
+    /**
+     * Reset reconnection attempts
+     */
+    resetReconnectAttempts() {
+        this.status.reconnectAttempts = 0;
+    }
+}

package/dist/lib/mcp/unified-registry.d.ts

@@ -4,14 +4,20 @@
 import type { DiscoveredMCP, ExecutionContext } from "./contracts/mcp-contract.js";
 import type { DiscoveryOptions } from "./auto-discovery.js";
 import { MCPToolRegistry, type ToolInfo } from "./tool-registry.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { ErrorManager } from "./error-manager.js";
 /**
  * Unified registry combining multiple sources
  */
 export declare class UnifiedMCPRegistry extends MCPToolRegistry {
+    private errorManager;
     private autoDiscoveryEnabled;
     private autoDiscoveredServers;
     private manualServers;
     private availableServers;
+    private transportManager;
+    private activeConnections;
+    constructor(errorManager?: ErrorManager);
     /**
      * Initialize with auto-discovery
      */
@@ -80,9 +86,44 @@ export declare class UnifiedMCPRegistry extends MCPToolRegistry {
         tools?: number;
     }>;
     /**
-     * Clear all registries
+     * Add external MCP server programmatically
+     *
+     * @param serverId - Unique server identifier
+     * @param config - Server configuration (stdio, sse, or http)
+     */
+    addExternalServer(serverId: string, config: {
+        type: "stdio" | "sse" | "http";
+        command?: string;
+        args?: string[];
+        env?: Record<string, string>;
+        cwd?: string;
+        url?: string;
+        headers?: Record<string, string>;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Get active connection for a server
+     */
+    getConnection(serverId: string): Client | undefined;
+    /**
+     * Check if server is actively connected
+     */
+    isConnected(serverId: string): boolean;
+    /**
+     * Clear all registries and active connections (synchronous, preserves base API contract)
+     */
+    /**
+     * Clear registries without closing connections (internal use)
+     */
+    private clearRegistriesOnly;
+    /**
+     * Clear all registries and initiate async connection cleanup
      */
     clear(): void;
+    /**
+     * Clear all registries and close active connections asynchronously
+     */
+    clearAsync(): Promise<void>;
 }
 /**
  * Default unified registry instance

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
      */
@@ -159,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

@@ -129,6 +129,47 @@ 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
@@ -141,4 +182,38 @@ export declare class NeuroLink {
      * @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;
 }