@_nazmiforreal/agent-browser-mcp 0.2.0

package/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "agent-browser": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "D:/agent-browser-mcp/dist/index.js"
+      ],
+      "env": {}
+    }
+  }
+}

package/AGENTS.md

@@ -0,0 +1,100 @@
+# AGENTS.md
+
+## Progress: Full CLI-to-MCP Tool Coverage + Browser Manager
+
+### Architecture
+- `src/tools/executor.ts` — Maps MCP tool names to `agent-browser` CLI args + auto-injects `--executable-path`
+- `src/tools/browser.ts` — Registers all MCP tools via `@modelcontextprotocol/sdk`
+- `src/cli.ts` — CLI entry point with browser management commands
+- `src/browsers/registry.ts` — Browser definitions (name, install method, binary paths)
+- `src/browsers/installer.ts` — Install logic per browser
+- `src/browsers/discover.ts` — Auto-discover installed browsers
+- `src/browsers/env.ts` — `.env` loader for `BROWSER_PATH_*` and `ACTIVE_BROWSER`
+
+### Browser Manager (NEW)
+
+| Command | Description |
+|---------|-------------|
+| `agent-browser-mcp -i <browser>` | Install a browser by name |
+| `agent-browser-mcp --list` | List all browsers and their status |
+| `agent-browser-mcp --select <browser>` | Set active browser (writes to `.env`) |
+| `agent-browser-mcp --discover` | Show auto-discovered browsers |
+| `agent-browser-mcp --env` | Show `.env` file path |
+| `agent-browser-mcp` | Start MCP server with active browser |
+
+### Supported Browsers
+
+| Name | Install Method | Binary Paths |
+|------|----------------|--------------|
+| `chromium` | `ppa:xtradeb/apps` + apt | `/usr/bin/chromium` |
+| `cloakbrowser` | npm global + binary download | `~/.cloakbrowser/chromium-*/chrome` |
+| `chrome` | `agent-browser install` | `~/.agent-browser/browsers/chrome-*/chrome` |
+| `firefox` | apt | `/usr/bin/firefox` |
+| `brave` | apt | `/usr/bin/brave-browser` |
+| `edge` | Microsoft repo + apt | `/usr/bin/microsoft-edge-stable` |
+
+### .env Configuration (`~/.agent-browser-mcp/.env`)
+```env
+ACTIVE_BROWSER=cloakbrowser
+BROWSER_PATH_CHROMIUM=/usr/bin/chromium
+BROWSER_PATH_CLOAKBROWSER=/home/user/.cloakbrowser/chromium-146.0.7680.177.5/chrome
+```
+
+### Auto-Discovery Flow
+1. Check `.env` for `ACTIVE_BROWSER` and `BROWSER_PATH_*`
+2. If not set, scan known binary paths for each browser
+3. First found becomes default
+4. `--executable-path` injected into all `agent-browser` commands automatically
+
+### Tool Coverage (target: 100% of agent-browser CLI commands)
+
+All CLI commands are covered by **66 composite MCP tools**. Multiple related CLI commands are grouped into a single MCP tool with an `action`/`property`/`mode` parameter to keep the surface area manageable for AI agents.
+
+| Category | CLI Commands | MCP Tools (66 total) | Status |
+|----------|-------------|----------------------|--------|
+| Navigation | open, back, forward, reload, pushstate | `browser_navigate`, `browser_go_back`, `browser_go_forward`, `browser_reload`, `browser_pushstate` | ✅ |
+| Core Interaction | click, dblclick, fill, type, hover, focus, check, uncheck, select, drag, upload, download | `browser_click`, `browser_dblclick`, `browser_fill`, `browser_type`, `browser_hover`, `browser_focus`, `browser_check`, `browser_uncheck`, `browser_select`, `browser_drag`, `browser_upload`, `browser_download` | ✅ |
+| Keyboard | press, keydown, keyup, keyboard type, keyboard inserttext | `browser_keyboard` (action: press\|keydown\|keyup\|type\|inserttext) | ✅ |
+| Mouse | mouse move, mouse down, mouse up, mouse wheel | `browser_mouse` (action: move\|down\|up\|wheel) | ✅ |
+| Scroll | scroll, scrollintoview | `browser_scroll`, `browser_scroll_into_view` | ✅ |
+| Get Info | get text, get html, get value, get attr, get url, get title, get cdp-url, get count, get box, get styles | `browser_get` (property: text\|html\|value\|attr\|url\|title\|cdp-url\|count\|box\|styles) | ✅ |
+| State Checks | is visible, is enabled, is checked | `browser_is` (state: visible\|enabled\|checked) | ✅ |
+| Find (Locators) | find role, find text, find label, find placeholder, find alt, find title, find testid, find first, find last, find nth | `browser_find` (by: role\|text\|label\|placeholder\|alt\|title\|testid\|first\|last\|nth) | ✅ |
+| Wait | wait (selector\|ms\|--url\|--load\|--fn\|--text\|--download) | `browser_wait` (mode: selector\|timeout\|url\|load-state\|function\|text\|download) | ✅ |
+| Screenshot/PDF | screenshot, pdf | `browser_screenshot`, `browser_pdf` | ✅ |
+| Snapshot | snapshot (-i, -c, -C, -u, -d, -s) | `browser_snapshot` | ✅ |
+| Eval | eval, eval -b, eval --stdin | `browser_evaluate`, `browser_evaluate_base64` | ✅ |
+| Batch | batch [--bail] | `browser_batch` | ✅ |
+| Clipboard | clipboard read/write/copy/paste | `browser_clipboard` (action: read\|write\|copy\|paste) | ✅ |
+| Settings | set viewport, set device, set geo, set offline, set headers, set credentials, set media | `browser_settings` (setting: viewport\|device\|geo\|offline\|headers\|credentials\|media) | ✅ |
+| Cookies | cookies get, cookies set, cookies set --curl, cookies clear | `browser_cookies` (action: get\|set\|set-file\|clear) | ✅ |
+| Storage | storage local/session get/set/clear | `browser_storage` (area: local\|session, action: get\|set\|clear) | ✅ |
+| Network | network route, unroute, requests, request, har start/stop | `browser_network` (action: route\|unroute\|requests\|request-detail\|har-start\|har-stop) | ✅ |
+| Tabs | tab new, tab list, tab close, tab \<ref\>, window new | `browser_tab` (action: list\|new\|close\|switch\|new-window) | ✅ |
+| Frames | frame \<selector\>, frame main | `browser_frame` (action: switch\|main) | ✅ |
+| Dialogs | dialog accept, dialog dismiss, dialog status | `browser_dialog` (action: accept\|dismiss\|status) | ✅ |
+| Debug | trace start/stop, profiler start/stop, console, errors, highlight, inspect | `browser_trace`, `browser_profiler`, `browser_console`, `browser_errors`, `browser_highlight`, `browser_inspect` | ✅ |
+| State Mgmt | state save/load/list/show/rename/clear/clean | `browser_state` (action: save\|load\|list\|show\|rename\|clear\|clean) | ✅ |
+| Recording | record start/stop/restart | `browser_record` (action: start\|stop\|restart) | ✅ |
+| Auth Vault | auth save/login/list/delete/show | `browser_auth` (action: save\|login\|list\|delete\|show) | ✅ |
+| Diff | diff snapshot, diff screenshot, diff url | `browser_diff` (mode: snapshot\|screenshot\|url) | ✅ |
+| React | react tree, react inspect, react renders start/stop, react suspense | `browser_react` (action: tree\|inspect\|renders-start\|renders-stop\|suspense) | ✅ |
+| Vitals | vitals | `browser_vitals` | ✅ |
+| iOS | device list, tap, swipe | `browser_device_list`, `browser_tap`, `browser_swipe` | ✅ |
+| Session | session, session list | `browser_session` (action: show\|list) | ✅ |
+| Streaming | stream enable/disable/status | `browser_stream` (action: enable\|disable\|status) | ✅ |
+| Dashboard | dashboard start/stop | `browser_dashboard` (action: start\|stop) | ✅ |
+| Init Scripts | removeinitscript | `browser_remove_init_script` | ✅ |
+| Confirm/Deny | confirm, deny | `browser_confirm`, `browser_deny` | ✅ |
+| Connect | connect \<port\|url\> | `browser_connect` | ✅ |
+| Session Mgmt | close | `browser_close` | ✅ |
+| **Browser Manager** | list, discover, install, select | `browser_manager` (action: list\|discover\|install\|select) | ✅ |
+
+### Total: 63 MCP tools covering 35 CLI command categories + 1 browser manager tool
+
+All 153 individual CLI subcommands are reachable via `action`/`property`/`mode`/`state`/`by` parameters within these 62 composite tools.
+
+### Commands Not Exposed as MCP Tools
+- `install`, `upgrade`, `doctor`, `profiles`, `skills`, `chat` — Setup/CLI-only operations
+- `close --all` — Daemon-wide operation
+- `addinitscript` — No CLI command exists (daemon-only JSON action; use `--init-script` flag at daemon start)

