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

package/README.md

@@ -12,7 +12,9 @@
 
 **सभी 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)
+[📖 **All 5 Protocols Complete Guide**](./ALL-PROTOCOLS.md) 👈 **NEW! Step-by-step setup for all protocols**
+
+[Installation](#-installation) | [Quick Start](#-quick-start) | [Tools](#-available-tools-111) | [HTTP/WebSocket](#-httpwebsocket-setup) | [Configuration](#-ide-configurations) | [Troubleshooting](#-troubleshooting)
 
 </div>
 
@@ -24,7 +26,7 @@
 
 - ✅ **15+ AI IDEs में काम करता है** (Claude, Cursor, Windsurf, Cline, Zed, VSCode, Qoder AI, etc.)
 - ✅ **111+ Automation Tools** - Browser control, scraping, CAPTCHA solving, video extraction
-- ✅ **3 Protocol Modes** - MCP (STDIO), LSP, HTTP/WebSocket
+- ✅ **5 Protocol Modes** - MCP (STDIO), LSP, HTTP/WebSocket, SSE
 - ✅ **Auto-Detection** - Automatically detects your IDE
 - ✅ **Real Brave Browser** - Anti-detection features, bypass Cloudflare
 - ✅ **Universal API** - Works with any programming language (JS, Python, PHP, Go, etc.)
@@ -33,13 +35,51 @@
 
 ## 🚀 Quick Start
 
+### ⚡ Quick Setup Summary
+
+**Choose your setup based on your AI Editor:**
+
+| Editor | Setup Time | Protocol | Method |
+|--------|-----------|----------|--------|
+| **Claude Desktop** | 2 min | MCP | Add config → Restart | 
+| **Cursor AI** | 2 min | MCP | Add config → Restart |
+| **Windsurf** | 2 min | MCP | Add config → Restart |
+| **Zed Editor** | 3 min | LSP | Add to `context_servers` → Restart |
+| **Qoder AI** | 4 min | HTTP | Start HTTP server → Add config → Restart |
+| **Custom Apps** | 1 min | HTTP/WebSocket/SSE | Start server → Use API |
+
+**Quick Commands:**
+
+```bash
+# Auto-detect environment
+npx brave-real-browser-mcp-server@latest
+
+# MCP mode (Claude, Cursor, Windsurf)
+npx brave-real-browser-mcp-server@latest --mode mcp
+
+# LSP mode (Zed, VSCode, Neovim)
+npx brave-real-browser-mcp-server@latest --mode lsp
+
+# HTTP mode (Universal API + WebSocket)
+npx brave-real-browser-mcp-server@latest --mode http --port 3000
+
+# SSE mode (Real-time monitoring)
+npx brave-real-browser-mcp-server@latest --mode sse --sse-port 3001
+
+# Check if working
+curl http://localhost:3000/health  # For HTTP mode
+curl http://localhost:3001/health  # For SSE 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
 ```
 
@@ -127,7 +167,7 @@ curl http://localhost:3000/tools
 
 ---
 
-### WebSocket Protocol - 5 Steps
+### WebSocket Protocol - Complete Setup Guide
 
 WebSocket provides **real-time, bidirectional communication** for modern applications.
 
@@ -140,18 +180,545 @@ npx brave-real-browser-mcp-server@latest --mode http --port 3000
 # WebSocket will be available at: ws://localhost:3000
 ```
 
+**Server will start and show:**
+
+```
+🟢 [HTTP] Starting HTTP/WebSocket server...
+✅ [HTTP] Server ready at http://localhost:3000
+✅ [WebSocket] Server running on ws://localhost:3000
+💡 [HTTP] Universal mode - works with ALL AI IDEs
+```
+
+#### Step 2: Verify WebSocket Connection
+
+Test WebSocket connection using browser console or Node.js:
+
+**Using Browser Console:**
+
+```javascript
+// Open browser console (F12) and paste:
+const ws = new WebSocket('ws://localhost:3000');
+
+ws.onopen = () => {
+  console.log('✅ WebSocket connected!');
+  
+  // Test tool execution
+  ws.send(JSON.stringify({
+    id: 1,
+    tool: 'browser_init',
+    args: {}
+  }));
+};
+
+ws.onmessage = (event) => {
+  console.log('📥 Response:', JSON.parse(event.data));
+};
+
+ws.onerror = (error) => {
+  console.error('❌ WebSocket error:', error);
+};
+
+ws.onclose = () => {
+  console.log('🔴 WebSocket disconnected');
+};
+```
+
+**Using Node.js:**
+
+```javascript
+// Install ws package: npm install ws
+const WebSocket = require('ws');
+
+const ws = new WebSocket('ws://localhost:3000');
+
+ws.on('open', () => {
+  console.log('✅ WebSocket connected!');
+  
+  // Execute a tool
+  ws.send(JSON.stringify({
+    id: 1,
+    tool: 'browser_init',
+    args: {}
+  }));
+});
+
+ws.on('message', (data) => {
+  console.log('📥 Response:', JSON.parse(data));
+});
+
+ws.on('error', (error) => {
+  console.error('❌ Error:', error);
+});
+
+ws.on('close', () => {
+  console.log('🔴 Connection closed');
+});
+```
+
+#### Step 3: WebSocket Message Format
+
+**Request Format:**
+
+```json
+{
+  "id": 1,
+  "tool": "tool_name",
+  "args": {
+    "param1": "value1",
+    "param2": "value2"
+  }
+}
+```
+
+**Response Format:**
+
+```json
+{
+  "id": 1,
+  "success": true,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "Result data"
+      }
+    ]
+  }
+}
+```
+
+**Error Response:**
+
+```json
+{
+  "id": 1,
+  "success": false,
+  "error": "Error message"
+}
+```
+
+#### Step 4: Example - Complete Browser Automation via WebSocket
+
+```javascript
+const WebSocket = require('ws');
+const ws = new WebSocket('ws://localhost:3000');
+
+let messageId = 0;
+
+function sendCommand(tool, args) {
+  return new Promise((resolve, reject) => {
+    const id = ++messageId;
+    
+    const handler = (data) => {
+      const response = JSON.parse(data);
+      if (response.id === id) {
+        ws.removeListener('message', handler);
+        if (response.success) {
+          resolve(response.result);
+        } else {
+          reject(new Error(response.error));
+        }
+      }
+    };
+    
+    ws.on('message', handler);
+    
+    ws.send(JSON.stringify({ id, tool, args }));
+  });
+}
+
+ws.on('open', async () => {
+  try {
+    // Step 1: Initialize browser
+    console.log('Initializing browser...');
+    await sendCommand('browser_init', {});
+    
+    // Step 2: Navigate to URL
+    console.log('Navigating to page...');
+    await sendCommand('navigate', { url: 'https://example.com' });
+    
+    // Step 3: Get page content
+    console.log('Getting content...');
+    const content = await sendCommand('get_content', { type: 'text' });
+    console.log('Content:', content);
+    
+    // Step 4: Close browser
+    console.log('Closing browser...');
+    await sendCommand('browser_close', {});
+    
+    console.log('✅ Automation complete!');
+    ws.close();
+  } catch (error) {
+    console.error('❌ Error:', error);
+    ws.close();
+  }
+});
+```
+
+#### Step 5: WebSocket Client Libraries
+
+**JavaScript/Node.js:**
+```bash
+npm install ws
+```
+
+**Python:**
+```bash
+pip install websockets
+```
+
+```python
+import asyncio
+import websockets
+import json
+
+async def automation():
+    uri = "ws://localhost:3000"
+    async with websockets.connect(uri) as websocket:
+        # Initialize browser
+        await websocket.send(json.dumps({
+            "id": 1,
+            "tool": "browser_init",
+            "args": {}
+        }))
+        response = await websocket.recv()
+        print(f"Response: {response}")
+        
+        # Navigate
+        await websocket.send(json.dumps({
+            "id": 2,
+            "tool": "navigate",
+            "args": {"url": "https://example.com"}
+        }))
+        response = await websocket.recv()
+        print(f"Response: {response}")
+
+asyncio.run(automation())
+```
+
+**Go:**
+```bash
+go get github.com/gorilla/websocket
+```
+
+```go
+package main
+
+import (
+    "encoding/json"
+    "fmt"
+    "github.com/gorilla/websocket"
+)
+
+type Message struct {
+    ID   int                    `json:"id"`
+    Tool string                 `json:"tool"`
+    Args map[string]interface{} `json:"args"`
+}
+
+func main() {
+    ws, _, err := websocket.DefaultDialer.Dial("ws://localhost:3000", nil)
+    if err != nil {
+        panic(err)
+    }
+    defer ws.Close()
+    
+    // Initialize browser
+    msg := Message{
+        ID:   1,
+        Tool: "browser_init",
+        Args: make(map[string]interface{}),
+    }
+    
+    ws.WriteJSON(msg)
+    
+    var response map[string]interface{}
+    ws.ReadJSON(&response)
+    fmt.Printf("Response: %+v\n", response)
+}
+```
+
+**PHP:**
+```bash
+composer require textalk/websocket
+```
+
+```php
+<?php
+require 'vendor/autoload.php';
+
+use WebSocket\Client;
+
+$client = new Client("ws://localhost:3000");
+
+// Initialize browser
+$client->send(json_encode([
+    'id' => 1,
+    'tool' => 'browser_init',
+    'args' => new stdClass()
+]));
+
+$response = json_decode($client->receive());
+echo "Response: " . print_r($response, true);
+
+$client->close();
+?>
+```
+
+#### Step 6: WebSocket Advanced Features
+
+**Connection Options:**
+
+```javascript
+const ws = new WebSocket('ws://localhost:3000', {
+  headers: {
+    'Authorization': 'Bearer your-token',
+    'X-Custom-Header': 'value'
+  }
+});
+```
+
+**Reconnection Logic:**
+
+```javascript
+function connectWebSocket() {
+  const ws = new WebSocket('ws://localhost:3000');
+  
+  ws.on('close', () => {
+    console.log('Connection closed, reconnecting in 5s...');
+    setTimeout(connectWebSocket, 5000);
+  });
+  
+  ws.on('error', (error) => {
+    console.error('WebSocket error:', error);
+  });
+  
+  return ws;
+}
+
+const ws = connectWebSocket();
+```
+
+**Heartbeat/Ping-Pong:**
+
+```javascript
+const ws = new WebSocket('ws://localhost:3000');
+
+setInterval(() => {
+  if (ws.readyState === WebSocket.OPEN) {
+    ws.ping();
+  }
+}, 30000); // Ping every 30 seconds
+
+ws.on('pong', () => {
+  console.log('Pong received - connection alive');
+});
+```
+
+#### Troubleshooting WebSocket
+
+**Issue: Connection Refused**
+
+```bash
+# Check if HTTP server is running
+curl http://localhost:3000/health
+
+# If not running, start it:
+npx brave-real-browser-mcp-server@latest --mode http --port 3000
+```
+
+**Issue: WebSocket Disabled**
+
+```bash
+# Start server with WebSocket explicitly enabled
+npx brave-real-browser-mcp-server@latest --mode http --port 3000
+
+# Note: WebSocket is enabled by default
+# To disable: use --no-websocket flag
+```
+
+**Issue: Connection Timeout**
+
+```javascript
+// Increase connection timeout
+const ws = new WebSocket('ws://localhost:3000', {
+  handshakeTimeout: 10000 // 10 seconds
+});
+```
+
+**Issue: Firewall Blocking**
+
+```bash
+# Windows - Allow Node.js through firewall
+netsh advfirewall firewall add rule name="Node.js WebSocket" dir=in action=allow program="C:\Program Files\nodejs\node.exe" enable=yes
+
+# Linux - Allow port 3000
+sudo ufw allow 3000
+```
+
 ## 🎨 IDE Configurations
 
 ### Claude Desktop
 
-**File:** `claude_desktop_config.json`
+**Protocol:** MCP (STDIO) | **Setup Time:** 2 minutes | **Auto-Start:** ✅ Yes
 
-**Location:**
+#### 📋 Step-by-Step Setup Guide:
+
+**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
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server@latest"]
+    }
+  }
+}
+```
+
+**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
+
+**Protocol:** MCP (STDIO) | **Setup Time:** 2 minutes | **Auto-Start:** ✅ Yes
+
+#### 📋 Step-by-Step Setup Guide:
+
+**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": {
@@ -163,15 +730,275 @@ npx brave-real-browser-mcp-server@latest --mode http --port 3000
 }
 ```
 
-### Cursor AI
+**Advanced Configuration (with Brave path):**
+```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"
+      }
+    }
+  }
+}
+```
 
-**File:** `cline_mcp_settings.json`
+**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"
+      }
+    }
+  }
+}
+```
 
-**Location:**
+**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`
+
+**Location:**
+
+- Windows: `%APPDATA%\Windsurf\mcp.json`
+- Mac: `~/.windsurf/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server@latest"]
+    }
+  }
+}
+```
+
+### Cline (VSCode Extension)
+
+**File:** `cline_mcp_settings.json`
+
+**Location:**
+
+- Windows: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
+- Mac: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+
+```json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server@latest"]
+    }
+  }
+}
+```
+
+### 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": {
+      "source": "custom",
+      "command": "npx.cmd",
+      "args": ["-y", "brave-real-browser-mcp-server"]
+    }
+  }
+}
+```
+
+**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:** MCP (STDIO) | **Setup Time:** 3 minutes | **Auto-Start:** ✅ Yes
+
+**✅ Good News:** Qoder AI supports standard STDIO-based MCP servers (just like Claude, Cursor, Windsurf)!
+
+#### 📋 Step-by-Step Setup Guide:
+
+**Step 1: Open Qoder Settings**
+
+```bash
+# Method 1: Using keyboard shortcut
+# Windows: Ctrl + Shift + ,
+# Mac: ⌘ + Shift + ,
+
+# Method 2: Click user icon in upper-right corner
+# Then select "Qoder Settings"
+```
+
+**Step 2: Navigate to MCP Section**
+
+1. In left-side navigation pane, click **MCP**
+2. Click on **My Servers** tab
+3. Click **+ Add** button in upper-right corner
+
+**Step 3: Install Package Globally (Important for Qoder AI)**
+
+```bash
+# Install globally for faster startup
+npm install -g brave-real-browser-mcp-server@latest
+
+# Verify installation
+where brave-real-browser-mcp-server  # Windows
+which brave-real-browser-mcp-server  # Mac/Linux
+```
+
+**Why global install?** Qoder AI has a short timeout for MCP server initialization. Using `npx` can be slow on first run. Global installation ensures fast startup.
+
+**Step 4: Add Configuration**
+
+A JSON file will appear. Add this configuration:
+
+**Option A - Using Global Install (Recommended):**
+```json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "brave-real-browser-mcp-server",
+      "args": []
+    }
+  }
+}
+```
+
+**Option B - Using NPX (May timeout on first run):**
+```json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server@latest"]
+    }
+  }
+}
+```
+
+**Option C - Using Node directly:**
+```json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "node",
+      "args": [
+        "C:\\Users\\Admin\\AppData\\Roaming\\npm\\node_modules\\brave-real-browser-mcp-server\\dist\\index.js"
+      ]
+    }
+  }
+}
+```
+
+**Note:** Replace path in Option C with your actual global npm modules path:
+- Windows: `%APPDATA%\npm\node_modules\brave-real-browser-mcp-server\dist\index.js`
+- Mac/Linux: `/usr/local/lib/node_modules/brave-real-browser-mcp-server/dist/index.js`
+
+**Advanced Configuration (with environment variables):**
+
 ```json
 {
   "mcpServers": {
@@ -179,93 +1006,201 @@ 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"
       }
     }
   }
 }
 ```
 
