browser-control
by adrianhoehne
README.md
# browser-control
A Firefox extension drives your **visible, logged-in browser**, and a small
bridge exposes that browser as an **MCP server** for agents. The agent works in
its own tab — one you can watch — with your logins, your cookies and your
profile. No headless browser, no second profile, no automated login.
```
Agent ──MCP over HTTP──▶ Bridge (Node) ──WebSocket──▶ Firefox extension
(bearer token) 127.0.0.1:8111 agent tab
```
The extension dials **out** to the bridge. That is why the bridge needs no
inbound port, and why the agent can only see tabs it created itself.
## What it does
**Thirteen tools**, all with the `browser_` prefix:
| Tool | Purpose |
|---|---|
| `status` | windows and tabs as JSON, agent tabs marked |
| `navigate`, `read` | open a page (waits for it to settle), read its content as text |
| `click`, `type`, `focus` | interact, type, bring the tab to the front |
| `inspect` | query the DOM, selector and attributes |
| `open_tab`, `close_tab` | manage agent tabs (at most five) |
| `eval` | run code in the page context (**off by default**) |
| `screenshot` | the visible part of the tab (**off by default**) |
| `frames` | list and address iframes |
| `transcript` | a YouTube transcript as segments with timestamps, in the video's original track |
Plus: settle detection instead of fixed sleeps, shadow DOM and frames,
persistence across a background tab, and a log that does not copy page text.
## Security
- **One token**, kept on the operator's filesystem and never in the repo; the
bridge checks it on every MCP request.
- **Loopback only.** The MCP port is bound to `127.0.0.1` and does not belong
behind a public proxy.
- **Three switches**, all off by default: password fields, code evaluation,
screenshots. The agent never flips them itself.
- **The agent only sees its own tabs.** It does not drive yours.
## Quick start
The full guide is **[INSTALL.md](INSTALL.md)**: token file, bridge as a systemd
user service, loading the extension. A reverse proxy is optional and covered at
the end.
Short version for one machine without a proxy:
```bash
# 1. server side: token file, systemd user unit, service start — one command
cd ~/browser-control
./scripts/install.sh
# 2. extension: about:debugging#/runtime/this-firefox → "Load Temporary Add-on…"
# → pick extension/manifest.json, then paste the token under Preferences.
# The endpoint is pre-filled with ws://127.0.0.1:8110.
```
`./scripts/install.sh --dry-run` shows what the first step would do without writing
anything. The manual equivalent — `openssl rand -hex 32` for the token, `cp` of the
unit plus `systemctl --user enable --now` — is in [INSTALL.md](INSTALL.md)
sections 2 and 3, for when you want to see or change a single step.
The extension is **unsigned**. After a Firefox restart it is gone and has to be
loaded again; signing through AMO is not set up.
## Development
There are **no dependencies** — Node ≥ 22 is enough:
```bash
npm test # 757 cases, TAP output, ~95 s
npm run check # node --check over every .js/.mjs
```
How changes happen (spec → gate → dev plan → review → acceptance) is described
in **[CONTRIBUTING.md](CONTRIBUTING.md)**; the design and measurement history
lives in [`docs/`](docs/README.md) — 34 specs, each with its measurements and the
decisions that followed.
## Known limits
- **Unsigned**: temporary load, again after every Firefox restart.
- **Windows** is only partly covered (`docs/29`, `docs/30`).
- **YouTube labels can lie**: `browser_transcript` reads the track YouTube calls
the original; language detection is deliberately out of scope.
- **One operator, one browser**: the bridge serves the extension that is
connected.
## License
[MIT](LICENSE).
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessOutdated data