npm - brave-real-browser-mcp-server - Versions diffs - 2.11.8 → 2.12.0 - Mend

brave-real-browser-mcp-server 2.11.8 → 2.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md +461 -1240
package/dist/index.js +134 -124
package/dist/launcher.js +106 -34
package/dist/universal-ide-adapter.js +855 -0
package/package.json +26 -4

package/README.md CHANGED Viewed

@@ -1,1456 +1,677 @@
+# 🌐 Brave Real Browser MCP Server - Universal AI IDE Support
-⚠️ **UNDER MAINTENANCE** - This project is still being actively developed. Some features may be incomplete or change without notice.
-# Brave Real Browser MCP Server
-Provides AI assistants with powerful, detection-resistant browser automation capabilities built on ZFC Digital's brave-real-browser package.
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-## Table of Contents
-1. [Quick Start for Beginners](#quick-start-for-beginners)
-2. [Introduction](#introduction)
-3. [Features](#features)
-4. [Prerequisites](#prerequisites)
-5. [Installation](#installation)
-6. [Multi-Protocol Support](#-multi-protocol-support)
-7. [Usage](#usage)
-   - [Quick Configuration Reference](#-quick-configuration-reference)
-   - [With Claude Desktop](#with-claude-desktop-mcp-protocol)
-   - [With Claude Code CLI](#with-claude-code-cli)
-   - [With Cursor IDE](#with-cursor-ide)
-   - [With Warp AI Terminal](#with-warp-ai-terminal)
-   - [With Windsurf IDE](#with-windsurf-ide-codeium)
-   - [With Continue.dev](#with-continuedev-vscode-extension)
-   - [With Cody AI](#with-cody-ai-sourcegraph)
-   - [With Zed Editor](#with-zed-editor-lsp-mode)
-   - [With VSCode](#with-vscode-via-lsp)
-   - [HTTP/WebSocket Mode](#httpwebsocket-mode-for-any-language)
-   - [Complete MCP IDE Compatibility Matrix](#-complete-mcp-ide-compatibility-matrix)
-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
-### What is this?
-This is an MCP (Model Context Protocol) server that lets AI assistants like Claude control a real web browser. Think of it as giving Claude "hands" to interact with websites - it can click buttons, fill forms, extract content, and much more, all while avoiding bot detection.
-### Important: You DON'T Need to Install This Package!
-If you're just using this MCP server (not developing it), you don't need to run `npm install`. The `npx` command in the configuration will automatically download and run the latest version for you. Installation is only required for development purposes.
-### Step-by-Step Setup
-#### 1. Install Node.js (Required)
-- Go to [nodejs.org](https://nodejs.org/)
-- Download and install Node.js (version 18 or higher)
-- Verify installation by opening terminal/command prompt and typing: `node --version`
-#### 2. Configure Claude Desktop
-**For Windows:**
-1. Open File Explorer and navigate to: `%APPDATA%\Claude\`
-2. Open (or create) `claude_desktop_config.json`
-3. Add this configuration:
+<div align="center">
-```json
-{
-  "mcpServers": {
-    "brave-real-browser": {
-      "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"]
-    }
-  }
-}
-```
-**For Mac:**
-1. Open Finder and press `Cmd+Shift+G`
-2. Go to: `~/Library/Application Support/Claude/`
-3. Open (or create) `claude_desktop_config.json`
-4. Add the same configuration as above
-**For Linux:**
-1. Navigate to: `~/.config/Claude/`
-2. Open (or create) `claude_desktop_config.json`
-3. Add the same configuration as above
-**Why @latest?** The `@latest` tag ensures you always get the most recent version with bug fixes and improvements. The `npx` command automatically downloads and runs it without installing anything permanently on your system.
-#### 3. Restart Claude Desktop
-Close and reopen Claude Desktop completely.
-#### 4. Test It Works
-In Claude Desktop, try saying:
-> "Initialize a browser and navigate to google.com, then get the page content"
-If everything is working, Claude should be able to:
-- Start a browser
-- Navigate to Google
-- Extract and show you the page content
-### What Can You Do With It?
-Once set up, you can ask Claude to:
-- **Browse websites**: "Go to amazon.com and search for laptops"
-- **Fill forms**: "Fill out this contact form with my details"
-- **Extract data**: "Get all the product prices from this page"
-- **Automate tasks**: "Log into my account and download my invoice"
-- **Solve captchas**: "Handle any captchas that appear"
-### Safety Notes
-- Claude will show you what it's doing - you can see the browser window
-- Always review what Claude does before approving sensitive actions
-- Use headless mode (`headless: true`) if you don't want to see the browser window
-- Be respectful of websites' terms of service
-## 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.
-This server implements the Model Context Protocol (MCP), allowing AI
-assistants to control a real browser, extract content, and more.
-## Features
-- **🔄 Auto-Update System**: Automatically updates all dependencies to latest versions on every `npm install`
-- **Stealth by default**: All browser instances use anti-detection features
-- **Enhanced Windows support**: Comprehensive Brave detection and ECONNREFUSED error fixes (v1.3.0)
-- **Smart Brave detection**: Registry-based detection + 15+ installation paths (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
-- **Dynamic selector discovery**: Intelligent element finding without hardcoded selectors
-- **Random scrolling**: Tools for natural scrolling to avoid detection
-- **Comprehensive toolset**: 11 tools covering all browser automation needs
-- **Proxy support**: Built-in proxy configuration for enhanced privacy
-- **Captcha handling**: Support for solving reCAPTCHA, hCaptcha, and Turnstile
-- **Robust error handling**: Advanced error recovery with circuit breaker pattern
-- **Stack overflow protection**: Comprehensive protection against infinite recursion
-- **Timeout controls**: Automatic timeout mechanisms prevent hanging operations
-- **Platform optimization**: Windows-specific flags and longer timeouts for better compatibility
-## Prerequisites
-- Node.js >= 18.0.0
-- npm or yarn
-- Brave Browser installed (recommended) or Google Chrome/Chromium as fallback
-- Basic understanding of TypeScript/JavaScript (for development)
-### Platform-Specific Requirements
-**Windows:**
-- Brave Browser installation (automatic detection in v1.3.0+ includes):
-  - Standard installations: `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`
-  - 32-bit installations: `C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`
-  - User installations: `%LOCALAPPDATA%\BraveSoftware\Brave-Browser\Application\brave.exe`
-  - Brave Beta/Nightly: `%LOCALAPPDATA%\BraveSoftware\Brave-Browser-Beta\Application\brave.exe`
-  - Portable installations and Registry-detected paths
-  - Manual path specification: Use `BRAVE_PATH` environment variable
-**macOS:**
-- Brave Browser must be installed in `/Applications/Brave Browser.app`
-**Linux:**
-- Install Brave: `sudo apt install brave-browser` or download from https://brave.com/linux/
-- Install xvfb for headless operation: `sudo apt-get install -y xvfb`
-## 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.
-This section is for developers who want to:
-- Contribute to the project
-- Run the server locally for development
-- Create custom modifications
-### Global Installation (For Command Line Usage)
-If you want to run the server directly from the command line without using npx:
-```bash
-npm install -g brave-real-browser-mcp-server@latest
-```
-After global installation, you can run:
-```bash
-brave-real-browser-mcp-server
-```
-### Development Setup (For Contributors)
-```bash
-# Clone the repository
-git clone https://github.com/withLinda/brave-real-browser-mcp-server.git
-cd brave-real-browser-mcp-server
+![Version](https://img.shields.io/badge/version-2.11.8-blue.svg)
+![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-green.svg)
+![License](https://img.shields.io/badge/license-MIT-orange.svg)
+![AI IDEs](https://img.shields.io/badge/AI_IDEs-15+-purple.svg)
+![Protocols](https://img.shields.io/badge/protocols-4-red.svg)
-# Install dependencies
-npm install
+**सभी AI IDEs के लिए Universal MCP Server | Browser Automation | Web Scraping | CAPTCHA Solving**
-# Build the project
-npm run build
+[English](#english) | [हिन्दी](#hindi)
-# Run in development mode
-npm run dev
-```
-## 🚀 Multi-Protocol Support
-This server now supports **three protocols** for maximum compatibility:
-| Protocol | Best For | Setup Difficulty |
-|----------|----------|-----------------|
-| **MCP** | Claude Desktop, Cursor, Warp AI | Easy |
-| **HTTP/WebSocket** | Any programming language | Easy |
-| **LSP** | Zed, VSCode, Neovim | Medium |
-### Quick Protocol Selection
-```bash
-# MCP mode (default) - For Claude Desktop, Cursor, Warp
-npx brave-real-browser-mcp-server
-# HTTP mode - For REST API / Any language
-npx brave-real-browser-mcp-server --mode http --port 3000
-# LSP mode - For Zed AI IDE, VSCode, Neovim
-npx brave-real-browser-mcp-server --mode lsp
-```
-📖 **Complete Guide:** See [MULTI_PROTOCOL_GUIDE.md](./MULTI_PROTOCOL_GUIDE.md) for detailed setup instructions.
+</div>
 ---
-## Usage
+## 🎯 What Makes This Universal?
-### 📝 Quick Configuration Reference
+**यह प्रोजेक्ट सभी AI IDEs में स्वचालित रूप से काम करता है!**
-| Your IDE/Tool | Jump To Section |
-|---------------|----------------|
-| Claude Desktop | [Configuration](#with-claude-desktop-mcp-protocol) |
-| Claude Code CLI | [Configuration](#with-claude-code-cli) |
-| Cursor IDE | [Configuration](#with-cursor-ide) |
-| Warp Terminal | [Configuration](#with-warp-ai-terminal) |
-| Windsurf IDE | [Configuration](#with-windsurf-ide-codeium) |
-| Continue.dev | [Configuration](#with-continuedev-vscode-extension) |
-| Cody AI | [Configuration](#with-cody-ai-sourcegraph) |
-| Zed Editor | [Configuration](#with-zed-editor-lsp-mode) |
-| VSCode | [Configuration](#with-vscode-via-lsp) |
-| Python/Node.js/Any Language | [Configuration](#httpwebsocket-mode-for-any-language) |
-**All platforms use the same simple pattern:**
-```json
-{
-  "mcpServers": {
-    "brave-real-browser": {
-      "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"]
-    }
-  }
-}
-```
+✅ **Auto-Detection** - आपका IDE automatically detect होता है
+✅ **Multi-Protocol** - MCP, LSP, HTTP, WebSocket सभी supported
+✅ **Zero Configuration** - कोई manual setup की जरूरत नहीं
+✅ **15+ AI IDEs** - सभी popular AI tools supported
+✅ **Real Brave Browser** - असली Brave browser के साथ काम करता है
+✅ **Anti-Detection** - Cloudflare, reCAPTCHA bypass करता है
 ---
-### With Claude Desktop (MCP Protocol)
-The configuration below uses `npx` to automatically download and run the latest version. No installation required!
-```json
-{
-  "mcpServers": {
-    "brave-real-browser": {
-      "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"]
-    }
-  }
-}
-```
-> **What does npx do?** The `npx` command downloads and runs the package without permanently installing it. The `@latest` ensures you always get the newest version with all bug fixes and improvements.
-### With Claude Code CLI
+<a name="english"></a>
+# 📖 English Documentation
+## 🤖 Supported AI IDEs (Universal Compatibility)
+This server **automatically detects and adapts** to your AI IDE!
+### ✅ Fully Supported & Auto-Detected
+| IDE | Protocol | Auto-Config | Status |
+|-----|----------|-------------|--------|
+| **Claude Desktop** | MCP/STDIO | ✅ | 🟢 Working |
+| **Cursor AI** | MCP/STDIO | ✅ | 🟢 Working |
+| **Windsurf** | MCP/STDIO | ✅ | 🟢 Working |
+| **Cline** (VSCode) | MCP/STDIO | ✅ | 🟢 Working |
+| **Warp Terminal** | MCP/STDIO | ✅ | 🟢 Working |
+| **Roo Coder** | MCP/STDIO | ✅ | 🟢 Working |
+| **Zed Editor** | LSP/MCP | ✅ | 🟢 Working |
+| **VSCode** | LSP/HTTP | ✅ | 🟢 Working |
+| **Qoder AI** | HTTP/WS | ✅ | 🟢 Working |
+| **Continue.dev** | MCP/HTTP | ✅ | 🟢 Working |
+| **GitHub Copilot** | HTTP/LSP | ✅ | 🟢 Working |
+| **Amazon CodeWhisperer** | HTTP/LSP | ✅ | 🟢 Working |
+| **Tabnine** | HTTP/WS | ✅ | 🟢 Working |
+| **Cody** (Sourcegraph) | HTTP/LSP | ✅ | 🟢 Working |
+| **Aider** | STDIO/HTTP | ✅ | 🟢 Working |
+| **Pieces for Developers** | HTTP/WS | ✅ | 🟢 Working |
+### 📡 Supported Protocols
+- **MCP** (Model Context Protocol) - Claude Desktop, Cursor, Windsurf, Cline, Warp, Roo Coder
+- **LSP** (Language Server Protocol) - Zed, VSCode, Neovim, Emacs, Sublime Text
+- **HTTP/REST** - Universal API for all IDEs
+- **WebSocket** - Real-time communication for modern IDEs
-Claude Code CLI offers multiple convenient methods to add the brave-real-browser MCP server. Choose the method that best fits your workflow:
+---
-#### Method 1: Quick Setup (Recommended)
+## 🚀 Quick Start
-The fastest way to get started is using the `claude mcp add` command:
+### Installation
 ```bash
-claude mcp add brave-real-browser -- npx brave-real-browser-mcp-server@latest
-```
-This command:
-- Adds the server to your local scope (available only to you in current project)
-- Uses npx to automatically download and run the latest version
-- No installation required - everything is handled automatically
-#### Method 2: Add with Environment Variables
+# Install globally
+npm install -g brave-real-browser-mcp-server
-If you need to configure proxy settings or custom Brave paths:
-```bash
-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
+# Or use with npx (no installation needed)
+npx brave-real-browser-mcp-server
 ```
-#### Method 3: Scoped Configuration
+### Usage
-**For User-Wide Access (Available Across All Projects):**
 ```bash
-claude mcp add brave-real-browser -s user -- npx brave-real-browser-mcp-server@latest
-```
+# Auto mode (automatically detects your IDE) - DEFAULT
+brave-real-browser-mcp-server
-**For Project-Wide Access (Shared with Team via .mcp.json):**
-```bash
-claude mcp add brave-real-browser -s project -- npx brave-real-browser-mcp-server@latest
-```
+# Or explicitly specify protocol
+brave-real-browser-mcp-server --mode auto
-#### Method 4: JSON Configuration
+# MCP mode (for Claude, Cursor, Windsurf, etc.)
+brave-real-browser-mcp-server --mode mcp
-For advanced users who want precise control:
+# HTTP mode (universal - works with ALL IDEs)
+brave-real-browser-mcp-server --mode http --port 3000
-```bash
-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"
-  }
-}'
+# LSP mode (for Zed, VSCode, etc.)
+brave-real-browser-mcp-server --mode lsp
 ```
-#### Verification and Testing
-After adding the server:
-1. **Check MCP Server Status:**
-   ```bash
-   /mcp
-   ```
-   This command in Claude Code shows all active MCP servers.
-2. **Test the Server:**
-   In Claude Code, try:
-   > "Initialize a browser and navigate to google.com, then get the page content"
-   If working correctly, you should see:
-   - Browser initialization
-   - Navigation to Google
-   - Page content extracted and displayed
-#### Configuration Scopes Explained
-| Scope | Description | Config Location | Use Case |
-|-------|-------------|----------------|----------|
-| **local** (default) | Available only to you in current project | `.mcp.json` in project | Testing, project-specific |
-| **project** | Shared with entire team | `.mcp.json` committed to repo | Team collaboration |
-| **user** | Available to you across all projects | User config directory | Personal productivity |
-#### Benefits of Claude Code CLI
-- **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.
-- **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
-### With Cursor IDE
-Cursor IDE uses the same npx approach - no installation needed! Here are the setup methods:
+---
-#### Method 1: One-Click Installation (Recommended)
+## ⚙️ Configuration for Specific IDEs
-1. **Open Cursor IDE**
-2. **Open Command Palette** (`Ctrl+Shift+P` on Windows/Linux, `Cmd+Shift+P` on Mac)
-3. **Search for "Cursor Settings"** and select it
-4. **Click on "MCP" in the sidebar**
-5. **Browse curated MCP servers** and install browser automation tools with one-click
-6. **OAuth authentication** will be handled automatically
+### 1. Claude Desktop
-#### Method 2: Manual Configuration
+**File:** `claude_desktop_config.json`
-**Configuration File Location:**
-- **Project-specific**: Create `.cursor/mcp.json` in your project directory
-- **Global**: Create `~/.cursor/mcp.json` in your home directory
+**Location:**
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
-**Basic Configuration (No Installation Required):**
 ```json
 {
   "mcpServers": {
-    "brave-real-browser": {
+    "brave-browser": {
       "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"]
+      "args": ["-y", "brave-real-browser-mcp-server"]
     }
   }
 }
 ```
-> **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!
+### 2. Cursor AI
-**Windows-Specific Configuration (if experiencing Brave path issues):**
-```json
-{
-  "mcpServers": {
-    "brave-real-browser": {
-      "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"],
-      "env": {
-        "BRAVE_PATH": "C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe"
-      }
-    }
-  }
-}
-```
+**File:** `cline_mcp_settings.json`
-> **Note**: Browser options like headless mode should be configured when initializing the browser through the `browser_init` tool, not via environment variables.
+**Location:**
+- **Windows:** `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
+- **macOS:** `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
-**Advanced Configuration with Custom Brave Path:**
 ```json
 {
   "mcpServers": {
-    "brave-real-browser": {
+    "brave-browser": {
       "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"],
+      "args": ["-y", "brave-real-browser-mcp-server"],
       "env": {
-        "BRAVE_PATH": "C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe"
+        "BRAVE_PATH": "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
       }
     }
   }
 }
 ```
-> **Note**: Proxy settings and browser options should be configured when asking Claude to initialize the browser using the `browser_init` tool.
-#### Platform-Specific Brave Paths for Cursor IDE
-If Brave auto-detection fails, you can specify the Brave path using the `BRAVE_PATH` environment variable:
-**Windows:**
-```json
-"env": {
-  "BRAVE_PATH": "C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe"
-}
-```
-Alternative Windows paths:
-- `"C:/Program Files (x86)/BraveSoftware/Brave-Browser/Application/brave.exe"`
-- `"%LOCALAPPDATA%/BraveSoftware/Brave-Browser/Application/brave.exe"`
-**macOS:**
-```json
-"env": {
-  "BRAVE_PATH": "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
-}
-```
-**Linux:**
-```json
-"env": {
-  "BRAVE_PATH": "/usr/bin/brave-browser"
-}
-```
-Alternative Linux paths: `/usr/bin/brave`, `/snap/bin/brave`
-#### Testing Cursor IDE Setup
-After configuration:
-1. **Restart Cursor IDE completely**
-2. **Open a new chat**
-3. **Test with**: "Initialize a browser and navigate to google.com, then get the page content"
-If successful, you should see:
-- Browser window opening
-- Navigation to Google
-- Page content extracted and displayed in the chat
-#### Cursor IDE Troubleshooting
-**Common Issues:**
-1. **"MCP server not found"**
-   - Verify config file location and JSON syntax
-   - Use [jsonlint.com](https://jsonlint.com/) to validate JSON
-   - Ensure Node.js 18+ is installed
-2. **"Browser failed to launch" on Windows**
-   - Add explicit Brave path in `executablePath`
-   - Try running Cursor IDE as Administrator
-   - Check Windows Defender isn't blocking Brave
-3. **"Permission denied"**
-   - Use `sudo npm install -g brave-real-browser-mcp-server` on Linux/Mac
-   - Run Command Prompt as Administrator on Windows
+### 3. Windsurf
-4. **Configuration not loading**
-   - Ensure file is named exactly `mcp.json` (not `mcp.json.txt`)
-   - Check file is in correct directory
-   - Restart Cursor IDE after changes
+**File:** `mcp.json`
-### With Warp AI Terminal
+**Location:**
+- **Windows:** `%APPDATA%\Windsurf\mcp.json`
+- **macOS:** `~/.windsurf/mcp.json`
-Warp Terminal has native MCP support built-in.
-**Configuration Location:**
-- macOS: `~/.warp/mcp_config.json`
-- Linux: `~/.warp/mcp_config.json`
-- Windows: `%USERPROFILE%\.warp\mcp_config.json`
-**Configuration:**
 ```json
 {
   "mcpServers": {
-    "brave-real-browser": {
+    "brave-browser": {
       "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"]
+      "args": ["-y", "brave-real-browser-mcp-server"]
     }
   }
 }
 ```
-**Testing:**
-1. Restart Warp Terminal
-2. Type: `/mcp` to see available servers
-3. Test: "Initialize browser and go to google.com"
-### With Windsurf IDE (Codeium)
+### 4. Cline (VSCode Extension)
-Windsurf IDE by Codeium supports MCP servers.
+**File:** `cline_mcp_settings.json`
-**Configuration Location:**
-- Create `.windsurf/mcp.json` in your project
-- Or `~/.windsurf/mcp.json` for global configuration
+**Location:**
+- **Windows:** `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
+- **macOS:** `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
-**Configuration:**
 ```json
 {
   "mcpServers": {
-    "brave-real-browser": {
+    "brave-browser": {
       "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"],
-      "disabled": false
+      "args": ["-y", "brave-real-browser-mcp-server"]
     }
   }
 }
 ```
-### With Continue.dev (VSCode Extension)
+### 5. Zed Editor
-Continue.dev supports MCP through its VSCode/JetBrains extension.
+**File:** `settings.json`
-**Configuration Location:**
-- `~/.continue/config.json` (Global)
-- Or `.continue/config.json` in your project
+**Location:**
+- **Windows:** `%APPDATA%\Zed\settings.json`
+- **macOS:** `~/.config/zed/settings.json`
-**Configuration:**
-```json
-{
-  "mcpServers": [
-    {
-      "name": "brave-real-browser",
-      "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"]
-    }
-  ]
-}
-```
-### With Cody AI (Sourcegraph)
-Cody AI in VS Code supports MCP servers.
-**Configuration Location:**
-- VS Code Settings: `settings.json`
-**Configuration:**
-```json
-{
-  "cody.mcp.servers": {
-    "brave-real-browser": {
-      "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"]
-    }
-  }
-}
-```
-### With Zed Editor (LSP Mode)
-Zed uses LSP protocol instead of MCP.
-**Configuration Location:**
-- macOS/Linux: `~/.config/zed/settings.json`
-- Windows: `%APPDATA%\Zed\settings.json`
-**Configuration:**
 ```json
 {
   "lsp": {
-    "brave-browser-automation": {
-      "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest", "--mode", "lsp"],
-      "settings": {}
+    "brave-browser": {
+      "command": "brave-real-browser-mcp-server",
+      "args": ["--mode", "lsp"]
     }
   }
 }
 ```
-### With VSCode (via LSP)
-VSCode can use LSP mode for browser automation.
-**Create:** `.vscode/settings.json` in your project
-**Configuration:**
-```json
-{
-  "brave-browser-automation.serverPath": "npx",
-  "brave-browser-automation.serverArgs": [
-    "brave-real-browser-mcp-server@latest",
-    "--mode",
-    "lsp"
-  ]
-}
-```
-### HTTP/WebSocket Mode (For Any Language)
+### 6. Qoder AI & Other HTTP-based IDEs
-Use REST API mode for maximum compatibility with any programming language.
+Start the server in HTTP mode:
-**Start Server:**
 ```bash
-npx brave-real-browser-mcp-server --mode http --port 3000
+brave-real-browser-mcp-server --mode http --port 3000
 ```
-**Example - Python:**
-```python
-import requests
+Then use the REST API endpoint: `http://localhost:3000`
-base_url = "http://localhost:3000"
+---
-# Initialize browser
-requests.post(f"{base_url}/browser/init", json={"headless": False})
+## 🛠️ Features & Tools
+### 🌐 Browser Management
+- `browser_init` - Initialize Brave browser with anti-detection
+- `browser_close` - Close browser instance
+- `navigate` - Navigate to URL
+- `wait` - Wait for elements/timeout
+### 🖱️ Interaction Tools
+- `click` - Click on elements
+- `type` - Type text into inputs
+- `solve_captcha` - Solve CAPTCHA (reCAPTCHA, hCaptcha, Turnstile, etc.)
+- `random_scroll` - Human-like scrolling
+### 📄 Content Extraction
+- `get_content` - Extract page content (HTML/Text/Markdown)
+- `find_selector` - Find CSS selectors
+- `scrape_table` - Extract table data
+- `extract_list` - Extract lists
+- `extract_json` - Extract JSON data
+- `scrape_meta_tags` - Extract meta information
+- `extract_schema` - Extract schema.org data
+### 🔍 Advanced Extraction
+- `batch_element_scraper` - Scrape multiple elements
+- `nested_data_extraction` - Extract nested data structures
+- `attribute_harvester` - Extract element attributes
+- `image_scraper` - Extract all images
+- `link_harvester` - Extract all links
+- `media_extractor` - Extract media files
+- `video_link_finder` - Find video URLs
+### 🤖 AI-Powered Tools
+- `smart_selector_generator` - Auto-generate selectors
+- `content_classification` - Classify content type
+- `sentiment_analysis` - Analyze sentiment
+- `summary_generator` - Generate summaries
+- `translation_support` - Translate content
+### 📊 Data Processing
+- `smart_text_cleaner` - Clean extracted text
+- `html_to_text` - Convert HTML to text
+- `price_parser` - Extract & parse prices
+- `date_normalizer` - Normalize dates
+- `contact_extractor` - Extract contact info
+- `data_deduplication` - Remove duplicates
+- `data_type_validator` - Validate data types
+### 🔐 CAPTCHA & Security
+- `solve_captcha` - Multi-CAPTCHA solver
+- `ocr_engine` - OCR for text CAPTCHAs
+- `audio_captcha_solver` - Audio CAPTCHA solver
+- `puzzle_captcha_handler` - Puzzle CAPTCHA handler
+### 📸 Visual Tools
+- `full_page_screenshot` - Full page screenshot
+- `element_screenshot` - Element screenshot
+- `pdf_generation` - Generate PDF
+- `video_recording` - Record page video
+- `visual_comparison` - Compare screenshots
+### 🔄 Pagination & Navigation
+- `auto_pagination` - Auto-paginate through pages
+- `infinite_scroll` - Handle infinite scroll
+- `multi_page_scraper` - Scrape multiple pages
+- `sitemap_parser` - Parse sitemaps
+- `breadcrumb_navigator` - Navigate breadcrumbs
+### 🌐 Session Management
+- `cookie_manager` - Manage cookies
+- `session_persistence` - Persist sessions
+- `form_auto_fill` - Auto-fill forms
+- `login_session_manager` - Manage login sessions
+- `modal_popup_handler` - Handle popups
+### 📈 Monitoring & Reporting
+- `progress_tracker` - Track progress
+- `error_logger` - Log errors
+- `success_rate_reporter` - Report success rates
+- `performance_monitor` - Monitor performance
+- `monitoring_summary` - Get monitoring summary
-# Navigate
-requests.post(f"{base_url}/browser/navigate", json={"url": "https://google.com"})
+---
-# Get content
-response = requests.post(f"{base_url}/browser/get-content", json={"type": "text"})
-print(response.json())
-```
+## 💡 Usage Examples
+### Example 1: Simple Web Scraping
-**Example - Node.js:**
 ```javascript
-const axios = require('axios');
+// Initialize browser
+await use_mcp_tool({
+  server_name: "brave-browser",
+  tool_name: "browser_init",
+  arguments: {}
+});
+// Navigate to website
+await use_mcp_tool({
+  server_name: "brave-browser",
+  tool_name: "navigate",
+  arguments: { url: "https://example.com" }
+});
+// Get content
+await use_mcp_tool({
+  server_name: "brave-browser",
+  tool_name: "get_content",
+  arguments: { type: "text" }
+});
+```
+### Example 2: Solve CAPTCHA & Extract Data
-const baseUrl = 'http://localhost:3000';
+```javascript
+// Navigate to page with CAPTCHA
+await use_mcp_tool({
+  server_name: "brave-browser",
+  tool_name: "navigate",
+  arguments: { url: "https://example.com/protected-page" }
+});
+// Solve CAPTCHA
+await use_mcp_tool({
+  server_name: "brave-browser",
+  tool_name: "solve_captcha",
+  arguments: { type: "recaptcha" }
+});
+// Extract table data
+await use_mcp_tool({
+  server_name: "brave-browser",
+  tool_name: "scrape_table",
+  arguments: { selector: "table.data" }
+});
+```
+### Example 3: HTTP API Usage
-// Initialize and automate
-await axios.post(`${baseUrl}/browser/init`, {headless: false});
-await axios.post(`${baseUrl}/browser/navigate`, {url: 'https://google.com'});
-const content = await axios.post(`${baseUrl}/browser/get-content`, {type: 'text'});
-console.log(content.data);
+```bash
+# Start HTTP server
+brave-real-browser-mcp-server --mode http --port 3000
 ```
-### With Other MCP-Compatible Tools
-For any other MCP-compatible IDE or tool, use the standard MCP configuration:
+```javascript
+// Use REST API
+const response = await fetch('http://localhost:3000/tools/navigate', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ url: 'https://example.com' })
+});
-```json
-{
-  "mcpServers": {
-    "brave-real-browser": {
-      "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"]
-    }
-  }
-}
+const result = await response.json();
 ```
-The server communicates via stdin/stdout using the MCP protocol.
 ---
-## 📊 Complete MCP IDE Compatibility Matrix
-| IDE/Tool | Protocol | Config File | Status |
-|----------|----------|-------------|--------|
-| **Claude Desktop** | MCP | `claude_desktop_config.json` | ✅ Fully Tested |
-| **Claude Code CLI** | MCP | `.mcp.json` | ✅ Fully Tested |
-| **Cursor IDE** | MCP | `.cursor/mcp.json` | ✅ Fully Tested |
-| **Warp Terminal** | MCP | `mcp_config.json` | ✅ Supported |
-| **Windsurf IDE** | MCP | `.windsurf/mcp.json` | ✅ Supported |
-| **Continue.dev** | MCP | `.continue/config.json` | ✅ Supported |
-| **Cody AI** | MCP | `settings.json` | ✅ Supported |
-| **Zed Editor** | LSP | `settings.json` | ✅ LSP Mode |
-| **VSCode** | LSP | `.vscode/settings.json` | ✅ LSP Mode |
-| **Any HTTP Client** | HTTP/WebSocket | REST API | ✅ Fully Supported |
+## 📋 Requirements
-**Total Supported Platforms:** 10+
+- **Node.js** >= 18.0.0
+- **Brave Browser** (auto-detected or specify path)
+- **Operating System:** Windows, macOS, or Linux
-### Example Interactions
+---
-#### Basic Web Browsing
-```text
-User: "Initialize a browser and navigate to example.com"
-AI: I'll initialize a stealth browser and navigate to the website.
-[Uses browser_init and navigate tools]
+## 🔧 Environment Variables
-```
+```bash
+# Optional: Specify Brave browser path
+BRAVE_PATH="C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe"
-#### Form Automation
-```text
-User: "Fill in the search form with 'test query'"
-AI: I'll type that into the search field.
-[Uses type tool with selector and text]
+# Optional: Run in headless mode
+HEADLESS=true
-User: "Click the search button"
-AI: I'll click the search button.
-[Uses click tool]
+# Optional: Disable content priority
+DISABLE_CONTENT_PRIORITY=true
 ```
-#### Data Extraction
-```text
-User: "Get all the product names from this e-commerce page"
-AI: I'll extract the product information from the page.
-[Uses get_content tool with appropriate selectors]
+---
-User: "Save the page content as text"
-AI: I'll get the text content of the entire page.
-[Uses get_content tool with type: 'text']
+## 🐛 Troubleshooting
-User: "Save this page content as a markdown file"
-AI: I'll extract the page content and save it as a formatted markdown file.
-[Uses save_content_as_markdown tool with specified file path]
-```
+### Brave Browser Not Found
+**Solution 1:** Set environment variable
+```bash
+# Windows
+set BRAVE_PATH="C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe"
-#### Working with Proxies
-```text
-User: "Initialize a browser with a proxy server"
-AI: I'll set up the browser with your proxy configuration.
-[Uses browser_init with proxy: "https://proxy.example.com:8080"]
+# Linux/macOS
+export BRAVE_PATH="/usr/bin/brave-browser"
 ```
-## Available Tools
-### Core Browser Tools
-| Tool Name | Description | Required Parameters | Optional Parameters |
-|-----------|-------------|---------------------|-------------------|
-| `browser_init` | Initialize stealth browser with advanced options | None | `headless`, `disableXvfb`, `ignoreAllFlags`, `proxy`, `plugins`, `connectOption` |
-| `navigate` | Navigate to a URL | `url` | `waitUntil` |
-| `get_content` | Get page content (HTML or text) | None | `type`, `selector` |
-| `browser_close` | Close the browser instance | None | None |
-### Interaction Tools
-| Tool Name | Description | Required Parameters | Optional Parameters |
-|-----------|-------------|---------------------|-------------------|
-| `click` | Standard click on element | `selector` | `waitForNavigation` |
-| `type` | Type text into input field | `selector`, `text` | `delay` |
-| `wait` | Wait for various conditions | `type`, `value` | `timeout` |
-| `find_selector` | Find CSS selector for element containing specific text | `text` | `elementType`, `exact` |
-### Behavior Tools
-| Tool Name | Description | Required Parameters | Optional Parameters |
-|-----------|-------------|---------------------|-------------------|
-| `random_scroll` | Perform random scrolling with natural timing | None | None |
-### Element Discovery Tools
-| Tool Name | Description | Required Parameters | Optional Parameters |
-|-----------|-------------|---------------------|-------------------|
-| `find_selector` | Find CSS selector for element containing specific text | `text` | `elementType`, `exact` |
-### Content Tools
+**Solution 2:** Specify in browser_init
+```javascript
+await use_mcp_tool({
+  server_name: "brave-browser",
+  tool_name: "browser_init",
+  arguments: {
+    customConfig: {
+      chromePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
+    }
+  }
+});
+```
-| Tool Name | Description | Required Parameters | Optional Parameters |
-|-----------|-------------|---------------------|-------------------|
-| `save_content_as_markdown` | Extract page content and save it as a formatted markdown file | `filePath` | `contentType`, `selector`, `formatOptions` |
+### Server Not Starting
-### Anti-Detection Tools
+1. Check Node.js version: `node --version` (should be >= 18)
+2. Clear npm cache: `npm cache clean --force`
+3. Reinstall: `npm install -g brave-real-browser-mcp-server`
+4. Check logs in stderr
-| Tool Name | Description | Required Parameters | Optional Parameters |
-|-----------|-------------|---------------------|-------------------|
-| `solve_captcha` | Attempt to solve captchas | `type` | None |
+### CAPTCHA Not Solving
-## Advanced Features
+1. Wait for CAPTCHA to fully load
+2. Use longer timeout: `{ "timeout": 30000 }`
+3. Try different CAPTCHA types: `recaptcha`, `hcaptcha`, `turnstile`
-### Dynamic Selector Discovery
+---
-The server includes intelligent element discovery capabilities through the `find_selector` tool:
+## 🤝 Contributing
-- **Text-based element finding**: Automatically locates elements containing specific text
-- **Smart CSS selector generation**: Creates unique, robust CSS selectors similar to Chrome DevTools
-- **Element type filtering**: Optionally restrict search to specific HTML elements (e.g., buttons, links)
-- **Exact or partial text matching**: Choose between precise text matching or substring searches
-- **Universal compatibility**: Works across any website without hardcoded selectors
+Contributions are welcome! Please feel free to submit a Pull Request.
-**Example Usage:**
-```text
-User: "Find the submit button that says 'Sign Up'"
-AI: I'll locate that button for you.
-[Uses find_selector with text: "Sign Up", elementType: "button"]
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
-AI: Found button at selector: "form > button.btn-primary:nth-of-type(2)"
-```
+---
-This approach eliminates the need for manually crafted selectors and makes automation more reliable across different websites.
+## 📄 License
-### Natural Interactions
+This project is licensed under the MIT License.
-The server includes tools designed for natural browsing behavior:
+---
-- **Random scrolling**: Performs scrolling with natural timing and variable distances
+## 🔗 Links
-This feature helps avoid detection by sophisticated bot-detection systems
-that analyze user behavior patterns.
+- **GitHub:** https://github.com/withLinda/brave-real-browser-mcp-server
+- **NPM:** https://www.npmjs.com/package/brave-real-browser-mcp-server
+- **Issues:** https://github.com/withLinda/brave-real-browser-mcp-server/issues
-### Captcha Handling
+---
-The server includes basic support for solving common captcha types:
+<a name="hindi"></a>
+# 📖 हिन्दी दस्तावेज़
-- reCAPTCHA
-- hCaptcha
-- Cloudflare Turnstile
+## 🤖 समर्थित AI IDEs (सार्वभौमिक संगतता)
-Note that captcha solving capabilities depend on the underlying
-brave-real-browser implementation.
+यह server **स्वचालित रूप से आपके AI IDE को detect करता है और adapt हो जाता है!**
-## Configuration
+### ✅ पूर्णतः समर्थित और स्वतः-पता लगाना
-### Automatic Brave Path Detection (Enhanced in v1.3.0)
+सभी 15+ AI IDEs स्वचालित रूप से समर्थित हैं। कोई manual configuration की जरूरत नहीं!
-The server automatically detects Brave installation paths across different operating systems with significantly improved Windows support:
+---
-- **Windows (v1.3.0+)**:
-  - Registry-based detection for installed Brave versions
-  - Searches 15+ common installation directories including Program Files, user-specific locations, and portable installations
-  - Support for Brave Beta and Nightly fallback
-  - Environment variable detection (`BRAVE_PATH`, `PUPPETEER_EXECUTABLE_PATH`)
-  - Detailed troubleshooting guidance when Brave is not found
-- **macOS**: Looks for Brave in `/Applications/Brave Browser.app/` and Beta/Nightly locations
+## 🚀 त्वरित शुरुआत
-- **Linux**: Checks multiple locations including `/usr/bin/brave-browser`, `/usr/bin/brave`, and snap installations
+### इंस्टॉलेशन
-**Windows Registry Detection** (NEW in v1.3.0):
-The server now queries Windows Registry to find Brave installations, making detection more reliable across different installation types.
+```bash
+# Global इंस्टॉल करें
+npm install -g brave-real-browser-mcp-server
-If Brave is not found automatically, you can specify a custom path using:
-1. Environment variable: `set BRAVE_PATH="C:\Your\Brave\Path\brave.exe"`
-2. Browser init option: `customConfig.bravePath` when initializing the browser
+# या npx से चलाएं (बिना installation के)
+npx brave-real-browser-mcp-server
+```
-### Configuring Custom Options (like headless mode)
-Custom options like headless mode are **not configured in the MCP config file**. Instead, they're passed when initializing the browser using the `browser_init` tool:
+### उपयोग
-When you ask Claude to initialize a browser, you can specify options like:
+```bash
+# Auto mode (आपका IDE automatically detect होगा) - डिफ़ॉल्ट
+brave-real-browser-mcp-server
-```
-Please initialize a browser with headless mode enabled and a 30-second timeout
-```
+# MCP mode (Claude, Cursor, Windsurf आदि के लिए)
+brave-real-browser-mcp-server --mode mcp
-Claude will then use the `browser_init` tool with appropriate parameters:
+# HTTP mode (सभी IDEs के साथ काम करता है)
+brave-real-browser-mcp-server --mode http --port 3000
-```json
-{
-  "headless": true,
-  "connectOption": {
-    "timeout": 30000
-  }
-}
+# LSP mode (Zed, VSCode आदि के लिए)
+brave-real-browser-mcp-server --mode lsp
 ```
-### Available Browser Options
-When initializing with `browser_init`, you can configure:
+---
-- `headless`: true/false (Set to true for headless operation)
-- `disableXvfb`: true/false (Disable X Virtual Framebuffer)
-- `ignoreAllFlags`: true/false (Ignore all Chrome flags)
-- `proxy`: "https://proxy:8080" (Proxy server URL)
-- `plugins`: ["plugin1", "plugin2"] (Array of plugins to load)
-- `connectOption`: Additional connection options like:
-  - `slowMo`: 250 (Slow down operations by milliseconds)
-  - `timeout`: 60,000 (Connection timeout)
+## ⚙️ विशिष्ट IDEs के लिए कॉन्फ़िगरेशन
-The MCP config file only tells Claude where to find the server - all browser-specific options are configured through your conversations with Claude.
+### 1. Claude Desktop
-### Browser Options Example
+**फ़ाइल:** `claude_desktop_config.json`
-When initializing the browser with `browser_init`, you can configure:
+**स्थान:**
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 ```json
 {
-  "headless": false,
-  "disableXvfb": false,
-  "ignoreAllFlags": false,
-  "proxy": "https://proxy:8080",
-  "plugins": ["plugin1", "plugin2"],
-  "connectOption": {
-    "slowMo": 250,
-    "timeout": 60000
+  "mcpServers": {
+    "brave-browser": {
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server"]
+    }
   }
 }
 ```
-### Advanced Configuration Examples
+### 2. Cursor AI
-#### Specifying Custom Brave Path
-```json
-{
-  "customConfig": {
-    "bravePath": "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
-  }
-}
-```
+**फ़ाइल:** `cline_mcp_settings.json`
-#### Using a Proxy
-```json
-{
-  "headless": true,
-  "proxy": "https://username:password@proxy.example.com:8080"
-}
-```
+**स्थान:**
+- **Windows:** `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
-#### Stealth Mode with Custom Options
 ```json
 {
-  "headless": false,
-  "ignoreAllFlags": true,
-  "disableXvfb": false,
-  "connectOption": {
-    "slowMo": 100,
-    "devtools": false
+  "mcpServers": {
+    "brave-browser": {
+      "command": "npx",
+      "args": ["-y", "brave-real-browser-mcp-server"]
+    }
   }
 }
 ```
+### 3. HTTP-आधारित IDEs (Qoder AI आदि)
-### Server Configuration
-For advanced users, you can modify the server behavior by editing the source code:
-- Change default viewport size in the `initializeBrowser` function
-- Adjust timeout values for various operations
-- Enable debug logging
-## Troubleshooting
-### Major Windows Connection Issues (Fixed in v1.3.0)
-**🔧 ECONNREFUSED Error Solutions**
-Version 1.3.0 includes comprehensive fixes for the `connect ECONNREFUSED 127.0.0.1:60725` error commonly experienced on Windows systems:
-**Enhanced Brave Path Detection:**
-- Added Windows Registry-based Brave detection
-- Expanded search to 15+ Windows installation locations including portable installations
-- Added support for Brave Beta and Nightly fallback
-- Environment variable support (`BRAVE_PATH`, `PUPPETEER_EXECUTABLE_PATH`)
-**Windows-Specific Launch Optimizations:**
-- 20+ Windows-specific Brave flags for better compatibility
-- Multiple fallback strategies (5 different connection approaches)
-- Progressive retry logic with exponential backoff
-- Enhanced timeout handling (120s for Windows vs 90s for other platforms)
-**Connection Resilience Features:**
-- Localhost vs 127.0.0.1 fallback handling (fixes known Puppeteer issue)
-- Port availability checking and automatic port assignment
-- Network connectivity testing before browser launch
-- Enhanced error categorization and automatic fallback strategies
-**If you're still experiencing ECONNREFUSED errors:**
-1. **Environment Variables (Recommended):**
-   ```bash
-   set BRAVE_PATH="C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe"
-   ```
-2. **Manual Brave Path Configuration:**
-   ```text
-   Ask Claude: "Initialize browser with custom Brave path at C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
-   ```
-3. **Network Troubleshooting:**
-   ```bash
-   # Test localhost resolution
-   ping localhost
-   # Should resolve to 127.0.0.1
-   # Check Windows hosts file
-   notepad C:\Windows\System32\drivers\etc\hosts
-   # Ensure: 127.0.0.1 localhost
-   ```
-4. **Brave Process Management:**
-   ```bash
-   # Kill existing Brave processes
-   taskkill /f /im brave.exe
-   ```
-### Common Issues
-#### npx-Specific Issues
-1. **"spawn npx ENOENT" or "command not found" errors**
-   - **Cause:** npx is not in your system PATH or Node.js is not properly installed
-   - **Solutions:**
-     - Verify Node.js installation: `node --version` and `npm --version`
-     - Reinstall Node.js from [nodejs.org](https://nodejs.org/)
-     - For NVM users, see the NVM-specific section below
-2. **"npx: command not found" in Claude Desktop/Cursor**
-   - **Windows:** Make sure to restart your IDE after installing Node.js
-   - **Mac/Linux:** Add npm to PATH: `export PATH="$PATH:$(npm bin -g)"`
-   - **Alternative:** Use the full path to npx: `/usr/local/bin/npx`
-3. **npx hangs or takes too long**
-   - npx downloads the package on first run, which can take 30-60 seconds
-   - Ensure you have a stable internet connection
-   - Try clearing npm cache: `npm cache clean --force`
-4. **Using NVM (Node Version Manager)?**
-   - Standard npx commands may fail with NVM
-   - **Solution 1:** Use absolute paths in your config:
-     ```json
-     {
-       "mcpServers": {
-         "brave-real-browser": {
-           "command": "/Users/yourname/.nvm/versions/node/v20.0.0/bin/npx",
-           "args": ["brave-real-browser-mcp-server@latest"]
-         }
-       }
-     }
-     ```
-   - **Solution 2:** Set a default Node version: `nvm alias default 20.0.0`
-5. **Permission denied errors with npx**
-   - **Mac/Linux:** Try with sudo: `sudo npx brave-real-browser-mcp-server@latest`
-   - **Better solution:** Fix npm permissions: `npm config set prefix ~/.npm`
-#### Other Common Issues
-1. **"Maximum call stack size exceeded" errors**
-   - This was fixed in version 1.2.0 with comprehensive stack overflow protection
-   - The server now includes circuit breaker patterns and recursion depth tracking
-   - Timeout controls prevent hanging operations that could lead to stack overflow
-   - If you encounter this error, ensure you're using the latest version: `npx brave-real-browser-mcp-server@latest`
-2. **"command not found" or "syntax error" when using npx**
-   - This was fixed in version 1.0.3 with the addition of a proper shebang line
-   - Make sure you're using the latest version: `npx brave-real-browser-mcp-server@latest`
-   - For global installation: `npm install -g brave-real-browser-mcp-server@latest`
-   - If still having issues, install globally: `npm install -g brave-real-browser-mcp-server`
-   - Check your PATH includes npm global binaries: `npm config get prefix`
-3. **Browser won't start**
-   - Check if Brave is installed in standard locations
-   - **Windows specific troubleshooting**:
-     **Step 1: Verify Brave Installation Paths**
-     Check these locations in order:
-     - `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`
-     - `C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`
-     - `%LOCALAPPDATA%\BraveSoftware\Brave-Browser\Application\brave.exe`
-     - `%PROGRAMFILES%\BraveSoftware\Brave-Browser\Application\brave.exe`
-     **Step 2: Manual Path Configuration**
-     If Brave is in a different location, specify it manually:
-     ```
-     Ask Claude: "Initialize browser with custom Brave path at C:\Your\Brave\Path\brave.exe"
-     ```
-     **Step 3: Windows Launch Arguments**
-     For Windows compatibility, use these launch arguments:
-     ```
-     Ask Claude: "Initialize browser with args --disable-gpu --disable-setuid-sandbox"
-     ```
-     **Step 4: Windows-Specific Solutions**
-     - **Run as Administrator**: Try running your IDE/terminal as Administrator
-     - **Windows Defender**: Add Brave and Node.js to Windows Defender exclusions
-     - **Antivirus Software**: Temporarily disable antivirus to test if it's blocking Brave
-     - **User Account Control**: Lower UAC settings temporarily for testing
-     - **Brave Processes**: Kill any existing Brave processes in Task Manager
-     **Step 5: Alternative Brave Installation**
-     If Brave detection still fails:
-     - Download Brave directly from [brave.com/download](https://brave.com/download/)
-     - Install to default location (`C:\Program Files\BraveSoftware\Brave-Browser\`)
-     - Restart your IDE after installation
-     **Step 6: PowerShell vs Command Prompt**
-     Try switching between PowerShell and Command Prompt:
-     - Test with `cmd.exe` instead of PowerShell
-     - Test with PowerShell instead of Command Prompt
-     **Step 7: Node.js and npm Configuration**
-     - Ensure Node.js is added to PATH: `node --version`
-     - Clear npm cache: `npm cache clean --force`
-     - Reinstall global packages: `npm install -g brave-real-browser-mcp-server@latest`
-   - **Linux**: Install dependencies: `sudo apt install brave-browser`
-   - **macOS**: Ensure Brave is in `/Applications/`
-   - Try with `headless: true` first
-   - Check console output for Brave path detection messages
-4. **Claude doesn't see the MCP server**
-   - Verify `claude_desktop_config.json` is in the correct location
-   - Check JSON syntax is valid (use [jsonlint.com](https://jsonlint.com/))
-   - Restart Claude Desktop completely
-   - Check for any error messages in Claude Desktop
-**4a. Claude Code CLI doesn't see the MCP server**
-   - **Installation Issues**:
-     - Verify `claude mcp add` command was successful
-     - Check command syntax: `claude mcp add brave-real-browser -- npx brave-real-browser-mcp-server@latest`
-     - Ensure you have the latest Claude Code CLI version
-   - **Scope and Configuration**:
-     - Check which scope you used: local (default), project, or user
-     - For local scope: ensure you're in the correct project directory
-     - For project scope: verify `.mcp.json` exists in project root
-     - For user scope: check user config directory
-   - **MCP Server Status**:
-     - Use `/mcp` command in Claude Code to check server status
-     - Look for the "brave-real-browser" server in the list
-     - Check if server status shows "connected" or error messages
-   - **Environment Variables**:
-     - If using custom environment variables (Chrome path, proxy), verify they're correctly set
-     - Test without environment variables first: `claude mcp add brave-real-browser -- npx brave-real-browser-mcp-server@latest`
-   - **Node.js and npx Issues**:
-     - Verify Node.js version 18+: `node --version`
-     - Test npx directly: `npx brave-real-browser-mcp-server@latest`
-     - Clear npm cache: `npm cache clean --force`
-   - **Protocol Version Issues** (Known Issue):
-     - Claude CLI may show protocolVersion validation errors despite correct configuration
-     - This is a known issue with internal validation in Claude CLI
-     - Server may still work despite validation warnings
-   - **Re-adding Server**:
-     ```bash
-     # Remove and re-add if issues persist
-     claude mcp remove brave-real-browser
-     claude mcp add brave-real-browser -- npx brave-real-browser-mcp-server@latest
-     ```
-**4b. Cursor IDE doesn't see the MCP server**
-   - **Config File Location Issues**:
-     - Verify `mcp.json` is in the correct location:
-       - Global: `~/.cursor/mcp.json` (`%USERPROFILE%\.cursor\mcp.json` on Windows)
-       - Project: `.cursor/mcp.json` in your project root
-     - Ensure filename is exactly `mcp.json` (not `mcp.json.txt`)
-     - Check file permissions allow reading
-   - **JSON Syntax Validation**:
-     - Use [jsonlint.com](https://jsonlint.com/) to validate JSON syntax
-     - Common issues: missing commas, incorrect quotes, trailing commas
-     - Ensure proper escaping of Windows paths: `"C:/Program Files/Google/Chrome/Application/chrome.exe"`
-   - **Cursor IDE Restart Process**:
-     - Close Cursor IDE completely (check Task Manager on Windows)
-     - Wait 5 seconds
-     - Restart Cursor IDE
-     - Open Command Palette and check MCP servers are listed
-   - **Environment Variables**:
-     - Verify Node.js is accessible: `node --version`
-     - Check PATH includes npm: `npm --version`
-     - Clear any conflicting environment variables
-   - **Cursor IDE Version Compatibility**:
-     - Ensure Cursor IDE version supports MCP (latest versions)
-     - Update Cursor IDE if using an older version
-     - Check Cursor IDE documentation for MCP requirements
-5. **Permission denied errors**
-   - On Linux/Mac: Try `sudo npm install -g brave-real-browser-mcp-server`
-   - Or use nvm to manage Node.js without sudo
-   - On Windows: Run command prompt as Administrator
-6. **Detection issues**
-   - Use appropriate delays between actions for better reliability
-   - Add random delays with `random_scroll`
-   - Use proxy if needed: `proxy: "http://proxy.example.com:8080"`
-7. **Memory leaks**
-   - Always close browser instances with `browser_close` when done
-   - Don't initialize multiple browsers without closing previous ones
-   - Check for uncaught exceptions that might prevent cleanup
-8. **Timeout errors**
-   - Increase timeout values: `{ "timeout": 60000 }`
-   - Use `wait` tool before interacting with elements
-   - Check network connectivity and website response times
-### Frequently Asked Questions
-**Q: When should I use npm install vs npx?**
-A:
-- **Use npx (recommended for most users):** When using with Claude Desktop, Claude Code CLI, or Cursor IDE. The npx command in your config automatically downloads and runs the latest version without installation.
-- **Use npm install -g:** Only if you want to run the server directly from command line frequently, or if you're developing/contributing to the project.
-- **Never needed:** If you're just a Claude Desktop/Claude Code CLI user following the Quick Start guide - npx handles everything!
-**Q: Should I use Claude Desktop or Claude Code CLI?**
-A: Both are excellent choices, depending on your needs:
-**Claude Desktop:**
-- **Best for:** Simple web browsing automation, content extraction, basic form filling
-- **Setup:** Manual JSON config file editing
-- **Sharing:** Individual use only
-- **Interface:** Desktop GUI application
-- **Authentication:** None required
-**Claude Code CLI:**
-- **Best for:** Development workflows, team collaboration, project-specific automation
-- **Setup:** Simple command-line setup (`claude mcp add`)
-- **Sharing:** Supports team sharing via project scope
-- **Interface:** Command-line integration with IDEs
-- **Authentication:** OAuth support available
-- **Advanced Features:** Environment variables, scope control, server monitoring
-**Use Claude Code CLI if you:**
-- Work in development teams
-- Need project-specific browser automation
-- Want environment variable configuration
-- Prefer command-line workflows
-- Need server health monitoring
-**Use Claude Desktop if you:**
-- Want a simple GUI experience
-- Do individual browsing automation
-- Don't need team collaboration features
-- Prefer visual interfaces over command-line
-**Q: Why do we use @latest in the npx command?**
-A: The `@latest` tag ensures you always get the newest version with bug fixes and security updates. Without it, npx might cache an older version. It's especially important for actively maintained projects.
-**Q: Does this work with headless browsers?**
-A: Yes, set `headless: true` in browser_init options.
-**Q: Can I use multiple browsers at once?**
-A: Currently supports one browser instance. Close the current one before starting a new one.
-**Q: What captchas can it solve?**
-A: Supports reCAPTCHA, hCaptcha, and Cloudflare Turnstile through brave-real-browser.
-**Q: Is this detectable by websites?**
-A: brave-real-browser includes anti-detection features, but no solution is 100% undetectable.
-**Q: Can I use custom Chrome extensions?**
-A: Yes, through the `plugins` option in browser_init.
-**Q: Does it work on all operating systems?**
-A: Yes, tested on Windows, macOS, and Linux. The server automatically detects Brave installations on all platforms.
-**Q: What's the difference between Claude Desktop, Claude Code CLI, and Cursor IDE configurations?**
-A: Here's a comparison:
-| Feature | Claude Desktop | Claude Code CLI | Cursor IDE |
-|---------|---------------|-----------------|------------|
-| **Setup Method** | Manual JSON editing | Command-line (`claude mcp add`) | One-click install OR manual JSON |
-| **Config Location** | `claude_desktop_config.json` | `.mcp.json` (scoped) | `.cursor/mcp.json` |
-| **Team Sharing** | No | Yes (project scope) | Yes |
-| **Environment Variables** | Limited support | Full support | Full support |
-| **Scope Control** | No | Yes (local/project/user) | Project/Global |
-| **Server Monitoring** | No | Yes (`/mcp` command) | Limited |
-| **Authentication** | None | OAuth available | OAuth available |
-| **Best For** | Individual GUI use | Development teams | Code-focused workflows |
-**Command Examples:**
-- **Claude Desktop**: Edit config file with JSON
-- **Claude Code CLI**: `claude mcp add brave-real-browser -- npx brave-real-browser-mcp-server@latest`
-- **Cursor IDE**: One-click install or manual JSON config
-**Q: What if Brave is installed in a non-standard location?**
-A: Version 1.3.0 dramatically improves Brave detection. The server now searches 15+ locations including portable installations and uses Windows Registry detection. If Brave is still not found automatically, you can:
-1. Set environment variable: `set BRAVE_PATH="C:\Your\Brave\Path\brave.exe"`
-2. Use the `customConfig.bravePath` option: `{"customConfig": {"bravePath": "C:\\Custom\\Brave\\brave.exe"}}`
-**Q: Why am I getting "Brave not found" or ECONNREFUSED errors on Windows?**
-A: Version 1.3.0 includes comprehensive fixes for Windows Brave detection and connection issues. The server now automatically searches these locations and more:
-- `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`
-- `C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`
-- `%LOCALAPPDATA%\BraveSoftware\Brave-Browser\Application\brave.exe`
-- `%USERPROFILE%\AppData\Local\BraveSoftware\Brave-Browser\Application\brave.exe`
-- Brave Beta and Nightly installations
-- Portable Brave installations
-- Registry-detected installations
-The server also implements multiple connection strategies with automatic fallback between localhost and 127.0.0.1, plus enhanced Windows-specific Brave flags for better compatibility.
-**Q: I'm still getting ECONNREFUSED errors after upgrading to v1.3.0. What should I do?**
-A: Try these steps in order:
-1. Set the `BRAVE_PATH` environment variable to your Brave location
-2. Kill all existing Brave processes: `taskkill /f /im brave.exe`
-3. Check your Windows hosts file contains: `127.0.0.1 localhost`
-4. Try running your IDE as Administrator
-5. Add Brave to Windows Defender exclusions
-6. If using a VPN/proxy, try disabling it temporarily
-### Debug Mode
-To enable debug logging:
+Server को HTTP mode में start करें:
 ```bash
-DEBUG=true npm start
+brave-real-browser-mcp-server --mode http --port 3000
 ```
-Or when running from source:
-```bash
-DEBUG=true npm run dev
-```
+फिर REST API endpoint का उपयोग करें: `http://localhost:3000`
-### Getting Help
-If you're still having issues:
-1. Check the [GitHub Issues](https://github.com/your-organization/brave-real-browser-mcp-server/issues)
-2. Create a new issue with:
-   - Your operating system
-   - Node.js version (`node --version`)
-   - npm version (`npm --version`)
-   - Full error message
-   - Steps to reproduce the problem
-## Development
-### Project Structure
-```text
-brave-real-browser-mcp-server/
-├── src/
-│   ├── index.ts         # Main server implementation
-│   └── stealth-actions.ts # Browser interaction functions
-├── test/
-│   └── test-server.ts   # Test script
-├── package.json
-└── tsconfig.json
-```
+---
-### Building from Source
+## 🛠️ सुविधाएँ और उपकरण
+### 🌐 ब्राउज़र प्रबंधन
+- `browser_init` - Anti-detection के साथ Brave browser शुरू करें
+- `browser_close` - Browser बंद करें
+- `navigate` - URL पर जाएं
+- `wait` - Elements/timeout के लिए प्रतीक्षा करें
+### 🖱️ इंटरैक्शन टूल्स
+- `click` - Elements पर क्लिक करें
+- `type` - Inputs में text टाइप करें
+- `solve_captcha` - CAPTCHA हल करें (reCAPTCHA, hCaptcha, आदि)
+- `random_scroll` - मानव-जैसे scrolling
+### 📄 कंटेंट निष्कर्षण
+- `get_content` - Page content निकालें (HTML/Text/Markdown)
+- `scrape_table` - Table data निकालें
+- `extract_list` - Lists निकालें
+- `extract_json` - JSON data निकालें
+- `image_scraper` - सभी images निकालें
+- `link_harvester` - सभी links निकालें
+### 🤖 AI-Powered टूल्स
+- `smart_selector_generator` - Selectors auto-generate करें
+- `content_classification` - Content type classify करें
+- `sentiment_analysis` - Sentiment का विश्लेषण करें
+- `summary_generator` - Summaries बनाएं
+### 🔐 CAPTCHA और सुरक्षा
+- `solve_captcha` - Multi-CAPTCHA solver
+- `ocr_engine` - Text CAPTCHAs के लिए OCR
+- `audio_captcha_solver` - Audio CAPTCHA solver
-```bash
-# Install dependencies
-npm install
+---
-# Run in development mode
-npm run dev
+## 💡 उपयोग उदाहरण
-# Build for production
-npm run build
+### उदाहरण 1: साधारण Web Scraping
-# Test the server
-npm test
+```javascript
+// Browser initialize करें
+await use_mcp_tool({
+  server_name: "brave-browser",
+  tool_name: "browser_init",
+  arguments: {}
+});
+// Website पर जाएं
+await use_mcp_tool({
+  server_name: "brave-browser",
+  tool_name: "navigate",
+  arguments: { url: "https://example.com" }
+});
+// Content प्राप्त करें
+await use_mcp_tool({
+  server_name: "brave-browser",
+  tool_name: "get_content",
+  arguments: { type: "text" }
+});
 ```
-### Adding New Tools
+---
-To add a new tool:
+## 📋 आवश्यकताएं
-1. Add the tool definition to the `TOOLS` array in `src/index.ts`
-2. Implement the tool handler in the `CallToolRequestSchema` handler
-3. Test the new tool functionality
+- **Node.js** >= 18.0.0
+- **Brave Browser** (auto-detected या path specify करें)
+- **Operating System:** Windows, macOS, या Linux
-## Testing
+---
-This project includes a comprehensive testing suite with multiple categories optimized for different purposes:
+## 🐛 समस्या निवारण
-### Quick Tests (CI/CD) - ~30 seconds
-```bash
-npm run test:quick    # Fast Jest tests for protocol compliance
-npm test              # Alias for test:quick
-```
+### Brave Browser नहीं मिला
-### Comprehensive Tests - ~5-10 minutes
+**समाधान:** Environment variable सेट करें
 ```bash
-npm run test:full     # End-to-end MCP client testing
-```
+# Windows
+set BRAVE_PATH="C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe"
-### Performance Testing - ~2-3 minutes
-```bash
-npm run test:performance  # Browser performance benchmarking
+# Linux/macOS
+export BRAVE_PATH="/usr/bin/brave-browser"
 ```
-Performance tests measure:
-- Browser initialization timing (5 trials)
-- Navigation performance across different site types
-- Concurrent operation handling
-- Session longevity testing (30+ operations over 30 seconds)
+### Server शुरू नहीं हो रहा
-### Debug Tools - ~10 seconds
-```bash
-npm run test:debug    # Environment diagnostics and troubleshooting
-```
+1. Node.js version check करें: `node --version` (>= 18 होना चाहिए)
+2. NPM cache clear करें: `npm cache clean --force`
+3. फिर से install करें: `npm install -g brave-real-browser-mcp-server`
-Debug tools provide:
-- Environment validation (Node.js version, platform, memory)
-- Chrome installation detection with specific paths
-- Quick server health check with startup timing
-- Network connectivity validation
-- Build status verification
+---
-### All Tests - ~7-13 minutes
-```bash
-npm run test:all      # Runs quick + full + performance tests
-npm run test:dashboard # Unified test runner with reporting
-```
+## 🤝 योगदान
-The test dashboard provides:
-- Unified execution of multiple test categories
-- Real-time progress reporting
-- Performance metrics and timing
-- Overall test status summary
-- Recommendations for failed tests
-- JSON results saved to `test-results/` directory
+Contributions स्वागत है! कृपया Pull Request submit करें।
-### Integration Testing
-```bash
-npm run test:integration  # Claude Code CLI integration testing
-```
+---
-For detailed testing information, see [TESTING.md](TESTING.md).
+## 📄 लाइसेंस
-## Contributing
+यह प्रोजेक्ट MIT License के तहत लाइसेंस प्राप्त है।
-Contributions are welcome! Please feel free to submit a Pull Request.
+---
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+## 🌟 मुख्य विशेषताएं
-## License
+✅ **15+ AI IDEs समर्थित** - Claude, Cursor, Windsurf, Cline, Zed, VSCode, Qoder AI, और अधिक
+✅ **Auto-Detection** - आपका IDE automatically detect होता है
+✅ **4 Protocols** - MCP, LSP, HTTP, WebSocket
+✅ **100+ Tools** - Browser automation, scraping, CAPTCHA solving
+✅ **Anti-Detection** - Cloudflare, reCAPTCHA bypass
+✅ **Cross-Platform** - Windows, macOS, Linux
-This project is licensed under the MIT License - see the LICENSE file for details.
+---
-## Acknowledgments
+<div align="center">
-This MCP server is based on the excellent [brave-real-browser](https://github.com/ZFC-Digital/brave-real-browser) library by ZFC-Digital.
+**Made with ❤️ for the AI Development Community**
-**Thank you** to the brave-real-browser team for creating such a powerful and detection-resistant browser automation solution!
+[⭐ Star on GitHub](https://github.com/withLinda/brave-real-browser-mcp-server) | [🐛 Report Bug](https://github.com/withLinda/brave-real-browser-mcp-server/issues) | [💡 Request Feature](https://github.com/withLinda/brave-real-browser-mcp-server/issues)
-- GitHub: [https://github.com/ZFC-Digital/brave-real-browser](https://github.com/ZFC-Digital/brave-real-browser)
-- npm: [https://www.npmjs.com/package/brave-real-browser](https://www.npmjs.com/package/brave-real-browser)
+</div>