brave-real-browser-mcp-server 2.12.4 → 2.12.5

package/README.md

@@ -12,7 +12,7 @@
 
 **सभी AI IDEs के लिए Universal MCP Server | 111+ Tools | Browser Automation | Web Scraping | CAPTCHA Solving**
 
-[Installation](#-installation) | [Quick Start](#-quick-start) | [Tools](#-available-tools-111) | [HTTP/WebSocket](#-httpwebsocket-setup) | [Configuration](#-ide-configurations)
+[Installation](#-installation) | [Quick Start](#-quick-start) | [Tools](#-available-tools-111) | [HTTP/WebSocket](#-httpwebsocket-setup) | [Configuration](#-ide-configurations) | [Troubleshooting](#-troubleshooting)
 
 </div>
 
@@ -33,13 +33,41 @@
 
 ## 🚀 Quick Start
 
+### ⚡ Quick Setup Summary
+
+**Choose your setup based on your AI Editor:**
+
+| Editor | Setup Time | Method |
+|--------|-----------|--------|
+| **Claude Desktop** | 2 min | Add config → Restart | 
+| **Cursor AI** | 2 min | Add config → Restart |
+| **Windsurf** | 2 min | Add config → Restart |
+| **Zed Editor** | 3 min | Add to `context_servers` → Restart |
+| **Qoder AI** | 4 min | Start HTTP server → Add config → Restart |
+| **Others (HTTP)** | 3 min | Start HTTP server → Configure endpoint |
+
+**Quick Commands:**
+
+```bash
+# For MCP Editors (Claude, Cursor, Windsurf)
+npx -y brave-real-browser-mcp-server@latest
+
+# For HTTP-based Editors (Qoder AI, Custom)
+npx brave-real-browser-mcp-server@latest --mode http --port 3000
+
+# Check if working
+curl http://localhost:3000/health  # For HTTP mode
+```
+
+---
+
 ### Installation
 
 ```bash
 # Install globally
 npm install -g brave-real-browser-mcp-server@latest
 
-# Or use with npx (no installation)
+# Or use with npx (no installation needed)
 npx brave-real-browser-mcp-server@latest
 ```
 
@@ -144,13 +172,44 @@ npx brave-real-browser-mcp-server@latest --mode http --port 3000
 
 ### Claude Desktop
 
-**File:** `claude_desktop_config.json`
+**Protocol:** MCP (STDIO) | **Setup Time:** 2 minutes | **Auto-Start:** ✅ Yes
 
-**Location:**
+#### 📋 Step-by-Step Setup Guide:
 
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Linux: `~/.config/Claude/claude_desktop_config.json`
+**Step 1: Locate Configuration File**
+
+```bash
+# Windows (PowerShell)
+cd $env:APPDATA\Claude
+notepad claude_desktop_config.json
+
+# Windows (CMD)
+cd %APPDATA%\Claude
+notepad claude_desktop_config.json
+
+# Mac
+cd ~/Library/Application\ Support/Claude
+open -e claude_desktop_config.json
+
+# Linux
+cd ~/.config/Claude
+gedit claude_desktop_config.json
+```
+
+**If file doesn't exist, create it:**
+
+```bash
+# Windows (PowerShell)
+New-Item -Path "$env:APPDATA\Claude\claude_desktop_config.json" -ItemType File -Force
+
+# Mac/Linux
+mkdir -p ~/.config/Claude
+touch ~/.config/Claude/claude_desktop_config.json
+```
+
+**Step 2: Add Configuration**
+
+Copy and paste this configuration:
 
 ```json
 {
@@ -163,15 +222,127 @@ npx brave-real-browser-mcp-server@latest --mode http --port 3000
 }
 ```
 
+**Advanced Configuration (Optional):**
+
+```json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server@latest"],
+      "env": {
+        "BRAVE_PATH": "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
+        "HEADLESS": "false"
+      }
+    }
+  }
+}
+```
+
+**Step 3: Save and Close File**
+
+Press `Ctrl+S` (Windows/Linux) or `Cmd+S` (Mac) to save.
+
+**Step 4: Restart Claude Desktop**
+
+```bash
+# Windows
+taskkill /F /IM claude.exe
+# Then reopen Claude Desktop
+
+# Mac
+pkill -f Claude
+# Then reopen Claude Desktop
+```
+
+**Step 5: Verify Installation**
+
+1. Open Claude Desktop
+2. Look for 🔧 icon or "Tools" section
+3. You should see "brave-real-browser" with 111 tools
+4. Try this command in Claude:
+   ```
+   Use browser_init tool to start the browser
+   ```
+
+**Troubleshooting:**
+
+```bash
+# Check Claude logs
+# Windows
+type "%APPDATA%\Claude\logs\mcp*.log"
+
+# Mac
+cat ~/Library/Logs/Claude/mcp*.log
+
+# If server fails, test manually:
+npx -y brave-real-browser-mcp-server@latest
+```
+
+**Configuration Locations:**
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
 ### Cursor AI
 
-**File:** `cline_mcp_settings.json`
+**Protocol:** MCP (STDIO) | **Setup Time:** 2 minutes | **Auto-Start:** ✅ Yes
 
-**Location:**
+#### 📋 Step-by-Step Setup Guide:
 
-- Windows: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
-- Mac: `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+**Step 1: Install Cline Extension (if not installed)**
+
+1. Open Cursor AI
+2. Press `Ctrl+Shift+X` (Extensions)
+3. Search for "Cline" or "Claude Dev"
+4. Click Install
+5. Restart Cursor
+
+**Step 2: Locate Configuration File**
+
+```bash
+# Windows (PowerShell)
+$configPath = "$env:APPDATA\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings"
+cd $configPath
+notepad cline_mcp_settings.json
+
+# Windows (CMD)
+cd %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings
+notepad cline_mcp_settings.json
+
+# Mac
+cd ~/Library/Application\ Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings
+open -e cline_mcp_settings.json
+```
+
+**If file doesn't exist, create it:**
+
+```bash
+# Windows (PowerShell)
+$settingsPath = "$env:APPDATA\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings"
+New-Item -Path $settingsPath -ItemType Directory -Force
+New-Item -Path "$settingsPath\cline_mcp_settings.json" -ItemType File -Force
+
+# Mac
+mkdir -p ~/Library/Application\ Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings
+touch ~/Library/Application\ Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
+```
+
+**Step 3: Add Configuration**
+
+**Basic Configuration:**
+```json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server@latest"]
+    }
+  }
+}
+```
 
+**Advanced Configuration (with Brave path):**
 ```json
 {
   "mcpServers": {
@@ -179,13 +350,86 @@ npx brave-real-browser-mcp-server@latest --mode http --port 3000
       "command": "npx",
       "args": ["-y", "brave-real-browser-mcp-server@latest"],
       "env": {
-        "BRAVE_PATH": "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
+        "BRAVE_PATH": "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
+        "HEADLESS": "false"
       }
     }
   }
 }
 ```
 
+**For Mac:**
+```json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server@latest"],
+      "env": {
+        "BRAVE_PATH": "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+      }
+    }
+  }
+}
+```
+
+**Step 4: Save and Restart Cursor**
+
+```bash
+# Windows
+taskkill /F /IM Cursor.exe
+# Then reopen Cursor
+
+# Mac
+pkill -f Cursor
+# Then reopen Cursor
+```
+
+**Step 5: Verify Installation**
+
+1. Open Cursor AI
+2. Open Cline panel (usually in sidebar)
+3. Look for MCP tools section
+4. You should see "brave-real-browser" listed
+5. Test with:
+   ```
+   @brave-real-browser browser_init
+   ```
+
+**Step 6: Using Tools in Cursor**
+
+```
+# In Cline chat:
+Use the browser_init tool from brave-real-browser to start automation
+
+# Or directly:
+@brave-real-browser navigate {"url": "https://example.com"}
+```
+
+**Troubleshooting:**
+
+```bash
+# Check if Cline extension is active
+# Cursor → Extensions → Search "Cline" → Should show "Active"
+
+# View Cline logs
+# Cursor → View → Output → Select "Cline" from dropdown
+
+# Test server manually
+npx -y brave-real-browser-mcp-server@latest
+
+# Clear Cursor cache
+# Windows
+Remove-Item -Recurse -Force "$env:APPDATA\Cursor\Cache"
+
+# Mac
+rm -rf ~/Library/Application\ Support/Cursor/Cache
+```
+
+**Configuration Locations:**
+- Windows: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
+- Mac: `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+
 ### Windsurf
 
 **File:** `mcp.json`