-### Windsurf
+**For Mac:**
 
-**File:** `mcp.json`
+```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 5: Save Configuration**
+
+1. Close the JSON file
+2. Click **Save** when prompted
+3. The new server will appear in your list
+4. A **link icon** (🔗) means the connection is successful
+
+**Step 6: Verify Installation**
+
+1. Expand the **brave-real-browser** entry
+2. You should see list of 111 available tools
+3. If server fails to start, click **Quick Fix** button
+4. If issue persists, check troubleshooting section below
+
+**Step 7: Using Tools in Qoder AI**
+
+1. Switch to **Agent mode** in AI Chat panel
+2. Ask Qoder to use browser automation:
+   ```
+   Use brave-real-browser to navigate to https://example.com and extract the main content
+   ```
+3. Qoder will prompt for confirmation before using MCP tools
+4. Press `Ctrl+Enter` (Windows) or `⌘+Enter` (Mac) to execute
+
+**Important Notes:**
+
+- ⚠️ **Maximum 10 MCP servers** can be used simultaneously
+- ✅ **Only works in Agent mode** (not in Ask mode)
+- ✅ **Server auto-starts** when Qoder launches
+- ✅ **Node.js V18+ required** (includes NPM V8+)
+
+**Prerequisites Check:**
+
+```bash
+# Verify Node.js installation
+node -v  # Should show v18.0.0 or higher
+npx -v   # Should show version number
+
+# If not installed:
+# Windows: Download from https://nodejs.org/
+# Mac: brew install node
+# Linux: Use package manager (apt, yum, etc.)
+```
+
+**Troubleshooting:**
+
+**Issue: "context deadline exceeded" or Timeout Error**
+
+```
+failed to initialize MCP client: context deadline exceeded
+```
 
-**Location:**
+**Cause:** Qoder AI has a short initialization timeout. Using `npx` can be slow on first run because it needs to download and cache the package.
 
-- Windows: `%APPDATA%\Windsurf\mcp.json`
-- Mac: `~/.windsurf/mcp.json`
+**Solution 1 - Install Globally (Recommended):**
+```bash
+# Install package globally for instant startup
+npm install -g brave-real-browser-mcp-server@latest
+```
 
+Then update your configuration to:
 ```json
 {
   "mcpServers": {
     "brave-real-browser": {
-      "command": "npx",
-      "args": ["-y", "brave-real-browser-mcp-server@latest"]
+      "command": "brave-real-browser-mcp-server",
+      "args": []
     }
   }
 }
 ```
 
-### Cline (VSCode Extension)
+**Solution 2 - Pre-cache npx package:**
+```bash
+# Run once to cache the package
+npx -y brave-real-browser-mcp-server@latest
+# Press Ctrl+C after server starts
 
