@dynamicu/chromedebug-mcp 2.5.0 → 2.5.4

package/README.md

@@ -40,24 +40,52 @@ The MCP server will automatically start both the stdio MCP server and HTTP serve
 
 #### Windows
 
-On Windows, the MCP server and HTTP server should be run separately for best reliability:
+⚠️ **Important: WSL2 Recommended for Windows Users**
 
-**Step 1: Add MCP Server for Claude Code**
-```bash
-claude mcp add chromedebug -s user -- cmd /c chromedebug-mcp
-```
+ChromeDebug MCP uses stdio-based communication which works best on Unix systems. For Windows users, we **strongly recommend using WSL2** for full compatibility.
 
-**Step 2: Start HTTP Server for Chrome Extension (separate terminal)**
-```bash
-chromedebug-mcp-server
-```
+**WSL2 Setup (5 minutes):**
+
+1. **Install WSL2** (PowerShell as Administrator):
+   ```powershell
+   wsl --install
+   ```
+
+2. **Restart your computer**
 
-**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.
+3. **Open WSL terminal** and install Node.js:
+   ```bash
+   sudo apt update
+   sudo apt install nodejs npm -y
+   ```
+
+4. **Install ChromeDebug in WSL**:
+   ```bash
+   npm install -g @dynamicu/chromedebug-mcp
+   ```
+
+5. **Configure Claude Code** to use WSL:
+   ```bash
+   claude mcp add chromedebug -s user -- wsl chromedebug-mcp
+   ```
+
+6. **Verify it works**:
+   ```bash
+   claude mcp list
+   # Should show: chromedebug: wsl chromedebug-mcp - ✓ Connected
+   ```
+
+**Alternative: Native Windows (Limited Support)**
+
+If you cannot use WSL2, you can force native Windows mode, but stdio communication may be unreliable:
+
+```powershell
+# Set environment variable to enable native Windows mode
+set CHROMEDEBUG_FORCE_WINDOWS=1
+chromedebug-mcp --help
+```
 
-**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.
+**Note:** Native Windows may experience stdio communication issues due to cmd.exe limitations. WSL2 is strongly recommended for the best experience.
 
 ### Standalone HTTP Server (New in v2.4.3)
 

package/chrome-extension/extension-config.js

@@ -64,7 +64,7 @@ const CHROMEDEBUG_CONFIG = {
   3027
 ],
   discoveryTimeout: 3000,
-  lastGenerated: '2025-10-01T22:12:24.724Z'
+  lastGenerated: '2025-10-17T23:32:00.030Z'
 };
 
 // Export for use in extension scripts

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dynamicu/chromedebug-mcp",
-  "version": "2.5.0",
+  "version": "2.5.4",
   "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/index.js",
