@dynamicu/chromedebug-mcp 2.4.5 → 2.5.2

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.4.5",
+  "version": "2.5.2",
   "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/index.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/index.js

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 /**
  * Chrome Debug MCP Server - Modular Architecture
  * Refactored from monolithic design to modular components
@@ -261,6 +263,34 @@ async function main() {
   // 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({

package/src/cli.js

@@ -1,19 +0,0 @@
-#!/usr/bin/env node
-
-import { spawn } from 'child_process';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const indexPath = join(__dirname, 'index.js');
-
-const child = spawn('node', [indexPath], {
-  stdio: 'inherit',
-  env: process.env
-});
-
-child.on('exit', (code) => {
-  process.exit(code);
-});