-**File:** `cline_mcp_settings.json`
+# Now npx will be fast on subsequent runs
+```
 
-**Location:**
+**Solution 3 - Use Direct Node Path:**
 
-- Windows: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
-- Mac: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+First, find the global package location:
+```bash
+# Windows
+npm root -g
+# Usually: C:\Users\<USERNAME>\AppData\Roaming\npm\node_modules
+
+# Mac/Linux  
+npm root -g
+# Usually: /usr/local/lib/node_modules
+```
 
+Then use full path:
 ```json
 {
   "mcpServers": {
     "brave-real-browser": {
-      "command": "npx",
-      "args": ["-y", "brave-real-browser-mcp-server@latest"]
+      "command": "node",
+      "args": ["<npm-root>\\brave-real-browser-mcp-server\\dist\\index.js"]
     }
   }
 }
 ```
 
-### Zed Editor
-
-**File:** `settings.json`
+**Issue: "exec: npx: executable file not found"**
 
-**Location:**
+```bash
+# Solution: Install Node.js V18 or later
+# Windows
+nvm install 22.14.0
+nvm use 22.14.0
 
-- Windows: `%APPDATA%\Zed\settings.json`
-- Mac: `~/.config/zed/settings.json`
+# Mac
+brew install node
 
-```json
-{
-  "context_servers": {
-    "brave-real-browser": {
-      "command": {
-        "path": "npx",
-        "args": ["-y", "brave-real-browser-mcp-server@latest"]
-      },
-      "settings": {}
-    }
-  }
-}
+# Verify
+node -v
+npx -v
 ```
 
