brave-real-browser-mcp-server 2.21.7 → 2.23.0

package/README.md

@@ -1,54 +1,13 @@
-
-⚠️ **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.
+> **AI assistants के लिए powerful, anti-detection browser automation - Unified MCP+LSP+SSE ecosystem**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/brave-real-browser-mcp-server.svg)](https://www.npmjs.com/package/brave-real-browser-mcp-server)
 
-## 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. [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)
-
-## 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
+## 🚀 Quick Start
 
-#### 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:
+### Option 1: NPX (Recommended for AI IDEs)
 
 ```json
 {
@@ -61,1274 +20,211 @@ If you're just using this MCP server (not developing it), you don't need to run
 }
 ```
 
-**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
-
-- **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)
-- **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**: 33 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
-- Google Chrome or 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`
-  - Portable installations and Registry-detected paths
-  - Manual path specification: Use `CHROME_PATH` environment variable
+**Config locations:**
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Mac:** `~/Library/Application Support/Claude/`
+- **Linux:** `~/.config/Claude/`
 
-**macOS:**
-- Google Chrome or Chromium must be installed in `/Applications/`
-
-**Linux:**
-- Install Chrome/Chromium: `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`
-
-## 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)
+### Option 2: Unified Server (Full Features)
 
 ```bash
-# Clone the repository
-git clone https://github.com/withLinda/brave-real-browser-mcp-server.git
-cd brave-real-browser-mcp-server
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Run in development mode
 npm run dev
 ```
 
-## Usage
-
-### With Claude Desktop
-
-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
-
-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)
-
-The fastest way to get started is using the `claude mcp add` command:
-
-```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
-
-If you need to configure proxy settings or custom Chrome paths:
-
-```bash
-claude mcp add brave-real-browser \
-  -e CHROME_PATH="/path/to/chrome" \
-  -e PROXY_URL="http://proxy:8080" \
-  -- npx brave-real-browser-mcp-server@latest
-```
-
-#### Method 3: Scoped Configuration
-
-**For User-Wide Access (Available Across All Projects):**
-```bash
-claude mcp add brave-real-browser -s user -- npx brave-real-browser-mcp-server@latest
-```
-
-**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
-```
-
-#### Method 4: JSON Configuration
-
-For advanced users who want precise control:
-
-```bash
-claude mcp add-json brave-real-browser '{
-  "type": "stdio",
-  "command": "npx",
-  "args": ["brave-real-browser-mcp-server@latest"],
-  "env": {
-    "CHROME_PATH": "/path/to/chrome",
-    "PROXY_URL": "http://proxy:8080"
-  }
-}'
-```
-
-#### 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)
-
-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
-
-#### Method 2: Manual Configuration
-
-**Configuration File Location:**
-- **Project-specific**: Create `.cursor/mcp.json` in your project directory
-- **Global**: Create `~/.cursor/mcp.json` in your home directory
-
-**Basic Configuration (No Installation Required):**
-```json
-{
-  "mcpServers": {
-    "brave-real-browser": {
-      "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"]
-    }
-  }
-}
-```
-
-> **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):**
-```json
-{
-  "mcpServers": {
-    "brave-real-browser": {
-      "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"],
-      "env": {
-        "CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.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:**
-```json
-{
-  "mcpServers": {
-    "brave-real-browser": {
-      "command": "npx",
-      "args": ["brave-real-browser-mcp-server@latest"],
-      "env": {
-        "CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"
-      }
-    }
-  }
-}
-```
-
-> **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
-
-If Chrome auto-detection fails, you can specify the Chrome path using the `CHROME_PATH` environment variable:
-
-**Windows:**
-```json
-"env": {
-  "CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"
-}
-```
-Alternative Windows paths:
-- `"C:/Program Files (x86)/Google/Chrome/Application/chrome.exe"`
-- `"%LOCALAPPDATA%/Google/Chrome/Application/chrome.exe"`
-
-**macOS:**
-```json
-"env": {
-  "CHROME_PATH": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
-}
-```
-
-**Linux:**
-```json
-"env": {
-  "CHROME_PATH": "/usr/bin/google-chrome"
-}
-```
-Alternative Linux paths: `/usr/bin/chromium-browser`, `/snap/bin/chromium`
-
-
-#### 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 Chrome path in `executablePath`
-   - Try running Cursor IDE as Administrator
-   - Check Windows Defender isn't blocking Chrome
+## ✨ Features
 
-3. **"Permission denied"**
-   - Use `sudo npm install -g brave-real-browser-mcp-server` on Linux/Mac
-   - Run Command Prompt as Administrator on Windows
+| Feature | Description |
+|---------|-------------|
+| **33 MCP Tools** | Complete browser automation toolkit |
+| **Unified Server** | MCP + SSE + LSP in one command |
+| **Stealth Mode** | 50+ anti-detection features |
+| **Captcha Solving** | reCAPTCHA, hCaptcha, Turnstile |
+| **Brave Browser** | Auto-detection, uBlock Origin built-in |
+| **TypeScript Analyzer** | Full Compiler API integration |
+| **Real-time Streaming** | SSE for live progress updates |
+| **Auto-Sync** | SharedEventBus connects all protocols |
 
-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
+---
 
-### With Other AI Assistants
+## 🌐 Unified MCP+LSP+SSE Ecosystem
 
-Start the server:
+**एक command से सब active:**
 
 ```bash
-brave-real-browser-mcp-server
-```
-
-Or if installed from source:
-
-```bash
-npm start
-```
-
-The server communicates via stdin/stdout using the MCP protocol.
-
-### 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]
-
-```
-
-#### 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]
-
-User: "Click the search button"
-AI: I'll click the search button.
-[Uses click tool]
+npm run dev
 ```
 
-#### 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']
-
-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]
+### Output:
 ```
+🦁 Brave Real Browser - Unified Server v2.22.0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📡 HTTP Server: http://localhost:3000
 
+🛠️  Available MCP Tools:
+   🚀 browser_init    🔴 browser_close   🌐 navigate
+   📄 get_content     🔍 find_element    🖱️ click
+   ⌨️ type           🤖 solve_captcha   🎬 media_extractor
+   ... and 24 more tools
 
-#### 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"]
+🔗 SharedEventBus: Auto-syncing MCP ↔ LSP ↔ SSE
+📋 Total: 33 MCP tools | TypeScript Analyzer Active
+✅ Ready! All protocols unified and auto-synced.
 ```
 
-## Available Tools
-
-This server provides **33 powerful tools** organized into categories for comprehensive browser automation.
-
----
-
-### 🖥️ Core Browser Tools (4 tools)
-
-| Tool | Description |
-|------|-------------|
-| `browser_init` | Initialize stealth browser with anti-detection features, uBlock Origin, and configurable options (headless, proxy, plugins) |
-| `navigate` | Navigate to any URL with customizable wait conditions (load, domcontentloaded, networkidle) |
-| `get_content` | Extract page content as HTML or plain text, with optional CSS selector for specific elements |
-| `browser_close` | Safely close the browser instance and cleanup resources |
-
----
+### All Endpoints:
 
-### 🖱️ Interaction Tools (4 tools)
-
-| Tool | Description |
-|------|-------------|
-| `click` | Click on any element using CSS selector, with optional navigation wait |
-| `type` | Type text into input fields with human-like delays between keystrokes |
-| `wait` | Wait for various conditions: selector visibility, navigation, or timeout |
-| `press_key` | Simulate keyboard key presses with modifiers (Ctrl, Shift, Alt) - supports Enter, Tab, Escape, etc. |
+| Category | Endpoint | Purpose |
+|----------|----------|---------|
+| **MCP** | `POST /mcp` | MCP over HTTP |
+| **MCP** | `GET /mcp/sse` | SSE real-time streaming |
+| **MCP** | `POST /mcp/message` | SSE message handler |
+| **LSP** | `POST /lsp/completion` | Autocomplete |
+| **LSP** | `POST /lsp/hover` | Hover documentation |
+| **LSP** | `POST /lsp/analyze` | TypeScript analysis |
+| **LSP** | `POST /lsp/definition` | Go to definition |
+| **LSP** | `POST /lsp/references` | Find references |
+| **Other** | `GET /health` | Health check |
+| **Other** | `GET /events` | Event bus stats |
 
 ---
 
-### 🔍 Selector & Element Discovery Tools (4 tools)
+## 🛠️ All 33 MCP Tools
 
+### Browser Management
 | Tool | Description |
 |------|-------------|
-| `find_selector` | Find CSS selector for elements containing specific text (exact or partial match) |
-| `find_element_advanced` | Advanced element finding using XPath, CSS selectors, or text content |
-| `smart_selector_generator` | AI-powered selector generation based on natural language descriptions |
-| `batch_element_scraper` | Efficiently scrape lists of similar elements with customizable attributes |
-
----
-
-### 📝 Content Extraction Tools (5 tools)
+| `browser_init` | Initialize Brave browser with stealth |
+| `browser_close` | Close browser instance |
 
+### Navigation
 | Tool | Description |
 |------|-------------|
-| `save_content_as_markdown` | Convert page content to formatted markdown file with metadata |
-| `search_content` | Search text or regex patterns in page content with context |
-| `extract_json` | Extract embedded JSON data (LD+JSON, __NEXT_DATA__, window variables) |
-| `scrape_meta_tags` | Extract SEO, Open Graph, and Twitter meta tags |
-| `extract_schema` | Extract Schema.org structured data (JSON-LD and Microdata) |
-
----
-
-### 🔗 Navigation & Redirect Tools (3 tools)
+| `navigate` | Navigate to URL |
+| `wait` | Wait for conditions |
 
+### Content
 | Tool | Description |
 |------|-------------|
-| `breadcrumb_navigator` | Navigate using site breadcrumbs - find and click breadcrumb links |
-| `url_redirect_tracer` | Trace standard URL redirects and show the complete redirect chain |
-| `multi_layer_redirect_trace` | Trace complex redirects including JavaScript and meta refresh redirects |
-
----
-
-### 🌐 Network & API Tools (4 tools)
+| `get_content` | Get page HTML/text |
+| `find_element` | Find by selector/text/AI |
+| `save_content_as_markdown` | Save as markdown file |
 
+### Interaction
 | Tool | Description |
 |------|-------------|
-| `network_recorder` | Record full network traffic with headers, body, and response data |
-| `api_finder` | Discover hidden API endpoints by monitoring XHR/fetch requests |
-| `ajax_content_waiter` | Wait for dynamic AJAX/JavaScript content to load |
-| `deep_analysis` | Comprehensive analysis: console logs, network, DOM stats, and screenshot |
-
----
-
-### 🎬 Media Extraction Tools (3 tools)
+| `click` | Click on element |
+| `type` | Type text into input |
+| `press_key` | Keyboard press |
+| `random_scroll` | Natural scrolling |
+| `solve_captcha` | Solve CAPTCHAs |
 
+### Media Extraction
 | Tool | Description |
 |------|-------------|
-| `advanced_video_extraction` | Extract video URLs from pages including YouTube, Vimeo, embedded players |
-| `media_extractor` | Extract audio/video elements and embedded media |
-| `image_extractor_advanced` | Advanced image extraction with size filtering, backgrounds, and lazy-load support |
-
----
-
-### 📷 Screenshot Tools (1 tool)
+| `media_extractor` | Extract video/audio |
+| `m3u8_parser` | Parse HLS streams |
+| `stream_extractor` | Direct download URLs |
 
+### Advanced
 | Tool | Description |
 |------|-------------|
-| `element_screenshot` | Capture screenshot of specific elements by selector |
+| `search_content` | Search patterns |
+| `extract_json` | Extract embedded JSON |
+| `scrape_meta_tags` | Meta/OG tags |
+| `deep_analysis` | Full page analysis |
+| `network_recorder` | Record traffic |
+| `api_finder` | Discover APIs |
+| `ajax_content_waiter` | Wait for AJAX |
+| `link_harvester` | Harvest links |
+| `batch_element_scraper` | Batch scrape |
+| `extract_schema` | Schema.org data |
+| `element_screenshot` | Screenshot element |
+| `breadcrumb_navigator` | Navigate breadcrumbs |
+| `redirect_tracer` | Trace redirects |
+| `progress_tracker` | Track progress |
+| `cookie_manager` | Manage cookies |
+| `file_downloader` | Download files |
+| `iframe_handler` | Handle iframes |
+| `popup_handler` | Handle popups |
 
 ---
 
-### 🔗 Link Tools (1 tool)
-
-| Tool | Description |
-|------|-------------|
-| `link_harvester` | Harvest all links from page with filtering (internal, external, pattern) |
+## 📋 Commands
 
----
+```bash
+# Install
+npm install
 
-### 🛡️ Anti-Detection Tools (1 tool)
+# Build
+npm run build
 
-| Tool | Description |
-|------|-------------|
-| `solve_captcha` | Solve CAPTCHAs (reCAPTCHA, hCaptcha, Turnstile) with auto-detection |
+# Development (Unified - Recommended!)
+npm run dev           # MCP + SSE + LSP on port 3000
 
----
+# Alternate modes
+npm run dev:stdio     # STDIO only (for AI IDEs)
+npm run dev:sse       # SSE standalone
+npm run dev:http      # HTTP Stream standalone
 
-### 📊 Utility Tools (2 tools)
+# Production
+npm start             # Unified server
+npm run start:stdio   # STDIO mode
 
-| Tool | Description |
-|------|-------------|
-| `random_scroll` | Perform natural random scrolling to avoid bot detection |
-| `progress_tracker` | Track automation progress for multi-step tasks |
+# Tests
+npm test
+npm run test:e2e
+```
 
 ---
 
-### 🎬 Streaming & Download Tools (3 tools)
+## ⚙️ Environment Variables
 
-| Tool | Description |
-|------|-------------|
-| `iframe_handler` | Extract content from nested iframes including embedded video players |
-| `popup_handler` | Handle popups, new tabs, and ad overlays during navigation |
-| `stream_extractor` | Master tool: Extract direct download/stream URLs with automatic countdown waiting and format detection |
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MCP_PORT` | `3000` | Server port |
+| `MCP_HOST` | `localhost` | Server host |
+| `DEBUG` | `false` | Debug logging |
 
 ---
 
-### Tool Parameters Quick Reference
+## 🔧 Browser Options
 
-#### browser_init
 ```json
 {
   "headless": false,
-  "disableXvfb": false,
-  "ignoreAllFlags": true,
-  "proxy": "http://proxy:8080",
-  "plugins": ["plugin1"],
-  "customConfig": { "bravePath": "/path/to/brave" }
-}
-```
-
-#### navigate
-```json
-{
-  "url": "https://example.com",
-  "waitUntil": "domcontentloaded"  // or: load, networkidle0, networkidle2
+  "proxy": "http://proxy:8080"
 }
 ```
 
-#### get_content
-```json
-{
-  "type": "html",  // or: text
-  "selector": ".main-content"
-}
-```
-
-#### search_content
-```json
-{
-  "pattern": "search term",
-  "isRegex": false,
-  "caseSensitive": false,
-  "selector": "body"
-}
-```
-
-#### find_element_advanced
-```json
-{
-  "xpath": "//button[@type='submit']",
-  "cssSelector": "form button",
-  "contains": "Submit"
-}
-```
-
-## Advanced Features
-
-### Dynamic Selector Discovery
-
-The server includes intelligent element discovery capabilities through the `find_selector` tool:
-
-- **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
-
-**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"]
-
-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.
-
-### Natural Interactions
-
-The server includes tools designed for natural browsing behavior:
-
-- **Random scrolling**: Performs scrolling with natural timing and variable distances
-
-This feature helps avoid detection by sophisticated bot-detection systems
-that analyze user behavior patterns.
-
-### Captcha Handling
-
-The server includes basic support for solving common captcha types:
-
-- reCAPTCHA
-- hCaptcha
-- Cloudflare Turnstile
-
-Note that captcha solving capabilities depend on the underlying
-brave-real-browser implementation.
-
-## Configuration
-
-### Automatic Chrome Path Detection (Enhanced in v1.3.0)
-
-The server automatically detects Chrome installation paths across different operating systems with significantly improved Windows support:
-
-- **Windows (v1.3.0+)**: 
-  - Registry-based detection for installed Chrome versions
-  - Searches 15+ common installation directories including Program Files, user-specific locations, and portable installations
-  - Support for Chrome Canary fallback
-  - Environment variable detection (`CHROME_PATH`, `PUPPETEER_EXECUTABLE_PATH`)
-  - Detailed troubleshooting guidance when Chrome is not found
-  
-- **macOS**: Looks for Chrome in `/Applications/Google Chrome.app/` and Chrome Canary locations
-
-- **Linux**: Checks multiple locations including `/usr/bin/google-chrome`, `/usr/bin/chromium-browser`, and snap installations
-
-**Windows Registry Detection** (NEW in v1.3.0):
-The server now queries Windows Registry to find Chrome installations, making detection more reliable across different installation types.
-
-If Chrome is not found automatically, you can specify a custom path using:
-1. Environment variable: `set CHROME_PATH="C:\Your\Chrome\Path\chrome.exe"`
-2. Browser init option: `customConfig.chromePath` when initializing the browser
-
-### 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:
-
-```
-Please initialize a browser with headless mode enabled and a 30-second timeout
-```
-
-Claude will then use the `browser_init` tool with appropriate parameters:
-
-```json
-{
-  "headless": true,
-  "connectOption": {
-    "timeout": 30000
-  }
-}
-```
-
-### 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)
-
-The MCP config file only tells Claude where to find the server - all browser-specific options are configured through your conversations with Claude.
-
-### Browser Options Example
-
-When initializing the browser with `browser_init`, you can configure:
-
-```json
-{
-  "headless": false,
-  "disableXvfb": false,
-  "ignoreAllFlags": false,
-  "proxy": "https://proxy:8080",
-  "plugins": ["plugin1", "plugin2"],
-  "connectOption": {
-    "slowMo": 250,
-    "timeout": 60000
-  }
-}
-```
-
-### Advanced Configuration Examples
-
-#### Specifying Custom Chrome Path
-```json
-{
-  "customConfig": {
-    "chromePath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
-  }
-}
-```
-
-#### Using a Proxy
-```json
-{
-  "headless": true,
-  "proxy": "https://username:password@proxy.example.com:8080"
-}
-```
-
-#### Stealth Mode with Custom Options
-```json
-{
-  "headless": false,
-  "ignoreAllFlags": true,
-  "disableXvfb": false,
-  "connectOption": {
-    "slowMo": 100,
-    "devtools": false
-  }
-}
-```
-
-
-### 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 Chrome Path Detection:**
-- Added Windows Registry-based Chrome detection
-- Expanded search to 15+ Windows installation locations including portable installations
-- Added support for Chrome Canary fallback
-- Environment variable support (`CHROME_PATH`, `PUPPETEER_EXECUTABLE_PATH`)
-
-**Windows-Specific Launch Optimizations:**
-- 20+ Windows-specific Chrome 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 CHROME_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"
-   ```
-
-2. **Manual Chrome Path Configuration:**
-   ```text
-   Ask Claude: "Initialize browser with custom Chrome path at C:\\Program Files\\Google\\Chrome\\Application\\chrome.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. **Chrome Process Management:**
-   ```bash
-   # Kill existing Chrome processes
-   taskkill /f /im chrome.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 Chrome/Chromium is installed in standard locations
-   - **Windows specific troubleshooting**:
-     
-     **Step 1: Verify Chrome Installation Paths**
-     Check these locations in order:
-     - `C:\Program Files\Google\Chrome\Application\chrome.exe`
-     - `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`
-     - `%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe`
-     - `%PROGRAMFILES%\Google\Chrome\Application\chrome.exe`
-     
-     **Step 2: Manual Path Configuration**
-     If Chrome is in a different location, specify it manually:
-     ```
-     Ask Claude: "Initialize browser with custom Chrome path at C:\Your\Chrome\Path\chrome.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 Chrome and Node.js to Windows Defender exclusions
-     - **Antivirus Software**: Temporarily disable antivirus to test if it's blocking Chrome
-     - **User Account Control**: Lower UAC settings temporarily for testing
-     - **Chrome Processes**: Kill any existing Chrome processes in Task Manager
-     
-     **Step 5: Alternative Chrome Installation**
-     If Chrome detection still fails:
-     - Download Chrome directly from [google.com/chrome](https://www.google.com/chrome/)
-     - Install to default location (`C:\Program Files\Google\Chrome\`)
-     - 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-get install -y google-chrome-stable`
-   - **macOS**: Ensure Chrome is in `/Applications/`
-   - Try with `headless: true` first
-   - Check console output for Chrome 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 Chrome 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 Chrome is installed in a non-standard location?**
-A: Version 1.3.0 dramatically improves Chrome detection. The server now searches 15+ locations including portable installations and uses Windows Registry detection. If Chrome is still not found automatically, you can:
-1. Set environment variable: `set CHROME_PATH="C:\Your\Chrome\Path\chrome.exe"`
-2. Use the `customConfig.chromePath` option: `{"customConfig": {"chromePath": "C:\\Custom\\Chrome\\chrome.exe"}}`
-
-**Q: Why am I getting "Chrome not found" or ECONNREFUSED errors on Windows?**
-A: Version 1.3.0 includes comprehensive fixes for Windows Chrome detection and connection issues. The server now automatically searches these locations and more:
-- `C:\Program Files\Google\Chrome\Application\chrome.exe`
-- `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe` 
-- `%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe`
-- `%USERPROFILE%\AppData\Local\Google\Chrome\Application\chrome.exe`
-- Chrome Canary installations
-- Portable Chrome 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 Chrome flags for better compatibility.
+## 📋 Prerequisites
 
-**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 `CHROME_PATH` environment variable to your Chrome location
-2. Kill all existing Chrome processes: `taskkill /f /im chrome.exe`
-3. Check your Windows hosts file contains: `127.0.0.1 localhost`
-4. Try running your IDE as Administrator
-5. Add Chrome to Windows Defender exclusions
-6. If using a VPN/proxy, try disabling it temporarily
+- **Node.js** >= 18.0.0
+- **Brave Browser** (auto-detected)
 
-### Debug Mode
+---
 
-To enable debug logging:
+## 🐛 Troubleshooting
 
+### Port in use
 ```bash
-DEBUG=true npm start
+MCP_PORT=3001 npm run dev
 ```
 
-Or when running from source:
+### Debug mode
 ```bash
 DEBUG=true npm run dev
 ```
 
-### 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
-
-```bash
-# Install dependencies
-npm install
-
-# Run in development mode
-npm run dev
-
-# Build for production
-npm run build
-
-# Test the server
-npm test
-```
-
-### 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
-
-## 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
-```
-
-### Comprehensive Tests - ~5-10 minutes  
-```bash
-npm run test:full     # End-to-end MCP client testing
-```
-
-### Performance Testing - ~2-3 minutes
-```bash
-npm run test:performance  # Browser performance benchmarking
-```
-
-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)
-
-### Debug Tools - ~10 seconds
-```bash
-npm run test:debug    # Environment diagnostics and troubleshooting
-```
-
-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
-
-### Integration Testing
-```bash
-npm run test:integration  # Claude Code CLI integration testing
-```
-
-For detailed testing information, see [TESTING.md](TESTING.md).
-
-## Contributing
-
-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
-
-This project is licensed under the MIT License - see the LICENSE file for details.
+---
 
-## Acknowledgments
+## 📄 License
 
-This MCP server is based on the excellent [brave-real-browser](https://github.com/ZFC-Digital/brave-real-browser) library by ZFC-Digital.
+MIT License - see [LICENSE](LICENSE)
 
-**Thank you** to the brave-real-browser team for creating such a powerful and detection-resistant browser automation solution!
+---
 
-- 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)
+Made with ❤️ by [codeiva4u](https://github.com/codeiva4u)