# Brave Real Browser MCP Server

[![npm version](https://img.shields.io/npm/v/brave-real-browser-mcp-server.svg)](https://www.npmjs.com/package/brave-real-browser-mcp-server)
[![Auto-Update](https://github.com/codeiva4u/Brave-Real-Browser-Mcp-Server/actions/workflows/auto-update-deps.yml/badge.svg)](https://github.com/codeiva4u/Brave-Real-Browser-Mcp-Server/actions/workflows/auto-update-deps.yml)
[![Monorepo Publish](https://github.com/codeiva4u/Brave-Real-Browser-Mcp-Server/actions/workflows/monorepo-publish.yml/badge.svg)](https://github.com/codeiva4u/Brave-Real-Browser-Mcp-Server/actions/workflows/monorepo-publish.yml)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)

**MCP Server for Puppeteer + Brave Browser + Stealth + Ad Blocker + Turnstile Auto-Solver**

A production-ready MCP (Model Context Protocol) server that combines Puppeteer with Brave Browser for undetectable web automation. Passes all major bot detectors including Cloudflare, DataDome, and reCAPTCHA v3.

## Key Features

| Feature | Description |
|---------|-------------|
| **MCP Server** | Model Context Protocol compatible server with 23 optimized tools |
| **LSP Server** | Language Server Protocol for IDE code intelligence |
| **AI Core** | Automatic AI enhancement for all tools (auto-healing, smart retry) |
| Brave Browser | Uses Brave instead of Chromium for better privacy |
| 50+ Stealth Features | Passes all major bot detectors |
| Built-in Ad Blocker | 45+ filter sources, 100/100 score, auto-update |
| Turnstile Auto-Solver | Cloudflare CAPTCHA bypass |
| Real Cursor | Ghost-cursor for human-like movements |
| Plugin Support | Puppeteer-extra plugins compatible |
| Proxy Support | Built-in proxy with authentication |
| Auto-Install | Brave auto-installs if missing |
| TypeScript Support | Full type definitions included |
| ESM + CJS | Dual module support |
| **Multi-language** | English & Hindi language support |
| **Auto-Update** | Daily automatic dependency updates |
| **Auto-Publish** | Automatic NPM publishing on updates |
| **Monorepo** | npm workspaces with linked packages |
| **Singleton Blocker** | Single shared blocker instance |
| **Decoder Utilities** | URL, Base64, AES decryption built-in |
| **Batch Operations** | Extract from multiple URLs/pages at once |
| **Nested Iframe Support** | Scan 3+ levels deep in iframes |

---

## MCP Server (Model Context Protocol)

This package is a fully-featured MCP Server with **23 optimized browser automation tools** for AI assistants like Claude, Cursor, Copilot, and other MCP-compatible clients. Tools intelligently merged for maximum efficiency with AI auto-healing capabilities.

### Quick Start MCP Server

```bash
# Start the MCP server
npm run dev

# Or with verbose mode (shows all tool details)
npm run mcp:verbose
```

### MCP Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "brave-real-browser-mcp-server": {
      "command": "node",
      "args": [
        "C:/Users/Admin/Desktop/Brave-Real-Browser-Mcp-Server/dist/index.js"
      ],
      "env": {
        "HEADLESS": "false"
      }
    }
  }
}
```


```json
"mcp": {
    "brave-real-browser-mcp-server": {
      "type": "local",
      "command": ["node", "c:\\Users\\Admin\\Desktop\\Brave-Real-Browser-Mcp-Server\\dist\\index.js"],
      "environment": {
        "HEADLESS": "false"
      },
      "enabled": true
    }
  },
```
Or if installed globally:

```json
{
  "mcpServers": {
    "brave-browser": {
      "command": "brave-mcp"
    }
  }
}
```

### Available MCP Tools (23 Optimized)

| # | Tool | Description | Status |
|---|------|-------------|--------|
| 1 | `browser_init` 🚀 | Initialize Brave browser with 50+ stealth features, anti-detection, Turnstile auto-solver, proxy support, ad blocker, AI auto-healing | ✅ |
| 2 | `navigate` 🧭 | Navigate to URL with smart retry (3 attempts), context recovery, AI healing, customizable wait strategies (load/DOMContentLoaded/networkidle) | ✅ |
| 3 | `get_content` 📄 | Get page content in 4 formats: **html** (full HTML), **text** (plain), **markdown** (formatted), **rawHttp** (raw HTTP without JS — fast, bypasses JS protections). AI selector healing + attribute extraction | ✅ **Enhanced** |
| 4 | `wait` ⏳ | Smart wait: selector, navigation, timeout, networkidle, or AI-predicted optimal timing | ✅ |
| 5 | `click` 👆 | Human-like click with ghost cursor, AI healing, iframe support, hover-first for dynamic controls, auto video player detection (JWPlayer/VideoJS/Plyr/VidStack/DooPlayer) | ✅ |
| 6 | `type` ⌨️ | Type with human speed variation, smart clearing, iframe support, optional Enter key press | ✅ |
| 7 | `browser_close` 🔴 | Close browser with cleanup, optional session save (cookies + storage) | ✅ |
| 8 | `solve_captcha` 🔓 | Auto-solve: Turnstile, reCAPTCHA, hCaptcha (JS-based) + Text/Image OCR. Merged with form automation — AI field matching, human-like typing, auto-submit | ✅ |
| 9 | `random_scroll` 📜 | Human-like scroll with AI pattern detection, lazy-load trigger, direction: up/down/random/smart | ✅ |
| 10 | `find_element` 🔍 | Find elements by CSS selector, XPath, or text content. AI auto-heals broken selectors, extracts smart attributes | ✅ |
| 11 | `save_content_as_markdown` 📝 | Save page as AI-cleaned Markdown file — removes ads/clutter, includes images and meta | ✅ |
| 12 | `redirect_tracer` 🔀 | Trace full redirect chains: HTTP 301/302 + JS navigations (window.location, setTimeout) + meta refresh. Auto-decodes encoded URLs, returns status codes + headers | ✅ |
| 13 | **`extract_data`** 🔎 | **8 modes:** regex, json, meta, structured, auto, **deobfuscate** (JS decode: _0x arrays, hex, unicode, eval, webpack, terser, string concat, rotation), **apiDiscovery** (hidden APIs via runtime interception), **decrypt** (Base64 chain, hex, URL, ROT13, AES-256-CBC + auto key extract) | ✅ **Power** |
| 14 | `press_key` 🎹 | Press keyboard keys with human-like timing, modifier support (Ctrl/Shift/Alt), repeat count | ✅ |
| 15 | `progress_tracker` 📈 | Track automation progress (0-100%), AI estimates remaining time | ✅ |
| 16 | `deep_analysis` 🧠 | Deep page analysis: DOM structure, scripts, anti-bot detection (Cloudflare/DataDome/reCAPTCHA), tech stack, SEO tags, security headers, AI scraping strategy recommendations | ✅ |
| 17 | **`network_recorder`** 📡 | **9 actions:** start (+ inject API interceptors for fetch/XHR/sendBeacon + WebSocket interceptor), stop, get, clear, **get_media** (HLS/DASH/video), **get_navigations** (JS redirects), **get_api_calls** (with full request/response bodies), **get_intercepted_apis** (runtime monkey-patched calls), **get_websockets** (all WS connections + messages) | ✅ **Power** |
| 18 | `link_harvester` 🔗 | Extract all links: hidden (display:none), Base64/URL encoded, obfuscated (data attrs, JS vars), iframe links (multi-level), dynamic links. Auto-decode enabled | ✅ |
| 19 | `cookie_manager` 🍪 | Cookie CRUD: get/set/delete/clear/export/import. AI optimizes session persistence | ✅ |
| 20 | `file_downloader` ⬇️ | Download files with resume support, batch download (multiple URLs), auto-decode Base64/URL encoded URLs, AES decryption for encrypted files | ✅ |
| 21 | **`media_extractor`** 🎬 | **6 actions:** extract (video/audio/HLS/DASH/download from page + 3+ level nested iframes), list_iframes, switch_iframe, player_control (JWPlayer/VideoJS/Plyr/VidStack/DooPlayer — play/pause/seek/sources), decode_url (auto/url/base64/aes), batch_extract | ✅ **New** |
| 22 | `execute_js` 💻 | Execute custom JavaScript: async support, error handling, iframe context execution (by index or selector), configurable timeout | ✅ |
| 23 | `form_automator` 📋 | Smart form automation: AI field detection and matching, human-like typing, auto-fill, captcha integration, validation before submit | ✅ |

#### Tool Optimization Summary

**Merged Tools (5 → 2):**
- ✅ `iframe_handler` + `stream_extractor` + `player_api_hook` → **`media_extractor`**
- ✅ `search_regex` + `extract_json` + `scrape_meta_tags` → **`extract_data`**
- ✅ `get_content` enhanced with `js_scrape` features

**Benefits:**
- 🎯 **18% reduction** in tool count (28 → 23)
- 🚀 **Simpler API** for AI agents
- 💪 **More powerful** combined features
- 🤖 **AI-first design** with auto-healing
- 📦 **Decoder utilities** built-in (URL, Base64, AES)

### MCP Example Usage

```
User: Open a browser and go to example.com

AI: I'll use browser_init to start the browser, then navigate to the URL.

[Calls browser_init] -> Browser started
[Calls navigate with url="https://example.com"] -> Page loaded

User: Get all links on the page

AI: [Calls link_harvester] -> Found 15 links...

User: Download the main image

AI: [Calls file_downloader with url="..."] -> Downloaded to ./downloads/image.png
```

---

## LSP Server (Language Server Protocol)

This package also includes a full-featured **LSP Server** for IDE code intelligence when writing browser automation scripts.

### Quick Start LSP Server

```bash
# Start the LSP server
npm run lsp
```

### LSP Capabilities

| Feature | Description |
|---------|-------------|
| **Autocomplete** | Tool names, parameters, and enum values |
| **Hover** | Full documentation on hover |
| **Diagnostics** | Error & warning detection (missing browser_init, etc.) |
| **Snippets** | Code templates for common workflows |
| **Refactoring** | Quick fixes (add browser_init, try-catch, etc.) |
| **Simulation** | Workflow simulation in IDE |
| **Multi-language** | English & Hindi support |

### VS Code Setup

Create `.vscode/settings.json` in your project:

```json
{
  "braveRealBrowser.language": "en",
  "braveRealBrowser.maxDiagnostics": 100,
  "braveRealBrowser.enableSnippets": true,
  "braveRealBrowser.enableSimulation": true,
  "braveRealBrowser.enableRefactoring": true
}
```

### Diagnostic Features

The LSP detects common issues:

- Missing `browser_init()` before page operations
- Missing `navigate()` before content extraction
- Invalid selectors and URLs
- Missing required parameters
- Unclosed browser sessions
- Security issues (eval usage, etc.)

### Quick Fixes

When diagnostics are detected, quick fixes are offered:

- Add `browser_init()` at start
- Add `navigate()` before page tools
- Add `browser_close()` at end
- Wrap in try-catch
- Extract to function

---

## AI Core (Automatic Enhancement)

All 23 tools are automatically enhanced with AI capabilities. No configuration needed - AI features work transparently.

### How It Works

```
AI Agent calls any tool (e.g., click, type, find_element)
                │
                ▼
        ┌───────────────────┐
        │   AI Core Check   │
        │ (Lazy initialize) │
        └───────────────────┘
                │
                ▼
        Execute Original Tool
                │
        ┌───────┴───────┐
        │               │
     Success         Failed (selector not found)
        │               │
        ▼               ▼
   Return result    ┌─────────────────┐
   with _ai meta    │ AI Auto-Healing │
                    │ - Find alts     │
                    │ - Try healed    │
                    │ - Retry op      │
                    └─────────────────┘
                            │
                            ▼
                    Return healed result
```

### AI Features

| Feature | Description |
|---------|-------------|
| **Auto-Healing Selectors** | If a CSS selector fails, AI finds alternative selectors |
| **Smart Retry** | Failed operations are automatically retried with AI assistance |
| **Confidence Scoring** | AI provides confidence scores for healed selectors |
| **Caching** | Healed selectors are cached for performance |
| **Zero Configuration** | Works out of the box with all 23 tools |

### Example Response with AI Metadata

When AI heals a broken selector:

```json
{
  "success": true,
  "selector": "#new-login-btn",
  "clicked": true,
  "_ai": {
    "enabled": true,
    "healed": true,
    "originalSelector": "#old-login-button",
    "healedSelector": "#new-login-btn",
    "duration": 245
  }
}
```

### AI Modules

| Module | Description |
|--------|-------------|
| `AICore` | Central AI intelligence singleton |
| `ElementFinder` | Smart element finding with multiple strategies |
| `SelectorHealer` | Auto-fix broken CSS selectors |
| `PageAnalyzer` | Page structure analysis |
| `ActionParser` | Natural language command parsing |

### Programmatic Access

For advanced usage, you can access AI features directly:

```javascript
const { getAICore, aiEnhancedSelector } = require('./src/mcp/handlers');

// Get AI Core instance
const ai = getAICore();

// Use AI-enhanced selector finding
const { element, selector, healed } = await aiEnhancedSelector(page, '#old-selector', 'click');
```

---

## Unified Architecture

Both MCP and LSP servers share the same tool definitions:

```
src/
├── shared/
│   └── tools.js         # Single source of truth (28 tools)
├── ai/                  # AI Core Module (Auto-enhancement)
│   ├── index.js         # AI module exports
│   ├── core.js          # AI Core singleton
│   ├── element-finder.js# Smart element finding
│   ├── selector-healer.js# Auto-heal selectors
│   ├── page-analyzer.js # Page analysis
│   └── action-parser.js # NL command parsing
├── mcp/
│   ├── server.js        # MCP server for AI agents
│   └── handlers.js      # Tool implementations + AI integration
├── lsp/
│   ├── server.js        # LSP server for IDEs
│   └── capabilities/    # Autocomplete, hover, diagnostics, etc.
└── index.js             # Unified entry point
```

## Decoder Utilities (Built-in)

Powerful decoding capabilities for obfuscated content extraction:

| Decoder | Description | Use Cases |
|---------|-------------|-----------|
| **URL Decoder** | Multi-layer URL decoding | Obfuscated links, redirect chains |
| **Base64 Decoder** | Standard, URL-safe, padded variants | Encoded parameters, tokens |
| **AES Decryptor** | AES-256-CBC/ECB decryption | Encrypted streams, secure tokens |
| **tryAll()** | Attempts all decoders automatically | Unknown encoding detection |

### Usage Examples

```javascript
// Automatic decoder (via media_extractor)
{
  "action": "decode_url",
  "encodedData": "aHR0cHM6Ly9leGFtcGxlLmNvbQ==",
  "decoderType": "auto"  // Tries all decoders
}

// Manual decoding options
{
  "action": "decode_url",
  "encodedData": "U2Fsd2Fy...",
  "decoderType": "aes",
  "aesKey": "my-secret-key",
  "aesIV": "initialization-vec"
}
```

### Real-World Example: Movie Download Chain

```javascript
// 1. Navigate to movie page
{ "tool": "navigate", "params": { "url": "https://moviesdrive.surf/movies/dhurandhar-2025/" }}

// 2. Click download button to get redirect
{ "tool": "click", "params": { "selector": "#hubcloud-480p" }}

// 3. Trace full redirect chain
{ "tool": "redirect_tracer", "params": { "url": "current_page_url", "followJS": true }}

// 4. Extract and decode obfuscated links
{ "tool": "extract_data", "params": { 
  "type": "regex", 
  "pattern": "hubcloud\\.fans/drive/[^\"']+",
  "autoDecode": true  // Auto-decode found URLs
}}

// 5. Get direct download link from nested iframes
{ "tool": "media_extractor", "params": { 
  "action": "extract",
  "types": ["download"],
  "deep": true  // Scan nested iframes
}}
```

---

## 🔥 Deep Scraping Power Features

Advanced capabilities for bypassing obfuscation, intercepting hidden APIs, and decrypting encoded data.

### 1. Raw HTTP Mode (`get_content`)

Fetch raw HTML without JavaScript rendering — fast, lightweight, bypasses JS-based protections:

```javascript
{ "tool": "get_content", "params": { "format": "rawHttp" }}
// Returns: raw HTML source code via Node.js fetch (no browser needed)
```

### 2. Enhanced Deobfuscation (`extract_data`)

Decode obfuscated JavaScript from any page:

```javascript
{ "tool": "extract_data", "params": { "type": "deobfuscate" }}
```

| Capability | Pattern |
|---|---|
| String arrays | `var _0x3f0cd6 = [...]` |
| Hex strings | `'\x68\x74\x74\x70'` → `http` |
| Unicode escapes | `'\u0066\u0065\u0074\u0063\u0068'` → `fetch` |
| Eval unpacker | `eval(function(p,a,c,k,e,d){...})` |
| Webpack modules | `__webpack_require__`, `module.exports` |
| Terser mappings | `var a="fetch",b="POST"` |
| String concat | `"htt"+"ps://"+"api"` → `https://api` |
| Array rotation | `push(arr.shift())` patterns |

### 3. API Discovery (`extract_data`)

Find hidden API endpoints via static analysis + runtime interception:

```javascript
{ "tool": "extract_data", "params": { "type": "apiDiscovery" }}
// Returns: fetchEndpoints, xhrEndpoints, formActions, scriptSources, dynamicApis
```

### 4. Response Auto-Decryption (`extract_data`)

Auto-detect and decode encrypted/encoded data:

```javascript
// Auto-decrypt with key extraction from page scripts
{ "tool": "extract_data", "params": { "type": "decrypt", "encryptedData": "base64string..." }}

// With explicit AES key
{ "tool": "extract_data", "params": { "type": "decrypt", "encryptedData": "...", "aesKey": "secret" }}
```

| Decoder | Description |
|---|---|
| Base64 chain | Recursive decode up to 5 levels, auto-detect JSON |
| Hex | `68747470733a2f2f` → `https://` |
| URL decode | Multi-level `%2F%2F` → `//` |
| ROT13 | Caesar cipher (reports if result contains URLs) |
| AES-256-CBC | With user key or auto-extracted key from CryptoJS patterns |

### 5. Runtime API Interception (`network_recorder`)

Capture API calls from obfuscated/webpack code via pre-page-load monkey-patching:

```javascript
// Start recording (injects interceptors via evaluateOnNewDocument)
{ "tool": "network_recorder", "params": { "action": "start" }}

// Navigate to page...

// Get intercepted APIs (caught from monkey-patched fetch/XHR/sendBeacon)
{ "tool": "network_recorder", "params": { "action": "get_intercepted_apis" }}
// Returns: { type, url, method, headers, body, timestamp }
```

### 6. WebSocket Recording (`network_recorder`)

Capture WebSocket connections and messages:

```javascript
{ "tool": "network_recorder", "params": { "action": "get_websockets" }}
// Returns: { count, totalMessages, websockets: [{ id, url, status, messages }] }
```

### 7. XHR Body Capture (`network_recorder`)

Capture full request/response bodies for API calls:

```javascript
{ "tool": "network_recorder", "params": { "action": "start", "captureXhrBody": true }}
// Later:
{ "tool": "network_recorder", "params": { "action": "get_api_calls" }}
// Returns: requestBody, responseBody, responseJson for each API call
```

---

### Unified CLI

```bash
# List all tools (23 optimized)
node src/index.js --list

# Start MCP server (default)
node src/index.js mcp

# Start LSP server
node src/index.js lsp

# Show help
node src/index.js --help
```

### Tool Categories

| Category | Tools | Description |
|----------|-------|-------------|
| **Browser** | 3 | Browser lifecycle (init, close, cookies) |
| **Navigation** | 1 | Page navigation with smart retry |
| **Interaction** | 4 | User actions with AI healing (click, type, scroll, key press) |
| **Extraction** | 5 | Content scraping (get_content, extract_data, link_harvester, media_extractor, deep_analysis) |
| **Network** | 3 | Network operations (recorder, download, trace) |
| **Analysis** | 2 | Page analysis and form automation |
| **Utility** | 5 | Helpers (wait, progress, elements, cookies, JavaScript) |

---

## Monorepo Ecosystem

```
brave-real-browser-mcp-server (Top Level - MCP Server)
    └── brave-real-puppeteer-core (Stealth patches)
        └── brave-real-launcher (Browser launch)
            └── brave-real-blocker (Ad/Tracker blocking - Singleton)
```

### Package Details

| Package | Description | npm |
|---------|-------------|-----|
| `brave-real-browser-mcp-server` | MCP Server + Puppeteer integration | [![npm](https://img.shields.io/npm/v/brave-real-browser-mcp-server.svg)](https://www.npmjs.com/package/brave-real-browser-mcp-server) |
| `brave-real-puppeteer-core` | 50+ stealth patches for Puppeteer/Playwright | [![npm](https://img.shields.io/npm/v/brave-real-puppeteer-core.svg)](https://www.npmjs.com/package/brave-real-puppeteer-core) |
| `brave-real-launcher` | Brave Browser launcher with auto-detection | [![npm](https://img.shields.io/npm/v/brave-real-launcher.svg)](https://www.npmjs.com/package/brave-real-launcher) |
| `brave-real-blocker` | uBlock Origin-based ad/tracker blocker (45+ filter sources, 100/100 score) | [![npm](https://img.shields.io/npm/v/brave-real-blocker.svg)](https://www.npmjs.com/package/brave-real-blocker) |

### Ad Blocker Features (brave-real-blocker)

| Category | Details |
|----------|---------|
| **Filter Sources** | 45+ lists (uBlock Origin, EasyList, AdGuard, Anti-Adblock, etc.) |
| **Built-in Rules** | 200+ aggressive blocking rules |
| **Protection Layers** | 5 layers (Ad blocking, Stealth, Scriptlets, Cosmetic, Redirect) |
| **Test Score** | AdBlock Tester: **100/100** |
| **Auto-Update** | Filter lists cached 7 days, auto-refresh |
| **Singleton** | Single shared instance across ecosystem |

---

## Automation & CI/CD

### GitHub Actions Workflows

| Workflow | Schedule | Description |
|----------|----------|-------------|
| `auto-update-deps.yml` | Daily 6 AM UTC | Auto-updates all dependencies across all packages |
| `monorepo-publish.yml` | Daily 6 AM UTC + Push/PR | Version bump + NPM publish for all packages |

### Auto-Update Flow

```
Daily 6 AM UTC
      ↓
Check all packages for outdated dependencies
      ↓
┌─────────────────────────────────────────┐
│  brave-real-blocker                      │
│  brave-real-launcher                     │
│  brave-real-puppeteer-core               │
│  brave-real-browser-mcp-server           │
└─────────────────────────────────────────┘
      ↓
Update found? → Install → Build → Test → Commit → Push
      ↓
Trigger NPM Publish Workflow
      ↓
All packages published to NPM automatically
```

### Dependencies Auto-Updated

| Package | Auto-Updated Dependencies |
|---------|---------------------------|
| **blocker** | `@cliqz/adblocker-puppeteer`, `cross-fetch`, `fs-extra` |
| **launcher** | `which`, `escape-string-regexp`, `is-wsl` |
| **puppeteer-core** | `puppeteer-core`, `playwright-core`, `yargs` |
| **root** | `ghost-cursor`, `puppeteer-extra`, `puppeteer-extra-plugin-stealth` |

---

## Installation

```bash
npm install brave-real-browser-mcp-server
```

For Linux (required for headless mode):
```bash
sudo apt-get install xvfb
```

---

## Quick Start

### CommonJS

```javascript
const { connect } = require('brave-real-browser-mcp-server');

(async () => {
  const { browser, page, blocker } = await connect({
    headless: false,
    turnstile: true,  // Auto-solve Cloudflare
  });

  await page.goto('https://example.com');

  // Human-like click with ghost-cursor
  await page.realClick('#button');

  await browser.close();
})();
```

### ESM

```javascript
import { connect } from 'brave-real-browser-mcp-server';

const { browser, page, blocker } = await connect({
  headless: false,
  turnstile: true,
});

await page.goto('https://example.com');
await page.realClick('#button');
await browser.close();
```

---

## Connect Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `headless` | `boolean \| 'new'` | `false` | Headless mode (also respects `.env` HEADLESS variable) |
| `args` | `string[]` | `[]` | Additional Chrome flags |
| `customConfig` | `object` | `{}` | Brave launcher options |
| `proxy` | `ProxyOptions` | `{}` | Proxy configuration |
| `turnstile` | `boolean` | `false` | Auto-solve Cloudflare Turnstile |
| `connectOption` | `object` | `{}` | Puppeteer connect options |
| `disableXvfb` | `boolean` | `false` | Disable virtual display (Linux) |
| `plugins` | `array` | `[]` | Puppeteer-extra plugins |
| `ignoreAllFlags` | `boolean` | `false` | Override all default flags |
| `enableBlocker` | `boolean` | `true` | Enable ad/tracker blocker |
| `blockerOptions` | `BlockerOptions` | `{}` | Blocker configuration |

### BlockerOptions

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enableAdBlocking` | `boolean` | `true` | Network request blocking (Ads/Trackers) |
| `enableStealth` | `boolean` | `true` | Stealth evasions (Navigator, WebGL, etc.) |
| `enableCosmeticFiltering` | `boolean` | `true` | Element hiding (CSS-based) |
| `enableRedirectBlocking` | `boolean` | `true` | Popup and redirect blocking |
| `enableScriptlets` | `boolean` | `true` | Scriptlet injection for anti-adblock |
| `customFiltersPath` | `string` | `null` | Path to custom filter list file |
| `enableFilterAutoUpdate` | `boolean` | `true` | Auto-update uBlock Origin filters |

### ProxyOptions

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `host` | `string` | Yes | Proxy host |
| `port` | `number` | Yes | Proxy port |
| `username` | `string` | No | Proxy username |
| `password` | `string` | No | Proxy password |

---

## Usage Examples

### Proxy Configuration

```javascript
const { browser, page } = await connect({
  proxy: {
    host: '127.0.0.1',
    port: 8080,
    username: 'user',     // Optional
    password: 'pass'      // Optional
  }
});
```

### Custom Brave Path

```javascript
const { browser, page } = await connect({
  customConfig: {
    bravePath: 'C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe',
    userDataDir: './my-profile'
  }
});
```

### Disable Blocker

```javascript
const { browser, page } = await connect({
  enableBlocker: false,  // Disable all blocking
});
```

### Custom Blocker Options

```javascript
const { browser, page, blocker } = await connect({
  blockerOptions: {
    enableAdBlocking: true,
    enableStealth: true,
    enableCosmeticFiltering: true,
    enableRedirectBlocking: true,
    enableScriptlets: true,
    customFiltersPath: './my-filters.txt',
    enableFilterAutoUpdate: true,
  }
});
```

### Real Cursor (Ghost-Cursor)

Built-in ghost-cursor for human-like mouse movements:

```javascript
const { browser, page } = await connect();

// Human-like click
await page.realClick('#submit-button');

// Full cursor control
await page.realCursor.move('#element');
await page.realCursor.click('#button');
```

### Turnstile Auto-Solver

Automatically solves Cloudflare Turnstile challenges:

```javascript
const { browser, page } = await connect({
  turnstile: true
});

await page.goto('https://site-with-turnstile.com');
// Turnstile is automatically solved!
```

### Puppeteer-Extra Plugins

```javascript
const clickAndWait = require('puppeteer-extra-plugin-click-and-wait')();

const { browser, page } = await connect({
  plugins: [clickAndWait]
});
```

### Singleton Blocker Usage

The blocker is a singleton - only one instance is created and shared:

```javascript
// From brave-real-blocker package
import { 
  getBraveBlockerSingleton, 
  initBraveBlockerSingleton,
  isBraveBlockerInitialized 
} from 'brave-real-blocker/singleton';

// Initialize once at startup
const blocker = await initBraveBlockerSingleton({
  enableAdBlocking: true,
  enableStealth: true,
});

// Get the same instance anywhere else
const sameBlocker = getBraveBlockerSingleton();
console.log(blocker === sameBlocker); // true
```

---

## Commands

### Root Level

| Command | Description |
|---------|-------------|
| `npm start` | Start unified server (MCP by default) |
| `npm run dev` | Start MCP server |
| `npm run mcp` | Start MCP server (alias) |
| `npm run mcp:verbose` | Start MCP server with tool details |
| `npm run lsp` | Start LSP server for IDE intelligence |
| `npm run lsp:tcp` | Start LSP server on TCP port 7777 |
| `npm run list` | List all 23 optimized tools with categories |
| `npm install` | Install dependencies + auto-build workspaces + Brave check |
| `npm test` | Run all tests (CJS + ESM) |
| `npm run cjs_test` | Run CommonJS tests only |
| `npm run esm_test` | Run ESM tests only |
| `npm run build` | Build root package (pre-built lib/) |
| `npm run build:all` | Build all workspace packages (blocker, launcher, puppeteer-core) |
| `npm run clean:all` | Clean all workspace build outputs |
| `npm run test:all` | Run tests for all workspace packages |
| `npm run update-deps` | Manually check for dependency updates |
| `npm run upstream-patch` | Update to latest upstream (puppeteer-core, playwright-core) |
| `npm run lint` | Run linter |

> **Note:** `npm install` automatically runs `npm run build:all` to compile TypeScript packages (brave-real-blocker, brave-real-launcher) before the auto-update check. This ensures the browser tools work immediately after installation.

### Workspace Scripts

| Command | Description |
|---------|-------------|
| `node scripts/prepare-publish.js` | Sync dependency versions before publish |
| `node scripts/restore-workspace.js` | Verify workspace linking |
| `node scripts/version-bump.js patch` | Increment all versions (patch/minor/major) |

### Package: brave-real-puppeteer-core

| Command | Description |
|---------|-------------|
| `npm run patch-puppeteer` | Apply stealth patches to puppeteer-core |
| `npm run patch-playwright` | Apply stealth patches to playwright-core |
| `npm run patch-both` | Apply patches to both engines |
| `npm run setup-puppeteer` | Full puppeteer setup with patches |
| `npm run test-bot-detector` | Run bot detection tests |
| `npm run ai-agent` | Run AI agent tests |

### Package: brave-real-launcher

| Command | Description |
|---------|-------------|
| `npm run build` | Build the launcher |
| `npm run test:detection` | Test Brave browser detection |

### Package: brave-real-blocker

| Command | Description |
|---------|-------------|
| `npm run build` | Build the blocker |
| `npm run visual-test` | Run visual blocking tests |

---

## Testing

```bash
# Run all 7 bot detector tests
npm test

# Run CJS tests only
npm run cjs_test

# Run ESM tests only
npm run esm_test
```

### Test Coverage

All 7 bot detection tests pass:

| Test | Description | Status |
|------|-------------|--------|
| DrissionPage Detector | Chinese bot detector | ✅ Pass |
| Sannysoft WebDriver | WebDriver detection | ✅ Pass |
| Cloudflare WAF | Full page challenge | ✅ Pass |
| Cloudflare Turnstile | CAPTCHA widget | ✅ Pass |
| FingerprintJS | Browser fingerprinting | ✅ Pass |
| Datadome | Anti-bot detection | ✅ Pass |
| reCAPTCHA v3 | Google score test (0.7+) | ✅ Pass |

---

## Docker

### Build and Run

```bash
# Build the image
docker build -t brave-real-browser-mcp-server .

# Run tests in container
docker run brave-real-browser-mcp-server

# Run with custom command
docker run brave-real-browser-mcp-server npm run esm_test
```

### Docker Features

- Multi-stage build for smaller image size
- Node.js 20 LTS (pinned version)
- Non-root user for security
- Health check included
- Headless mode enabled by default

---

## Project Structure

```
brave-real-browser-mcp-server/
├── src/
│   ├── shared/
│   │   └── tools.js              # Single source of truth (23 optimized tools)
│   ├── mcp/                      # MCP Server
│   │   ├── index.js              # Entry point with startup logs
│   │   ├── server.js             # MCP server with STDIO transport
│   │   ├── handlers.js           # 23 optimized tool implementations + decoders
│   │   └── tools.js              # Re-export from shared
│   ├── lsp/                      # LSP Server
│   │   ├── server.js             # LSP server for IDE intelligence
│   │   └── capabilities/         # Autocomplete, hover, diagnostics
│   └── ai/                       # AI Core Module
│       ├── core.js               # AI Core singleton
│       ├── element-finder.js     # Smart element finding
│       ├── selector-healer.js    # Auto-heal broken selectors
│       ├── page-analyzer.js      # Page analysis
│       └── action-parser.js      # Natural language parsing
├── lib/
│   ├── cjs/                      # CommonJS build
│   └── esm/                      # ESM build
├── packages/
│   ├── brave-real-blocker/       # Ad/Tracker blocker (singleton)
│   │   ├── src/
│   │   │   ├── brave-blocker.ts
│   │   │   ├── singleton.ts      # Singleton pattern
│   │   │   ├── stealth.ts
│   │   │   ├── cosmetic.ts
│   │   │   └── scriptlets.ts
│   │   └── package.json
│   ├── brave-real-launcher/      # Browser launcher
│   │   └── package.json
│   └── brave-real-puppeteer-core/  # Stealth patches
│       └── package.json
├── scripts/
│   ├── prepare-publish.js        # Sync versions before publish
│   ├── restore-workspace.js      # Verify workspace
│   └── version-bump.js           # Version management
├── .github/
│   └── workflows/
│       ├── auto-update-deps.yml      # Daily dependency updates
│       └── monorepo-publish.yml      # Auto-publish to NPM
├── test/
│   ├── cjs/                      # CJS tests
│   └── esm/                      # ESM tests
├── Dockerfile
├── typings.d.ts
└── package.json                  # Root with workspaces
```

---

## Environment Variables

Create a `.env` file in your project root:

```env
# Headless mode (true = headless, false = GUI)
HEADLESS=true
```

The library automatically reads `.env` files and respects the `HEADLESS` variable.

---

## Re-exports

Access brave-real-launcher features directly:

```javascript
const { 
  connect,
  launcher,      // brave-real-launcher module
  launch,        // Direct browser launch
  killAll,       // Kill all browsers
  getBravePath,  // Get Brave path
  DEFAULT_FLAGS  // Default browser flags
} = require('brave-real-browser-mcp-server');
```

---

## TypeScript

Full TypeScript support with type definitions:

```typescript
import { connect, Options, ConnectResult } from 'brave-real-browser-mcp-server';

const options: Options = {
  headless: false,
  turnstile: true,
  enableBlocker: true,
  blockerOptions: {
    enableAdBlocking: true,
    enableStealth: true,
  }
};

const { browser, page, blocker }: ConnectResult = await connect(options);
```

---

## Real-World Examples

### Example 1: Complete Movie Download Chain

**Use Case:** Extract download links from movie streaming sites with multi-layer redirects

```javascript
// Step 1: Initialize browser with all protections
{
  "tool": "browser_init",
  "params": {
    "headless": false,
    "turnstile": true,
    "enableBlocker": true
  }
}

// Step 2: Navigate to movie page
{
  "tool": "navigate",
  "params": {
    "url": "https://moviesdrive.surf/movies/dhurandhar-2025/",
    "waitUntil": "networkidle2",
    "smartWait": true
  }
}

// Step 3: Find and click quality selector
{
  "tool": "click",
  "params": {
    "selector": "a[href*='hubcloud']",
    "humanLike": true,
    "aiHeal": true
  }
}

// Step 4: Wait for redirect chain to complete
{
  "tool": "wait",
  "params": {
    "type": "smart",
    "value": "2000",
    "aiOptimize": true
  }
}

// Step 5: Trace complete redirect chain
{
  "tool": "redirect_tracer",
  "params": {
    "url": "current",
    "followJS": true,
    "followMeta": true,
    "decodeURLs": true
  }
}

// Step 6: Extract obfuscated download links
{
  "tool": "extract_data",
  "params": {
    "type": "regex",
    "pattern": "https?://[^\"'<>\\s]+\\.(mkv|mp4|avi)",
    "autoDecode": true,
    "source": "all"
  }
}

// Step 7: Extract from nested iframes if present
{
  "tool": "media_extractor",
  "params": {
    "action": "extract",
    "types": ["download", "video"],
    "deep": true,
    "aiOptimize": true
  }
}

// Step 8: Download the file
{
  "tool": "file_downloader",
  "params": {
    "url": "extracted_download_link",
    "directory": "./downloads",
    "resume": true
  }
}

// Step 9: Cleanup
{
  "tool": "browser_close",
  "params": {
    "saveSession": false
  }
}
```

### Example 2: TV Show Episode Batch Extraction

**Use Case:** Extract all episodes from a TV show season

```javascript
// Navigate to TV show page
{
  "tool": "navigate",
  "params": { "url": "https://multimovies.gripe/tvshows/sacred-games/" }
}

// Extract all episode links
{
  "tool": "extract_data",
  "params": {
    "type": "structured",
    "selector": ".episode-item a",
    "extractAttributes": true
  }
}

// For each episode, extract streaming sources
{
  "tool": "media_extractor",
  "params": {
    "action": "batch_extract",
    "urls": ["episode1_url", "episode2_url", "..."],
    "types": ["hls", "dash", "download"],
    "deep": true
  }
}

// Get network recorded streams
{
  "tool": "network_recorder",
  "params": {
    "action": "get_media",
    "aiDetectStreams": true
  }
}
```

### Example 3: Advanced Link Harvesting with Decoding

**Use Case:** Find hidden/obfuscated links on complex pages

```javascript
// Navigate to target
{
  "tool": "navigate",
  "params": { "url": "https://example-site.com/protected-content/" }
}

// Harvest all links including hidden/encoded ones
{
  "tool": "link_harvester",
  "params": {
    "includeHidden": true,
    "autoDecode": true,
    "detectObfuscation": true,
    "searchIframes": true,
    "types": ["all"]
  }
}

// Decode any obfuscated links found
{
  "tool": "media_extractor",
  "params": {
    "action": "decode_url",
    "encodedData": "aHR0cHM6Ly9leGFtcGxlLmNvbQ==",
    "decoderType": "auto"
  }
}
```

### Example 4: Form Automation with AI Detection

**Use Case:** Automatically fill and submit complex forms

```javascript
// Navigate to form page
{
  "tool": "navigate",
  "params": { "url": "https://example.com/contact-form/" }
}

// AI-powered form detection and filling
{
  "tool": "form_automator",
  "params": {
    "data": {
      "name": "John Doe",
      "email": "john@example.com",
      "message": "Hello, this is a test message",
      "country": "United States"
    },
    "aiMatch": true,
    "aiValidate": true,
    "humanLike": true,
    "captcha": true,
    "submit": true
  }
}
```

### Example 5: Streaming Media Extraction

**Use Case:** Extract video streams from JWPlayer, VideoJS, custom players

```javascript
// Navigate to video page
{
  "tool": "navigate",
  "params": { 
    "url": "https://multimovies.gripe/movies/movie-name/",
    "waitUntil": "networkidle0"
  }
}

// Start recording network
{
  "tool": "network_recorder",
  "params": { "action": "start", "aiDetectStreams": true }
}

// Extract all media types
{
  "tool": "media_extractor",
  "params": {
    "action": "extract",
    "types": ["hls", "dash", "video", "audio", "download"],
    "quality": "all",
    "deep": true
  }
}

// Get all recorded streams
{
  "tool": "network_recorder",
  "params": { 
    "action": "get_media",
    "filter": { "type": "m3u8" }
  }
}

// Control player if needed
{
  "tool": "media_extractor",
  "params": {
    "action": "player_control",
    "playerAction": "sources"
  }
}
```

---

## FAQ

### Why can't I pass reCAPTCHA v3?

When there's no Google session, reCAPTCHA identifies you as a bot. This is a known limitation - log into a Google account first.

### page.setViewport not working?

Set `defaultViewport` in connectOption:

```javascript
const { browser, page } = await connect({
  connectOption: { defaultViewport: null }
});
```

### Mouse positions don't match?

This is automatically patched. Use `page.realClick()` for best results.

### How to disable ad blocker?

```javascript
const { browser, page } = await connect({
  enableBlocker: false
});
```

### How to use custom filter lists?

```javascript
const { browser, page } = await connect({
  blockerOptions: {
    customFiltersPath: './my-custom-filters.txt'
  }
});
```

### How does the singleton blocker work?

The blocker uses a global Symbol-based singleton pattern. No matter how many times you import it, the same instance is shared across the entire Node.js process, preventing duplicate filter loading and saving memory.

### How does npm workspaces linking work?

When packages are listed in the root `package.json` `workspaces` array, npm automatically creates symlinks to local packages instead of downloading from npm registry. This enables seamless local development.

---

## Requirements

- Node.js >= 18.0.0
- Brave Browser (auto-installed if missing)
- Linux: xvfb package for headless mode

---

## License

ISC - See [LICENSE](https://github.com/codeiva4u/Brave-Real-Browser-Mcp-Server/blob/main/LICENSE.md)

---

## Credits

- **rebrowser** - Runtime patches
- **ghost-cursor** - Human-like mouse movements
- **brave-real-launcher** - Brave Browser launcher
- **@cliqz/adblocker-puppeteer** - Ad blocking engine
- **uBlock Origin** - Filter lists

---

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## Support

- GitHub Issues: [Report bugs](https://github.com/codeiva4u/Brave-Real-Browser-Mcp-Server/issues)
- Documentation: [README.md](https://github.com/codeiva4u/Brave-Real-Browser-Mcp-Server#readme)

---

## Changelog

See [Releases](https://github.com/codeiva4u/Brave-Real-Browser-Mcp-Server/releases) for version history and changes.