real-browser-mcp / rules

---
description: Core project context for real-browser-mcp
alwaysApply: true
---

# real-browser-mcp

MCP server (TypeScript) + Chrome extension (plain JS) that talk over WebSocket on localhost:7225.

## Versioning

Bump minor versions: 1.0.0 -> 1.1.0 -> 1.2.0. Three places must stay in sync:
1. `package.json` "version"
2. `extension/manifest.json` "version"
3. `mcp-server/src/index.ts` SERVER_VERSION

## Adding a Tool

Four files to touch:
1. `mcp-server/src/tools/<name>.ts` - ToolDefinition with Zod schema
2. `mcp-server/src/tools/index.ts` - add to allTools array
3. `extension/background.js` - add handler in dispatch() map + handler function
4. `tests/tools/` - add test

The schema type MUST be `z.ZodObject<z.ZodRawShape>`, not `z.ZodType`. The MCP SDK calls `.shape` on it.

## Tool inventory (18 tools)

Navigation: browser_navigate, browser_tabs
Interaction: browser_click (ref OR selector), browser_click_text (by visible text, CSP-safe), browser_type, browser_press_key, browser_scroll, browser_hover, browser_select
Reading: browser_snapshot (compact mode default), browser_screenshot, browser_text, browser_find
JS execution: browser_evaluate (via chrome.debugger CDP - bypasses CSP but shows debugger banner)
Dialogs: browser_handle_dialog (override alert/confirm/prompt)
Wait: browser_wait
Debug: browser_console (read-only), browser_network

## CSP and browser_evaluate

`browser_evaluate` uses chrome.debugger API (CDP Runtime.evaluate). This bypasses CSP but:
- Shows "is being debugged" infobar
- Attaching/detaching the debugger can steal focus and close open popups/dropdowns
- Requires `debugger` permission in manifest.json

For DOM interactions (clicking dropdown options, etc.), prefer `browser_click` with CSS selectors or `browser_click_text` instead. These use `chrome.scripting.executeScript` with compiled functions — no eval, no CSP issues.

Previous attempts using `new Function()` in MAIN world failed on GitHub/Google/strict-CSP sites. Sandbox/offscreen approaches can't access page DOM. chrome.debugger is the only universal eval but has the focus-stealing side effect.

## Snapshot modes

`compact: true` (default) - returns only interactive elements + landmarks, ~70% smaller output. No `tag` field.
`compact: false` - full accessibility tree with all visible elements. Includes `tag` for generic roles.

## Extension is plain JS

No build step. Reload in chrome://extensions after changes. Chrome kills service workers after 30s idle - the `chrome.alarms` keepalive handles this. Don't remove it.

## Element refs are ephemeral

`browser_snapshot` assigns `data-mcp-ref` attributes. These refs break after navigation, scroll, or DOM changes. Always re-snapshot before using refs.

## Port 7225

Not negotiable without updating both server default (index.ts) AND extension default (background.js + popup.html). Configurable via `WS_PORT` env var on server side, popup input on extension side.

## Tests need port isolation

Each test gets a unique port (counter starting at 19230). WebSocket servers take time to unbind - tests will flake without this.