+    "chromedebug-mcp": "./src/cli.js",
     "chromedebug-mcp-server": "./src/standalone-server.js"
   },
   "publishConfig": {
@@ -116,7 +116,7 @@
     "joi": "^18.0.0",
     "jsonwebtoken": "^9.0.2",
     "multer": "^2.0.2",
-    "puppeteer": "^23.10.0",
+    "puppeteer": "^24.25.0",
     "uuid": "^11.1.0",
     "web-vitals": "^5.1.0",
     "ws": "^8.16.0"

package/scripts/diagnose-windows.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+/**
+ * Windows MCP Diagnostic Tool
+ * Helps identify why ChromeDebug MCP may not work on Windows
+ */
+
+console.error('=== ChromeDebug Windows Diagnostic ===\n');
+
+// Test 1: Environment
+console.error('1. Environment Check:');
+console.error('   Platform:', process.platform);
+console.error('   Node Version:', process.version);
+console.error('   argv[0]:', process.argv[0]);
+console.error('   argv[1]:', process.argv[1]);
+console.error('   CWD:', process.cwd());
+console.error('   WSL:', process.env.WSL_DISTRO_NAME || 'No (native Windows)');
+console.error('   Force Windows:', process.env.CHROMEDEBUG_FORCE_WINDOWS || 'No');
+console.error('');
+
+// Test 2: Module Detection
+console.error('2. Module Detection:');
+console.error('   import.meta.url:', import.meta.url);
+console.error('');
+
+// Test 3: Stdio Check
+console.error('3. Stdio Configuration:');
+console.error('   stdin.isTTY:', process.stdin.isTTY);
+console.error('   stdout.isTTY:', process.stdout.isTTY);
+console.error('   stderr.isTTY:', process.stderr.isTTY);
+console.error('');
+
+// Test 4: Recommendations
+console.error('4. Recommendations:');
+if (process.platform === 'win32' && !process.env.WSL_DISTRO_NAME) {
+  console.error('   ⚠️  Running on native Windows');
+  console.error('   ✓ Recommended: Install WSL2 for best compatibility');
+  console.error('   ✓ Quick setup: wsl --install');
+  console.error('   ✓ After WSL2: npm install -g @dynamicu/chromedebug-mcp');
+  console.error('   ✓ Configure Claude: claude mcp add chromedebug -s user -- wsl chromedebug-mcp');
+} else if (process.env.WSL_DISTRO_NAME) {
+  console.error('   ✅ Running in WSL2 - Full compatibility available');
+} else {
+  console.error('   ✅ Running on Unix-based system - Full compatibility available');
+}
+console.error('');
+
+console.error('For more information:');
+console.error('  https://github.com/dynamicupgrade/ChromeDebug#windows-setup');
+console.error('');
+
+// Exit successfully
+process.exit(0);

package/src/cli.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+/**
+ * Chrome Debug MCP Server - CLI Entry Point
+ *
+ * This file should only be executed directly as a CLI command.
+ * For library usage, import ChromePilotApp from './index.js'
+ *
+ * This separation ensures that importing the package as a library
+ * won't accidentally launch Chrome or start servers.
+ */
+
+import { ChromePilotApp } from './index.js';
+import {
+  initializeSessionManager,
+  getSessionInfo,
+  registerProcess,
+  findActiveSessions
+} from './services/unified-session-manager.js';
+import logger from './utils/logger.js';
+
+/**
+ * Main CLI entry point
+ */
+async function main() {
+  const app = new ChromePilotApp();
+
+  // Parse arguments first to get session settings
+  const args = app.parseArguments();
+
+  // Detect Windows and provide WSL2 guidance
+  if (process.platform === 'win32' && !process.env.WSL_DISTRO_NAME && !process.env.CHROMEDEBUG_FORCE_WINDOWS) {
+    console.error(`
+⚠️  ChromeDebug MCP runs best on Unix-based systems.
+
+Windows users have two options:
+
+1. WSL2 (RECOMMENDED - Full Compatibility):
+   • Install WSL2: Run in PowerShell as Admin:
+     wsl --install
+   • Restart your computer
+   • Inside WSL, install Node.js:
+     sudo apt update && sudo apt install nodejs npm
+   • Install ChromeDebug in WSL:
+     npm install -g @dynamicu/chromedebug-mcp
+   • Configure Claude to use WSL:
+     claude mcp add chromedebug -s user -- wsl chromedebug-mcp
+
+2. Native Windows (LIMITED - May have stdio issues):
+   • Set: set CHROMEDEBUG_FORCE_WINDOWS=1
+   • Then run: chromedebug-mcp
+   • Note: MCP stdio communication may fail due to cmd.exe limitations
+
+For details: https://github.com/dynamicupgrade/ChromeDebug#windows-setup
+`);
+    process.exit(1);
+  }
+
+  try {
+    // Initialize unified session manager with options
+    const sessionManager = await initializeSessionManager({
+      sessionId: args.sessionId,
+      skipCleanup: args.noCleanup,
+      verbose: args.verbose
+    });
+
+    // Register this process for tracking
+    await registerProcess(process.pid, 'mcp-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}`);
+
+      // Show other active sessions
+      const activeSessions = await findActiveSessions();
+      if (activeSessions.length > 1) {
+        logger.debug(`  Other active sessions: ${activeSessions.length - 1}`);
+        activeSessions.filter(s => s.sessionId !== sessionInfo.sessionId).forEach(session => {
+          logger.debug(`    - ${session.sessionId} (PID: ${session.pid}, Port: ${session.port})`);
+        });
+      }
+    }
+
+    // Pass session manager to app
+    app.sessionManager = sessionManager;
+
+    await app.start();
+  } catch (error) {
+    logger.error('Fatal error starting Chrome Debug:', 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);
+});
+
+// Always run main in CLI context
+main().catch((error) => {
+  logger.error('Unhandled error:', error);
+  process.exit(1);
+});

package/src/index.js

@@ -254,73 +254,6 @@ For more information, see the documentation in CLAUDE.md
   }
 }
 
-/**
- * Main entry point
- */
-async function main() {
-  const app = new ChromePilotApp();
-
-  // 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,
-      skipCleanup: args.noCleanup,
-      verbose: args.verbose
-    });
-
-    // Register this process for tracking
-    await registerProcess(process.pid, 'mcp-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}`);
-
-      // Show other active sessions
-      const activeSessions = await findActiveSessions();
-      if (activeSessions.length > 1) {
-        logger.debug(`  Other active sessions: ${activeSessions.length - 1}`);
-        activeSessions.filter(s => s.sessionId !== sessionInfo.sessionId).forEach(session => {
-          logger.debug(`    - ${session.sessionId} (PID: ${session.pid}, Port: ${session.port})`);
-        });
-      }
-    }
-
-    // Pass session manager to app
-    app.sessionManager = sessionManager;
-
-    await app.start();
-  } catch (error) {
-    logger.error('Fatal error starting Chrome Debug:', 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 { ChromePilotApp };
-
-// 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);
-  });
-}
+// Export for library usage and testing
+// This file is now safe to import without side effects
+export { ChromePilotApp };