@juspay/neurolink 7.13.0 → 7.14.0

package/dist/lib/mcp/mcpCircuitBreaker.d.ts

@@ -0,0 +1,184 @@
+/**
+ * MCP Circuit Breaker
+ * Implements circuit breaker pattern for external MCP operations
+ * Provides fault tolerance and prevents cascading failures
+ */
+import { EventEmitter } from "events";
+/**
+ * Circuit breaker states
+ */
+export type CircuitBreakerState = "closed" | "open" | "half-open";
+/**
+ * Circuit breaker configuration
+ */
+export interface CircuitBreakerConfig {
+    /** Number of failures before opening the circuit */
+    failureThreshold: number;
+    /** Time to wait before attempting reset (milliseconds) */
+    resetTimeout: number;
+    /** Maximum calls allowed in half-open state */
+    halfOpenMaxCalls: number;
+    /** Timeout for individual operations (milliseconds) */
+    operationTimeout: number;
+    /** Minimum number of calls before calculating failure rate */
+    minimumCallsBeforeCalculation: number;
+    /** Window size for calculating failure rate (milliseconds) */
+    statisticsWindowSize: number;
+}
+/**
+ * Circuit breaker statistics
+ */
+export interface CircuitBreakerStats {
+    /** Current state */
+    state: CircuitBreakerState;
+    /** Total number of calls */
+    totalCalls: number;
+    /** Number of successful calls */
+    successfulCalls: number;
+    /** Number of failed calls */
+    failedCalls: number;
+    /** Current failure rate (0-1) */
+    failureRate: number;
+    /** Calls in current time window */
+    windowCalls: number;
+    /** Last state change timestamp */
+    lastStateChange: Date;
+    /** Next retry time (for open state) */
+    nextRetryTime?: Date;
+    /** Half-open call count */
+    halfOpenCalls: number;
+}
+/**
+ * Circuit breaker events
+ */
+export interface CircuitBreakerEvents {
+    stateChange: {
+        oldState: CircuitBreakerState;
+        newState: CircuitBreakerState;
+        reason: string;
+        timestamp: Date;
+    };
+    callSuccess: {
+        duration: number;
+        timestamp: Date;
+    };
+    callFailure: {
+        error: string;
+        duration: number;
+        timestamp: Date;
+    };
+    circuitOpen: {
+        failureRate: number;
+        totalCalls: number;
+        timestamp: Date;
+    };
+    circuitHalfOpen: {
+        timestamp: Date;
+    };
+    circuitClosed: {
+        timestamp: Date;
+    };
+}
+/**
+ * MCPCircuitBreaker
+ * Implements circuit breaker pattern for fault tolerance
+ */
+export declare class MCPCircuitBreaker extends EventEmitter {
+    private name;
+    private state;
+    private config;
+    private callHistory;
+    private lastFailureTime;
+    private halfOpenCalls;
+    private lastStateChange;
+    constructor(name: string, config?: Partial<CircuitBreakerConfig>);
+    /**
+     * Execute an operation with circuit breaker protection
+     */
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    /**
+     * Record a call in the history
+     */
+    private recordCall;
+    /**
+     * Check if failure threshold is exceeded
+     */
+    private checkFailureThreshold;
+    /**
+     * Change circuit breaker state
+     */
+    private changeState;
+    /**
+     * Create a timeout promise
+     */
+    private timeoutPromise;
+    /**
+     * Clean up old call records
+     */
+    private cleanupCallHistory;
+    /**
+     * Get current statistics
+     */
+    getStats(): CircuitBreakerStats;
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset(): void;
+    /**
+     * Force open the circuit breaker
+     */
+    forceOpen(reason?: string): void;
+    /**
+     * Get circuit breaker name
+     */
+    getName(): string;
+    /**
+     * Check if circuit is open
+     */
+    isOpen(): boolean;
+    /**
+     * Check if circuit is closed
+     */
+    isClosed(): boolean;
+    /**
+     * Check if circuit is half-open
+     */
+    isHalfOpen(): boolean;
+}
+/**
+ * Circuit breaker manager for multiple circuit breakers
+ */
+export declare class CircuitBreakerManager {
+    private breakers;
+    /**
+     * Get or create a circuit breaker
+     */
+    getBreaker(name: string, config?: Partial<CircuitBreakerConfig>): MCPCircuitBreaker;
+    /**
+     * Remove a circuit breaker
+     */
+    removeBreaker(name: string): boolean;
+    /**
+     * Get all circuit breaker names
+     */
+    getBreakerNames(): string[];
+    /**
+     * Get statistics for all circuit breakers
+     */
+    getAllStats(): Record<string, CircuitBreakerStats>;
+    /**
+     * Reset all circuit breakers
+     */
+    resetAll(): void;
+    /**
+     * Get health summary
+     */
+    getHealthSummary(): {
+        totalBreakers: number;
+        closedBreakers: number;
+        openBreakers: number;
+        halfOpenBreakers: number;
+        unhealthyBreakers: string[];
+    };
+}
+export declare const globalCircuitBreakerManager: CircuitBreakerManager;

