@dynamicu/chromedebug-mcp 2.4.2 → 2.4.3

package/README.md

@@ -36,19 +36,56 @@ npm install
 claude mcp add chromedebug -s user -- chromedebug-mcp
 ```
 
+The MCP server will automatically start both the stdio MCP server and HTTP server for Chrome extension integration.
+
 #### Windows
 
-On Windows, use `cmd /c` to properly execute the server:
+On Windows, the MCP server and HTTP server should be run separately for best reliability:
 
+**Step 1: Add MCP Server for Claude Code**
 ```bash
 claude mcp add chromedebug -s user -- cmd /c chromedebug-mcp
 ```
 
-**Note for Windows Users:** Process cleanup is currently limited on Windows. The server will start successfully but won't clean up orphaned processes from previous sessions. A full cross-platform process management solution is planned for a future release.
+**Step 2: Start HTTP Server for Chrome Extension (separate terminal)**
+```bash
+chromedebug-mcp-server
+```
+
+**Why Separate?** On Windows, the stdio-based MCP server (for Claude Code) works best when running independently from the HTTP server (for Chrome extension). This separation provides better stability and prevents connection issues.
+
+**Note for Windows Users:**
+- Process cleanup is currently limited on Windows. The server will start successfully but won't clean up orphaned processes from previous sessions.
+- If you only need Claude Code integration (no Chrome extension), the MCP server alone is sufficient.
+- If you need the Chrome extension, run both servers in separate terminal windows.
+
+### Standalone HTTP Server (New in v2.4.3)
+
+For Windows users or those who prefer to run services separately, you can start the HTTP server independently:
+
+```bash
+# Start HTTP server only (no MCP)
+chromedebug-mcp-server
+
+# With options
+chromedebug-mcp-server --verbose --port 3000
+```
+
+**Available Options:**
+- `--port PORT` - Specify HTTP server port (optional, auto-discovers if not set)
+- `--verbose` - Enable verbose logging
+- `--debug` - Enable debug mode
+- `--no-cleanup` - Skip process cleanup on startup
+- `--session-id ID` - Set custom session ID
+
+**Use Cases:**
+- Windows users who want Chrome extension support without running full MCP server
+- Development environments where you want HTTP server running persistently
+- Situations where MCP and HTTP servers should run in separate processes
 
 ### Embedded HTTP Server
 
-Chrome Debug automatically starts an embedded HTTP server for Chrome extension communication. The server uses ports configured in `config/chrome-pilot-config.json` (default: 3001, 3000, 3002, 3028). The server provides these REST API endpoints:
+Chrome Debug can automatically start an embedded HTTP server for Chrome extension communication. The server uses ports configured in `config/chrome-pilot-config.json` (default: 3001, 3000, 3002, 3028). The server provides these REST API endpoints:
 
 | Endpoint | Method | Description | Body |
 |----------|--------|-------------|------|

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@dynamicu/chromedebug-mcp",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "ChromeDebug MCP - MCP server that provides full control over a Chrome browser instance for debugging and automation with AI assistants like Claude Code",
   "main": "src/index.js",
   "type": "module",
   "bin": {
-    "chromedebug-mcp": "./src/cli.js"
+    "chromedebug-mcp": "./src/cli.js",
+    "chromedebug-mcp-server": "./src/cli-http.js"
   },
   "publishConfig": {
     "access": "public"

package/src/cli-http.js

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+
+/**
+ * ChromeDebug HTTP Server CLI
+ * Standalone HTTP server for Chrome extension integration
+ * Does not start MCP stdio server - only HTTP API server
+ */
+
+import { ChromeController } from './chrome-controller.js';
+import { ChromeService } from './services/chrome-service.js';
+import { ProcessManager } from './services/process-manager.js';
+import {
+  initializeSessionManager,
+  getSessionInfo,
+  registerProcess
+} from './services/unified-session-manager.js';
+import logger from './utils/logger.js';
+
+/**
+ * Standalone HTTP Server Application
+ * Provides Chrome extension API without MCP stdio interface
+ */
+class ChromeDebugHttpServer {
+  constructor() {
+    this.chromeController = null;
+    this.chromeService = null;
+    this.processManager = null;
+    this.sessionManager = null;
+    this.initialized = false;
+  }
+
+  /**
+   * Initializes HTTP server components
+   * @param {Object} options - Initialization options
+   */
+  async initialize(options = {}) {
+    try {
+      // Parse command line arguments
+      const args = this.parseArguments();
+      const finalOptions = { ...options, ...args };
+
+      logger.info('🚀 Starting ChromeDebug HTTP Server (Extension API)...');
+
+      // Create Chrome controller instance
+      this.chromeController = new ChromeController();
+
+      // Create Chrome service wrapper with process management
+      this.chromeService = new ChromeService(this.chromeController);
+      this.processManager = this.chromeService.getProcessManager();
+
+      // Initialize Chrome service with HTTP server REQUIRED
+      const serviceResult = await this.chromeService.initialize({
+        ...finalOptions,
+        startHttp: true, // Force HTTP server on
+        singleServer: false, // Ensure HTTP starts
+        sessionManager: this.sessionManager
+      });
+
+      if (serviceResult.httpServer) {
+        logger.info(`✅ HTTP Server Started Successfully`);
+        logger.info(`   Port: ${serviceResult.httpServer.port}`);
+        logger.info(`   Status: ${serviceResult.httpServer.status}`);
+        logger.info('');
+        logger.info('📍 Chrome Extension Connection:');
+        logger.info(`   Use port ${serviceResult.httpServer.port} in extension settings`);
+        logger.info('');
+        logger.info('💡 Server is ready for Chrome extension connections');
+      } else {
+        logger.error('❌ HTTP Server Failed to Start');
+        if (serviceResult.httpServer?.error) {
+          logger.error(`   Error: ${serviceResult.httpServer.error}`);
+        }
+        throw new Error('HTTP server initialization failed');
+      }
+
+      this.initialized = true;
+      return {
+        status: 'initialized',
+        options: finalOptions,
+        serviceResult
+      };
+    } catch (error) {
+      logger.error('Failed to initialize ChromeDebug HTTP Server:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Starts the HTTP server and keeps it running
+   */
+  async start() {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+
+    try {
+      // Clean up any existing ChromeDebug processes (optional, controlled by flag)
+      const args = this.parseArguments();
+      if (!args.noCleanup) {
+        const cleanupResult = await this.processManager.cleanupChromePilotProcesses();
+        if (cleanupResult.total > 0) {
+          logger.debug(`Cleaned up ${cleanupResult.killed.length} existing processes`);
+        }
+      }
+
+      // Keep the server alive
+      logger.info('🔄 HTTP Server is running. Press Ctrl+C to stop.');
+
+      // Prevent process from exiting
+      process.stdin.resume();
+
+    } catch (error) {
+      logger.error('Failed to start ChromeDebug HTTP Server:', error);
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Parses command line arguments
+   * @returns {Object} Parsed arguments
+   */
+  parseArguments() {
+    const args = {
+      debug: false,
+      sessionId: null,
+      noCleanup: false,
+      verbose: false,
+      port: null
+    };
+
+    const argv = process.argv.slice(2);
+    for (let i = 0; i < argv.length; i++) {
+      const arg = argv[i];
+
+      switch (arg) {
+        case '--debug':
+          args.debug = true;
+          break;
+        case '--session-id':
+          if (i + 1 < argv.length) {
+            args.sessionId = argv[++i];
+          } else {
+            logger.error('--session-id requires a value');
+            process.exit(1);
+          }
+          break;
+        case '--no-cleanup':
+          args.noCleanup = true;
+          break;
+        case '--verbose':
+          args.verbose = true;
+          break;
+        case '--port':
+          if (i + 1 < argv.length) {
+            args.port = parseInt(argv[++i], 10);
+          } else {
+            logger.error('--port requires a value');
+            process.exit(1);
+          }
+          break;
+        case '--help':
+          this.showHelp();
+          process.exit(0);
+          break;
+        default:
+          if (arg.startsWith('--session-id=')) {
+            args.sessionId = arg.split('=')[1];
+          } else if (arg.startsWith('--port=')) {
+            args.port = parseInt(arg.split('=')[1], 10);
+          } else if (arg.startsWith('--')) {
+            logger.error(`Unknown argument: ${arg}`);
+            this.showHelp();
+            process.exit(1);
+          }
+          break;
+      }
+    }
+
+    return args;
+  }
+
+  /**
+   * Shows help information
+   */
+  showHelp() {
+    console.log(`
+ChromeDebug HTTP Server - Standalone Chrome Extension API
+
+This server provides HTTP endpoints for Chrome extension integration.
+It does NOT start the MCP stdio server for Claude Code.
+
+Usage: chromedebug-mcp-server [options]
+
+Options:
+  --debug             Enable debug logging
+  --session-id ID     Set custom session ID for resource isolation
+  --no-cleanup        Skip cleanup of dead processes on startup
+  --verbose           Enable verbose logging including session info
+  --port PORT         Specify HTTP server port (optional, auto-discovers if not set)
+  --help              Show this help message
+
+Examples:
+  chromedebug-mcp-server
+  chromedebug-mcp-server --verbose --no-cleanup
+  chromedebug-mcp-server --port 3000
+  chromedebug-mcp-server --session-id extension-session-1
+
+Environment Variables:
+  NODE_ENV            Set to 'development' for debug mode
+  CHROME_PILOT_PORT   Configure HTTP server port
+
+What this server does:
+  ✓ Starts HTTP REST API for Chrome extension
+  ✓ Provides endpoints for screen recording uploads
+  ✓ Handles workflow recording and playback
+  ✓ Manages Chrome browser instances for extension
+
+What this server does NOT do:
+  ✗ Start MCP stdio server for Claude Code
+  ✗ Provide AI assistant integration
+
+For MCP integration, use: chromedebug-mcp
+
+For more information, see the documentation in README.md
+    `);
+  }
+
+  /**
+   * Graceful shutdown
+   */
+  async shutdown() {
+    logger.info('Shutting down ChromeDebug HTTP Server...');
+
+    try {
+      if (this.chromeService) {
+        await this.chromeService.cleanup();
+      }
+
+      if (this.processManager) {
+        await this.processManager.killAllManagedProcesses();
+      }
+
+      logger.info('HTTP Server shutdown complete');
+    } catch (error) {
+      logger.error('Error during shutdown:', error);
+    }
+  }
+}
+
+/**
+ * Main entry point
+ */
+async function main() {
+  const app = new ChromeDebugHttpServer();
+
+  // Parse arguments first to get session settings
+  const args = app.parseArguments();
+
+  try {
+    // Initialize unified session manager with options
+    const sessionManager = await initializeSessionManager({
+      sessionId: args.sessionId || 'http-server',
+      skipCleanup: args.noCleanup,
+      verbose: args.verbose
+    });
+
+    // Register this process for tracking
+    await registerProcess(process.pid, 'http-server');
+
+    // Log session information if verbose
+    if (args.verbose) {
+      const sessionInfo = getSessionInfo();
+      logger.debug('Session Information:');
+      logger.debug(`  Session ID: ${sessionInfo.sessionId}`);
+      logger.debug(`  PID: ${sessionInfo.pid}`);
+      logger.debug(`  Port: ${sessionInfo.port}`);
+      logger.debug(`  Session File: ${sessionInfo.sessionFile}`);
+    }
+
+    // Pass session manager to app
+    app.sessionManager = sessionManager;
+
+    await app.start();
+  } catch (error) {
+    logger.error('Fatal error starting ChromeDebug HTTP Server:', error);
+    process.exit(1);
+  }
+}
+
+// Handle graceful shutdown
+process.on('SIGINT', async () => {
+  logger.info('Received SIGINT, shutting down gracefully...');
+  process.exit(0);
+});
+
+process.on('SIGTERM', async () => {
+  logger.info('Received SIGTERM, shutting down gracefully...');
+  process.exit(0);
+});
+
+// Export for testing
+export { ChromeDebugHttpServer };
+
+// Run if this is the main module
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    logger.error('Unhandled error:', error);
+    process.exit(1);
+  });
+}

package/src/services/chrome-service.js

@@ -26,11 +26,13 @@ export class ChromeService {
 
   /**
    * Initializes the Chrome service with HTTP server if needed
+   * Windows-specific: HTTP server failures are non-fatal to prevent MCP crashes
    * @param {Object} options - Initialization options
    * @returns {Promise<Object>} Initialization result
    */
   async initialize(options = {}) {
     const { startHttp = true, singleServer = false, sessionManager = null } = options;
+    const isWindows = process.platform === 'win32';
 
     const result = {
       chromeService: 'initialized',
@@ -57,7 +59,16 @@ export class ChromeService {
           console.error('Falling back to port discovery');
         }
 
-        const { httpServer, serverPort } = await startHttpServer(this.chromeController, targetPort);
+        // Platform-specific timeout: Windows needs longer initialization time
+        const httpTimeout = isWindows ? 20000 : 10000;
+
+        // Start HTTP server with timeout protection
+        const httpServerPromise = startHttpServer(this.chromeController, targetPort);
+        const timeoutPromise = new Promise((_, reject) =>
+          setTimeout(() => reject(new Error(`HTTP server startup timeout after ${httpTimeout}ms`)), httpTimeout)
+        );
+
+        const { httpServer, serverPort } = await Promise.race([httpServerPromise, timeoutPromise]);
 
         this.httpServer = httpServer;
         this.httpServerPort = serverPort;
@@ -69,11 +80,25 @@ export class ChromeService {
 
         console.error(`HTTP server started on port ${serverPort}`);
       } catch (error) {
-        console.error('Failed to start HTTP server:', error);
+        // IMPORTANT: HTTP server failures are non-fatal
+        // This prevents MCP server crashes when HTTP server can't start
+        const errorMessage = error.message || String(error);
+        console.error('⚠️  HTTP Server Initialization Failed (non-fatal):', errorMessage);
+
+        if (isWindows) {
+          console.error('ℹ️  On Windows, you can start the HTTP server separately:');
+          console.error('   npm run server');
+          console.error('   or: chromedebug-mcp-server');
+        }
+
         result.httpServer = {
-          error: error.message,
-          status: 'failed'
+          error: errorMessage,
+          status: 'failed',
+          platform: process.platform,
+          fatal: false // Explicitly mark as non-fatal
         };
+
+        // Do NOT throw - allow MCP server to continue without HTTP
       }
     }