@@ -228,33 +472,120 @@ npx brave-real-browser-mcp-server@latest --mode http --port 3000
 
 ### Zed Editor
 
+**Protocol:** Context Servers (MCP)
+
 **File:** `settings.json`
 
 **Location:**
 
 - Windows: `%APPDATA%\Zed\settings.json`
 - Mac: `~/.config/zed/settings.json`
+- Linux: `~/.config/zed/settings.json`
+
+#### Step-by-Step Setup Guide:
+
+**Step 1:** Open Zed Editor and press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (Mac)
+
+**Step 2:** Type "Open Settings" and select "Zed: Open Settings"
+
+**Step 3:** Add the following configuration:
 
 ```json
 {
   "context_servers": {
     "brave-real-browser": {
-      "command": {
-        "path": "npx",
-        "args": ["-y", "brave-real-browser-mcp-server@latest"]
-      },
-      "settings": {}
+      "source": "custom",
+      "command": "npx.cmd",
+      "args": ["-y", "brave-real-browser-mcp-server"]
     }
   }
 }
 ```
 
-**Note:** Zed uses `context_servers` (not `lsp`) for MCP servers. Make sure you're using Zed Preview version for MCP support.
+**For Mac/Linux, use:**
+```json
+{
+  "context_servers": {
+    "brave-real-browser": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server"]
+    }
+  }
+}
+```
+
+**Step 4:** Save the file and restart Zed Editor
+
+**Step 5:** Verify installation by checking Zed's output panel
+
+**Important Notes:**
+- ⚠️ **Zed uses `context_servers` NOT `mcpServers` or `lsp`**
+- ✅ Make sure you're using Zed Preview version (v0.120.0+) for MCP support
+- ✅ On Windows, use `npx.cmd` instead of `npx`
+- ✅ Server will auto-start when Zed launches
+
+### Qoder AI Editor
+
+**Protocol:** HTTP/WebSocket
+
+**⚠️ Important:** Qoder AI requires HTTP server to be running separately before configuration!
+
+#### Step-by-Step Setup Guide:
+
+**Step 1: Start HTTP Server First**
+
+Open a terminal and run:
+
+```bash
+# Windows (PowerShell)
+npx brave-real-browser-mcp-server@latest --mode http --port 3000
+
+# Mac/Linux
+npx brave-real-browser-mcp-server@latest --mode http --port 3000
+```
+
+**Expected Output:**
+```
+🟢 [HTTP] Starting HTTP/WebSocket server...
+✅ [HTTP] Server ready at http://localhost:3000
+💡 [HTTP] Universal mode - works with ALL AI IDEs
+```
+
+**Step 2: Test Server is Running**
 