-**Note:** Zed uses `context_servers` (not `lsp`) for MCP servers. Make sure you're using Zed Preview version for MCP support.
+**Issue: "failed to initialize MCP client: context deadline exceeded"**
 
-### Qoder AI / HTTP-based IDEs
+1. Click **Copy complete command** in Qoder UI
+2. Run command in terminal to see detailed error
+3. Check if Node.js is blocked by security software
+4. Add Node.js to security software whitelist
 
-Start server in HTTP mode and configure:
+**Issue: Server fails to connect**
 
-```json
-{
-  "extensions": {
-    "brave-real-browser": {
-      "type": "http",
-      "enabled": true,
-      "endpoint": "http://localhost:3000",
-      "timeout": 30000
-    }
-  }
-}
+1. Click **Retry** icon in Qoder interface
+2. Qoder will attempt to restart MCP server automatically
+3. Check **My Servers** tab for connection status
+4. Expand server details to see tools list
+
+**Issue: Tools not being called by LLM**
+
+1. Make sure you're in **Agent mode** (not Ask mode)
+2. Open a project directory in Qoder
+3. Ensure MCP server shows **link icon** (connected)
+4. Try explicit prompt: "Use brave-real-browser to..."
+
+**Configuration Locations:**
+
+- Windows: Qoder Settings → MCP → My Servers
+- Mac: Qoder Settings → MCP → My Servers
+- Linux: Qoder Settings → MCP → My Servers
+
+**Official Documentation:**
+- Qoder MCP Guide: https://docs.qoder.com/user-guide/chat/model-context-protocol
+- MCP Common Issues: https://docs.qoder.com/support/mcp-common-issues
+
+### 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"}'
 ```
 
 ---
