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

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
 
-# For HTTP-based Editors (Qoder AI, Custom)
+# 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
 ```
 
 ---
@@ -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,106 @@ 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 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,107 +639,273 @@ rm -rf ~/Library/Application\ Support/Cursor/Cache
 
 ### Qoder AI Editor
 
-**Protocol:** HTTP/WebSocket
+**Protocol:** MCP (STDIO) | **Setup Time:** 3 minutes | **Auto-Start:** ✅ Yes
 
-**⚠️ Important:** Qoder AI requires HTTP server to be running separately before configuration!
+**✅ Good News:** Qoder AI supports standard STDIO-based MCP servers (just like Claude, Cursor, Windsurf)!
 
-#### Step-by-Step Setup Guide:
-
-**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": []
+    }
+  }
+}
+```
+
+**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"
+      ]
+    }
+  }
+}
 ```
 
-**Step 3: Configure Qoder AI**
+**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`
 
-Open Qoder AI settings and add:
+**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**
+
+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
 
-Close and reopen Qoder AI for changes to take effect.
+**Step 6: Verify Installation**
 
-**Step 5: Verify Connection**
+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
 
-Check Qoder AI's output/console for connection confirmation.
+**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
-# Install pm2 globally
-npm install -g pm2
+# 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.)
+```
 
-# Start server in background
-pm2 start npx --name "brave-browser-server" -- brave-real-browser-mcp-server@latest --mode http --port 3000
+**Troubleshooting:**
 
-# View logs
-pm2 logs brave-browser-server
+**Issue: "context deadline exceeded" or Timeout Error**
 
-# Stop server
-pm2 stop brave-browser-server
 ```