-### Qoder AI / HTTP-based IDEs
+Open another terminal and verify:
 
-Start server in HTTP mode and configure:
+```bash
+# Health check
+curl http://localhost:3000/health
+
+# Expected response:
+# {"status":"ok","timestamp":"..."}
+
+# List all tools
+curl http://localhost:3000/tools
+```
+
+**Step 3: Configure Qoder AI**
+
+Open Qoder AI settings and add:
+
+**Option A - MCP Configuration (Recommended):**
+```json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "type": "http",
+      "endpoint": "http://localhost:3000",
+      "enabled": true,
+      "timeout": 30000
+    }
+  }
+}
+```
 
+**Option B - Extensions Configuration:**
 ```json
 {
   "extensions": {
@@ -268,6 +599,56 @@ Start server in HTTP mode and configure:
 }
 ```
 
+**Step 4: Restart Qoder AI**
+
+Close and reopen Qoder AI for changes to take effect.
+
+**Step 5: Verify Connection**
+
+Check Qoder AI's output/console for connection confirmation.
+
+**Important Notes:**
+- 🔴 **Server must be running BEFORE starting Qoder AI**
+- ✅ Keep the HTTP server terminal window open while using Qoder AI
+- ✅ If server stops, restart it before using browser automation
+- 💡 You can run server in background with `pm2` or as a service
+
+**Background Server Setup (Optional):**
+
+```bash
+# Install pm2 globally
+npm install -g pm2
+
+# Start server in background
+pm2 start npx --name "brave-browser-server" -- brave-real-browser-mcp-server@latest --mode http --port 3000
+
+# View logs
+pm2 logs brave-browser-server
+
+# Stop server
+pm2 stop brave-browser-server
+```
+
+### Other HTTP-based IDEs (Gemini CLI, Qwen Code CLI, Custom Tools)
+
+**Step 1:** Start HTTP server as shown above
+
+**Step 2:** Configure your IDE/tool to use endpoint: `http://localhost:3000`
+
+**Step 3:** Make HTTP POST requests to execute tools:
+
+```bash
+# Example: Navigate to URL
+curl -X POST http://localhost:3000/tools/navigate \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com"}'
+
+# Example: Get page content
+curl -X POST http://localhost:3000/tools/get_content \
+  -H "Content-Type: application/json" \
+  -d '{"type": "text"}'
+```
+
 ---
 
 ## 🛠️ Available Tools (111)
