Skip to main content
Glama
README.md
# mcp-zen

A persistent MCP HTTP server paired with a Zen/Firefox extension that lets any
MCP client remote-control your **already-running** browser.

The public tool surface is **`zen_browser_*`**: one prefix for core browsing,
frames, and additive media/locate tools. Schemas were captured from
[agent-browser](https://github.com/vercel-labs/agent-browser) `0.36.0` (pinned
in `common/agent-browser/`) then renamed. The backend is your attached
Firefox/Zen window, not a managed Chromium process. See
[docs/parity.md](docs/parity.md).

The server is one long-lived process. The extension's WebSocket stays up
independently of short-lived MCP client sessions.

## Setup

### 1. Load the extension in Zen

1. `npm install && npm run build`
2. Zen: `about:debugging` → This Firefox → Load Temporary Add-on →
   `firefox-extension/manifest.json`
3. Options page: **Enable browser automation** (`<all_urls>`). Optional:
   **Enable isolated sessions** (Firefox containers for named `session`s).
4. Temporary add-ons unload on browser restart unless you install permanently.

### 2. Ports (optional)

```bash
cd mcp-server
cp .env.example .env
```

- `MCP_HTTP_PORT` (default `8791`) — MCP clients
- `EXTENSION_PORT` (default `8765`) — extension WebSocket
- `MCP_SCREENSHOT_DIR` — screenshot files (server filesystem)

Localhost only. The extension origin is required on the WebSocket; browser
origins are rejected on `/mcp`.

### 3. Run

`bin/` is gitignored. Create the wrapper once per checkout:

```bash
mkdir -p bin
cat > bin/mcp-zen <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
exec node "$SCRIPT_DIR/../mcp-server/server.js" "$@"
EOF
chmod +x bin/mcp-zen
ln -sf "$(pwd)/bin/mcp-zen" ~/.local/bin/mcp-zen
mcp-zen
```

Point an MCP client at `http://localhost:8791/mcp`.

```bash
node mcpcall.mjs zen_browser_tab_list '{}'
node mcpcall.mjs zen_browser_open '{"url":"https://example.com"}'
node mcpcall.mjs zen_browser_snapshot '{}'
node mcpcall.mjs zen_browser_click '{"selector":"@e1"}'
```

## Tools

Default profile is agent-browser **core** (29 tools). Every tool accepts the
upstream common options; unsupported ones (`allowedDomains`, `restore*`,
`extraArgs`, `caCert`, …) return `UNSUPPORTED_CAPABILITY` instead of being
ignored.

| Tool | Notes |
|---|---|
| `zen_browser_tools_profiles` | `core` only in this version |
| `zen_browser_open` | Navigate the currently selected tab; no browser launch flags |
| `zen_browser_read` | Live tab HTML; `url` navigates first if needed. `llms` fetches llms.txt |
| `zen_browser_snapshot` | A11y-style tree + `@eN` refs |
| `zen_browser_click` | `@ref`, bare `eN`, or first CSS match; `newTab` opens the link |
| `zen_browser_fill` / `type` | `text` (not `value`); synthetic input |
| `zen_browser_press` | Chords like `Control+a`; untrusted events |
| `zen_browser_check` / `uncheck` / `select` | `select` takes `values: string[]` |
| `zen_browser_scroll` | `up\|down\|left\|right`, default 300px |
| `zen_browser_wait_ms` | Required `ms` ≥ 0 |
| `zen_browser_wait_for_selector` / `_text` / `_load` | `waitTimeoutMs`; no `networkidle` |
| `zen_browser_screenshot` | Path + image content; `fullPage` / `selector` / `annotate` |
| `zen_browser_get_text` | Requires `selector` |
| `zen_browser_get_url` / `get_title` | Currently selected tab |
| `zen_browser_eval` | Page-realm JS |
| `zen_browser_tab_new` / `tab_list` / `tab_switch` / `tab_close` | `tN` / label / `firefox:<id>` |
| `zen_browser_back` / `forward` / `reload` | |
| `zen_browser_close` | Owned tabs/containers only — not your browser |
| `zen_browser_frame_switch` / `frame_main` | Iframes (Stripe/PayPal/3DS) |
| `zen_browser_find` | Click/fill by role, text, label, testid, … |
| `zen_browser_wait_for_url` | Substring, glob, or `/regex/` |
| `zen_browser_hover` / `scroll_into_view` | |
| `zen_browser_get_value` / `get_attr` / `is_visible` / `is_enabled` / `is_checked` | |
| `zen_browser_dialog_*` | `alert`/`confirm`/`prompt` hooked after the runtime is installed |
| `zen_browser_window_new` | |
| `zen_browser_tap` / `swipe` | Synthetic touch |
| `zen_browser_console` | `{ clear?: boolean }` — page console buffer |

### Reliable targeting

- Use `@eN` from snapshots; bare `eN` is also accepted. Repeated snapshots
  retain refs for the same connected DOM node. Removed/replaced nodes, navigation,
  or evicted refs require a fresh snapshot; refs never automatically retarget.
