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

package/README.md

@@ -12,6 +12,8 @@
 
 **सभी AI IDEs के लिए Universal MCP Server | 111+ Tools | Browser Automation | Web Scraping | CAPTCHA Solving**
 
+[📖 **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.)
@@ -37,26 +39,36 @@
 
 **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 |
+| 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
-# For MCP Editors (Claude, Cursor, Windsurf)
-npx -y brave-real-browser-mcp-server@latest
+# 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
 
-# For HTTP-based Editors (Qoder AI, Custom)
+# 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
 ```
 
 ---
@@ -155,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.
 
@@ -168,6 +180,382 @@ 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
@@ -527,108 +915,274 @@ rm -rf ~/Library/Application\ Support/Cursor/Cache
 
 ### Qoder AI Editor
 
-**Protocol:** HTTP/WebSocket
-
-**⚠️ Important:** Qoder AI requires HTTP server to be running separately before configuration!
+**Protocol:** MCP (STDIO) | **Setup Time:** 3 minutes | **Auto-Start:** ✅ Yes
 
-#### Step-by-Step Setup Guide:
+**✅ Good News:** Qoder AI supports standard STDIO-based MCP servers (just like Claude, Cursor, Windsurf)!
 
-**Step 1: Start HTTP Server First**
+#### 📋 Step-by-Step Setup Guide:
 
-Open a terminal and run:
+**Step 1: Open Qoder Settings**
 
 ```bash
-# Windows (PowerShell)
-npx brave-real-browser-mcp-server@latest --mode http --port 3000
+# Method 1: Using keyboard shortcut
+# Windows: Ctrl + Shift + ,
+# Mac: ⌘ + Shift + ,
 
-# Mac/Linux
-npx brave-real-browser-mcp-server@latest --mode http --port 3000
+# Method 2: Click user icon in upper-right corner
+# Then select "Qoder Settings"
 ```
 
-**Expected Output:**
-```
-🟢 [HTTP] Starting HTTP/WebSocket server...
-✅ [HTTP] Server ready at http://localhost:3000
-💡 [HTTP] Universal mode - works with ALL AI IDEs
-```
+**Step 2: Navigate to MCP Section**
 
-**Step 2: Test Server is Running**
+1. In left-side navigation pane, click **MCP**
+2. Click on **My Servers** tab
+3. Click **+ Add** button in upper-right corner
 
-Open another terminal and verify:
+**Step 3: Install Package Globally (Important for Qoder AI)**
 
 ```bash
-# Health check
-curl http://localhost:3000/health
+# Install globally for faster startup
+npm install -g brave-real-browser-mcp-server@latest
 
-# Expected response:
-# {"status":"ok","timestamp":"..."}
+# Verify installation
+where brave-real-browser-mcp-server  # Windows
+which brave-real-browser-mcp-server  # Mac/Linux
+```
 
-# List all tools
-curl http://localhost:3000/tools
+**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": []
+    }
+  }
+}
 ```
 
-**Step 3: Configure Qoder AI**
+**Option B - Using NPX (May timeout on first run):**
+```json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server@latest"]
+    }
+  }
+}
+```
 
-Open Qoder AI settings and add:
+**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):**
 
-**Option A - MCP Configuration (Recommended):**
 ```json
 {
   "mcpServers": {
     "brave-real-browser": {
-      "type": "http",
-      "endpoint": "http://localhost:3000",
-      "enabled": true,
-      "timeout": 30000
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server@latest"],
+      "env": {
+        "BRAVE_PATH": "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
+        "HEADLESS": "false"
+      }
     }
   }
 }
 ```
 
-**Option B - Extensions Configuration:**
+**For Mac:**
+
 ```json
 {
-  "extensions": {
+  "mcpServers": {
     "brave-real-browser": {
-      "type": "http",
-      "enabled": true,
-      "endpoint": "http://localhost:3000",
-      "timeout": 30000
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server@latest"],
+      "env": {
+        "BRAVE_PATH": "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+      }
     }
   }
 }
 ```
 
-**Step 4: Restart Qoder AI**
+**Step 5: Save Configuration**
 
-Close and reopen Qoder AI for changes to take effect.
+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 5: Verify Connection**
+**Step 6: Verify Installation**
 
-Check Qoder AI's output/console for connection confirmation.
+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:**
-- 🔴 **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):**
+- ⚠️ **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
+```
+
+**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.
+
+**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": "brave-real-browser-mcp-server",
+      "args": []
+    }
+  }
+}
+```
+
+**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
 
+# Now npx will be fast on subsequent runs
+```
+
+**Solution 3 - Use Direct Node Path:**
+
+First, find the global package location:
 ```bash
-# Install pm2 globally
-npm install -g pm2
+# Windows
+npm root -g
+# Usually: C:\Users\<USERNAME>\AppData\Roaming\npm\node_modules
 
-# Start server in background
-pm2 start npx --name "brave-browser-server" -- brave-real-browser-mcp-server@latest --mode http --port 3000
+# Mac/Linux  
+npm root -g
+# Usually: /usr/local/lib/node_modules
+```
 
-# View logs
-pm2 logs brave-browser-server
+Then use full path:
+```json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "node",
+      "args": ["<npm-root>\\brave-real-browser-mcp-server\\dist\\index.js"]
+    }
+  }
+}
+```
 
-# Stop server
-pm2 stop brave-browser-server
+**Issue: "exec: npx: executable file not found"**
+
+```bash
+# Solution: Install Node.js V18 or later
+# Windows
+nvm install 22.14.0
+nvm use 22.14.0
+
+# Mac
+brew install node
+
+# Verify
+node -v
+npx -v
 ```
 
+**Issue: "failed to initialize MCP client: context deadline exceeded"**
+
+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
+
+**Issue: Server fails to connect**
+
+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
@@ -1402,6 +1956,7 @@ DEBUG=* npx brave-real-browser-mcp-server@latest --mode http
 || **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 |
 
 ---
 
@@ -1459,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**