@@ -620,47 +1001,431 @@ HTTP_PORT=3000
 
 ## 🐛 Troubleshooting
 
-### Brave Browser Not Found
+### Common Issues & Solutions
+
+#### 1. Brave Browser Not Found
+
+**Symptoms:**
+- Error: "Brave browser not found"
+- Browser fails to launch
 
-**Solution:**
+**Solutions:**
 
 ```bash
-# Windows
+# Windows (PowerShell)
+$env:BRAVE_PATH="C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe"
+
+# Windows (CMD)
 set BRAVE_PATH="C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe"
 
-# Linux/Mac
+# Mac
+export BRAVE_PATH="/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+
+# Linux (Ubuntu/Debian)
 export BRAVE_PATH="/usr/bin/brave-browser"
+
+# Linux (Snap)
+export BRAVE_PATH="/snap/bin/brave"
+```
+
+**Permanent Fix (Windows):**
+```powershell
+# Add to System Environment Variables
+[System.Environment]::SetEnvironmentVariable('BRAVE_PATH', 'C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe', 'User')
 ```
 
-### Server Won't Start
+---
 
-1. Check Node.js version: `node --version` (should be >= 18)
-2. Clear npm cache: `npm cache clean --force`
-3. Reinstall: `npm install -g brave-real-browser-mcp-server@latest`
+#### 2. Server Won't Start
 
-### Port Already in Use
+**Symptoms:**
+- "Failed to start server" error
+- Process exits immediately
+- No output in terminal
+
+**Solutions:**
+
+**Step 1:** Check Node.js version
+```bash
+node --version
+# Should show v18.0.0 or higher
+```
+
+**Step 2:** If Node.js is old, update it:
+```bash
+# Windows (using Chocolatey)
+choco upgrade nodejs
+
+# Mac (using Homebrew)
+brew upgrade node
+
+# Or download from: https://nodejs.org/
+```
 
