brave-real-browser-mcp-server 2.0.3 → 2.0.6

package/README.md

@@ -13,20 +13,24 @@ Provides AI assistants with powerful, detection-resistant browser automation cap
 2. [Introduction](#introduction)
 3. [Features](#features)
 4. [Prerequisites](#prerequisites)
-5. [Installation](#installation)
-6. [Usage](#usage)
+5. [Platform-Specific Installation](#platform-specific-installation)
+   - [Windows Installation](#windows-installation)
+   - [macOS Installation](#macos-installation)
+   - [Linux Installation](#linux-installation)
+6. [Installation](#installation)
+7. [Usage](#usage)
    - [With Claude Desktop](#with-claude-desktop)
    - [With Claude Code CLI](#with-claude-code-cli)
    - [With Cursor IDE](#with-cursor-ide)
    - [With Other AI Assistants](#with-other-ai-assistants)
-7. [Available Tools](#available-tools)
-8. [Advanced Features](#advanced-features)
-9. [Configuration](#configuration)
-10. [Troubleshooting](#troubleshooting)
-11. [Development](#development)
-12. [Testing](#testing)
-13. [Contributing](#contributing)
-14. [License](#license)
+8. [Available Tools](#available-tools)
+9. [Advanced Features](#advanced-features)
+10. [Configuration](#configuration)
+11. [Troubleshooting](#troubleshooting)
+12. [Development](#development)
+13. [Testing](#testing)
+14. [Contributing](#contributing)
+15. [License](#license)
 
 ## Quick Start for Beginners
 
@@ -104,17 +108,22 @@ Once set up, you can ask Claude to:
 ## Introduction
 
 The Brave Real Browser MCP Server acts as a bridge between AI assistants
-and browser automation. It leverages brave-real-browser to provide stealth
-browsing capabilities that can bypass common bot detection mechanisms.
+and browser automation. It leverages the **brave-real-browser** package to provide
+advanced stealth browsing capabilities that can bypass common bot detection mechanisms.
+
+**🎯 Optimized for Brave Browser**: While compatible with Chrome and Chromium,
+this server is specifically optimized for Brave Browser, providing enhanced
+privacy, ad-blocking, and anti-fingerprinting capabilities out-of-the-box.
 
 This server implements the Model Context Protocol (MCP), allowing AI
-assistants to control a real browser, extract content, and more.
+assistants to control a real browser, extract content, solve CAPTCHAs, and perform
+complex web automation tasks with human-like behavior.
 
 ## Features
 
 - **Stealth by default**: All browser instances use anti-detection features
-- **Enhanced Windows support**: Comprehensive Chrome detection and ECONNREFUSED error fixes (v1.3.0)
-- **Smart Chrome detection**: Registry-based detection + 15+ installation paths (Windows)
+- **Enhanced Windows support**: Comprehensive Brave/Chrome detection and ECONNREFUSED error fixes
+- **Smart browser detection**: Registry-based detection + 15+ installation paths for Brave and Chrome (Windows)
 - **Connection resilience**: Automatic localhost/127.0.0.1 fallback with port management
 - **Multiple retry strategies**: 5 different connection approaches with progressive fallback
 - **Advanced configuration**: Full support for all brave-real-browser options
@@ -132,27 +141,384 @@ assistants to control a real browser, extract content, and more.
 
 - Node.js >= 18.0.0
 - npm or yarn
-- Google Chrome or Chromium browser installed
+- **Brave Browser** (recommended) or Google Chrome/Chromium browser installed
 - Basic understanding of TypeScript/JavaScript (for development)
 
 ### Platform-Specific Requirements
 
 **Windows:**
-- Google Chrome installation (automatic detection in v1.3.0+ includes):
-  - Standard installations: `C:\Program Files\Google\Chrome\Application\chrome.exe`
-  - 32-bit installations: `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`
-  - User installations: `%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe`
-  - Chrome Canary: `%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe`
+- **Brave Browser** (recommended) or Google Chrome installation (automatic detection includes):
+  - **Brave Browser paths:**
+    - Standard: `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`
+    - 32-bit: `C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`
+    - User: `%LOCALAPPDATA%\BraveSoftware\Brave-Browser\Application\brave.exe`
+    - Nightly: `%LOCALAPPDATA%\BraveSoftware\Brave-Browser-Nightly\Application\brave.exe`
+  - **Google Chrome paths:**
+    - Standard: `C:\Program Files\Google\Chrome\Application\chrome.exe`
+    - 32-bit: `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`
+    - User: `%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe`
+    - Canary: `%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe`
   - Portable installations and Registry-detected paths
-  - Manual path specification: Use `CHROME_PATH` environment variable
+  - Manual path specification: Use `CHROME_PATH` or `BRAVE_PATH` environment variable
 
 **macOS:**
-- Google Chrome or Chromium must be installed in `/Applications/`
+- **Brave Browser** (recommended): Install from [brave.com](https://brave.com) or App Store
+- Alternative: Google Chrome or Chromium in `/Applications/`
+- **Brave paths:**
+  - `/Applications/Brave Browser.app/Contents/MacOS/Brave Browser`
+  - `/Applications/Brave Browser Nightly.app/Contents/MacOS/Brave Browser Nightly`
 
 **Linux:**
-- Install Chrome/Chromium: `sudo apt-get install -y google-chrome-stable` or `sudo apt-get install -y chromium-browser`
+- **Brave Browser** (recommended):
+  ```bash
+  # Install Brave Browser
+  sudo curl -fsSLo /usr/share/keyrings/brave-browser-archive-keyring.gpg https://brave-browser-apt-release.s3.brave.com/brave-browser-archive-keyring.gpg
+  echo "deb [signed-by=/usr/share/keyrings/brave-browser-archive-keyring.gpg] https://brave-browser-apt-release.s3.brave.com/ stable main" | sudo tee /etc/apt/sources.list.d/brave-browser-release.list
+  sudo apt update && sudo apt install brave-browser
+  ```
+- **Alternative Chrome/Chromium:**
+  ```bash
+  sudo apt-get install -y google-chrome-stable
+  # or
+  sudo apt-get install -y chromium-browser
+  ```
 - Install xvfb for headless operation: `sudo apt-get install -y xvfb`
 
+## Platform-Specific Installation
+
+> **🎯 Choose Your Platform:** Select the installation method that matches your operating system. Each section includes complete setup commands for both Brave Browser and MCP server configuration.
+
+### Windows Installation
+
+#### Method 1: Complete Windows Setup (Recommended)
+
+**Step 1: Install Node.js**
+```powershell
+# Download and install from nodejs.org, or use winget
+winget install OpenJS.NodeJS
+
+# Verify installation
+node --version
+npm --version
+```
+
+**Step 2: Install Brave Browser (Recommended)**
+```powershell
+# Option 1: Download from brave.com
+# Visit: https://brave.com/download/
+
+# Option 2: Use winget
+winget install BraveSoftware.BraveBrowser
+
+# Option 3: Use Chocolatey
+choco install brave
+
+# Verify installation
+& "C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe" --version
+```
+
+**Step 3: Setup Claude Desktop MCP Configuration**
+```powershell
+# Create Claude config directory
+$configPath = "$env:APPDATA\Claude"
+if (!(Test-Path $configPath)) { New-Item -ItemType Directory -Path $configPath }
+
+# Create MCP configuration file
+@"
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "npx",
+      "args": ["brave-real-browser-mcp-server@latest"]
+    }
+  }
+}
+"@ | Out-File -FilePath "$configPath\claude_desktop_config.json" -Encoding UTF8
+
+echo "✅ Claude Desktop MCP configuration created successfully!"
+echo "📁 Config file location: $configPath\claude_desktop_config.json"
+```
+
+**Step 4: Setup Environment Variables (Optional)**
+```powershell
+# Set Brave Browser path (if not auto-detected)
+[Environment]::SetEnvironmentVariable("BRAVE_PATH", "C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe", "User")
+
+# Alternative: Set Chrome path (if Brave not available)
+# [Environment]::SetEnvironmentVariable("CHROME_PATH", "C:\Program Files\Google\Chrome\Application\chrome.exe", "User")
+
+echo "✅ Environment variables set successfully!"
+```
+
+**Step 5: Test MCP Server**
+```powershell
+# Test the MCP server directly
+npx brave-real-browser-mcp-server@latest --help
+
+# Test with Claude Desktop (restart Claude first)
+echo "🔄 Restart Claude Desktop and test with: 'Initialize a browser and navigate to google.com'"
+```
+
+#### Method 2: Quick Setup (One-liner)
+```powershell
+# Complete Windows setup in one command
+iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/codeiva4u/Brave-Real-Browser-Mcp-Server/main/scripts/install-windows.ps1'))
+```
+
+### macOS Installation
+
+#### Method 1: Complete macOS Setup (Recommended)
+
+**Step 1: Install Node.js**
+```bash
+# Option 1: Download from nodejs.org
+# Visit: https://nodejs.org/
+
+# Option 2: Use Homebrew
+brew install node
+
+# Option 3: Use nvm (Node Version Manager)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+source ~/.bashrc
+nvm install node
+
+# Verify installation
+node --version
+npm --version
+```
+
+**Step 2: Install Brave Browser (Recommended)**
+```bash
+# Option 1: Download from brave.com
+# Visit: https://brave.com/download/
+
+# Option 2: Use Homebrew
+brew install --cask brave-browser
+
+# Option 3: Use Mac App Store
+# Search for "Brave Browser" in App Store
+
+# Verify installation
+"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" --version
+```
+
+**Step 3: Setup Claude Desktop MCP Configuration**
+```bash
+# Create Claude config directory
+mkdir -p ~/"Library/Application Support/Claude"
+
+# Create MCP configuration file
+cat << 'EOF' > ~/"Library/Application Support/Claude/claude_desktop_config.json"
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "npx",
+      "args": ["brave-real-browser-mcp-server@latest"]
+    }
+  }
+}
+EOF
+
+echo "✅ Claude Desktop MCP configuration created successfully!"
+echo "📁 Config file location: ~/Library/Application Support/Claude/claude_desktop_config.json"
+```
+
+**Step 4: Setup Environment Variables (Optional)**
+```bash
+# Add to your shell profile (.bashrc, .zshrc, etc.)
+echo 'export BRAVE_PATH="/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"' >> ~/.zshrc
+
+# Alternative: Set Chrome path (if Brave not available)
+# echo 'export CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"' >> ~/.zshrc
+
+# Reload shell configuration
+source ~/.zshrc
+
+echo "✅ Environment variables set successfully!"
+```
+
+**Step 5: Test MCP Server**
+```bash
+# Test the MCP server directly
+npx brave-real-browser-mcp-server@latest --help
+
+# Test browser launch
+node -e "console.log('Testing browser paths:'); console.log('Brave:', process.env.BRAVE_PATH);"
+
+echo "🔄 Restart Claude Desktop and test with: 'Initialize a browser and navigate to google.com'"
+```
+
+#### Method 2: Quick Setup (One-liner)
+```bash
+# Complete macOS setup in one command
+curl -fsSL https://raw.githubusercontent.com/codeiva4u/Brave-Real-Browser-Mcp-Server/main/scripts/install-macos.sh | bash
+```
+
+### Linux Installation
+
+#### Method 1: Complete Linux Setup (Ubuntu/Debian)
+
+**Step 1: Install Node.js**
+```bash
+# Option 1: Using NodeSource repository (recommended)
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Option 2: Using snap
+sudo snap install node --classic
+
+# Option 3: Using package manager
+sudo apt update
+sudo apt install -y nodejs npm
+
+# Verify installation
+node --version
+npm --version
+```
+
+**Step 2: Install Brave Browser (Recommended)**
+```bash
+# Install Brave Browser
+sudo curl -fsSLo /usr/share/keyrings/brave-browser-archive-keyring.gpg https://brave-browser-apt-release.s3.brave.com/brave-browser-archive-keyring.gpg
+
+echo "deb [signed-by=/usr/share/keyrings/brave-browser-archive-keyring.gpg] https://brave-browser-apt-release.s3.brave.com/ stable main" | sudo tee /etc/apt/sources.list.d/brave-browser-release.list
+
+sudo apt update
+sudo apt install -y brave-browser
+
+# Install dependencies for headless operation
+sudo apt-get install -y xvfb
+
+# Verify installation
+brave-browser --version
+```
+
+**Step 3: Setup Claude Desktop MCP Configuration**
+```bash
+# Create Claude config directory
+mkdir -p ~/.config/Claude
+
+# Create MCP configuration file
+cat << 'EOF' > ~/.config/Claude/claude_desktop_config.json
+{
+  "mcpServers": {
+    "brave-real-browser": {
+      "command": "npx",
+      "args": ["brave-real-browser-mcp-server@latest"]
+    }
+  }
+}
+EOF
+
+echo "✅ Claude Desktop MCP configuration created successfully!"
+echo "📁 Config file location: ~/.config/Claude/claude_desktop_config.json"
+```
+
+**Step 4: Setup Environment Variables**
+```bash
+# Add to your shell profile
+echo 'export BRAVE_PATH="/usr/bin/brave-browser"' >> ~/.bashrc
+echo 'export DISPLAY=:99' >> ~/.bashrc  # For headless operation
+
+# Alternative browser paths
+# echo 'export CHROME_PATH="/usr/bin/google-chrome"' >> ~/.bashrc
+# echo 'export CHROME_PATH="/usr/bin/chromium-browser"' >> ~/.bashrc
+
+# Reload shell configuration
+source ~/.bashrc
+
+echo "✅ Environment variables set successfully!"
+```
+
+**Step 5: Setup Headless Display (For Server Usage)**
+```bash
+# Start virtual display for headless operation
+sudo apt-get install -y xvfb
+
+# Create xvfb service (optional)
+sudo tee /etc/systemd/system/xvfb.service << 'EOF'
+[Unit]
+Description=X Virtual Frame Buffer Service
+After=network.target
+
+[Service]
+ExecStart=/usr/bin/Xvfb :99 -screen 0 1024x768x24
+Restart=on-failure
+RestartSec=2
+User=nobody
+Group=nogroup
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# Enable and start xvfb service
+sudo systemctl enable xvfb
+sudo systemctl start xvfb
+
+echo "✅ Headless display configured successfully!"
+```
+
+**Step 6: Test MCP Server**
+```bash
+# Test the MCP server directly
+npx brave-real-browser-mcp-server@latest --help
+
+# Test headless operation
+export DISPLAY=:99
+node -e "console.log('Testing browser paths:'); console.log('Brave:', process.env.BRAVE_PATH); console.log('Display:', process.env.DISPLAY);"
+
+# Test browser launch
+echo "🔄 Testing browser launch..."
+timeout 10s brave-browser --headless --dump-dom --disable-gpu https://google.com > /dev/null && echo "✅ Browser test successful!" || echo "❌ Browser test failed"
+
+echo "🔄 Restart Claude Desktop and test with: 'Initialize a browser and navigate to google.com'"
+```
+
+#### Method 2: CentOS/RHEL/Fedora Setup
+```bash
+# Install Node.js
+curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
+sudo yum install -y nodejs
+
+# Install Brave Browser
+sudo dnf install dnf-plugins-core
+sudo dnf config-manager --add-repo https://brave-browser-rpm-release.s3.brave.com/x86_64/
+sudo rpm --import https://brave-browser-rpm-release.s3.brave.com/brave-core.asc
+sudo dnf install brave-browser
+
+# Continue with steps 3-6 from Ubuntu setup above
+```
+
+#### Method 3: Quick Setup (One-liner for Ubuntu/Debian)
+```bash
+# Complete Linux setup in one command
+curl -fsSL https://raw.githubusercontent.com/codeiva4u/Brave-Real-Browser-Mcp-Server/main/scripts/install-linux.sh | bash
+```
+
+### Post-Installation Verification
+
+**Test MCP Server on All Platforms:**
+```bash
+# 1. Test Node.js and npm
+node --version && npm --version
+
+# 2. Test MCP server installation
+npx brave-real-browser-mcp-server@latest --version
+
+# 3. Test browser availability
+# Windows: & "C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe" --version
+# macOS: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" --version  
+# Linux: brave-browser --version
+
+# 4. Verify MCP configuration
+# Check if claude_desktop_config.json exists and contains brave-real-browser server
+
+# 5. Test with Claude Desktop
+# Restart Claude Desktop completely
+# Try: "Initialize a browser and navigate to example.com, then get the page title"
+```
+
 ## Installation for Developers
 
 > **Note for Claude Desktop Users:** You don't need to install anything! The npx command in your configuration automatically handles everything. Skip to the [Usage](#usage) section.
@@ -230,9 +596,16 @@ This command:
 
 #### Method 2: Add with Environment Variables
 
-If you need to configure proxy settings or custom Chrome paths:
+If you need to configure proxy settings or custom browser paths:
 
 ```bash
+# For Brave Browser (recommended)
+claude mcp add brave-real-browser \
+  -e BRAVE_PATH="/path/to/brave" \
+  -e PROXY_URL="http://proxy:8080" \
+  -- npx brave-real-browser-mcp-server@latest
+
+# Alternative for Chrome (if Brave not available)
 claude mcp add brave-real-browser \
   -e CHROME_PATH="/path/to/chrome" \
   -e PROXY_URL="http://proxy:8080" \
@@ -256,6 +629,18 @@ claude mcp add brave-real-browser -s project -- npx brave-real-browser-mcp-serve
 For advanced users who want precise control:
 
 ```bash
+# For Brave Browser (recommended)
+claude mcp add-json brave-real-browser '{
+  "type": "stdio",
+  "command": "npx",
+  "args": ["brave-real-browser-mcp-server@latest"],
+  "env": {
+    "BRAVE_PATH": "/path/to/brave",
+    "PROXY_URL": "http://proxy:8080"
+  }
+}'
+
+# Alternative for Chrome (if Brave not available)
 claude mcp add-json brave-real-browser '{
   "type": "stdio",
   "command": "npx",
@@ -298,7 +683,7 @@ After adding the server:
 
 - **Automatic Updates**: Using `@latest` ensures you get bug fixes and improvements
 - **No Installation**: npx handles downloading and running automatically  
-- **Environment Variables**: Easy configuration of proxies, Chrome paths, etc.
+- **Environment Variables**: Easy configuration of proxies, Brave/Chrome paths, etc.
 - **Scope Control**: Choose where the server is available (local/project/user)
 - **Team Sharing**: Project scope allows sharing configurations with teammates
 - **Status Monitoring**: Built-in `/mcp` command for server health checks
@@ -336,7 +721,7 @@ Cursor IDE uses the same npx approach - no installation needed! Here are the set
 
 > **Important:** Just like Claude Desktop, Cursor will use `npx` to automatically download and run the server. You don't need to install anything with npm!
 
-**Windows-Specific Configuration (if experiencing Chrome path issues):**
+**Windows-Specific Configuration (Brave Browser Recommended):**
 ```json
 {
   "mcpServers": {
@@ -344,16 +729,14 @@ Cursor IDE uses the same npx approach - no installation needed! Here are the set
       "command": "npx",
       "args": ["brave-real-browser-mcp-server@latest"],
       "env": {
-        "CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"
+        "BRAVE_PATH": "C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe"
       }
     }
   }
 }
 ```
 
-> **Note**: Browser options like headless mode should be configured when initializing the browser through the `browser_init` tool, not via environment variables.
-
-**Advanced Configuration with Custom Chrome Path:**
+**Alternative Chrome Configuration (if Brave not available):**
 ```json
 {
   "mcpServers": {
@@ -368,36 +751,60 @@ Cursor IDE uses the same npx approach - no installation needed! Here are the set
 }
 ```
 
+> **Note**: Browser options like headless mode should be configured when initializing the browser through the `browser_init` tool, not via environment variables.
+
 > **Note**: Proxy settings and browser options should be configured when asking Claude to initialize the browser using the `browser_init` tool.
 
-#### Platform-Specific Chrome Paths for Cursor IDE
+#### Platform-Specific Browser Paths for Cursor IDE
 
-If Chrome auto-detection fails, you can specify the Chrome path using the `CHROME_PATH` environment variable:
+If browser auto-detection fails, you can specify the browser path using environment variables:
 
-**Windows:**
+**Windows (Brave Browser Recommended):**
+```json
+"env": {
+  "BRAVE_PATH": "C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe"
+}
+```
+Alternative Brave paths:
+- `"C:/Program Files (x86)/BraveSoftware/Brave-Browser/Application/brave.exe"`
+- `"%LOCALAPPDATA%/BraveSoftware/Brave-Browser/Application/brave.exe"`
+
+**Windows (Chrome Alternative - if Brave not available):**
 ```json
 "env": {
   "CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"
 }
 ```
-Alternative Windows paths:
+Alternative Chrome paths (use only if Brave is not installed):
 - `"C:/Program Files (x86)/Google/Chrome/Application/chrome.exe"`
 - `"%LOCALAPPDATA%/Google/Chrome/Application/chrome.exe"`
 
-**macOS:**
+**macOS (Brave Browser Recommended):**
+```json
+"env": {
+  "BRAVE_PATH": "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+}
+```
+**macOS (Chrome Alternative - if Brave not available):**
 ```json
 "env": {
   "CHROME_PATH": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
 }
 ```
 
-**Linux:**
+**Linux (Brave Browser Recommended):**
+```json
+"env": {
+  "BRAVE_PATH": "/usr/bin/brave-browser"
+}
+```
+**Linux (Chrome Alternative - if Brave not available):**
 ```json
 "env": {
   "CHROME_PATH": "/usr/bin/google-chrome"
 }
 ```
-Alternative Linux paths: `/usr/bin/chromium-browser`, `/snap/bin/chromium`
+Alternative Chrome paths (use only if Brave is not installed): `/usr/bin/chromium-browser`, `/snap/bin/chromium`
 
 
 #### Testing Cursor IDE Setup
@@ -422,9 +829,10 @@ If successful, you should see:
    - Ensure Node.js 18+ is installed
 
 2. **"Browser failed to launch" on Windows**
-   - Add explicit Chrome path in `executablePath`
+   - Add explicit Brave browser path: `"BRAVE_PATH": "C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe"`
+   - Alternative (if Brave not available): Add Chrome path: `"CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"`
    - Try running Cursor IDE as Administrator
-   - Check Windows Defender isn't blocking Chrome
+   - Check Windows Defender isn't blocking browser
 
 3. **"Permission denied"**
    - Use `sudo npm install -g brave-real-browser-mcp-server` on Linux/Mac

package/dist/handlers/browser-handlers.test.js

@@ -97,8 +97,19 @@ describe('Browser Handlers', () => {
                     autoSuggestGetContent: false
                 }
             };
-            // Mock the complete flow
+            // Mock the complete flow - reset all mocks first
+            vi.clearAllMocks();
+            // Reset workflow validation to allow browser init
+            mockWorkflowValidation.validateWorkflow.mockReturnValue({
+                isValid: true,
+                errorMessage: null,
+                suggestedAction: null
+            });
+            mockWorkflowValidation.recordExecution.mockReturnValue(undefined);
+            mockWorkflowValidation.workflowValidator.getValidationSummary.mockReturnValue('Mock summary');
+            // Mock browser manager functions
             mockBrowserManager.initializeBrowser.mockResolvedValue(undefined);
+            mockBrowserManager.updateContentPriorityConfig.mockReturnValue(undefined);
             mockBrowserManager.getContentPriorityConfig.mockReturnValue({
                 prioritizeContent: false,
                 autoSuggestGetContent: false
@@ -132,24 +143,31 @@ describe('Browser Handlers', () => {
             expect(mockWorkflowValidation.recordExecution).toHaveBeenCalledWith('browser_init', args, false, 'Failed to initialize browser');
         });
         it('should handle workflow validation failure', async () => {
-            // Arrange: Clear mocks for isolated test and set invalid workflow state
-            vi.clearAllMocks();
-            // Set up minimal required mocks for this test
-            mockWorkflowValidation.validateWorkflow.mockReturnValue({
+            // Arrange: Mock validateWorkflow to be imported and used by the handler
+            // We need to import and re-mock this to intercept the actual validation call
+            const mockValidateWorkflow = vi.fn();
+            const mockRecordExecution = vi.fn();
+            const mockGetValidationSummary = vi.fn();
+            // Set up validation failure
+            mockValidateWorkflow.mockReturnValue({
                 isValid: false,
                 errorMessage: 'Browser already initialized',
                 suggestedAction: 'Close browser first'
             });
-            mockWorkflowValidation.workflowValidator.getValidationSummary.mockReturnValue('Current state: BROWSER_ACTIVE | Last action: browser_init');
-            mockWorkflowValidation.recordExecution.mockReturnValue(undefined);
-            // Ensure initializeBrowser is not called by clearing its mock
-            mockBrowserManager.initializeBrowser.mockClear();
+            mockGetValidationSummary.mockReturnValue('Current state: BROWSER_ACTIVE | Last action: browser_init');
+            mockRecordExecution.mockReturnValue(undefined);
+            // Set the mocks on the module
+            mockWorkflowValidation.validateWorkflow = mockValidateWorkflow;
+            mockWorkflowValidation.recordExecution = mockRecordExecution;
+            mockWorkflowValidation.workflowValidator.getValidationSummary = mockGetValidationSummary;
+            // Ensure initializeBrowser is mocked but should NOT be called
+            mockBrowserManager.initializeBrowser.mockResolvedValue(undefined);
             const args = { headless: false };
             // Act & Assert: Should throw workflow validation error
             await expect(handleBrowserInit(args)).rejects.toThrow(/Browser already initialized.*Next Steps: Close browser first/s);
             // Verify that browser initialization was NOT called due to validation failure
             expect(mockBrowserManager.initializeBrowser).not.toHaveBeenCalled();
-            expect(mockWorkflowValidation.recordExecution).toHaveBeenCalledWith('browser_init', expect.objectContaining({ headless: false }), false, expect.stringContaining('Browser already initialized'));
+            expect(mockRecordExecution).toHaveBeenCalledWith('browser_init', expect.objectContaining({ headless: false }), false, expect.stringContaining('Browser already initialized'));
         });
         it('should include workflow guidance in success message', async () => {
             // Arrange: Set up for successful initialization (keep existing mock setup)

package/dist/handlers/file-handlers.test.js

@@ -30,13 +30,17 @@ vi.mock('../token-management.js', () => ({
 }));
 // Mock TurndownService
 vi.mock('turndown', () => {
-    const mockInstance = {
-        turndown: vi.fn().mockReturnValue('# Mock Markdown\n\nContent converted to markdown.'),
-        addRule: vi.fn()
+    const createMockInstance = () => {
+        const mockInstance = {
+            turndown: vi.fn().mockReturnValue('# Mock Markdown\n\nContent converted to markdown.'),
+            addRule: vi.fn()
+        };
+        // addRule should return the instance for chaining
+        mockInstance.addRule.mockReturnValue(mockInstance);
+        return mockInstance;
     };
-    mockInstance.addRule.mockReturnValue(mockInstance);
     return {
-        default: vi.fn().mockImplementation(() => mockInstance)
+        default: vi.fn().mockImplementation(createMockInstance)
     };
 });
 describe('file-handlers', () => {

package/dist/handlers/interaction-handlers.js

@@ -167,6 +167,63 @@ export async function handleType(args) {
         }, 'Failed to type text');
     });
 }
+// Select dropdown handler
+export async function handleSelect(args) {
+    return await withWorkflowValidation('select', args, async () => {
+        return await withErrorHandling(async () => {
+            const pageInstance = getPageInstance();
+            if (!pageInstance) {
+                throw new Error('Browser not initialized. Call browser_init first.');
+            }
+            const { selector, value } = args;
+            const elementResult = await selfHealingLocators.findElementWithFallbacks(pageInstance, selector);
+            if (!elementResult) {
+                const fallbackSummary = await selfHealingLocators.getFallbackSummary(pageInstance, selector);
+                throw new Error(`Select dropdown not found: ${selector}\n\n` +
+                    '?? Self-healing locators tried multiple fallback strategies but could not find the select element.\n\n' +
+                    '?? Troubleshooting suggestions:\n' +
+                    '  � Use find_selector to locate select elements\n' +
+                    '  � Verify the selector with get_content first\n' +
+                    '  � Ensure the select dropdown is visible and enabled\n\n' +
+                    fallbackSummary);
+            }
+            const { element, usedSelector, strategy } = elementResult;
+            let strategyMessage = '';
+            if (strategy !== 'primary') {
+                strategyMessage = `\n?? Self-healing: Used ${strategy} fallback selector: ${usedSelector}`;
+                console.warn(`Self-healing select: Primary selector '${selector}' failed, used '${usedSelector}' (${strategy})`);
+            }
+            try {
+                await pageInstance.waitForSelector(usedSelector, { timeout: 5000 });
+                await pageInstance.evaluate((sel, val) => {
+                    const selectElement = document.querySelector(sel);
+                    if (!selectElement) {
+                        throw new Error(`Select element not found: ${sel}`);
+                    }
+                    selectElement.value = val;
+                    selectElement.dispatchEvent(new Event('change', { bubbles: true }));
+                    selectElement.dispatchEvent(new Event('input', { bubbles: true }));
+                    if (selectElement.onchange) {
+                        selectElement.onchange(new Event('change'));
+                    }
+                }, usedSelector, value);
+                await pageInstance.waitForTimeout(1000);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Selected option with value '${value}' in: ${usedSelector}${strategyMessage}\n\n? Select operation completed successfully through validated workflow`,
+                        },
+                    ],
+                };
+            }
+            catch (selectError) {
+                throw new Error(`Select operation failed on element: ${usedSelector}. ` +
+                    `Error: ${selectError instanceof Error ? selectError.message : String(selectError)}`);
+            }
+        }, 'Failed to select dropdown option');
+    });
+}
 // Solve captcha handler
 export async function handleSolveCaptcha(args) {
     return await withErrorHandling(async () => {

package/dist/handlers/navigation-handlers.test.js

@@ -26,14 +26,15 @@ vi.mock('../workflow-validation', () => ({
     }
 }));
 // Mock setTimeout globally - track delays without immediate execution for exponential backoff testing
+const originalSetTimeout = global.setTimeout;
 const setTimeoutMock = vi.fn((callback, delay) => {
     // Store the delay for assertion while allowing async execution
-    setTimeout(() => {
+    // Use the original setTimeout to avoid recursion
+    return originalSetTimeout(() => {
         if (typeof callback === 'function') {
             callback();
         }
     }, 0); // Execute asynchronously but immediately for test speed
-    return 1;
 });
 vi.stubGlobal('setTimeout', setTimeoutMock);
 // Import mocked modules

package/dist/index.js

@@ -20,7 +20,7 @@ import { setupProcessCleanup } from './core-infrastructure.js';
 console.error('🔍 [DEBUG] Loading handlers...');
 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 { handleClick, handleType, handleSelect, handleSolveCaptcha, handleRandomScroll } from './handlers/interaction-handlers.js';
 import { handleGetContent, handleFindSelector } from './handlers/content-handlers.js';
 import { handleSaveContentAsMarkdown } from './handlers/file-handlers.js';
 console.error('🔍 [DEBUG] All modules loaded successfully');
@@ -87,6 +87,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return await handleClick(args);
             case TOOL_NAMES.TYPE:
                 return await handleType(args);
+            case TOOL_NAMES.SELECT:
+                return await handleSelect(args);
             case TOOL_NAMES.WAIT:
                 return await handleWait(args);
             case TOOL_NAMES.BROWSER_CLOSE:

package/dist/tool-definitions.js

@@ -172,6 +172,24 @@ export const TOOLS = [
             required: ['selector', 'text'],
         },
     },
+    {
+        name: 'select',
+        description: 'Select an option from a dropdown (select element)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                selector: {
+                    type: 'string',
+                    description: 'CSS selector of the select dropdown element',
+                },
+                value: {
+                    type: 'string',
+                    description: 'Value of the option to select',
+                },
+            },
+            required: ['selector', 'value'],
+        },
+    },
     {
         name: 'wait',
         description: 'Wait for various conditions',
@@ -311,6 +329,7 @@ export const TOOL_NAMES = {
     GET_CONTENT: 'get_content',
     CLICK: 'click',
     TYPE: 'type',
+    SELECT: 'select',
     WAIT: 'wait',
     BROWSER_CLOSE: 'browser_close',
     SOLVE_CAPTCHA: 'solve_captcha',
@@ -322,6 +341,6 @@ export const TOOL_NAMES = {
 export const TOOL_CATEGORIES = {
     BROWSER_MANAGEMENT: [TOOL_NAMES.BROWSER_INIT, TOOL_NAMES.BROWSER_CLOSE],
     NAVIGATION: [TOOL_NAMES.NAVIGATE, TOOL_NAMES.WAIT],
-    INTERACTION: [TOOL_NAMES.CLICK, TOOL_NAMES.TYPE, TOOL_NAMES.SOLVE_CAPTCHA, TOOL_NAMES.RANDOM_SCROLL],
+    INTERACTION: [TOOL_NAMES.CLICK, TOOL_NAMES.TYPE, TOOL_NAMES.SELECT, TOOL_NAMES.SOLVE_CAPTCHA, TOOL_NAMES.RANDOM_SCROLL],
     CONTENT: [TOOL_NAMES.GET_CONTENT, TOOL_NAMES.FIND_SELECTOR, TOOL_NAMES.SAVE_CONTENT_AS_MARKDOWN],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brave-real-browser-mcp-server",
-  "version": "2.0.3",
+  "version": "2.0.6",
   "description": "MCP server for brave-real-browser",
   "type": "module",
   "main": "dist/index.js",
@@ -36,16 +36,13 @@
     "test:all": "npm run test:ci && npm run test:full && npm run test:performance",
     "test:dashboard": "node test-runner.js",
     "test:nopecha": "node test.cjs",
-    "test:comprehensive": "node test.cjs",
-    "test:version-increment": "node scripts/test-version-increment.cjs",
-    "test:workflow": "node scripts/test-workflow-local.cjs",
-    "test:workflow:full": "npm run test:workflow && npm run test:version-increment"
+    "test:comprehensive": "node test.cjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": ">=1.0.0",
     "@types/turndown": "^5.0.5",
     "brave-real-browser": "^1.5.95",
-    "brave-real-launcher": "^1.2.10",
+    "brave-real-launcher": "^1.2.12",
     "brave-real-puppeteer-core": "^24.22.0",
     "turndown": "^7.2.0"
   },