mcp-twin 1.2.0

package/src/twin-manager.ts

@@ -0,0 +1,596 @@
+/**
+ * MCP Twin Manager - TypeScript Port
+ * Zero-downtime MCP server updates via twin/hot-swap architecture
+ */
+
+import { spawn, ChildProcess } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as net from 'net';
+import * as os from 'os';
+
+// Types
+type ServerSlot = 'a' | 'b';
+
+enum ServerState {
+  STOPPED = 'stopped',
+  STARTING = 'starting',
+  RUNNING = 'running',
+  FAILED = 'failed',
+  RELOADING = 'reloading'
+}
+
+interface TwinServer {
+  name: string;
+  scriptPath: string;
+  portA: number;
+  portB: number;
+  active: ServerSlot;
+  stateA: ServerState;
+  stateB: ServerState;
+  pidA: number | null;
+  pidB: number | null;
+  lastSwap: number | null;
+  reloadCount: number;
+  errorA: string | null;
+  errorB: string | null;
+}
+
+interface ServerConfig {
+  script: string;
+  ports: [number, number];
+  healthEndpoint: string;
+  startupTimeout: number;
+  python: string;
+}
+
+interface TwinConfig {
+  servers: Record<string, ServerConfig>;
+  settings: {
+    autoHealthCheck: boolean;
+    healthCheckInterval: number;
+    autoRestartOnFailure: boolean;
+    maxRestartAttempts: number;
+    startupWait: number;
+    shutdownTimeout: number;
+  };
+}
+
+interface TwinResult {
+  ok: boolean;
+  [key: string]: any;
+}
+
+// Paths
+const CONFIG_DIR = path.join(os.homedir(), '.mcp-twin');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const STATE_FILE = path.join(CONFIG_DIR, 'state.json');
+const LOG_DIR = path.join(CONFIG_DIR, 'logs');
+
+/**
+ * MCPTwinManager - Manages twin MCP servers for zero-downtime updates
+ */
+export class MCPTwinManager {
+  private twins: Map<string, TwinServer> = new Map();
+  private config: TwinConfig;
+  private processes: Map<string, ChildProcess> = new Map();
+
+  constructor() {
+    this.ensureDirs();
+    this.config = this.loadConfig();
+    this.restoreState();
+  }
+
+  private ensureDirs(): void {
+    [CONFIG_DIR, LOG_DIR].forEach(dir => {
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+    });
+  }
+
+  private loadConfig(): TwinConfig {
+    if (fs.existsSync(CONFIG_FILE)) {
+      try {
+        return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+      } catch {
+        return this.defaultConfig();
+      }
+    }
+    const config = this.defaultConfig();
+    this.saveConfig(config);
+    return config;
+  }
+
+  private defaultConfig(): TwinConfig {
+    return {
+      servers: {},  // Will be populated by auto-detect
+      settings: {
+        autoHealthCheck: true,
+        healthCheckInterval: 30,
+        autoRestartOnFailure: true,
+        maxRestartAttempts: 3,
+        startupWait: 2000,
+        shutdownTimeout: 5000
+      }
+    };
+  }
+
+  private saveConfig(config?: TwinConfig): void {
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config || this.config, null, 2));
+  }
+
+  private saveState(): void {
+    const state: Record<string, any> = {};
+    this.twins.forEach((twin, name) => {
+      state[name] = {
+        name: twin.name,
+        scriptPath: twin.scriptPath,
+        portA: twin.portA,
+        portB: twin.portB,
+        active: twin.active,
+        stateA: twin.stateA,
+        stateB: twin.stateB,
+        pidA: twin.pidA,
+        pidB: twin.pidB,
+        lastSwap: twin.lastSwap,
+        reloadCount: twin.reloadCount
+      };
+    });
+    fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+  }
+
+  private restoreState(): void {
+    if (!fs.existsSync(STATE_FILE)) return;
+
+    try {
+      const state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+      Object.entries(state).forEach(([name, data]: [string, any]) => {
+        // Verify processes are still alive
+        const stateA = data.pidA && this.processAlive(data.pidA)
+          ? ServerState.RUNNING : ServerState.STOPPED;
+        const stateB = data.pidB && this.processAlive(data.pidB)
+          ? ServerState.RUNNING : ServerState.STOPPED;
+
+        this.twins.set(name, {
+          ...data,
+          stateA,
+          stateB,
+          pidA: stateA === ServerState.RUNNING ? data.pidA : null,
+          pidB: stateB === ServerState.RUNNING ? data.pidB : null,
+          errorA: null,
+          errorB: null
+        });
+      });
+    } catch (err) {
+      console.error('[MCPTwin] Failed to restore state:', err);
+    }
+  }
+
+  private processAlive(pid: number): boolean {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private async healthCheck(port: number, pid?: number | null): Promise<boolean> {
+    // Check PID first (works for stdio MCP servers)
+    if (pid && this.processAlive(pid)) {
+      return true;
+    }
+
+    // TCP port check (works for HTTP servers)
+    return new Promise(resolve => {
+      const socket = new net.Socket();
+      socket.setTimeout(2000);
+
+      socket.on('connect', () => {
+        socket.destroy();
+        resolve(true);
+      });
+
+      socket.on('timeout', () => {
+        socket.destroy();
+        resolve(false);
+      });
+
+      socket.on('error', () => {
+        socket.destroy();
+        resolve(false);
+      });
+
+      socket.connect(port, 'localhost');
+    });
+  }
+
+  private startServer(script: string, port: number, serverName: string, slot: ServerSlot): number | null {
+    if (!fs.existsSync(script)) {
+      return null;
+    }
+
+    const logFile = path.join(LOG_DIR, `${serverName}_${slot}.log`);
+    const logStream = fs.createWriteStream(logFile, { flags: 'a' });
+
+    const cfg = this.config.servers[serverName] || {};
+    const pythonCmd = cfg.python || 'python3';
+
+    try {
+      // All twin servers run in HTTP mode for hot-swap support
+      const proc = spawn(pythonCmd, [script, '--http', '--port', String(port)], {
+        cwd: path.dirname(script),
+        detached: true,
+        stdio: ['ignore', logStream, logStream]
+      });
+
+      proc.unref();
+
+      const key = `${serverName}_${slot}`;
+      this.processes.set(key, proc);
+
+      return proc.pid || null;
+    } catch (err) {
+      console.error(`[MCPTwin] Failed to start ${serverName}_${slot}:`, err);
+      return null;
+    }
+  }
+
+  private async stopServer(pid: number | null, timeout: number = 5000): Promise<boolean> {
+    if (!pid || !this.processAlive(pid)) {
+      return true;
+    }
+
+    try {
+      process.kill(pid, 'SIGTERM');
+
+      // Wait for graceful shutdown
+      const start = Date.now();
+      while (Date.now() - start < timeout) {
+        if (!this.processAlive(pid)) {
+          return true;
+        }
+        await this.sleep(100);
+      }
+
+      // Force kill
+      process.kill(pid, 'SIGKILL');
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  // === PUBLIC API ===
+
+  async startTwins(serverName: string): Promise<TwinResult> {
+    if (!this.config.servers[serverName]) {
+      return {
+        ok: false,
+        error: `Unknown server: ${serverName}. Available: ${Object.keys(this.config.servers).join(', ')}`
+      };
+    }
+
+    if (this.twins.has(serverName)) {
+      const twin = this.twins.get(serverName)!;
+      if (twin.stateA === ServerState.RUNNING || twin.stateB === ServerState.RUNNING) {
+        return {
+          ok: false,
+          error: `Twins already running for ${serverName}. Use 'twin stop ${serverName}' first.`
+        };
+      }
+    }
+
+    const cfg = this.config.servers[serverName];
+    const script = cfg.script.replace('~', os.homedir());
+
+    if (!fs.existsSync(script)) {
+      return { ok: false, error: `Script not found: ${script}` };
+    }
+
+    const [portA, portB] = cfg.ports;
+    const startupWait = this.config.settings.startupWait;
+
+    // Start server A
+    const pidA = this.startServer(script, portA, serverName, 'a');
+    await this.sleep(startupWait);
+    const healthA = await this.healthCheck(portA, pidA);
+
+    // Start server B
+    const pidB = this.startServer(script, portB, serverName, 'b');
+    await this.sleep(startupWait);
+    const healthB = await this.healthCheck(portB, pidB);
+
+    const twin: TwinServer = {
+      name: serverName,
+      scriptPath: script,
+      portA,
+      portB,
+      active: 'a',
+      stateA: healthA ? ServerState.RUNNING : ServerState.FAILED,
+      stateB: healthB ? ServerState.RUNNING : ServerState.FAILED,
+      pidA,
+      pidB,
+      lastSwap: null,
+      reloadCount: 0,
+      errorA: healthA ? null : 'Health check failed',
+      errorB: healthB ? null : 'Health check failed'
+    };
+
+    this.twins.set(serverName, twin);
+    this.saveState();
+
+    return {
+      ok: healthA || healthB,
+      server: serverName,
+      active: `a (port ${portA})`,
+      standby: `b (port ${portB})`,
+      statusA: twin.stateA,
+      statusB: twin.stateB,
+      pidA,
+      pidB,
+      hint: "Use 'twin status' to check, 'twin reload' after code changes"
+    };
+  }
+
+  async reloadStandby(serverName: string): Promise<TwinResult> {
+    if (!this.twins.has(serverName)) {
+      return {
+        ok: false,
+        error: `No twins running for ${serverName}. Use 'twin start ${serverName}' first.`
+      };
+    }
+
+    const twin = this.twins.get(serverName)!;
+    const standby: ServerSlot = twin.active === 'a' ? 'b' : 'a';
+    const standbyPort = standby === 'b' ? twin.portB : twin.portA;
+    const standbyPid = standby === 'b' ? twin.pidB : twin.pidA;
+
+    // Mark as reloading
+    if (standby === 'b') {
+      twin.stateB = ServerState.RELOADING;
+    } else {
+      twin.stateA = ServerState.RELOADING;
+    }
+    this.saveState();
+
+    // Stop standby
+    if (standbyPid) {
+      await this.stopServer(standbyPid, this.config.settings.shutdownTimeout);
+    }
+
+    // Start new instance
+    const newPid = this.startServer(twin.scriptPath, standbyPort, serverName, standby);
+    await this.sleep(this.config.settings.startupWait);
+    const healthy = await this.healthCheck(standbyPort, newPid);
+
+    // Update state
+    if (standby === 'b') {
+      twin.pidB = newPid;
+      twin.stateB = healthy ? ServerState.RUNNING : ServerState.FAILED;
+      twin.errorB = healthy ? null : 'Health check failed after reload';
+    } else {
+      twin.pidA = newPid;
+      twin.stateA = healthy ? ServerState.RUNNING : ServerState.FAILED;
+      twin.errorA = healthy ? null : 'Health check failed after reload';
+    }
+
+    twin.reloadCount++;
+    this.saveState();
+
+    return {
+      ok: healthy,
+      server: serverName,
+      reloaded: `standby (${standby}) on port ${standbyPort}`,
+      healthy,
+      newPid,
+      reloadCount: twin.reloadCount,
+      hint: healthy
+        ? `Standby ready. Use 'twin swap ${serverName}' to switch traffic.`
+        : `Health check failed. Check logs: ${path.join(LOG_DIR, `${serverName}_${standby}.log`)}`
+    };
+  }
+
+  async swapActive(serverName: string): Promise<TwinResult> {
+    if (!this.twins.has(serverName)) {
+      return { ok: false, error: `No twins running for ${serverName}` };
+    }
+
+    const twin = this.twins.get(serverName)!;
+    const newActive: ServerSlot = twin.active === 'a' ? 'b' : 'a';
+    const newPort = newActive === 'b' ? twin.portB : twin.portA;
+    const newState = newActive === 'b' ? twin.stateB : twin.stateA;
+
+    // Check standby is healthy
+    if (newState !== ServerState.RUNNING) {
+      return {
+        ok: false,
+        error: `Standby server (${newActive}) not healthy: ${newState}`,
+        hint: `Run 'twin reload ${serverName}' first to bring standby online`
+      };
+    }
+
+    const oldActive = twin.active;
+    const oldPort = oldActive === 'a' ? twin.portA : twin.portB;
+
+    // Swap
+    twin.active = newActive;
+    twin.lastSwap = Date.now();
+    this.saveState();
+
+    return {
+      ok: true,
+      server: serverName,
+      previousActive: `${oldActive} (port ${oldPort})`,
+      newActive: `${newActive} (port ${newPort})`,
+      swappedAt: twin.lastSwap,
+      hint: 'Traffic now routing to new active. Old server is now standby.'
+    };
+  }
+
+  async stopTwins(serverName: string): Promise<TwinResult> {
+    if (!this.twins.has(serverName)) {
+      return { ok: false, error: `No twins for ${serverName}` };
+    }
+
+    const twin = this.twins.get(serverName)!;
+    const timeout = this.config.settings.shutdownTimeout;
+
+    const stoppedA = await this.stopServer(twin.pidA, timeout);
+    const stoppedB = await this.stopServer(twin.pidB, timeout);
+
+    this.twins.delete(serverName);
+    this.saveState();
+
+    return {
+      ok: stoppedA && stoppedB,
+      server: serverName,
+      stopped: true,
+      stoppedA,
+      stoppedB
+    };
+  }
+
+  getActivePort(serverName: string): number | null {
+    const twin = this.twins.get(serverName);
+    if (!twin) return null;
+
+    if (twin.active === 'a' && twin.stateA === ServerState.RUNNING) {
+      return twin.portA;
+    } else if (twin.active === 'b' && twin.stateB === ServerState.RUNNING) {
+      return twin.portB;
+    }
+    return null;
+  }
+
+  async status(serverName?: string): Promise<TwinResult> {
+    if (serverName) {
+      if (!this.twins.has(serverName)) {
+        if (this.config.servers[serverName]) {
+          return {
+            ok: true,
+            server: serverName,
+            status: 'not_started',
+            hint: `Use 'twin start ${serverName}' to start twins`
+          };
+        }
+        return { ok: false, error: `Unknown server: ${serverName}` };
+      }
+
+      const twin = this.twins.get(serverName)!;
+      const healthA = await this.healthCheck(twin.portA, twin.pidA);
+      const healthB = await this.healthCheck(twin.portB, twin.pidB);
+
+      return {
+        ok: true,
+        server: serverName,
+        active: twin.active,
+        serverA: {
+          port: twin.portA,
+          state: twin.stateA,
+          pid: twin.pidA,
+          healthy: healthA,
+          isActive: twin.active === 'a'
+        },
+        serverB: {
+          port: twin.portB,
+          state: twin.stateB,
+          pid: twin.pidB,
+          healthy: healthB,
+          isActive: twin.active === 'b'
+        },
+        reloadCount: twin.reloadCount,
+        lastSwap: twin.lastSwap
+      };
+    }
+
+    // All twins
+    const twinsStatus: Record<string, any> = {};
+
+    for (const [name, twin] of this.twins) {
+      const healthA = await this.healthCheck(twin.portA, twin.pidA);
+      const healthB = await this.healthCheck(twin.portB, twin.pidB);
+
+      twinsStatus[name] = {
+        active: twin.active,
+        ports: [twin.portA, twin.portB],
+        states: [twin.stateA, twin.stateB],
+        healthy: [healthA, healthB],
+        reloadCount: twin.reloadCount
+      };
+    }
+
+    return {
+      ok: true,
+      twins: twinsStatus,
+      available: Object.keys(this.config.servers),
+      configPath: CONFIG_FILE
+    };
+  }
+
+  getConfig(): TwinResult {
+    return {
+      ok: true,
+      configPath: CONFIG_FILE,
+      config: this.config
+    };
+  }
+
+  addServer(name: string, script: string, ports: [number, number]): TwinResult {
+    const scriptPath = script.replace('~', os.homedir());
+
+    if (!fs.existsSync(scriptPath)) {
+      return { ok: false, error: `Script not found: ${scriptPath}` };
+    }
+
+    this.config.servers[name] = {
+      script: scriptPath,
+      ports,
+      healthEndpoint: '/health',
+      startupTimeout: 10,
+      python: 'python3'
+    };
+    this.saveConfig();
+
+    return {
+      ok: true,
+      added: name,
+      config: this.config.servers[name]
+    };
+  }
+
+  removeServer(name: string): TwinResult {
+    if (!this.config.servers[name]) {
+      return { ok: false, error: `Server not in config: ${name}` };
+    }
+
+    if (this.twins.has(name)) {
+      return {
+        ok: false,
+        error: `Server has running twins. Stop them first with 'twin stop ${name}'`
+      };
+    }
+
+    delete this.config.servers[name];
+    this.saveConfig();
+
+    return { ok: true, removed: name };
+  }
+}
+
+// Singleton
+let _twinManager: MCPTwinManager | null = null;
+
+export function getTwinManager(): MCPTwinManager {
+  if (!_twinManager) {
+    _twinManager = new MCPTwinManager();
+  }
+  return _twinManager;
+}
+
+export default MCPTwinManager;

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}