+**Step 3:** Clear npm cache and reinstall
+```bash
+npm cache clean --force
+npm uninstall -g brave-real-browser-mcp-server
+npm install -g brave-real-browser-mcp-server@latest
+```
+
+**Step 4:** Check for conflicting processes
+```bash
+# Windows
+taskkill /F /IM brave.exe
+
+# Mac/Linux
+pkill -f brave
+```
+
+---
+
+#### 3. Port Already in Use (HTTP Mode)
+
+**Symptoms:**
+- Error: "EADDRINUSE: address already in use ::3000"
+- HTTP server fails to start
+
+**Solutions:**
+
+**Option A:** Use a different port
 ```bash
-# Use different port
 npx brave-real-browser-mcp-server@latest --mode http --port 8080
 ```
 
-### CAPTCHA Not Solving
+**Option B:** Kill the process using port 3000
+
+```bash
+# Windows (PowerShell)
+Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process -Force
+
+# Windows (CMD)
+for /f "tokens=5" %a in ('netstat -aon ^| find ":3000" ^| find "LISTENING"') do taskkill /F /PID %a
 
-1. Ensure CAPTCHA is fully loaded
-2. Try longer timeout: `{ "timeout": 30000 }`
-3. Try different CAPTCHA types: `recaptcha`, `hcaptcha`, `turnstile`
+# Mac/Linux
+lsof -ti:3000 | xargs kill -9
+```
+
+---
+
+#### 4. Qoder AI Configuration Fails
+
+**Symptoms:**
+- "Connection refused" error
+- "Server not reachable" message
+- Tools not appearing in Qoder AI
+
+**Solutions:**
+
+**Step 1:** Verify HTTP server is running
+```bash
+# Start server in a separate terminal
+npx brave-real-browser-mcp-server@latest --mode http --port 3000
+
+# You should see:
+# ✅ [HTTP] Server ready at http://localhost:3000
+```
+
+**Step 2:** Test server connection
+```bash
+curl http://localhost:3000/health
+# Expected: {"status":"ok","timestamp":"..."}
+```
+
+**Step 3:** Check firewall settings
+```bash
+# Windows: Allow Node.js through firewall
+netsh advfirewall firewall add rule name="Node.js" dir=in action=allow program="C:\Program Files\nodejs\node.exe" enable=yes
+```
+
+**Step 4:** Try alternative configuration
+```json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server@latest", "--mode", "http", "--port", "3000"],
+      "env": {}
+    }
+  }
+}
+```
+
+---
+
+#### 5. Zed Editor Not Detecting Server
+
+**Symptoms:**
+- Context servers not appearing
+- "Failed to start context server" error
+
+**Solutions:**
+
+**Step 1:** Ensure Zed Preview version
+```bash
+# Check Zed version (should be v0.120.0 or higher)
+# Open Zed → Help → About Zed
+```
+
+**Step 2:** Verify correct configuration format
+```json
+{
+  "context_servers": {
+    "brave-real-browser": {
+      "source": "custom",
+      "command": "npx.cmd",  // Windows: use npx.cmd, Mac/Linux: use npx
+      "args": ["-y", "brave-real-browser-mcp-server"]
+    }
+  }
+}
+```
+
+**Step 3:** Check Zed logs
+```bash
+# Open Zed → View → Debug → Language Server Logs
+# Look for error messages
+```
+
+**Step 4:** Restart Zed completely
+```bash
+# Close Zed and kill any background processes
+# Windows
+taskkill /F /IM zed.exe
+
+# Mac
+pkill -f zed
+```
+
+---
+
+#### 6. Claude Desktop Configuration Issues
+
+**Symptoms:**
+- "MCP server failed to start"
+- Tools not appearing in Claude
+
+**Solutions:**
+
+**Step 1:** Check config file location
+```bash
+# Windows
+echo %APPDATA%\Claude\claude_desktop_config.json
+
+# Mac
+echo ~/Library/Application\ Support/Claude/claude_desktop_config.json
+```
+
+**Step 2:** Validate JSON format
+- Use https://jsonlint.com/ to validate your config
+- Ensure no trailing commas
+- Check quotes are properly escaped
+
+**Step 3:** Check Claude logs
+```bash
+# Windows
+type "%APPDATA%\Claude\logs\mcp*.log"
+
+# Mac
+cat ~/Library/Logs/Claude/mcp*.log
+```
+
+**Step 4:** Restart Claude Desktop completely
+```bash
+# Windows
+taskkill /F /IM claude.exe
+
+# Mac
+pkill -f Claude
+```
+
+---
+
+#### 7. CAPTCHA Not Solving
+
+**Symptoms:**
+- CAPTCHA solve timeout
+- "Failed to solve CAPTCHA" error
+
+**Solutions:**
+
+**Step 1:** Ensure CAPTCHA is fully loaded
+```javascript
+// Add wait before solving
+await use_mcp_tool({
+  server_name: "brave-real-browser",
+  tool_name: "wait",
+  arguments: { type: "timeout", value: "5000" }
+});
+```
+
+**Step 2:** Try longer timeout
+```javascript
+await use_mcp_tool({
+  server_name: "brave-real-browser",
+  tool_name: "solve_captcha",
+  arguments: { 
+    type: "recaptcha",
+    timeout: 60000  // 60 seconds
+  }
+});
+```
+
+**Step 3:** Try different CAPTCHA types
+- `recaptcha` - Google reCAPTCHA v2/v3
+- `hcaptcha` - hCaptcha
+- `turnstile` - Cloudflare Turnstile
+
+---
+
+#### 8. NPX Command Not Found
+
+**Symptoms:**
+- "npx: command not found"
+- "npx is not recognized"
+
+**Solutions:**
+
+**Step 1:** Verify npm installation
+```bash
+npm --version
+```
+
+**Step 2:** Reinstall Node.js
+- Download from: https://nodejs.org/
+- Choose LTS version
+- During installation, ensure "Add to PATH" is checked
+
+**Step 3:** Add npm to PATH manually (Windows)
+```powershell
+$env:PATH += ";C:\Program Files\nodejs"
+```
+
+---
+
+#### 9. Permission Denied Errors (Linux/Mac)
+
+**Symptoms:**
+- "EACCES: permission denied"
+- Cannot install globally
+
+**Solutions:**
+
+```bash
+# Option A: Fix npm permissions
+sudo chown -R $(whoami) ~/.npm
+sudo chown -R $(whoami) /usr/local/lib/node_modules
+
+# Option B: Use npx instead of global install
+npx brave-real-browser-mcp-server@latest
+
+# Option C: Use nvm (recommended)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install --lts
+```
+
+---
+
+#### 10. Browser Crashes or Hangs
+
+**Symptoms:**
+- Browser becomes unresponsive
+- "Page crashed" errors
+- Memory issues
+
+**Solutions:**
+
+**Step 1:** Enable headless mode
+```json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server@latest"],
+      "env": {
+        "HEADLESS": "true"
+      }
+    }
+  }
+}
+```
+
+**Step 2:** Increase timeout values
+```javascript
+await use_mcp_tool({
+  server_name: "brave-real-browser",
+  tool_name: "navigate",
+  arguments: { 
+    url: "https://example.com",
+    waitUntil: "networkidle2",
+    timeout: 60000
+  }
+});
+```
+
+**Step 3:** Clear browser cache
+```bash
+# Kill all Brave processes
+# Windows
+taskkill /F /IM brave.exe
+
+# Mac/Linux
+pkill -9 brave
+```
+
+---
+
+### Getting Help
+
+If you're still experiencing issues:
+
+1. **Check GitHub Issues:** https://github.com/codeiva4u/Brave-Real-Browser-Mcp-Server/issues
+2. **Enable Debug Logs:** Set `DEBUG=*` environment variable
+3. **Report Bug:** Include:
+   - Operating System & version
+   - Node.js version (`node --version`)
+   - Editor/IDE name & version
+   - Complete error message
+   - Configuration file (remove sensitive data)
+
+```bash
+# Run with debug logging
+DEBUG=* npx brave-real-browser-mcp-server@latest --mode http
+```
 
 ---
 
 ## 📊 Supported Protocols
 
