Building Dynamic MCP Fallbacks and Self-Healing Handshakes

graph TD
    subgraph Stage 1: Transport Lifecycle
        SSEDrop[SSE Stream Severed / TCP Reset] --> Reconnect[Exponential Backoff + Jitter Reconnect]
    end

    subgraph Stage 2: Negotiation Lifecycle
        SchemaDrift[Tool Renamed / -32601 Method Not Found] --> Refresh[Force tools/list Refresh & Alias Resolution]
        InvalidArgs[-32602 Invalid Params] --> SchemaHeal[Synthesize Schema Error Hint for LLM]
    end

    subgraph Stage 3: Execution Lifecycle
        Server500[-32603 Internal Error / Timeout] --> CircuitBreaker{Check Circuit Breaker}
        CircuitBreaker -->|Open| Fallback[Dispatch to Backup Tool / Cached Result]
        CircuitBreaker -->|Closed| Retry[Single Monitored Retry]
    end

{
  "jsonrpc": "2.0",
  "id": "call-184",
  "error": {
    "code": -32602,
    "message": "Invalid params: Missing required property 'target_table'. Unknown property 'table_name' provided.",
    "data": {
      "expected_schema": {
        "required": ["target_table"],
        "properties": {
          "target_table": { "type": "string" }
        }
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "call-184",
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Self-Correction Hint: Parameter schema for 'inspect_table' has changed. Replace argument 'table_name' with 'target_table'. Please re-invoke with corrected parameters."
      }
    ]
  }
}

import EventEmitter from 'events';

export interface McpClientOptions {
  maxRetries: number;
  baseDelayMs: number;
  maxDelayMs: number;
  circuitFailureThreshold: number;
  circuitResetTimeoutMs: number;
}

export class ResilientMcpClient extends EventEmitter {
  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';
  private failureCount = 0;
  private nextAttemptTimestamp = 0;
  private options: McpClientOptions;

  constructor(options: Partial<McpClientOptions> = {}) {
    super();
    this.options = {
      maxRetries: 3,
      baseDelayMs: 500,
      maxDelayMs: 8000,
      circuitFailureThreshold: 5,
      circuitResetTimeoutMs: 30000,
      ...options
    };
  }

  // 1. Invocation with Circuit Breaker and Auto-Retry
  async callToolWithRecovery(
    toolName: string,
    args: Record<string, any>,
    fallbackHandler?: (tool: string, args: any) => Promise<any>
  ): Promise<any> {
    // Check Circuit Breaker State
    if (this.state === 'OPEN') {
      if (Date.now() > this.nextAttemptTimestamp) {
        this.state = 'HALF_OPEN';
        console.warn(`[CircuitBreaker] Transitioning to HALF_OPEN for tool: ${toolName}`);
      } else {
        console.warn(`[CircuitBreaker] Circuit is OPEN. Triggering fallback for: ${toolName}`);
        if (fallbackHandler) return fallbackHandler(toolName, args);
        throw new Error(`CircuitBreaker: Service for tool '${toolName}' is temporarily unavailable.`);
      }
    }

    let attempt = 0;
    while (attempt <= this.options.maxRetries) {
      try {
        const result = await this.executeRawRpc('tools/call', { name: toolName, arguments: args });
        this.recordSuccess();
        return result;
      } catch (err: any) {
        attempt++;
        const isTransient = this.isTransientError(err);

        if (!isTransient || attempt > this.options.maxRetries) {
          this.recordFailure();
          if (fallbackHandler) {
            console.log(`[Failover] Primary failed. Dispatching fallback handler for ${toolName}.`);
            return fallbackHandler(toolName, args);
          }
          throw err;
        }

        const delay = this.calculateJitterDelay(attempt);
        console.warn(`[Retry] Transient error on ${toolName}. Retrying in ${delay}ms (Attempt ${attempt}/${this.options.maxRetries})`);
        await new Promise((resolve) => setTimeout(resolve, delay));
      }
    }
  }

  private isTransientError(err: any): boolean {
    // Network disconnects, timeouts, and JSON-RPC internal errors (-32603)
    if (err.code === 'ECONNRESET' || err.code === 'ETIMEDOUT') return true;
    if (err.rpcCode === -32603 || err.rpcCode === -32000) return true;
    return false;
  }

  private calculateJitterDelay(attempt: number): number {
    const exponential = Math.min(this.options.maxDelayMs, this.options.baseDelayMs * Math.pow(2, attempt));
    const jitter = exponential * 0.2 * Math.random();
    return Math.floor(exponential + jitter);
  }

  private recordSuccess() {
    this.failureCount = 0;
    this.state = 'CLOSED';
  }

  private recordFailure() {
    this.failureCount++;
    if (this.failureCount >= this.options.circuitFailureThreshold) {
      this.state = 'OPEN';
      this.nextAttemptTimestamp = Date.now() + this.options.circuitResetTimeoutMs;
      console.error(`[CircuitBreaker] TRIP: Circuit is now OPEN until ${new Date(this.nextAttemptTimestamp).toISOString()}`);
    }
  }

  // Simulated Raw Transport Hook
  private async executeRawRpc(method: string, params: any): Promise<any> {
    // Actual SSE / HTTP POST transport call goes here
    return { content: [{ type: 'text', text: 'Execution successful' }] };
  }
}