@dynamicu/chromedebug-mcp 2.4.1 → 2.4.3

package/README.md

@@ -30,15 +30,62 @@ npm install
 
 ### As MCP Server
 
-To add Chrome Debug to your Claude desktop app:
+#### macOS / Linux
 
 ```bash
 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, 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
+```
+
+**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/chrome-extension/manifest.json

@@ -1,8 +1,8 @@
 {
   "manifest_version": 3,
-  "name": "ChromeDebug MCP Assistant v2.1.2",
-  "version": "2.1.2",
-  "description": "ChromeDebug MCP visual element selector with function tracing [Build: 2025-10-14-v2.1.2]",
+  "name": "ChromeDebug MCP Assistant v2.1.3",
+  "version": "2.1.3",
+  "description": "ChromeDebug MCP visual element selector with function tracing [Build: 2025-10-16-v2.1.3]",
   "permissions": [
     "activeTab",
     "scripting",

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@dynamicu/chromedebug-mcp",
-  "version": "2.4.1",
+  "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/scripts/package-webstore-extension.js

@@ -1,89 +1,118 @@
 #!/usr/bin/env node
-
-/**
- * Package FREE Chrome extension for Chrome Web Store distribution
- * Creates a .zip file optimized for Chrome Web Store submission
- */
-
-import { createWriteStream, promises as fs } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
 import archiver from 'archiver';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const rootDir = join(__dirname, '..');
-const freeExtensionDir = join(rootDir, 'scripts', 'dist', 'free');
-const outputDir = join(rootDir, 'dist');
-const outputFile = join(outputDir, 'chromedebug-webstore-free.zip');
-
-async function packageWebStoreExtension() {
-  console.log('📦 Building and packaging FREE Chrome extension for Web Store...');
-
-  // Step 1: Build the free version
-  console.log('🔨 Building free version...');
-  try {
-    execSync('npm run build:free', {
-      cwd: rootDir,
-      stdio: 'inherit'
-    });
-  } catch (error) {
-    console.error('❌ Failed to build free version');
-    throw error;
-  }
-
-  // Step 2: Verify the build output exists
-  try {
-    await fs.access(freeExtensionDir);
-  } catch {
-    throw new Error(`Build output not found at ${freeExtensionDir}`);
-  }
+const __dirname = path.dirname(__filename);
 
-  // Step 3: Ensure output directory exists
-  try {
-    await fs.mkdir(outputDir, { recursive: true });
-  } catch (error) {
-    // Directory might already exist, that's fine
-  }
+const projectRoot = path.join(__dirname, '..');
+const extensionDir = path.join(projectRoot, 'chrome-extension');
+const distDir = path.join(projectRoot, 'dist');
+const outputFile = path.join(distDir, 'chromedebug-extension-webstore.zip');
 
-  // Step 4: Create zip file optimized for Chrome Web Store
-  console.log('📦 Creating Chrome Web Store package...');
-
-  const output = createWriteStream(outputFile);
-  const archive = archiver('zip', {
-    zlib: { level: 9 }
-  });
-
-  return new Promise((resolve, reject) => {
-    output.on('close', () => {
-      const sizeKB = (archive.pointer() / 1024).toFixed(2);
-      console.log(`✅ Chrome Web Store package created successfully!`);
-      console.log(`   Size: ${sizeKB} KB`);
-      console.log(`   Location: ${outputFile}`);
-      console.log(`   📌 This is the FREE version for Chrome Web Store`);
-      console.log(`   🌐 Ready to upload to: https://chrome.google.com/webstore/devconsole`);
-      console.log(`\n📋 Next steps:`);
-      console.log(`   1. Go to Chrome Web Store Developer Dashboard`);
-      console.log(`   2. Upload this zip file`);
-      console.log(`   3. Fill in store listing details`);
-      console.log(`   4. Submit for review`);
-      resolve();
-    });
-
-    archive.on('error', reject);
-
-    archive.pipe(output);
-
-    // Add all files from the free build directory
-    // Chrome Web Store expects all files to be in the root of the zip
-    archive.directory(freeExtensionDir, false);
-
-    archive.finalize();
-  });
+// Ensure dist directory exists
+if (!fs.existsSync(distDir)) {
+  fs.mkdirSync(distDir, { recursive: true });
 }
 
-packageWebStoreExtension().catch(err => {
-  console.error('❌ Failed to package Chrome Web Store extension:', err);
-  process.exit(1);
+// Create output stream
+const output = fs.createWriteStream(outputFile);
+const archive = archiver('zip', { zlib: { level: 9 } });
+
+console.log('📦 Packaging Chrome extension for Web Store...');
+
+// Listen for archive events
+output.on('close', () => {
+  const sizeKB = (archive.pointer() / 1024).toFixed(2);
+  console.log(`✅ Extension packaged successfully!`);
+  console.log(`   File: ${outputFile}`);
+  console.log(`   Size: ${sizeKB} KB`);
+  console.log(`\n🚀 Ready to upload to Chrome Web Store!`);
+});
+
+archive.on('error', (err) => {
+  throw err;
+});
+
+// Pipe archive to output file
+archive.pipe(output);
+
+// Files to include in the extension (FREE version for Web Store)
+const filesToInclude = [
+  // Manifest (use FREE version and rename to manifest.json)
+  { source: 'manifest.free.json', target: 'manifest.json' },
+
+  // Background service worker
+  'background.js',
+  'chrome-session-manager.js',
+  'logger.js',
+  'extension-config.js',
+  'firebase-client.js',
+  'firebase-config.js',
+  'license-helper.js',
+
+  // Content scripts (from manifest)
+  'content.js',
+  'content.css',
+  'pako.min.js',
+  'web-vitals.iife.js',
+  'pii-redactor.js',
+  'data-buffer.js',
+  'performance-monitor.js',
+  'dom-tracker.js',
+  'network-tracker.js',
+
+  // Popup
+  'popup.html',
+  'popup.js',
+
+  // Options page
+  'options.html',
+  'options.js',
+
+  // Activation manager
+  'activation-manager.html',
+  'activation-manager.js',
+
+  // Offscreen
+  'offscreen.html',
+  'offscreen.js',
+
+  // Frame capture
+  'frame-capture.js',
+
+  // Icons
+  'icon16.png',
+  'icon48.png',
+  'icon128.png',
+
+  // Documentation
+  'README.md'
+];
+
+// Add each file to the archive
+filesToInclude.forEach(file => {
+  let sourcePath, targetName;
+
+  if (typeof file === 'object') {
+    // Handle object format { source: 'file.json', target: 'renamed.json' }
+    sourcePath = path.join(extensionDir, file.source);
+    targetName = file.target;
+  } else {
+    // Handle simple string format
+    sourcePath = path.join(extensionDir, file);
+    targetName = file;
+  }
+
+  if (fs.existsSync(sourcePath)) {
+    archive.file(sourcePath, { name: targetName });
+    console.log(`   ✓ ${targetName}${typeof file === 'object' ? ` (from ${file.source})` : ''}`);
+  } else {
+    console.warn(`   ⚠ Skipping missing file: ${typeof file === 'object' ? file.source : file}`);
+  }
 });
+
+// Finalize the archive
+archive.finalize();

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
       }
     }
 

package/src/services/process-manager.js

@@ -57,18 +57,30 @@ async function safeKillProcess(pid, signal = 'SIGTERM') {
 /**
  * Find ChromeDebug MCP processes using Node.js process list instead of shell commands
  * This prevents command injection while maintaining functionality
+ *
+ * NOTE: Windows support is intentionally limited - the ps command doesn't exist on Windows.
+ * Process cleanup is skipped on Windows to allow the server to start. A proper cross-platform
+ * solution will be implemented in a future update.
  */
 async function findChromePilotProcesses() {
+  // Skip process cleanup on Windows - ps command doesn't exist
+  // This allows the server to start on Windows without crashing
+  // TODO: Implement proper Windows process management using tasklist or Node.js process handles
+  if (process.platform === 'win32') {
+    console.log('[ChromeDebug] Process cleanup skipped on Windows (not yet implemented)');
+    return { pidsToKill: [], processDescriptions: [] };
+  }
+
   const currentPid = process.pid;
   const pidsToKill = [];
   const processDescriptions = [];
-  
+
   try {
     // Security: Use Node.js process list instead of shell commands
     // This approach uses the 'ps-list' module or similar safe approach
     // For now, we'll use a safer implementation with spawn instead of exec
     const { spawn } = await import('child_process');
-    
+
     return new Promise((resolve) => {
       const ps = spawn('ps', ['aux'], { stdio: ['ignore', 'pipe', 'ignore'] });
       let stdout = '';