-| Protocol        | Used By                                       | Auto-Config | Status     |
-| --------------- | --------------------------------------------- | ----------- | ---------- |
-| **MCP (STDIO)** | Claude Desktop, Cursor, Windsurf, Cline, Warp | ✅          | 🟢 Working |
-| **LSP**         | Zed Editor, VSCode, Neovim                    | ✅          | 🟢 Working |
-| **HTTP/REST**   | Any IDE/Tool                                  | ✅          | 🟢 Working |
-| **WebSocket**   | Modern Web Apps, Real-time Tools              | ✅          | 🟢 Working |
+|| Protocol        | Used By                                       | Auto-Config | Status     |
+|| --------------- | --------------------------------------------- | ----------- | ---------- |
+|| **MCP (STDIO)** | Claude Desktop, Cursor, Windsurf, Cline, Warp | ✅          | 🟢 Working |
+|| **LSP**         | Zed Editor, VSCode, Neovim                    | ✅          | 🟢 Working |
+|| **HTTP/REST**   | Any IDE/Tool                                  | ✅          | 🟢 Working |
+|| **WebSocket**   | Modern Web Apps, Real-time Tools              | ✅          | 🟢 Working |
+
+---
+
+## 📊 Editor Compatibility Matrix
+
+| AI Editor | Protocol | Config File | Server Auto-Start | HTTP Server Required | Status |
+|-----------|----------|-------------|-------------------|----------------------|--------|
+| **Claude Desktop** | MCP | `claude_desktop_config.json` | ✅ Yes | ❌ No | 🟢 Working |
+| **Cursor AI** | MCP | `cline_mcp_settings.json` | ✅ Yes | ❌ No | 🟢 Working |
+| **Windsurf** | MCP | `mcp.json` | ✅ Yes | ❌ No | 🟢 Working |
+| **Cline (VSCode)** | MCP | `cline_mcp_settings.json` | ✅ Yes | ❌ No | 🟢 Working |
+| **Warp Terminal** | MCP | Warp config | ✅ Yes | ❌ No | 🟢 Working |
+| **Zed Editor** | Context Servers (MCP) | `settings.json` | ✅ Yes | ❌ No | 🟢 Working |
+| **Qoder AI** | HTTP | `mcp.json` or config | ❌ No | ✅ **Yes** | 🟢 Working |
+| **Gemini CLI** | HTTP | CLI config | ❌ No | ✅ **Yes** | 🟢 Working |
+| **Qwen Code CLI** | HTTP | CLI config | ❌ No | ✅ **Yes** | 🟢 Working |
+| **Continue.dev** | HTTP | Extension config | ❌ No | ✅ **Yes** | 🟢 Working |
+| **Custom Tools** | HTTP | API integration | ❌ No | ✅ **Yes** | 🟢 Working |
+| **VSCode (Generic)** | LSP/HTTP | Extension config | Varies | Optional | 🟢 Working |
+
+**Legend:**
+- ✅ **Server Auto-Start**: Editor automatically starts the MCP server
+- ❌ **HTTP Server Required**: You must manually start HTTP server before using
+- 🟢 **Working**: Fully tested and operational
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brave-real-browser-mcp-server",
-  "version": "2.12.4",
+  "version": "2.12.5",
   "description": "Universal AI IDE MCP Server - Auto-detects and supports all AI IDEs (Claude Desktop, Cursor, Windsurf, Cline, Zed, VSCode, Qoder AI, etc.) with Brave browser automation",
   "type": "module",
   "main": "dist/index.js",
@@ -36,7 +36,7 @@
     "test:brave:cleanup": "taskkill /F /IM brave.exe || pkill -f brave || true"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.20.1",
+    "@modelcontextprotocol/sdk": "^1.20.2",
     "@types/turndown": "^5.0.5",
     "ajv": "^8.12.0",
     "axios": "^1.6.5",