package/README.md

@@ -0,0 +1,502 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="">
+    <img alt="Agent Browser MCP" src="" width="140">
+  </picture>
+</p>
+
+<h1 align="center">Agent Browser MCP</h1>
+
+<p align="center">
+  <strong>The MCP-native bridge that gives AI agents full control over a real browser — with a built-in browser manager.</strong>
+  <br>
+  62 composite tools · 153 CLI subcommands · 6 browsers supported · Zero configuration · MCP-standard
+</p>
+
+<p align="center">
+  <a href="#"><img alt="Release" src="https://img.shields.io/github/v/release/user/agent-browser-mcp?style=flat-square&color=6C5CE7"></a>
+  <a href="#"><img alt="Build" src="https://img.shields.io/github/actions/workflow/status/user/agent-browser-mcp/ci.yml?style=flat-square&color=00CEC9"></a>
+  <a href="#"><img alt="Coverage" src="https://img.shields.io/codecov/c/github/user/agent-browser-mcp?style=flat-square&color=00CEC9"></a>
+  <a href="#"><img alt="npm" src="https://img.shields.io/npm/v/agent-browser-mcp?style=flat-square&color=6C5CE7"></a>
+  <a href="#"><img alt="Downloads" src="https://img.shields.io/npm/dm/agent-browser-mcp?style=flat-square&color=FD79A8"></a>
+  <a href="#"><img alt="License" src="https://img.shields.io/badge/License-MIT-6C5CE7?style=flat-square"></a>
+  <a href="#"><img alt="Node" src="https://img.shields.io/badge/node-%3E%3D18-636E72?style=flat-square"></a>
+</p>
+
+<p align="center">
+  <a href="#overview">Overview</a> ·
+  <a href="#features">Features</a> ·
+  <a href="#architecture">Architecture</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#browser-manager">Browser Manager</a> ·
+  <a href="#tool-coverage">Tools</a> ·
+  <a href="#comparison">Comparison</a> ·
+  <a href="#faq">FAQ</a> ·
+  <a href="#changelog">Changelog</a>
+</p>
+
+<br>
+
+> **For AI engineers and developers who need to automate browser tasks without writing brittle Playwright scripts.**  
+> Agent Browser MCP is an MCP server that translates MCP tool calls into `agent-browser` CLI commands.  
+> Unlike custom browser bridges or raw Playwright scripts, it gives any MCP-compatible LLM **62 pre-built tools** covering navigation, interaction, extraction, debugging, and state management — all through a single stdio connection.
+
+```bash
+npx agent-browser-mcp
+```
+
+<br>
+
+---
+
+## Use Cases
+
+<details>
+<summary><strong>AI Engineers</strong> — give agents autonomous browser control</summary>
+
+Equip Claude, Copilot, or any MCP client with the ability to navigate pages, fill forms, extract data, and manage sessions — all through natural language. No Playwright code required. Install the browser you need with `agent-browser-mcp -i <browser>`.
+
+</details>
+
+<details>
+<summary><strong>QA Engineers</strong> — automate visual regression and functional tests</summary>
+
+Use screenshot diffing, accessibility snapshots, and console/network monitors to validate page behaviour across sessions. Save and reload state for reproducible test scenarios.
+
+</details>
+
+<details>
+<summary><strong>Data Engineers</strong> — scrape and extract at scale</summary>
+
+Batch commands, multi-tab navigation, and full DOM extraction (text, HTML, attributes, styles) let agents collect structured data from any web page programmatically.
+
+</details>
+
+<details>
+<summary><strong>Platform Teams</strong> — embed browser automation into MCP workflows</summary>
+
+Expose browser capabilities as composable MCP tools alongside your own custom tools. Isolate sessions per user or per task with independent cookies, storage, and state.
+
+</details>
+
+<br>
+
+---
+
+## Overview
+
+Agent Browser MCP eliminates the gap between LLM reasoning and browser automation. Instead of wiring up custom browser bridges or maintaining brittle Playwright scripts, plug this MCP server into any MCP-compatible client and get:
+
+| Area | What you can do |
+|:-----|:----------------|
+| **Browser Manager** | Install, select, and auto-discover browsers from CLI |
+| **Navigation** | Open URLs, back, forward, reload, pushState |
+| **Interaction** | Click, fill, type, select, drag, upload, download, hover, focus |
+| **Extraction** | Text, HTML, attributes, screenshots, PDFs, accessibility snapshots |
+| **State** | Cookies, localStorage, sessionStorage, auth vaults, session save/load |
+| **Debugging** | Console logs, network requests, traces, profiles, HAR recordings |
+| **Advanced** | Iframe switching, dialog handling, React inspection, visual diffing |
+
+> [!TIP]
+> All commands run through [Vercel's agent-browser](https://github.com/vercel/agent-browser) CLI, which manages its own Chromium via Playwright — no separate browser install needed.
+
+<br>
+
+---
+
+## Features
+
+| Capability | Description |
+|:-----------|:------------|
+| **63 Composite Tools** | 153 CLI subcommands + 1 browser manager tool across 36 categories |
+| **Browser Manager** | Install, select, and auto-discover browsers from CLI or MCP tools |
+| **Multi-Session Isolation** | Independent browser sessions with isolated cookies, storage, and state per session |
+| **Full DOM Access** | Extract text, HTML, attributes, bounding boxes, computed styles, and element counts |
+| **Visual Output** | Screenshots (full-page + annotated), PDF generation, accessibility snapshots |
+| **Network Observability** | Route interception, request logging, HAR capture with start/stop controls |
+| **State Persistence** | Save and load sessions, cookie jars, auth vaults with named profiles |
+| **Debug Toolkit** | Chrome DevTools traces, CPU profiles, console monitors, error collectors |
+| **Cross-Framework** | React component tree inspection, renders tracking, suspense boundary detection |
+| **Visual Regression** | Snapshot diff, screenshot diff, and URL-to-URL diff with configurable thresholds |
+| **Zero Config** | Install once, connect any MCP client, start automating — no configuration files |
+
+<br>
+
+---
+
+## Architecture
+
+```
++-------------------------------------------------------------------+
+|                 MCP Client (Claude, Copilot, ...)                 |
++-------------------------------------------------------------------+
+|                           | stdio transport                       |
+|                           v                                       |
+|  +-------------------------------------------------------------+  |
+|  |                  Agent Browser MCP Server                   |  |
+|  |  +----------------------+  +-----------------------------+  |  |
+|  |  |     browser.ts       |  |         executor.ts         |  |  |
+|  |  |  62 tool handlers    |  |  COMMAND_MAP + arg builder  |  |  |
+|  |  |     zod schemas      |  |   + --executable-path inject|  |  |
+|  |  +----------------------+  +-----------------------------+  |  |
+|  |  +----------------------+                                   |  |
+|  |  |     cli.ts           |  Browser Manager                  |  |
+|  |  |  -i, --list, --select|  Install/Select/Discover browsers |  |
+|  |  +----------------------+                                   |  |
+|  +-------------------------------------------------------------+  |
+|                           |                                       |
+|                           v                                       |
+|  +-------------------------------------------------------------+  |
+|  |                    agent-browser CLI                        |  |
+|  |  Uses --executable-path to point to selected browser        |  |
+|  +-------------------------------------------------------------+  |
+|                           |                                       |
+|                           v                                       |
+|  +-------------------------------------------------------------+  |
+|  |  Chromium / CloakBrowser / Firefox / Brave / Edge / Chrome  |  |
+|  +-------------------------------------------------------------+  |
++-------------------------------------------------------------------+
+```
+
+<br>
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- **Node.js** >= 18
+
+### Install
+
+```bash
+npm install -g agent-browser-mcp
+
+# Or run directly without install
+npx agent-browser-mcp
+```
+
+### Install a Browser
+
+```bash
+# Install Chromium from xtradeb PPA
+agent-browser-mcp -i chromium
+
+# Install stealth CloakBrowser (58 C++ fingerprint patches)
+agent-browser-mcp -i cloakbrowser
+
+# Install Google Chrome
+agent-browser-mcp -i chrome
+
+# Install Firefox
+agent-browser-mcp -i firefox
+```
+
+### Select Active Browser
+
+```bash
+# Set CloakBrowser as default
+agent-browser-mcp --select cloakbrowser
+
+# List all browsers
+agent-browser-mcp --list
+
+# Show auto-discovered browsers
+agent-browser-mcp --discover
+```
+
+### Configure MCP Client
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["agent-browser-mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+**VS Code / GitHub Copilot** (`.vscode/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["agent-browser-mcp"]
+    }
+  }
+}
+```
+
+### Quick Commands
+
+```bash
+# Navigate to a URL
+browser_navigate url=https://example.com
+
+# Take a screenshot
+browser_screenshot
+
+# Click a button
+browser_click selector="#submit"
+
+# Extract all text from an element
+browser_get property=text selector="article"
+
+# Run multiple actions in batch
+browser_batch actions=[{"command":"click","selector":"#login"}]
+```
+
+> [!WARNING]
+> The `agent-browser` CLI must be installed separately and available in your PATH. Set `AGENT_BROWSER_PATH` to use a non-default binary location.
+
+<br>
+
+---
+
+## Browser Manager
+
+Install, select, and auto-discover browsers from the CLI. The active browser is automatically injected into all `agent-browser` commands via `--executable-path`.
+
+### Supported Browsers
+
+| Name | Install Command | Description |
+|:-----|:----------------|:------------|
+| `chromium` | `agent-browser-mcp -i chromium` | Open-source Chromium from xtradeb PPA |
+| `cloakbrowser` | `agent-browser-mcp -i cloakbrowser` | Stealth Chromium with 58 C++ fingerprint patches |
+| `chrome` | `agent-browser-mcp -i chrome` | Google Chrome (via agent-browser) |
+| `firefox` | `agent-browser-mcp -i firefox` | Mozilla Firefox |
+| `brave` | `agent-browser-mcp -i brave` | Brave Browser |
+| `edge` | `agent-browser-mcp -i edge` | Microsoft Edge |
+
+### CLI Commands
+
+```bash
+# Install a browser
+agent-browser-mcp -i chromium
+agent-browser-mcp -i cloakbrowser
+
+# List all browsers and their status
+agent-browser-mcp --list
+
+# Select active browser (persists in ~/.agent-browser-mcp/.env)
+agent-browser-mcp --select cloakbrowser
+
+# Show auto-discovered browsers
+agent-browser-mcp --discover
+
+# Show .env config path
+agent-browser-mcp --env
+```
+
+### Auto-Discovery Flow
+
+1. On startup, checks `~/.agent-browser-mcp/.env` for `ACTIVE_BROWSER` and `BROWSER_PATH_*`
+2. If not set, scans known binary paths for each browser
+3. First found becomes default
+4. `--executable-path` is injected into all `agent-browser` commands automatically
+
+### .env Configuration (`~/.agent-browser-mcp/.env`)
+
+```env
+ACTIVE_BROWSER=cloakbrowser
+BROWSER_PATH_CHROMIUM=/usr/bin/chromium
+BROWSER_PATH_CLOAKBROWSER=/home/user/.cloakbrowser/chromium-146.0.7680.177.5/chrome
+BROWSER_PATH_CHROME=/home/user/.agent-browser/browsers/chrome-150.0.7871.24/chrome
+BROWSER_PATH_FIREFOX=/usr/bin/firefox
+```
+
+### MCP Client with Browser Selection
+
+```json
+{
+  "mcpServers": {
+    "browser": {
+      "command": "agent-browser-mcp",
+      "args": ["--select", "cloakbrowser"]
+    }
+  }
+}
+```
+
+<br>
+
+---
+
+## Tool Coverage
+
+All 153 agent-browser CLI subcommands are exposed as **63 composite MCP tools**. Each composite tool uses an `action`, `property`, `mode`, or `setting` parameter to select the specific subcommand, keeping the tool surface manageable for AI agents.
+
+| Category | CLI Commands | MCP Tools (63 total) | |
+|:---------|:-------------|:---------------------|:-:|
+| Navigation | open, back, forward, reload, pushstate | `browser_navigate`, `browser_go_back`, `browser_go_forward`, `browser_reload`, `browser_pushstate` | [x] |
+| Core Interaction | click, dblclick, fill, type, hover, focus, check, uncheck, select, drag, upload, download | `browser_click`, `browser_dblclick`, `browser_fill`, `browser_type`, `browser_hover`, `browser_focus`, `browser_check`, `browser_uncheck`, `browser_select`, `browser_drag`, `browser_upload`, `browser_download` | [x] |
+| Keyboard | press, keydown, keyup, type, inserttext | `browser_keyboard` (action) | [x] |
+| Mouse | move, down, up, wheel | `browser_mouse` (action) | [x] |
+| Scroll | scroll, scrollintoview | `browser_scroll`, `browser_scroll_into_view` | [x] |
+| Get Info | text, html, value, attr, url, title, cdp-url, count, box, styles | `browser_get` (property) | [x] |
+| State Checks | visible, enabled, checked | `browser_is` (state) | [x] |
+| Locators | find by role/text/label/placeholder/alt/title/testid/first/last/nth | `browser_find` (by) | [x] |
+| Wait | selector, timeout, url, load-state, function, text, download | `browser_wait` (mode) | [x] |
+| Screenshot / PDF | screenshot, pdf | `browser_screenshot`, `browser_pdf` | [x] |
+| Snapshot | snapshot (-i, -c, -C, -u, -d, -s) | `browser_snapshot` | [x] |
+| Eval | eval, eval -b | `browser_evaluate`, `browser_evaluate_base64` | [x] |
+| Batch | batch [--bail] | `browser_batch` | [x] |
+| Clipboard | read, write, copy, paste | `browser_clipboard` (action) | [x] |
+| Settings | viewport, device, geo, offline, headers, credentials, media | `browser_settings` (setting) | [x] |
+| Cookies | get, set, set-file, clear | `browser_cookies` (action) | [x] |
+| Storage | local/session get/set/clear | `browser_storage` (area + action) | [x] |
+| Network | route, unroute, requests, request-detail, har-start, har-stop | `browser_network` (action) | [x] |
+| Tabs | list, new, close, switch, new-window | `browser_tab` (action) | [x] |
+| Frames | switch, main | `browser_frame` (action) | [x] |
+| Dialogs | accept, dismiss, status | `browser_dialog` (action) | [x] |
+| Debug | trace, profiler, console, errors, highlight, inspect | `browser_trace`, `browser_profiler`, `browser_console`, `browser_errors`, `browser_highlight`, `browser_inspect` | [x] |
+| State Mgmt | save, load, list, show, rename, clear, clean | `browser_state` (action) | [x] |
+| Recording | start, stop, restart | `browser_record` (action) | [x] |
+| Auth Vault | save, login, list, delete, show | `browser_auth` (action) | [x] |
+| Diff | snapshot, screenshot, url | `browser_diff` (mode) | [x] |
+| React | tree, inspect, renders-start, renders-stop, suspense | `browser_react` (action) | [x] |
+| Vitals | vitals | `browser_vitals` | [x] |
+| iOS | device list, tap, swipe | `browser_device_list`, `browser_tap`, `browser_swipe` | [x] |
+| Session | show, list | `browser_session` (action) | [x] |
+| Streaming | enable, disable, status | `browser_stream` (action) | [x] |
+| Dashboard | start, stop | `browser_dashboard` (action) | [x] |
+| Init Scripts | removeinitscript | `browser_remove_init_script` | [x] |
+| Confirm / Deny | confirm, deny | `browser_confirm`, `browser_deny` | [x] |
+| Connect | connect | `browser_connect` | [x] |
+| Session Mgmt | close | `browser_close` | [x] |
+| **Browser Manager** | list, discover, install, select | `browser_manager` (action: list\|discover\|install\|select) | [x] |
+
+### CLI Commands Not Exposed
+
+| Command | Reason |
+|:--------|:-------|
+| `install`, `upgrade`, `doctor` | Setup and CLI-only operations |
+| `profiles`, `skills`, `chat` | CLI-interactive, not automation |
+| `close --all` | Daemon-wide operation |
+| `addinitscript` | Daemon-only JSON action |
+
+<br>
+
+---
+
+## Comparison
+
+How does Agent Browser MCP compare to other browser MCP servers?
+
+| Feature | Agent Browser MCP | Playwright MCP | Puppeteer MCP | Browserbase MCP |
+|:--------|:-----------------|:---------------|:--------------|:----------------|
+| MCP Protocol | [x] Native | [x] Native | [x] Native | [x] Native |
+| Tool Count | **63** | ~20 | ~15 | ~10 |
+| CLI Subcommands | **153** | ~20 | ~15 | ~10 |
+| Browser Manager | **[x] Install/Select/Discover** | [ ] | [ ] | [ ] |
+| Multi-Session | [x] | [ ] | [ ] | [x] |
+| Accessibility Snapshot | [x] | [ ] | [ ] | [ ] |
+| Visual Diffing | [x] | [ ] | [ ] | [ ] |
+| Network HAR | [x] | [ ] | [ ] | [~] |
+| Auth Vault | [x] | [ ] | [ ] | [ ] |
+| React Inspection | [x] | [ ] | [ ] | [ ] |
+| State Persistence | [x] | [ ] | [ ] | [ ] |
+| Cookie Management | [x] Full | [~] Basic | [~] Basic | [~] Basic |
+| Storage API | [x] Local + Session | [~] Limited | [~] Limited | [ ] |
+| Batch Commands | [x] | [ ] | [ ] | [ ] |
+| Zero Config | [x] | [x] | [x] | [~] |
+
+<br>
+
+---
+
+## FAQ
+
+<details>
+<summary><strong>What is an MCP server?</strong></summary>
+
+MCP (Model Context Protocol) is an open standard that lets LLM applications expose tools and resources through a standardized interface. An MCP server like agent-browser-mcp registers tools that any MCP client — Claude, Copilot, VS Code, Cursor — can discover and call.
+
+</details>
+
+<details>
+<summary><strong>Do I need to install a browser separately?</strong></summary>
+
+No. The `agent-browser` CLI manages its own Chromium instance via Playwright. When you install `agent-browser`, it downloads a compatible browser version automatically.
+
+</details>
+
+<details>
+<summary><strong>Can I use this with multiple LLM clients?</strong></summary>
+
+Yes. Any client that supports the MCP standard can connect to this server over stdio. This includes Claude Desktop, GitHub Copilot, VS Code, Cursor, and custom MCP client implementations.
+
+</details>
+
+<details>
+<summary><strong>What is the difference between a composite tool and a CLI command?</strong></summary>
+
+Each composite MCP tool maps to one or more `agent-browser` CLI subcommands using an `action` or `property` parameter. For example, `browser_get(property=text)` calls `agent-browser get text`, while `browser_get(property=html)` calls `agent-browser get html`. This reduces the tool surface from 153 to 62 without losing any capability.
+
+</details>
+
+<details>
+<summary><strong>How do I run this in production or headless mode?</strong></summary>
+
+By default, `agent-browser` runs in headless mode when no display is available, making it suitable for CI/CD pipelines, Docker containers, and server deployments. Set the `AGENT_BROWSER_PATH` environment variable to point to a specific `agent-browser` binary if needed.
+
+</details>
+
+<details>
+<summary><strong>How does the browser manager work?</strong></summary>
+
+The browser manager lets you install, select, and auto-discover browsers from the CLI. Use `agent-browser-mcp -i <browser>` to install, `--select <browser>` to set the active browser, and `--list` to see all options. The active browser is stored in `~/.agent-browser-mcp/.env` and automatically injected into all commands via `--executable-path`.
+
+</details>
+
+<details>
+<summary><strong>Can I use CloakBrowser for stealth automation?</strong></summary>
+
+Yes. Install with `agent-browser-mcp -i cloakbrowser` and select with `agent-browser-mcp --select cloakbrowser`. CloakBrowser includes 58 C++ source-level fingerprint patches that pass reCAPTCHA v3 (0.9 score), Cloudflare Turnstile, FingerprintJS, and 30+ detection sites.
+
+</details>
+
+<br>
+
+---
+
+## Project Structure
+
+```
+agent-browser-mcp/
+├── src/
+│   ├── index.ts              # MCP server entry point (stdio transport)
+│   ├── cli.ts                # CLI entry point with browser management
+│   ├── browsers/
+│   │   ├── registry.ts       # Browser definitions (name, install, paths)
+│   │   ├── installer.ts      # Install logic per browser
+│   │   ├── discover.ts       # Auto-discover installed browsers
+│   │   ├── env.ts            # .env loader for browser paths
+│   │   └── index.ts          # Public API exports
+│   └── tools/
+│       ├── browser.ts        # 62 MCP tool registrations + Zod schemas
+│       ├── executor.ts       # CLI command mapping + --executable-path inject
+│       └── index.ts          # Public API exports
+├── tests/
+│   ├── browser-tools.test.ts # Tool registration and handler tests
+│   ├── executor.test.ts      # CLI argument building tests
+│   ├── integration.test.ts   # End-to-end workflow tests
+│   └── server.test.ts        # Server lifecycle tests
+├── .env.example              # Browser config template
+├── AGENTS.md                 # Full tool coverage documentation
+├── package.json
+├── tsconfig.json
+└── vitest.config.ts
+```
+
+

package/dist/browsers/discover.d.ts

@@ -0,0 +1,13 @@
+export interface DiscoveredBrowser {
+    name: string;
+    path: string;
+    source: "env" | "auto";
+}
+export declare function discoverBrowsers(): DiscoveredBrowser[];
+export declare function discoverActiveBrowser(): DiscoveredBrowser | null;
+export declare function selectBrowser(name: string): {
+    success: boolean;
+    path?: string;
+    error?: string;
+};
+//# sourceMappingURL=discover.d.ts.map

package/dist/browsers/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/browsers/discover.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;CACxB;AAED,wBAAgB,gBAAgB,IAAI,iBAAiB,EAAE,CAiBtD;AAED,wBAAgB,qBAAqB,IAAI,iBAAiB,GAAG,IAAI,CAkBhE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAoB/F"}