# Browser Runtime MCP

Give AI agents real-time access to browser runtime errors, console logs, and page diagnostics.

**The problem:** AI coding agents can read your source code but are blind to what actually happens in the browser — runtime errors, console warnings, failed API calls, CSS rendering issues. You end up copy-pasting DevTools output back and forth.

**The solution:** A Chrome Extension captures browser events and streams them to a local MCP server. Your AI agent (Claude Code, Cursor, etc.) can query errors, console logs, and page state directly through MCP tools.

```
Browser tab → Chrome Extension → localhost MCP server → AI agent
```

## Quick Start

### 1. Install the MCP server

```bash
pip install browser-runtime-mcp
```

### 2. Install the Chrome Extension

Download the `extension/` folder from this repo, then:

1. Open `chrome://extensions`
2. Enable **Developer mode**
3. Click **Load unpacked** → select the `extension/` folder

### 3. Configure your AI tool

**Claude Code** — add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "browser-runtime-mcp": {
      "command": "browser-runtime-mcp",
      "args": []
    }
  }
}
```

**Other MCP clients** — run the server in stdio mode:

```bash
browser-runtime-mcp
```

### 4. Use it

Open the extension popup on the site you want to debug and click **Enable capture on this site**.
Capture is disabled by default and the allowlist is stored locally in Chrome. Then ask your AI agent:

- "Are there any browser errors?"
- "What's in the console logs?"
- "What pages is the extension tracking?"

## MCP Tools

| Tool | Description |
|------|-------------|
| `get_browser_errors` | Runtime errors with stack traces and DOM context |
| `get_console_logs` | Console output (error/warn/log), filterable by level |
| `get_page_info` | Tracked pages and buffer statistics |
| `clear_buffers` | Clear all buffered data for a fresh start |

## How It Works

```
┌─────────────────┐     postMessage      ┌──────────────────┐
│   content.js    │ ──────────────────▶  │ content-bridge.js │
│  (MAIN world)   │                      │ (ISOLATED world)  │
│                 │                      │                    │
│ • window.onerror│                      │ chrome.runtime     │
│ • console patch │                      │ .sendMessage()     │
└─────────────────┘                      └────────┬───────────┘
                                                  │
                                    chrome.runtime.onMessage
                                                  ▼
                                         ┌────────────────┐
                                         │ background.js   │
                                         │ (service worker)│
                                         │                 │
                                         │ fetch() to      │
                                         │ localhost:18790  │
                                         └────────┬────────┘
                                                  │ HTTP POST
                                                  ▼
                                         ┌────────────────┐
                                         │ MCP Server      │
                                         │ (Python/stdio)  │
                                         │                 │     MCP tools
                                         │ • HTTP receiver ├──────────────▶ AI Agent
                                         │ • Error buffer  │
                                         │ • Log buffer    │
                                         └────────────────┘
```

The three-hop architecture (MAIN → ISOLATED → background) bypasses Chrome's Private Network Access policy, which blocks HTTPS pages from fetching to localhost directly.

## Privacy and trust boundary

- Capture is opt-in per origin and disabled by default. Use the popup to stop capture when finished.
- Captured URLs, page titles, errors, stack traces, DOM context, and console messages stay in bounded in-memory buffers on `127.0.0.1`; they are not uploaded by this project.
- `clear_buffers` removes all currently buffered data. Stopping the server also discards it.
- Do not enable capture on banking, authentication, health, internal administration, or other sensitive pages unless you intend to expose their diagnostics to your local MCP client.
- Browser pages control their own console output. Treat captured messages and DOM snippets as untrusted diagnostic input, not authoritative data or instructions.
- The HTTP diagnostic endpoints are intentionally local-only but are readable by other processes running as your user.

## Standalone HTTP Mode

For debugging without MCP, run the HTTP receiver only:

```bash
browser-runtime-mcp --http-only
```

Then query:
- `GET http://127.0.0.1:18790/health` — buffer stats
- `GET http://127.0.0.1:18790/errors` — all captured errors
- `GET http://127.0.0.1:18790/logs` — all captured logs
- `GET http://127.0.0.1:18790/pages` — tracked pages

## Requirements

- Python 3.10+
- Chrome (Manifest V3 extension)
- Zero Python dependencies (stdlib only)

## License

MIT