package/dist/lib/mcp/mcpCircuitBreaker.js

@@ -0,0 +1,338 @@
+/**
+ * MCP Circuit Breaker
+ * Implements circuit breaker pattern for external MCP operations
+ * Provides fault tolerance and prevents cascading failures
+ */
+import { EventEmitter } from "events";
+import { mcpLogger } from "../utils/logger.js";
+/**
+ * MCPCircuitBreaker
+ * Implements circuit breaker pattern for fault tolerance
+ */
+export class MCPCircuitBreaker extends EventEmitter {
+    name;
+    state = "closed";
+    config;
+    callHistory = [];
+    lastFailureTime = 0;
+    halfOpenCalls = 0;
+    lastStateChange = new Date();
+    constructor(name, config = {}) {
+        super();
+        this.name = name;
+        // Set default configuration
+        this.config = {
+            failureThreshold: config.failureThreshold ?? 5,
+            resetTimeout: config.resetTimeout ?? 60000,
+            halfOpenMaxCalls: config.halfOpenMaxCalls ?? 3,
+            operationTimeout: config.operationTimeout ?? 30000,
+            minimumCallsBeforeCalculation: config.minimumCallsBeforeCalculation ?? 10,
+            statisticsWindowSize: config.statisticsWindowSize ?? 300000, // 5 minutes
+        };
+        // Clean up old call records periodically
+        setInterval(() => this.cleanupCallHistory(), 60000);
+    }
+    /**
+     * Execute an operation with circuit breaker protection
+     */
+    async execute(operation) {
+        const startTime = Date.now();
+        try {
+            // Check if circuit is open
+            if (this.state === "open") {
+                if (Date.now() - this.lastFailureTime < this.config.resetTimeout) {
+                    throw new Error(`Circuit breaker '${this.name}' is open. Next retry at ${new Date(this.lastFailureTime + this.config.resetTimeout)}`);
+                }
+                // Transition to half-open
+                this.changeState("half-open", "Reset timeout reached");
+            }
+            // Check half-open call limit
+            if (this.state === "half-open" &&
+                this.halfOpenCalls >= this.config.halfOpenMaxCalls) {
+                throw new Error(`Circuit breaker '${this.name}' is half-open but call limit reached`);
+            }
+            // Execute operation with timeout
+            const result = await Promise.race([
+                operation(),
+                this.timeoutPromise(this.config.operationTimeout),
+            ]);
+            // Record successful call
+            this.recordCall(true, Date.now() - startTime);
+            // Handle half-open success
+            if (this.state === "half-open") {
+                this.halfOpenCalls++;
+                // If enough successful calls in half-open, close the circuit
+                if (this.halfOpenCalls >= this.config.halfOpenMaxCalls) {
+                    this.changeState("closed", "Half-open test successful");
+                }
+            }
+            return result;
+        }
+        catch (error) {
+            // Record failed call
+            const duration = Date.now() - startTime;
+            this.recordCall(false, duration);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Emit failure event
+            this.emit("callFailure", {
+                error: errorMessage,
+                duration,
+                timestamp: new Date(),
+            });
+            // Handle state transitions on failure
+            if (this.state === "half-open") {
+                // Failure in half-open immediately opens circuit
+                this.changeState("open", `Half-open test failed: ${errorMessage}`);
+            }
+            else if (this.state === "closed") {
+                // Check if we should open the circuit
+                this.checkFailureThreshold();
+            }
+            throw error;
+        }
+    }
+    /**
+     * Record a call in the history
+     */
+    recordCall(success, duration) {
+        const now = Date.now();
+        this.callHistory.push({
+            timestamp: now,
+            success,
+            duration,
+        });
+        // Emit success event
+        if (success) {
+            this.emit("callSuccess", {
+                duration,
+                timestamp: new Date(),
+            });
+        }
+        // Update failure time
+        if (!success) {
+            this.lastFailureTime = now;
+        }
+    }
+    /**
+     * Check if failure threshold is exceeded
+     */
+    checkFailureThreshold() {
+        const windowStart = Date.now() - this.config.statisticsWindowSize;
+        const windowCalls = this.callHistory.filter((call) => call.timestamp >= windowStart);
+        // Need minimum calls before calculating failure rate
+        if (windowCalls.length < this.config.minimumCallsBeforeCalculation) {
+            return;
+        }
+        const failedCalls = windowCalls.filter((call) => !call.success).length;
+        const failureRate = failedCalls / windowCalls.length;
+        mcpLogger.debug(`[CircuitBreaker:${this.name}] Failure rate: ${(failureRate * 100).toFixed(1)}% (${failedCalls}/${windowCalls.length})`);
+        // Open circuit if failure rate exceeds threshold
+        if (failedCalls >= this.config.failureThreshold) {
+            this.changeState("open", `Failure threshold exceeded: ${failedCalls} failures`);
+            this.emit("circuitOpen", {
+                failureRate,
+                totalCalls: windowCalls.length,
+                timestamp: new Date(),
+            });
+        }
+    }
+    /**
+     * Change circuit breaker state
+     */
+    changeState(newState, reason) {
+        const oldState = this.state;
+        this.state = newState;
+        this.lastStateChange = new Date();
+        // Reset counters based on state
+        if (newState === "half-open") {
+            this.halfOpenCalls = 0;
+            this.emit("circuitHalfOpen", {
+                timestamp: new Date(),
+            });
+        }
+        else if (newState === "closed") {
+            this.halfOpenCalls = 0;
+            this.emit("circuitClosed", {
+                timestamp: new Date(),
+            });
+        }
+        mcpLogger.info(`[CircuitBreaker:${this.name}] State changed: ${oldState} -> ${newState} (${reason})`);
+        // Emit state change event
+        this.emit("stateChange", {
+            oldState,
+            newState,
+            reason,
+            timestamp: new Date(),
+        });
+    }
+    /**
+     * Create a timeout promise
+     */
+    timeoutPromise(timeout) {
+        return new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(`Operation timed out after ${timeout}ms`));
+            }, timeout);
+        });
+    }
+    /**
+     * Clean up old call records
+     */
+    cleanupCallHistory() {
+        const cutoffTime = Date.now() - this.config.statisticsWindowSize;
+        const originalLength = this.callHistory.length;
+        this.callHistory = this.callHistory.filter((call) => call.timestamp >= cutoffTime);
+        const removed = originalLength - this.callHistory.length;
+        if (removed > 0) {
+            mcpLogger.debug(`[CircuitBreaker:${this.name}] Cleaned up ${removed} old call records`);
+        }
+    }
+    /**
+     * Get current statistics
+     */
+    getStats() {
+        const windowStart = Date.now() - this.config.statisticsWindowSize;
+        const windowCalls = this.callHistory.filter((call) => call.timestamp >= windowStart);
+        const successfulCalls = windowCalls.filter((call) => call.success).length;
+        const failedCalls = windowCalls.length - successfulCalls;
+        const failureRate = windowCalls.length > 0 ? failedCalls / windowCalls.length : 0;
+        return {
+            state: this.state,
+            totalCalls: this.callHistory.length,
+            successfulCalls: this.callHistory.filter((call) => call.success).length,
+            failedCalls: this.callHistory.filter((call) => !call.success).length,
+            failureRate,
+            windowCalls: windowCalls.length,
+            lastStateChange: this.lastStateChange,
+            nextRetryTime: this.state === "open"
+                ? new Date(this.lastFailureTime + this.config.resetTimeout)
+                : undefined,
+            halfOpenCalls: this.halfOpenCalls,
+        };
+    }
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset() {
+        this.changeState("closed", "Manual reset");
+        this.callHistory = [];
+        this.lastFailureTime = 0;
+        this.halfOpenCalls = 0;
+    }
+    /**
+     * Force open the circuit breaker
+     */
+    forceOpen(reason = "Manual force open") {
+        this.changeState("open", reason);
+        this.lastFailureTime = Date.now();
+    }
+    /**
+     * Get circuit breaker name
+     */
+    getName() {
+        return this.name;
+    }
+    /**
+     * Check if circuit is open
+     */
+    isOpen() {
+        return this.state === "open";
+    }
+    /**
+     * Check if circuit is closed
+     */
+    isClosed() {
+        return this.state === "closed";
+    }
+    /**
+     * Check if circuit is half-open
+     */
+    isHalfOpen() {
+        return this.state === "half-open";
+    }
+}
+/**
+ * Circuit breaker manager for multiple circuit breakers
+ */
+export class CircuitBreakerManager {
+    breakers = new Map();
+    /**
+     * Get or create a circuit breaker
+     */
+    getBreaker(name, config) {
+        if (!this.breakers.has(name)) {
+            const breaker = new MCPCircuitBreaker(name, config);
+            this.breakers.set(name, breaker);
+            mcpLogger.debug(`[CircuitBreakerManager] Created circuit breaker: ${name}`);
+        }
+        return this.breakers.get(name);
+    }
+    /**
+     * Remove a circuit breaker
+     */
+    removeBreaker(name) {
+        const removed = this.breakers.delete(name);
+        if (removed) {
+            mcpLogger.debug(`[CircuitBreakerManager] Removed circuit breaker: ${name}`);
+        }
+        return removed;
+    }
+    /**
+     * Get all circuit breaker names
+     */
+    getBreakerNames() {
+        return Array.from(this.breakers.keys());
+    }
+    /**
+     * Get statistics for all circuit breakers
+     */
+    getAllStats() {
+        const stats = {};
+        for (const [name, breaker] of this.breakers) {
+            stats[name] = breaker.getStats();
+        }
+        return stats;
+    }
+    /**
+     * Reset all circuit breakers
+     */
+    resetAll() {
+        for (const breaker of this.breakers.values()) {
+            breaker.reset();
+        }
+        mcpLogger.info("[CircuitBreakerManager] Reset all circuit breakers");
+    }
+    /**
+     * Get health summary
+     */
+    getHealthSummary() {
+        let closedBreakers = 0;
+        let openBreakers = 0;
+        let halfOpenBreakers = 0;
+        const unhealthyBreakers = [];
+        for (const [name, breaker] of this.breakers) {
+            const stats = breaker.getStats();
+            switch (stats.state) {
+                case "closed":
+                    closedBreakers++;
+                    break;
+                case "open":
+                    openBreakers++;
+                    unhealthyBreakers.push(name);
+                    break;
+                case "half-open":
+                    halfOpenBreakers++;
+                    break;
+            }
+        }
+        return {
+            totalBreakers: this.breakers.size,
+            closedBreakers,
+            openBreakers,
+            halfOpenBreakers,
+            unhealthyBreakers,
+        };
+    }
+}
+// Global circuit breaker manager instance
+export const globalCircuitBreakerManager = new CircuitBreakerManager();

