Metadata-Version: 2.4
Name: browser-runtime-mcp
Version: 0.1.0
Summary: MCP server that gives AI agents real-time access to browser runtime errors, console logs, and page diagnostics via a Chrome Extension.
Project-URL: Homepage, https://github.com/MakiDevelop/browser-runtime-mcp
Project-URL: Issues, https://github.com/MakiDevelop/browser-runtime-mcp/issues
Author-email: Makito Chiba <makiakatsu@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agent,browser,chrome-extension,debugging,devtools,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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

Browse any website. 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.

## 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
