browser-controller / rules

---
description: Core project context for browser-controller
alwaysApply: true
---

# browser-controller

Multi-client MCP server (TypeScript) + Chrome extension (plain JS). Renamed from `real-browser-mcp` (v2.0.0). npm `browser-controller`, MCP id `io.github.noiemany/browser-controller`.

## Three-piece architecture

```
Agent ─stdio─ thin MCP client (index.ts) ─IPC─► daemon (daemon.ts, owns :7225) ─WS─► extension (background.js)
```

- The daemon owns the WS server on 7225 AND an HTTP server on the **same port** (`/pair` returns the token, `/status` returns agents). The extension auto-fetches the token via `/pair` (MV3 can't read the filesystem).
- Bind host is **`127.0.0.1`** (NOT 'localhost' — macOS resolves localhost to IPv6 ::1 first and refuses IPv4). Both WS connect and HTTP fetch use 127.0.0.1.
- Thin client auto-spawns the daemon if absent. State in `~/.browser-controller/`.

## The two invariants

1. **`tabId` is mandatory** for every page-interaction tool. `navigate` is the ONE exception (optional: without it, it opens a new background tab owned by the session). `tabs` list takes no tabId; close and focus need one. Enforced by the `tabIdParam` schema in `mcp-server/src/tools/types.ts`.
2. **background.js never acts on "the active tab"** implicitly — `resolveTab(tabId)` is the entry point. The only active-tab lookup left is choosing the window for a new tab (`getActiveTab` in `handleNavigate`).

## Element identification (one ref grammar, one locator)

- Refs are `e<n>` only. `extension/lib/page-dom.js` issues them (`refFor`): an element keeps its ref for as long as its document lives. Refs live in the page registry; nothing is stamped onto the page DOM.
- Every `target` goes through `parseTarget` in `extension/lib/target.js` and then `resolveTarget` in `extension/lib/page-dom.js`: `e12` is a ref; `text=Sign in` is a visible element by text; `120,80` is a viewport point; anything else (`#save`, `x-1`) is a CSS selector.
- A stale ref re-finds its element through the snapshot descriptor kept in `fallbackByTab` (`extension/lib/state.js`). The descriptor holds a robust selector from `extension/utils/smart-selector.js`, the text, the role, and the `nth` ordinal, so one of several equal buttons is still picked correctly. When nothing matches it fails `REF_GONE` or `REF_NOT_FOUND`.

## Concurrency (extension/lib/tab-concurrency.js — pure, unit-tested)

- `TabMutexMap`: same-tab serializes, cross-tab parallelizes.
- `TabLockMap`: implicit per-session tab ownership (a tab `browser_navigate` opens without `tabId`). Another session's call on it fails `TAB_LOCKED`. No explicit lock tool in 3.0.
- `isIdempotent` (`mcp-server/src/tools/index.ts`, from each definition's `idempotent` flag): read tools retry on timeout; **click/type/navigate/evaluate NEVER retry**.

## Tool inventory (22 tools)

Navigation: browser_navigate (tabId optional: without it, opens a new background tab owned by the session), browser_tabs (list/close/focus; browser picks the Chrome profile), browser_emulate
Reading: browser_snapshot (refs e<n>; query, target, maxChars), browser_text, browser_screenshot, browser_inspect_element
Interaction: browser_click (target; hover, dragTo), browser_type, browser_fill, browser_scroll, browser_wait
Chain: browser_batch (up to 50 steps)
JS/Dialogs: browser_evaluate (CDP), browser_handle_dialog
Debug: browser_logs (console + network, per-tab buffers), browser_mock (tab-scoped Fetch rules)
Safety: browser_safety (allow, ask or block for submit, delete and upload actions and for browser_evaluate; per site or as the default), browser_vault (private credential vault: status, list, unlock, save_login or fill; the owner approves a site once)
Memory: browser_memory (read-only notes on the tab's site: language, search, login, common controls, a form's shape, visits), browser_memory_policy (owner-confirmed enable, disable, exclude, include, inspect, export, delete and map_* actions), browser_site_map (read-only map of one site in this profile: remembered pages and controls)

## browser_evaluate

Runs over CDP by default (`Runtime.evaluate`, top-level await): the page CSP does not block it, and the "being debugged" banner shows while attached. It falls back to `chrome.scripting` MAIN world (`via: scripting`) only when the debugger cannot attach. `browser_fill` (file inputs, `DOM.setFileInputFiles`) and `browser_click` (`Input.dispatchMouseEvent`) use CDP too.

## chrome.scripting serialization gotcha

`chrome.scripting.executeScript` args **cannot be functions** (recent MV3). The smart-selector fallback fns are passed as their `.toString()` source and rebuilt via `eval('(' + src + ')')` inside the page. If a tool suddenly fails with "Value is unserializable" at args index N, that's the cause.

## Adding a tool

1. `mcp-server/src/tools/<name>.ts`: a `ToolDefinition` with a zod `inputSchema` (`tabIdParam` from `tools/types.ts` for the tab), `handler: forwardHandler('browser_<name>')`, and `idempotent: true` only for read-only tools.
2. `mcp-server/src/tools/index.ts`: add it to `allTools`. `registerTools` in `mcp-server/src/register-tools.ts` registers every entry there. `isIdempotent` and `toolTimeoutMs` are derived from the definitions.
3. `extension/handlers/<area>.js`: the handler, `handle<Name>(params, sessionId, agentName, signal)`. It returns `{ success: true, text }` or `{ success: false, error: "CODE: message" }`.
4. `extension/lib/router.js`: add it to `HANDLERS`. The drift guard in `tests/extension-router.test.ts` fails when a registered tool has no extension handler, or when the two sets differ in size.

## Build/test

- `npm run build` (tsc), `npm test` (vitest), `npm run typecheck`
- Extension is plain JS (no build) — `node --check` each file after edits
- Daemon is built to `mcp-server/dist/`. Reload the extension at `chrome://extensions` after any extension edit. Open tabs keep the old page helper until `PAGE_DOM_VERSION` in `extension/lib/page-dom.js` changes, so bump it when you change page-side code.

## graphify

This repo is graphify-indexed (457 nodes / 727 edges / 28 communities). Use `graphify query "..."` to trace code paths, `graphify update .` for zero-cost code refresh, `graphify . --backend claude` for image extraction. See memory `mem:graphify-setup` for the Z.ai endpoint config.