- Selectors use standard CSS (first match), `xpath=...`, or snapshot refs—not
  Playwright `:has-text()` / `:text()`. Scope to the intended post/player rather
  than using a page-wide `[role=slider]` (which can also match volume).
- `zen_browser_find` **defaults to click**. Use `action: "text"` to read
  without activating the match. Snapshot queries do not click.
- `eval` may be blocked by a site's CSP. Ordinary DOM tools still work.
- Hover is synthetic and may not reveal CSS-only controls. A click response
  confirms dispatch, not application success: verify playback/seek state.
- MCP clients must forward screenshot image content, not just its filesystem
  path. An image placeholder is not visual evidence.
- Additive `zen_*` tools (locate, reveal, click_at, set_range, media_*) are
  Firefox capabilities, not agent-browser. Prefer `zen_browser_media_*` on CSP-strict
  video pages instead of `eval`. `zen_browser_locate` never clicks; `zen_browser_find` still defaults to click.

### Follow the operator's active tab

Every page tool operates in the selected tab of the last-focused normal browser
window. No remembered background-tab binding is used. `tab_list` reports actual
browser `active` flags, browser `windowId`, and `current` for the selected tab in
that window. Duplicate titles do not affect tab identity. If an older extension
cannot disambiguate multiple browser windows, the server asks for the update.

To work elsewhere, explicitly call `tab_switch`: it selects the tab and focuses
its browser window. New tabs/windows are visibly selected before navigation.
`tab_close` cannot close a background tab; switch first. Bulk `close` visibly
selects each owned tab before closing it and never closes personal tabs.

Manual tab changes are steering. Subsequent calls follow the newly selected tab
and prefix a warning describing the change. Read-only waits can resume in the new
tab within the original deadline. Old-tab element refs return a successful
`contextChanged` result with fresh targets rather than clicking an unrelated
control. Partially delivered input is never replayed: the response says
`previousAction: "possibly_partial"` and supplies fresh context to continue.
Concurrent sessions serialize against this single visible browser.

The extension rechecks selection before dispatch and capture; page waits and
per-character typing check visibility between steps. Already-dispatched page JS,
navigation, or input cannot be undone, and arbitrary `eval` scripts can schedule
work outside the lifetime of a tool call. This policy controls tool dispatch; it
is not a sandbox for arbitrary page JavaScript.

Omit `session` for personal tabs. Named sessions retain Firefox container isolation:
select a tab in that container before operating there. A switch out of the named
container does not silently transfer its work into a different cookie context.

For the permanent local installation, build then install the updated XPI through
`about:addons` → gear → **Install Add-on From File**. The stable Gecko ID preserves
the existing installation and permissions. Restart/reconnect MCP clients after
restarting the server so they reload its instructions.

## Optional animated agent cursor

If a listener exists at `$XDG_RUNTIME_DIR/agent-cursor.sock`, Zen notifies it before
clicks, find mutations, typing, dropdown changes and hover/reveal. It waits up to
1800 ms for animation, revalidates the element, then performs the existing DOM
operation exactly once. No listener means ordinary operation without animation.
There is no import or runtime dependency on mcp-computer-use.

The companion listener is shipped by mcp-computer-use as `agent-cursor.service`.
Both tools share the same renderer. `AGENT_CURSOR_SOCKET` overrides the endpoint;
`AGENT_CURSOR=off` disables Zen's notifications. The server-side notifier speaks
version 1 newline-delimited JSON, using desktop device pixels resolved internally.
It cannot execute input. The model never supplies notification coordinates.

Extension 0.1.2 adds internal preparation tokens for checking element identity,
position and hit testing after the arrow moves. Old extensions continue without
animation. Typing highlights the arrow amber; the listener clears it on completion
or a safety timeout. Unresponsive listeners are bounded and fail open.

To run the automated suite without drawing on your desktop:
`AGENT_CURSOR=off npm test`. Cursor protocol tests use isolated temporary sockets.

## Development

Plain ES modules, Node 22+. No TypeScript.

```bash
npm test
```

- Adapter tests use a mock extension.
- DOM tests use Chromium (`CHROMIUM_PATH`, default `/usr/bin/chromium`).
- Live tests use a **disposable** Zen/Firefox profile (`FIREFOX_PATH`) and
  never attach to your daily browser.
- `node scripts/capture-agent-browser.js` regenerates pinned schemas from a
  built agent-browser binary.

## Project layout

```
common/agent-browser/   pinned upstream MCP schemas + provenance
mcp-server/             HTTP MCP server, adapter, read pipeline
firefox-extension/      background client + in-page runtime
docs/parity.md          core vs remaining 156-tool surface
test/                   schema, adapter, DOM, live Firefox
mcpcall.mjs             one-shot Streamable HTTP client
```

## License

MIT — see [LICENSE](LICENSE).

Pinned agent-browser schema JSON is copied from an Apache-2.0 project; see
`common/agent-browser/LICENSE`.