@yusufffararatt/dombridge-mcp 2.7.5

package/src/bridge-daemon.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+/**
+ * Bridge Daemon — Standalone HTTP Bridge Process
+ *
+ * Phase 2.1: Runs the HTTP bridge (port 3101) independently from the MCP client.
+ * The MCP client connects to this daemon via HTTP instead of managing its own bridge.
+ *
+ * Lifecycle:
+ * - Started by MCP client (auto-spawn) or manually via `npm run bridge`
+ * - Survives MCP client restarts — extension connections are NOT lost
+ * - Graceful shutdown on SIGTERM/SIGINT with state persistence
+ * - PID file at mcp-server/state/bridge.pid for tracking
+ *
+ * Architecture:
+ * - Manages extensionData (in-memory + disk persistence)
+ * - Serves all /api/* routes for extension communication
+ * - NO MCP stdio transport — that's the client's responsibility
+ * - NO /api/die kill logic — this daemon decides when to exit
+ */
+
+import { readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+import { extensionData } from './state/extension-state.js';
+import { loadPersistedState, persistStateNow } from './state/bridge-persistence.js';
+import { createHttpServer, startHttpServer, connectionHealth } from './bridge/http-server.js';
+import { MetricsDB } from './metrics/metrics-db.js';
+
+// Metrics DB for lifecycle events
+const metricsDB = new MetricsDB();
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const { version: _mcpVersion } = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+const HTTP_PORT = parseInt(process.env.MCP_PORT || process.env.PORT || '3101', 10);
+const PID_FILE = join(__dirname, '..', 'state', 'bridge.pid');
+
+// ============================================================================
+// PID FILE MANAGEMENT
+// ============================================================================
+
+function writePidFile() {
+  try {
+    writeFileSync(PID_FILE, String(process.pid), 'utf8');
+  } catch (err) {
+    console.error(`[Bridge Daemon] Failed to write PID file: ${err.message}`);
+  }
+}
+
+function removePidFile() {
+  try {
+    unlinkSync(PID_FILE);
+  } catch {
+    // File may not exist, that's fine
+  }
+}
+
+// ============================================================================
+// STARTUP
+// ============================================================================
+
+async function start() {
+  console.error(`[Bridge Daemon] v${_mcpVersion} starting on port ${HTTP_PORT} (standalone mode)`);
+  console.error(`[Bridge Daemon] PID: ${process.pid}`);
+
+  // Load persisted state from disk
+  const stateLoaded = loadPersistedState(extensionData);
+  if (stateLoaded) {
+    console.error('[Bridge Daemon] Restored previous state from disk');
+  }
+
+  // Bind connection health
+  extensionData._connectionHealth = connectionHealth;
+
+  // Create and start HTTP server
+  const app = createHttpServer(HTTP_PORT);
+  const { httpServer } = await startHttpServer(app, HTTP_PORT, extensionData);
+
+  if (!httpServer) {
+    console.error('[Bridge Daemon] Failed to start HTTP server (port in use?). Exiting.');
+    process.exit(1);
+  }
+
+  // Write PID file for tracking
+  writePidFile();
+
+  // Record bridge_spawn lifecycle event
+  metricsDB.recordConnectionEvent({
+    event_type: 'bridge_spawn',
+    failure_reason: `v${_mcpVersion}`,
+    metadata: JSON.stringify({ port: HTTP_PORT, pid: process.pid }),
+  });
+
+  console.error(`[Bridge Daemon] HTTP bridge running on port ${HTTP_PORT}`);
+  console.error('[Bridge Daemon] Press Ctrl+C to stop gracefully');
+
+  // ============================================================================
+  // GRACEFUL SHUTDOWN
+  // ============================================================================
+
+  let isShuttingDown = false;
+
+  const shutdown = (signal) => {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+
+    console.error(`[Bridge Daemon] ${signal} received — shutting down gracefully...`);
+
+    // Persist state before exit
+    try {
+      persistStateNow(extensionData);
+      console.error('[Bridge Daemon] State persisted before shutdown');
+    } catch (err) {
+      console.error(`[Bridge Daemon] Failed to persist state: ${err.message}`);
+    }
+
+    // Remove PID file
+    removePidFile();
+
+    // Close HTTP server
+    if (httpServer) {
+      httpServer.close(() => {
+        console.error('[Bridge Daemon] HTTP server closed');
+        process.exit(0);
+      });
+
+      // Force exit after 5 seconds
+      setTimeout(() => {
+        console.error('[Bridge Daemon] Forced exit after 5s timeout');
+        process.exit(0);
+      }, 5000);
+    } else {
+      process.exit(0);
+    }
+  };
+
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+
+  // Windows compatibility
+  if (process.platform === 'win32') {
+    process.on('SIGHUP', () => shutdown('SIGHUP'));
+  }
+
+  // Handle uncaught errors
+  process.on('uncaughtException', (err) => {
+    console.error(`[Bridge Daemon] Uncaught exception: ${err.message}`);
+    console.error(err.stack);
+    // Record bridge_crash lifecycle event
+    metricsDB.recordConnectionEvent({
+      event_type: 'bridge_crash',
+      failure_reason: err.message.slice(0, 200),
+      metadata: JSON.stringify({ exit_code: 1 }),
+    });
+    // Try to persist state before crashing
+    try { persistStateNow(extensionData); } catch { /* ignore */ }
+    removePidFile();
+    process.exit(1);
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    console.error(`[Bridge Daemon] Unhandled rejection: ${reason}`);
+  });
+}
+
+start().catch((err) => {
+  console.error(`[Bridge Daemon] Fatal error: ${err.message}`);
+  removePidFile();
+  process.exit(1);
+});

package/src/cli/auto-config.js

@@ -0,0 +1,120 @@
+/* eslint-disable no-console */
+/**
+ * Auto-Config Module
+ * Automatically adds this MCP server to AI agent config files
+ * Supports: Claude Desktop, Cursor, Windsurf, generic MCP configs
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir, platform } from 'node:os';
+
+const SUPPORTED_CONFIGS = [
+    {
+        name: 'Claude Desktop',
+        getPaths() {
+            const home = homedir();
+            if (platform() === 'win32') {
+                return [join(home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json')];
+            } else if (platform() === 'darwin') {
+                return [join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')];
+            }
+            return [join(home, '.config', 'claude', 'claude_desktop_config.json')];
+        },
+    },
+    {
+        name: 'Cursor',
+        getPaths() {
+            const home = homedir();
+            if (platform() === 'win32') {
+                return [join(home, '.cursor', 'mcp.json')];
+            }
+            return [join(home, '.cursor', 'mcp.json')];
+        },
+    },
+    {
+        name: 'Windsurf (Codeium)',
+        getPaths() {
+            const home = homedir();
+            return [join(home, '.codeium', 'windsurf', 'mcp_config.json')];
+        },
+    },
+    {
+        name: 'Google Antigravity',
+        getPaths() {
+            return [join(homedir(), '.gemini', 'antigravity', 'mcp_config.json')];
+        },
+    },
+];
+
+const MCP_ENTRY_KEY = 'dombridge';
+
+function getMcpServerEntry() {
+    return {
+        command: 'npx',
+        args: ['-y', '@yusufffararatt/dombridge-mcp'],
+    };
+}
+
+function mergeConfig(existingContent) {
+    let config;
+    try {
+        config = JSON.parse(existingContent);
+    } catch {
+        config = {};
+    }
+
+    if (!config.mcpServers) {
+        config.mcpServers = {};
+    }
+
+    const alreadyExists = !!config.mcpServers[MCP_ENTRY_KEY];
+    config.mcpServers[MCP_ENTRY_KEY] = getMcpServerEntry();
+
+    return { config, alreadyExists };
+}
+
+export async function runAutoConfig(pkg) {
+    console.log(`\n  🔧 ${pkg.name} v${pkg.version} — Auto-Config\n`);
+
+    let configured = 0;
+    let skipped = 0;
+
+    for (const target of SUPPORTED_CONFIGS) {
+        const paths = target.getPaths();
+
+        for (const configPath of paths) {
+            const dirPath = dirname(configPath);
+
+            if (!existsSync(dirPath)) {
+                console.log(`  ⏭  ${target.name}: config directory not found, skipping`);
+                skipped++;
+                continue;
+            }
+
+            let existingContent = '{}';
+            if (existsSync(configPath)) {
+                existingContent = readFileSync(configPath, 'utf-8');
+            }
+
+            const { config, alreadyExists } = mergeConfig(existingContent);
+
+            if (alreadyExists) {
+                console.log(`  ✅ ${target.name}: already configured (updated)`);
+            } else {
+                console.log(`  ✅ ${target.name}: added successfully`);
+            }
+
+            writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            configured++;
+        }
+    }
+
+    console.log(`\n  📊 Result: ${configured} configured, ${skipped} skipped`);
+
+    if (configured > 0) {
+        console.log(`\n  ⚠️  Restart your AI agent (Claude/Cursor/Windsurf) to apply changes.`);
+    }
+
+    console.log('');
+}

package/src/constants.js

@@ -0,0 +1,13 @@
+/**
+ * MCP Server Constants
+ * Single source of truth for server-side configurable values.
+ *
+ * Extension mirror: modules/constants.js
+ * When changing MCP_PORT: update both files + manifest.json host_permissions.
+ */
+
+export const MCP_PORT = 3101;
+export const CONNECTION_STALE_TIMEOUT_MS = 60_000;
+export const STALE_MONITOR_CHECK_INTERVAL_MS = 20_000;
+export const HEALTH_CHECK_FETCH_TIMEOUT_MS = 2_000;
+export const CONNECTION_HEALTH_MAX_EVENTS = 20;

package/src/index.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+
+/**
+ * DOMBridge - MCP Thin Client
+ *
+ * Phase 2.2: MCP process is now a thin client that connects to the bridge daemon
+ * via HTTP. No direct extensionData access — all state goes through BridgeClient.
+ *
+ * Architecture:
+ *   AI Assistant ←stdio→ MCP Client (this file)
+ *                            │ HTTP (localhost:3101)
+ *                            ↓
+ *                     Bridge Daemon (bridge-daemon.js)
+ *                            ├── extensionData (IN-MEMORY + DISK)
+ *                            ├── HTTP Bridge ←→ Extension
+ *                            └── State persistence (JSON)
+ *
+ * Auto-spawn: If bridge daemon is not running, MCP client spawns it as a child process.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { readFileSync, unlinkSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { spawn } from 'child_process';
+import { logger } from './utils/logger.js';
+import { BridgeClient } from './state/bridge-client.js';
+import { getToolsList, getToolHandler } from './tools/index.js';
+import { MetricsDB } from './metrics/metrics-db.js';
+import { setMetricsDB } from './metrics/metrics-recorder.js';
+
+const __mcpDirname = dirname(fileURLToPath(import.meta.url));
+const MCP_ROOT = join(__mcpDirname, '..');
+const { version: _mcpVersion } = JSON.parse(readFileSync(join(MCP_ROOT, 'package.json'), 'utf8'));
+
+const HTTP_PORT = parseInt(process.env.MCP_PORT || process.env.PORT || '3101', 10);
+const PID_FILE = join(MCP_ROOT, 'state', 'bridge.pid');
+
+logger.info('Server', `v${_mcpVersion} starting (bridge port ${HTTP_PORT})`);
+if (_mcpVersion !== '2.7.5') {
+  logger.warn('Server', `Expected v2.7.5, running v${_mcpVersion}. Update: cd mcp-server && npm link`);
+}
+
+// ============================================================================
+// BRIDGE CONNECTION + AUTO-SPAWN
+// ============================================================================
+
+/**
+ * Check if bridge daemon is already running and healthy.
+ */
+async function checkBridgeHealth(port) {
+  try {
+    const response = await fetch(`http://localhost:${port}/health`, {
+      signal: AbortSignal.timeout(3000)
+    });
+    if (response.ok) {
+      return await response.json();
+    }
+  } catch {
+    // Not running or not reachable
+  }
+  return null;
+}
+
+/**
+ * Read PID file and check if process is alive.
+ */
+function checkStalePid() {
+  try {
+    const pid = parseInt(readFileSync(PID_FILE, 'utf8').trim(), 10);
+    if (isNaN(pid)) return false;
+
+    try {
+      process.kill(pid, 0); // Check if process exists (doesn't actually kill)
+      return true; // Process is alive
+    } catch {
+      // Process doesn't exist, stale PID
+      try { unlinkSync(PID_FILE); } catch { /* ignore */ }
+      return false;
+    }
+  } catch {
+    return false; // No PID file
+  }
+}
+
+/**
+ * Kill stale bridge process.
+ */
+function killStaleBridge(port) {
+  try {
+    fetch(`http://localhost:${port}/api/die`, { method: 'POST' }).catch(() => {});
+  } catch { /* ignore */ }
+}
+
+/**
+ * Spawn bridge daemon as a child process.
+ */
+function spawnBridge(port) {
+  logger.info('Server', `Spawning bridge daemon on port ${port}...`);
+
+  const bridgeProcess = spawn('node', ['src/bridge-daemon.js'], {
+    cwd: MCP_ROOT,
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, MCP_PORT: String(port) }
+  });
+  bridgeProcess.unref();
+
+  logger.info('Server', `Bridge daemon spawned (PID: ${bridgeProcess.pid})`);
+  return bridgeProcess;
+}
+
+/**
+ * Wait for bridge daemon to become healthy.
+ */
+async function waitForBridge(port, maxWaitMs = 5000) {
+  const startTime = Date.now();
+  const interval = 500;
+
+  while (Date.now() - startTime < maxWaitMs) {
+    await new Promise(resolve => setTimeout(resolve, interval));
+    const health = await checkBridgeHealth(port);
+    if (health) {
+      return health;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Ensure bridge daemon is running. If not, spawn it.
+ * Returns the BridgeClient instance.
+ */
+async function ensureBridgeRunning() {
+  // 1. Check if bridge is already running
+  const existingHealth = await checkBridgeHealth(HTTP_PORT);
+  if (existingHealth) {
+    logger.info('Server', `Bridge daemon already running on port ${HTTP_PORT}`);
+    return;
+  }
+
+  // 2. Check for stale PID
+  const isAlive = checkStalePid();
+  if (isAlive) {
+    logger.warn('Server', `Stale bridge process detected, killing...`);
+    killStaleBridge(HTTP_PORT);
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+
+  // 3. Spawn bridge daemon
+  spawnBridge(HTTP_PORT);
+
+  // 4. Wait for it to be ready
+  const health = await waitForBridge(HTTP_PORT, 5000);
+  if (!health) {
+    throw new Error(`Bridge daemon failed to start on port ${HTTP_PORT} within 5s`);
+  }
+
+  logger.info('Server', `Bridge daemon ready on port ${HTTP_PORT}`);
+}
+
+// ============================================================================
+// BRIDGE CLIENT INSTANCE
+// ============================================================================
+
+const bridgeClient = new BridgeClient(HTTP_PORT);
+
+// ============================================================================
+// MCP SERVER
+// ============================================================================
+
+const server = new Server(
+  {
+    name: 'dombridge',
+    version: _mcpVersion,
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+/**
+ * List Tools Handler
+ */
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: getToolsList()
+  };
+});
+
+/**
+ * Call Tool Handler
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    const handler = getToolHandler(name);
+
+    if (!handler) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `❌ Unknown tool: ${name}`
+          }
+        ],
+        isError: true
+      };
+    }
+
+    // Refresh bridge client state before each tool call
+    // so tool handlers can access fresh state synchronously
+    try {
+      await bridgeClient.refreshState();
+    } catch (err) {
+      logger.warn('Server', `Failed to refresh state from bridge: ${err.message}`);
+      // Continue with stale state — tool handlers should check isConnected
+    }
+
+    // Check if bridge has signaled a restart request — exit so Claude Code restarts us
+    if (bridgeClient.restartRequestedAt) {
+      logger.info('Server', `Bridge restart detected (signaled at ${new Date(bridgeClient.restartRequestedAt).toISOString()}). Exiting for restart.`);
+      process.exit(0);
+    }
+
+    // Call tool handler with bridgeClient instead of extensionData + httpPort
+    return await handler(args, bridgeClient);
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `❌ Error: ${error.message}`
+        }
+      ],
+      isError: true
+    };
+  }
+});
+
+// ============================================================================
+// START
+// ============================================================================
+
+async function main() {
+  // Ensure bridge daemon is running
+  await ensureBridgeRunning();
+
+  // Clear any pending restart signal (we are the fresh instance)
+  try {
+    await bridgeClient.refreshState();
+    if (bridgeClient.restartRequestedAt) {
+      logger.info('Server', 'Clearing restart signal from previous bridge restart');
+      await bridgeClient.post('clear-restart-signal');
+    }
+  } catch (err) {
+    logger.warn('Server', `Could not clear restart signal: ${err.message}`);
+    // Not critical — will be cleared on next tool call cycle
+  }
+
+  // Initialize metrics database
+  const metricsDB = new MetricsDB();
+  setMetricsDB(metricsDB);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  logger.info('Server', 'MCP client connected via stdio');
+}
+
+main().catch((error) => {
+  logger.error('Server', 'Fatal error:', error);
+  process.exit(1);
+});