+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
+# 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": "node",
+      "args": ["<npm-root>\\brave-real-browser-mcp-server\\dist\\index.js"]
+    }
+  }
+}
+```
+
+**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)
 
@@ -1402,6 +1680,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 +1738,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**
 

package/dist/index.js

@@ -111,11 +111,8 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => {
     console.error("🔍 [DEBUG] Prompts list requested");
     return { prompts: [] };
 });
-// Main tool call handler
-console.error("🔍 [DEBUG] Registering tool call handler...");
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-    console.error(`🔍 [DEBUG] Tool call received: ${name} with args: ${JSON.stringify(args)}`);
+// Tool execution function - exported for use in transports
+export async function executeToolByName(name, args) {
     try {
         let result;
         switch (name) {
@@ -492,6 +489,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             isError: true,
         };
     }
+}
+// Main tool call handler
+console.error("🔍 [DEBUG] Registering tool call handler...");
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    console.error(`🔍 [DEBUG] Tool call received: ${name} with args: ${JSON.stringify(args)}`);
+    return await executeToolByName(name, args);
 });
 // Main function - now using multi-protocol launcher
 import { main as launcherMain } from "./launcher.js";

package/dist/launcher.js

@@ -2,6 +2,7 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { HttpTransport } from "./transports/http-transport.js";
 import { LspTransport } from "./transports/lsp-transport.js";
+import { SseTransport } from "./transports/sse-transport.js";
 import { closeBrowser, forceKillAllBraveProcesses } from "./browser-manager.js";
 import { setupProcessCleanup } from "./core-infrastructure.js";
 import { UniversalIDEAdapter, ProtocolType, } from "./universal-ide-adapter.js";
@@ -9,6 +10,7 @@ export class MultiProtocolLauncher {
     config;
     httpTransport;
     lspTransport;
+    sseTransport;
     mcpServer;
     universalAdapter;
     constructor(config = {}) {
@@ -16,6 +18,8 @@ export class MultiProtocolLauncher {
             mode: config.mode || "auto",
             httpPort: config.httpPort || 3000,
             httpHost: config.httpHost || "0.0.0.0",
+            ssePort: config.ssePort || 3001,
+            sseHost: config.sseHost || "0.0.0.0",
             enableWebSocket: config.enableWebSocket !== false,
             enableCors: config.enableCors !== false,
             enableAutoDetection: config.enableAutoDetection !== false,
@@ -66,6 +70,9 @@ export class MultiProtocolLauncher {
             case "lsp":
                 await this.startLsp();
                 break;
+            case "sse":
+                await this.startSse();
+                break;
             case "all":
                 await this.startAll();
                 break;
@@ -111,6 +118,19 @@ export class MultiProtocolLauncher {
         await this.lspTransport.start();
         console.error("💡 [LSP] Compatible with: Zed Editor, VSCode, Neovim, Emacs, Sublime Text");
     }
+    async startSse() {
+        console.error("🟠 [SSE] Starting Server-Sent Events transport...");
+        if (this.universalAdapter?.getDetectionResult()) {
+            const result = this.universalAdapter.getDetectionResult();
+            console.error(`🎯 [SSE] Optimized for: ${result.capabilities.name}`);
+        }
+        this.sseTransport = new SseTransport({
+            port: this.config.ssePort,
+            host: this.config.sseHost,
+        });
+        await this.sseTransport.start();
+        console.error("💡 [SSE] Real-time streaming - works with web apps and modern clients");
+    }
     async startAll() {
         console.error("🌈 Starting all protocols...");
         // Start HTTP in background
@@ -137,6 +157,9 @@ export class MultiProtocolLauncher {
         if (this.lspTransport) {
             await this.lspTransport.stop();
         }
+        if (this.sseTransport) {
+            await this.sseTransport.stop();
+        }
         console.error("✅ All servers stopped");
     }
 }
@@ -148,17 +171,20 @@ export function parseArgs() {
         const arg = args[i];
         if (arg === "--mode" || arg === "-m") {
             const mode = args[++i];
-            if (["auto", "mcp", "http", "lsp", "all"].includes(mode)) {
+            if (["auto", "mcp", "http", "lsp", "sse", "all"].includes(mode)) {
                 config.mode = mode;
             }
             else {
-                console.error(`❌ Invalid mode: ${mode}. Use: auto, mcp, http, lsp, or all`);
+                console.error(`❌ Invalid mode: ${mode}. Use: auto, mcp, http, lsp, sse, or all`);
                 process.exit(1);
             }
         }
         else if (arg === "--port" || arg === "-p") {
             config.httpPort = parseInt(args[++i]);
         }
+        else if (arg === "--sse-port") {
+            config.ssePort = parseInt(args[++i]);
+        }
         else if (arg === "--host" || arg === "-h") {
             config.httpHost = args[++i];
         }
@@ -179,9 +205,10 @@ Brave Real Browser MCP Server - Universal AI IDE Support
 Usage: brave-real-browser-mcp-server [options]
 
 Options:
-  --mode, -m <mode>       Protocol mode: auto, mcp, http, lsp, or all (default: auto)
+  --mode, -m <mode>       Protocol mode: auto, mcp, http, lsp, sse, or all (default: auto)
   --port, -p <port>       HTTP server port (default: 3000)
-  --host, -h <host>       HTTP server host (default: 0.0.0.0)
+  --sse-port <port>       SSE server port (default: 3001)
+  --host, -h <host>       HTTP/SSE server host (default: 0.0.0.0)
   --no-websocket          Disable WebSocket support in HTTP mode
   --no-auto-detect        Disable automatic IDE detection
   --list-ides             Show list of all supported AI IDEs
@@ -211,7 +238,10 @@ Examples:
   # LSP mode (for Zed, VSCode, Neovim, Emacs, Sublime Text)
   brave-real-browser-mcp-server --mode lsp
 
-  # All protocols (HTTP only, MCP/LSP need separate instances)
+  # SSE mode (for real-time streaming, web apps)
+  brave-real-browser-mcp-server --mode sse --sse-port 3001
+
+  # All protocols (HTTP only, MCP/LSP/SSE need separate instances)
   brave-real-browser-mcp-server --mode all
 
   # Show all supported IDEs

package/dist/transports/http-transport.js

@@ -1,13 +1,13 @@
 import express from 'express';
 import { createServer } from 'http';
 import { WebSocketServer } from 'ws';
-import { TOOLS, TOOL_NAMES } from '../tool-definitions.js';
-// Import all handlers
+import { TOOLS } from '../tool-definitions.js';
+import { executeToolByName } from '../index.js';
+// Import specific handlers for direct endpoints (for backward compatibility)
 import { handleBrowserInit, handleBrowserClose } from '../handlers/browser-handlers.js';
-import { handleNavigate, handleWait } from '../handlers/navigation-handlers.js';
-import { handleClick, handleType, handleSolveCaptcha, handleRandomScroll } from '../handlers/interaction-handlers.js';
-import { handleGetContent, handleFindSelector } from '../handlers/content-handlers.js';
-import { handleSaveContentAsMarkdown } from '../handlers/file-handlers.js';
+import { handleNavigate } from '../handlers/navigation-handlers.js';
+import { handleClick, handleType } from '../handlers/interaction-handlers.js';
+import { handleGetContent } from '../handlers/content-handlers.js';
 export class HttpTransport {
     app;
     server = null;
@@ -128,32 +128,8 @@ export class HttpTransport {
         });
     }
     async executeTool(toolName, args) {
-        switch (toolName) {
-            case TOOL_NAMES.BROWSER_INIT:
-                return await handleBrowserInit(args || {});
-            case TOOL_NAMES.NAVIGATE:
-                return await handleNavigate(args);
-            case TOOL_NAMES.GET_CONTENT:
-                return await handleGetContent(args || {});
-            case TOOL_NAMES.CLICK:
-                return await handleClick(args);
-            case TOOL_NAMES.TYPE:
-                return await handleType(args);
-            case TOOL_NAMES.WAIT:
-                return await handleWait(args);
-            case TOOL_NAMES.BROWSER_CLOSE:
-                return await handleBrowserClose();
-            case TOOL_NAMES.SOLVE_CAPTCHA:
-                return await handleSolveCaptcha(args);
-            case TOOL_NAMES.RANDOM_SCROLL:
-                return await handleRandomScroll();
-            case TOOL_NAMES.FIND_SELECTOR:
-                return await handleFindSelector(args);
-            case TOOL_NAMES.SAVE_CONTENT_AS_MARKDOWN:
-                return await handleSaveContentAsMarkdown(args);
-            default:
-                throw new Error(`Unknown tool: ${toolName}`);
-        }
+        // Use universal tool executor from index.ts (supports all 110 tools)
+        return await executeToolByName(toolName, args);
     }
     setupWebSocket() {
         if (!this.server || !this.config.enableWebSocket)

package/dist/transports/sse-transport.js

@@ -0,0 +1,302 @@
+import express from 'express';
+import { createServer } from 'http';
+import { TOOLS } from '../tool-definitions.js';
+import { executeToolByName } from '../index.js';
+// Import specific handlers for direct endpoints (for backward compatibility)
+import { handleBrowserInit, handleBrowserClose } from '../handlers/browser-handlers.js';
+import { handleNavigate } from '../handlers/navigation-handlers.js';
+import { handleClick, handleType } from '../handlers/interaction-handlers.js';
+import { handleGetContent } from '../handlers/content-handlers.js';
+export class SseTransport {
+    app;
+    server = null;
+    config;
+    clients = new Map();
+    heartbeatTimer = null;
+    constructor(config = {}) {
+        this.config = {
+            port: config.port || 3001,
+            host: config.host || '0.0.0.0',
+            corsOrigins: config.corsOrigins || ['*'],
+            heartbeatInterval: config.heartbeatInterval || 30000, // 30 seconds
+        };
+        this.app = express();
+        this.setupMiddleware();
+        this.setupRoutes();
+    }
+    setupMiddleware() {
+        // Body parsing
+        this.app.use(express.json());
+        this.app.use(express.urlencoded({ extended: true }));
+        // CORS with SSE-specific headers
+        this.app.use((req, res, next) => {
+            res.header('Access-Control-Allow-Origin', this.config.corsOrigins?.[0] || '*');
+            res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+            res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization, Cache-Control');
+            res.header('Access-Control-Expose-Headers', 'Content-Type, Cache-Control');
+            if (req.method === 'OPTIONS') {
+                return res.sendStatus(200);
+            }
+            next();
+        });
+        // Request logging
+        this.app.use((req, res, next) => {
+            console.error(`📡 [SSE] ${req.method} ${req.path} - ${new Date().toISOString()}`);
+            next();
+        });
+    }
+    setupRoutes() {
+        // Health check
+        this.app.get('/health', (req, res) => {
+            res.json({
+                status: 'ok',
+                timestamp: new Date().toISOString(),
+                protocol: 'SSE',
+                clients: this.clients.size,
+            });
+        });
+        // List all available tools
+        this.app.get('/tools', (req, res) => {
+            res.json({ tools: TOOLS });
+        });
+        // SSE event stream endpoint
+        this.app.get('/events', (req, res) => {
+            // Set SSE headers
+            res.setHeader('Content-Type', 'text/event-stream');
+            res.setHeader('Cache-Control', 'no-cache');
+            res.setHeader('Connection', 'keep-alive');
+            res.setHeader('X-Accel-Buffering', 'no'); // Disable nginx buffering
+            const clientId = `client_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            // Add client to active connections
+            this.clients.set(clientId, {
+                id: clientId,
+                response: res,
+                lastActivity: Date.now(),
+            });
+            console.error(`📡 [SSE] Client connected: ${clientId} (Total: ${this.clients.size})`);
+            // Send initial connection message
+            this.sendEvent(res, 'connected', {
+                clientId,
+                message: 'Connected to Brave Browser MCP Server',
+                timestamp: new Date().toISOString(),
+            });
+            // Handle client disconnect
+            req.on('close', () => {
+                this.clients.delete(clientId);
+                console.error(`📡 [SSE] Client disconnected: ${clientId} (Remaining: ${this.clients.size})`);
+            });
+        });
+        // Execute tool via POST with SSE response
+        this.app.post('/tools/:toolName', async (req, res) => {
+            const { toolName } = req.params;
+            const args = req.body;
+            const clientId = req.headers['x-client-id'];
+            try {
+                // Send start event to SSE clients
+                this.broadcastEvent('tool_start', {
+                    tool: toolName,
+                    timestamp: new Date().toISOString(),
+                });
+                const result = await this.executeTool(toolName, args);
+                // Send success event to SSE clients
+                this.broadcastEvent('tool_success', {
+                    tool: toolName,
+                    timestamp: new Date().toISOString(),
+                });
+                res.json({ success: true, result });
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                // Send error event to SSE clients
+                this.broadcastEvent('tool_error', {
+                    tool: toolName,
+                    error: errorMessage,
+                    timestamp: new Date().toISOString(),
+                });
+                res.status(500).json({ success: false, error: errorMessage });
+            }
+        });
+        // Browser automation endpoints with SSE notifications
+        this.app.post('/browser/init', async (req, res) => {
+            try {
+                this.broadcastEvent('browser_init_start', { timestamp: new Date().toISOString() });
+                const result = await handleBrowserInit(req.body);
+                this.broadcastEvent('browser_init_success', { timestamp: new Date().toISOString() });
+                res.json({ success: true, result });
+            }
+            catch (error) {
+                this.broadcastEvent('browser_init_error', {
+                    error: error.message,
+                    timestamp: new Date().toISOString()
+                });
+                res.status(500).json({ success: false, error: error.message });
+            }
+        });
+        this.app.post('/browser/navigate', async (req, res) => {
+            try {
+                this.broadcastEvent('browser_navigate_start', {
+                    url: req.body.url,
+                    timestamp: new Date().toISOString()
+                });
+                const result = await handleNavigate(req.body);
+                this.broadcastEvent('browser_navigate_success', {
+                    url: req.body.url,
+                    timestamp: new Date().toISOString()
+                });
+                res.json({ success: true, result });
+            }
+            catch (error) {
+                this.broadcastEvent('browser_navigate_error', {
+                    error: error.message,
+                    timestamp: new Date().toISOString()
+                });
+                res.status(500).json({ success: false, error: error.message });
+            }
+        });
+        this.app.post('/browser/click', async (req, res) => {
+            try {
+                const result = await handleClick(req.body);
+                this.broadcastEvent('browser_action', {
+                    action: 'click',
+                    selector: req.body.selector,
+                    timestamp: new Date().toISOString()
+                });
+                res.json({ success: true, result });
+            }
+            catch (error) {
+                res.status(500).json({ success: false, error: error.message });
+            }
+        });
+        this.app.post('/browser/type', async (req, res) => {
+            try {
+                const result = await handleType(req.body);
+                this.broadcastEvent('browser_action', {
+                    action: 'type',
+                    selector: req.body.selector,
+                    timestamp: new Date().toISOString()
+                });
+                res.json({ success: true, result });
+            }
+            catch (error) {
+                res.status(500).json({ success: false, error: error.message });
+            }
+        });
+        this.app.post('/browser/get-content', async (req, res) => {
+            try {
+                const result = await handleGetContent(req.body);
+                res.json({ success: true, result });
+            }
+            catch (error) {
+                res.status(500).json({ success: false, error: error.message });
+            }
+        });
+        this.app.post('/browser/close', async (req, res) => {
+            try {
+                this.broadcastEvent('browser_close', { timestamp: new Date().toISOString() });
+                const result = await handleBrowserClose();
+                res.json({ success: true, result });
+            }
+            catch (error) {
+                res.status(500).json({ success: false, error: error.message });
+            }
+        });
+        // Error handling
+        this.app.use((err, req, res, next) => {
+            console.error('❌ [SSE] Error:', err);
+            res.status(500).json({ success: false, error: err.message });
+        });
+    }
+    async executeTool(toolName, args) {
+        // Use universal tool executor from index.ts (supports all 110 tools)
+        return await executeToolByName(toolName, args);
+    }
+    sendEvent(res, eventType, data) {
+        const eventData = `event: ${eventType}\ndata: ${JSON.stringify(data)}\n\n`;
+        res.write(eventData);
+    }
+    broadcastEvent(eventType, data) {
+        const eventData = `event: ${eventType}\ndata: ${JSON.stringify(data)}\n\n`;
+        this.clients.forEach((client, clientId) => {
+            try {
+                client.response.write(eventData);
+                client.lastActivity = Date.now();
+            }
+            catch (error) {
+                console.error(`❌ [SSE] Failed to send to client ${clientId}:`, error);
+                this.clients.delete(clientId);
+            }
+        });
+    }
+    startHeartbeat() {
+        this.heartbeatTimer = setInterval(() => {
+            const now = Date.now();
+            this.clients.forEach((client, clientId) => {
+                try {
+                    // Send heartbeat
+                    client.response.write(': heartbeat\n\n');
+                    // Check for stale connections (no activity for 2 minutes)
+                    if (now - client.lastActivity > 120000) {
+                        console.error(`📡 [SSE] Removing stale client: ${clientId}`);
+                        client.response.end();
+                        this.clients.delete(clientId);
+                    }
+                }
+                catch (error) {
+                    console.error(`❌ [SSE] Heartbeat failed for client ${clientId}:`, error);
+                    this.clients.delete(clientId);
+                }
+            });
+        }, this.config.heartbeatInterval);
+    }
+    async start() {
+        return new Promise((resolve) => {
+            this.server = createServer(this.app);
+            this.server.listen(this.config.port, this.config.host, () => {
+                console.error(`✅ [SSE] Server running on http://${this.config.host}:${this.config.port}`);
+                console.error(`📡 [SSE] Event stream available at http://${this.config.host}:${this.config.port}/events`);
+                console.error(`💡 [SSE] Real-time browser automation events enabled`);
+                this.startHeartbeat();
+                resolve();
+            });
+        });
+    }
+    async stop() {
+        return new Promise((resolve, reject) => {
+            // Stop heartbeat
+            if (this.heartbeatTimer) {
+                clearInterval(this.heartbeatTimer);
+                this.heartbeatTimer = null;
+            }
+            // Close all SSE connections
+            this.clients.forEach((client, clientId) => {
+                try {
+                    client.response.end();
+                }
+                catch (error) {
+                    console.error(`❌ [SSE] Error closing client ${clientId}:`, error);
+                }
+            });
+            this.clients.clear();
+            // Close server
+            if (this.server) {
+                this.server.close((err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    // Public method to broadcast custom events
+    broadcast(eventType, data) {
+        this.broadcastEvent(eventType, data);
+    }
+    // Get connected clients count
+    getClientsCount() {
+        return this.clients.size;
+    }
+}

package/dist/transports/sse-transport.test.js

@@ -0,0 +1,242 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { SseTransport } from './sse-transport.js';
+describe('SSE Transport', () => {
+    let transport;
+    const TEST_PORT = 3099; // Use different port to avoid conflicts
+    const TEST_HOST = 'localhost';
+    beforeAll(async () => {
+        transport = new SseTransport({
+            port: TEST_PORT,
+            host: TEST_HOST,
+            heartbeatInterval: 5000,
+        });
+        await transport.start();
+        // Give server time to fully start
+        await new Promise(resolve => setTimeout(resolve, 100));
+    });
+    afterAll(async () => {
+        await transport.stop();
+    });
+    describe('Server Initialization', () => {
+        it('should start SSE server successfully', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/health`);
+            const data = await response.json();
+            expect(response.status).toBe(200);
+            expect(data.status).toBe('ok');
+            expect(data.protocol).toBe('SSE');
+        });
+        it('should return tools list', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/tools`);
+            const data = await response.json();
+            expect(response.status).toBe(200);
+            expect(data.tools).toBeDefined();
+            expect(Array.isArray(data.tools)).toBe(true);
+            expect(data.tools.length).toBeGreaterThan(0);
+        });
+    });
+    describe('SSE Event Stream', () => {
+        it('should establish SSE connection and receive connected event', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/events`, {
+                headers: {
+                    'Accept': 'text/event-stream',
+                },
+            });
+            expect(response.status).toBe(200);
+            expect(response.headers.get('content-type')).toBe('text/event-stream');
+            expect(response.headers.get('cache-control')).toBe('no-cache');
+            expect(response.headers.get('connection')).toBe('keep-alive');
+        });
+        it('should track connected clients', async () => {
+            const initialClientsCount = transport.getClientsCount();
+            // Establish SSE connection
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/events`, {
+                headers: {
+                    'Accept': 'text/event-stream',
+                },
+            });
+            // Wait a bit for connection to be registered
+            await new Promise(resolve => setTimeout(resolve, 100));
+            const currentClientsCount = transport.getClientsCount();
+            expect(currentClientsCount).toBeGreaterThan(initialClientsCount);
+        });
+    });
+    describe('Browser Tool Execution', () => {
+        it('should handle browser init failure gracefully', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/browser/init`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({}),
+            });
+            const data = await response.json();
+            expect([200, 500]).toContain(response.status);
+            expect(data).toHaveProperty('success');
+            expect(data).toHaveProperty('result');
+        });
+        it('should handle navigation without browser', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/browser/navigate`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ url: 'https://example.com' }),
+            });
+            const data = await response.json();
+            expect(response.status).toBe(500);
+            expect(data.success).toBe(false);
+            expect(data.error).toBeTruthy();
+        });
+        it('should handle get-content without browser', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/browser/get-content`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ type: 'text' }),
+            });
+            const data = await response.json();
+            expect(response.status).toBe(500);
+            expect(data.success).toBe(false);
+            expect(data.error).toBeTruthy();
+        });
+    });
+    describe('Generic Tool Execution', () => {
+        it('should reject unknown tool', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/tools/unknown_tool`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({}),
+            });
+            const data = await response.json();
+            // MCP format: errors are returned in content with isError flag
+            expect(response.status).toBe(200);
+            expect(data.success).toBe(true);
+            expect(data.result.isError).toBe(true);
+            expect(data.result.content[0].text).toContain('Unknown tool');
+        });
+        it('should validate tool arguments', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/tools/navigate`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ /* missing url */}),
+            });
+            const data = await response.json();
+            expect(response.status).toBe(500);
+            expect(data.success).toBe(false);
+        });
+    });
+    describe('CORS Headers', () => {
+        it('should include CORS headers', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/health`);
+            expect(response.headers.get('access-control-allow-origin')).toBeTruthy();
+            expect(response.headers.get('access-control-allow-methods')).toBeTruthy();
+        });
+        it('should handle OPTIONS preflight', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/tools`, {
+                method: 'OPTIONS',
+            });
+            expect(response.status).toBe(200);
+        });
+    });
+    describe('Event Broadcasting', () => {
+        it('should broadcast custom events', () => {
+            // This is a unit test for the broadcast method
+            expect(typeof transport.broadcast).toBe('function');
+            // Call broadcast (won't fail even with no clients)
+            expect(() => {
+                transport.broadcast('test_event', { test: 'data' });
+            }).not.toThrow();
+        });
+        it('should handle broadcast to disconnected clients', () => {
+            // Broadcast should handle errors gracefully
+            expect(() => {
+                transport.broadcast('error_test', { data: 'test' });
+            }).not.toThrow();
+        });
+    });
+    describe('Error Handling', () => {
+        it('should handle malformed JSON', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/tools/navigate`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: 'invalid json',
+            });
+            expect(response.status).toBe(500); // Express body-parser returns 500 for bad JSON
+        });
+        it('should handle missing request body', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/browser/navigate`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+            });
+            const data = await response.json();
+            expect(response.status).toBe(500);
+            expect(data.success).toBe(false);
+        });
+    });
+    describe('Server Lifecycle', () => {
+        it('should stop gracefully', async () => {
+            const tempTransport = new SseTransport({
+                port: TEST_PORT + 1,
+                host: TEST_HOST,
+            });
+            await tempTransport.start();
+            expect(tempTransport.getClientsCount()).toBe(0);
+            await tempTransport.stop();
+            // Verify server is stopped by trying to connect
+            await expect(fetch(`http://${TEST_HOST}:${TEST_PORT + 1}/health`)).rejects.toThrow();
+        });
+        it('should handle stop when no clients connected', async () => {
+            const tempTransport = new SseTransport({
+                port: TEST_PORT + 2,
+                host: TEST_HOST,
+            });
+            await tempTransport.start();
+            await tempTransport.stop();
+            expect(tempTransport.getClientsCount()).toBe(0);
+        });
+    });
+    describe('Configuration', () => {
+        it('should use default configuration', () => {
+            const defaultTransport = new SseTransport();
+            expect(defaultTransport).toBeDefined();
+            // Don't start it to avoid port conflicts
+        });
+        it('should use custom port and host', async () => {
+            const customTransport = new SseTransport({
+                port: TEST_PORT + 3,
+                host: '127.0.0.1',
+                heartbeatInterval: 10000,
+            });
+            await customTransport.start();
+            const response = await fetch(`http://127.0.0.1:${TEST_PORT + 3}/health`);
+            const data = await response.json();
+            expect(response.status).toBe(200);
+            expect(data.status).toBe('ok');
+            await customTransport.stop();
+        });
+    });
+    describe('Health Check Details', () => {
+        it('should include client count in health check', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/health`);
+            const data = await response.json();
+            expect(data).toHaveProperty('clients');
+            expect(typeof data.clients).toBe('number');
+            expect(data.clients).toBeGreaterThanOrEqual(0);
+        });
+        it('should include timestamp in health check', async () => {
+            const response = await fetch(`http://${TEST_HOST}:${TEST_PORT}/health`);
+            const data = await response.json();
+            expect(data).toHaveProperty('timestamp');
+            expect(new Date(data.timestamp).getTime()).toBeGreaterThan(0);
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brave-real-browser-mcp-server",
-  "version": "2.12.5",
+  "version": "2.12.7",
   "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",