package/dist/lib/mcp/mcpClientFactory.d.ts

@@ -0,0 +1,104 @@
+/**
+ * MCP Client Factory
+ * Creates and manages MCP clients for external servers
+ * Supports stdio, SSE, and WebSocket transports
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { ClientCapabilities } from "@modelcontextprotocol/sdk/types.js";
+import { ChildProcess } from "child_process";
+import type { ExternalMCPServerConfig, MCPTransportType } from "../types/externalMcp.js";
+/**
+ * MCP client creation result
+ */
+export interface MCPClientResult {
+    /** Whether client creation was successful */
+    success: boolean;
+    /** Created client instance */
+    client?: Client;
+    /** Created transport instance */
+    transport?: Transport;
+    /** Created process (for stdio transport) */
+    process?: ChildProcess;
+    /** Error message if failed */
+    error?: string;
+    /** Creation duration in milliseconds */
+    duration: number;
+    /** Server capabilities reported during handshake */
+    capabilities?: ClientCapabilities;
+}
+/**
+ * MCPClientFactory
+ * Factory class for creating MCP clients with different transports
+ */
+export declare class MCPClientFactory {
+    private static readonly NEUROLINK_IMPLEMENTATION;
+    private static readonly DEFAULT_CAPABILITIES;
+    /**
+     * Create an MCP client for the given server configuration
+     */
+    static createClient(config: ExternalMCPServerConfig, timeout?: number): Promise<MCPClientResult>;
+    /**
+     * Internal client creation logic
+     */
+    private static createClientInternal;
+    /**
+     * Create transport based on configuration
+     */
+    private static createTransport;
+    /**
+     * Create stdio transport with process spawning
+     */
+    private static createStdioTransport;
+    /**
+     * Create SSE transport
+     */
+    private static createSSETransport;
+    /**
+     * Create WebSocket transport
+     */
+    private static createWebSocketTransport;
+    /**
+     * Perform MCP handshake and get server capabilities
+     */
+    private static performHandshake;
+    /**
+     * Get server information
+     */
+    private static getServerInfo;
+    /**
+     * Extract capabilities from server info
+     */
+    private static extractCapabilities;
+    /**
+     * Create a timeout promise
+     */
+    private static createTimeoutPromise;
+    /**
+     * Close an MCP client and clean up resources
+     */
+    static closeClient(client: Client, transport: Transport, process?: ChildProcess): Promise<void>;
+    /**
+     * Test connection to an MCP server
+     */
+    static testConnection(config: ExternalMCPServerConfig, timeout?: number): Promise<{
+        success: boolean;
+        error?: string;
+        capabilities?: ClientCapabilities;
+    }>;
+    /**
+     * Validate MCP server configuration for client creation
+     */
+    static validateClientConfig(config: ExternalMCPServerConfig): {
+        isValid: boolean;
+        errors: string[];
+    };
+    /**
+     * Get supported transport types
+     */
+    static getSupportedTransports(): MCPTransportType[];
+    /**
+     * Get default client capabilities
+     */
+    static getDefaultCapabilities(): ClientCapabilities;
+}