@@ -620,47 +1555,432 @@ HTTP_PORT=3000
 
 ## 🐛 Troubleshooting
 
-### Brave Browser Not Found
+### Common Issues & Solutions
+
+#### 1. Brave Browser Not Found
 
-**Solution:**
+**Symptoms:**
+- Error: "Brave browser not found"
+- Browser fails to launch
+
+**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')
+```
+
+---
+
+#### 2. Server Won't Start
+
+**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
 ```
 
-### Server Won't Start
+**Step 4:** Check for conflicting processes
+```bash
+# Windows
+taskkill /F /IM brave.exe
+
+# Mac/Linux
+pkill -f brave
+```
 
-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`
+---
+
+#### 3. Port Already in Use (HTTP Mode)
 
-### Port Already in Use
+**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
+
+# 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
+  }
+});
+```
 
-1. Ensure CAPTCHA is fully loaded
-2. Try longer timeout: `{ "timeout": 30000 }`
-3. Try different CAPTCHA types: `recaptcha`, `hcaptcha`, `turnstile`
+**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 |
+|| **SSE**         | Real-time Streaming, Web Apps                 | ✅          | 🟢 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
 
 ---
 
@@ -694,7 +2014,7 @@ MIT License - See LICENSE file for details.
 
 <div align="center">
 
-**🌟 111 Tools | 15+ AI IDEs | 3 Protocols | Universal Support 🌟**
+**🌟 111 Tools | 15+ AI IDEs | 5 Protocols | Universal Support 🌟**
 
 **Made with ❤️ for the AI Development Community**