Skip to main content
Glama
browser-use-mcp

browser-use-mcp

README.md
# @ricardochen1996/browser-use-mcp

[![CI](https://github.com/ricardochen1996/browser-use-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ricardochen1996/browser-use-mcp/actions/workflows/ci.yml)

**English** · [中文](README.zh-CN.md)

> An MCP server that gives **any agent** a browser it can *see and click*: a page is read as an
> **indexed action-space table**, and every step is one guarded operation on a target that came
> from that table.

`browser-use-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server. Claude
Code, Claude Desktop, Cursor, Codex, a DeepSeek Harness conversation, or any other MCP client
connects to it, and its agent gets a browser: open a page, read the page as a table of numbered
targets, then name one operation on one target. The model never writes a selector, a coordinate, or
a script, and the server never retries a change by itself.

It is built on [`dsh-browser-use`](https://github.com/ricardochen1996/dsh-browser-use): the same
Python engine, the same sidecar protocol, the same page-as-indexed-action-space idea — with the
DeepSeek Harness plugin host replaced by an MCP host. So there is no browser logic of its own: this
package is the adapter that lets any MCP client drive the [Jev Ultrafast](https://github.com/ricardochen1996/jev-ultrafast)
engine. The engine and [`browser-harness`](https://github.com/browser-use/browser-harness) ship as a
pinned wheel plus hash-pinned requirements, and are installed into a managed Python environment on
first use. No engine clone, no manual Python setup.

---

## What it is

The browser tools expose one loop:

1. **Read.** `browser_open` downloads the page and returns its **action space** as text: one line
   per reachable element, the operations that element supports, and the exact target indices those
   operations accept. The result carries an **observation number**.
2. **Choose.** The agent picks one operation and one target *from that observation*:
   `browser_act({ observation, operation, target })`.
3. **Guard.** The server sends the operation together with the fingerprint of the observation it
   came from. The engine re-reads the page first. If the page changed, **nothing is executed** and
   the result starts with `Nothing was executed:` followed by the fresh table. That is a refusal,
   not an error: the agent chooses again from something that is true.
4. **Verify.** If the page matched, the one operation runs and the server returns the new
   observation. The next step refers to the new number. A tool result is never proof of an
   outcome; the next observation is.

Here is a real table, produced by the bundled test fixture (the visible-text line is clipped):

```text
Page file:///…/test/fixtures/fixture.html — 🐴 Forma · Find a place to slow down
Observation 1. Targets below are valid only for this observation.
Visible text: forma. Find a stay Reading room PLACES WITH CHARACTER THE SLOWER WAY TO STAY …
[1] link forma. — CLICK
[2] link Find a stay — CLICK
[3] link Reading room — CLICK
[4] searchbox Destination — TYPE_TEXT, CLICK
[5] button Find stays — CLICK
[6] combobox Stay category · "All stays" — SELECT
      6:1 → Stay category → Design
      6:2 → Stay category → Nature
      6:3 → Stay category → Coastal
[7] checkbox Free cancellation · "on" (not checked) — CLICK
[8] button View Casa Flora — CLICK
[9] button View The Glasshouse — CLICK
[10] button View Serra Lodge — CLICK
Without a target: SCROLL_DOWN, WAIT
```

A step against it is one object, not code:

```jsonc
{ "observation": 1, "operation": "CLICK", "target": "5" }             // button Find stays
{ "observation": 1, "operation": "TYPE_TEXT", "target": "4", "text": "Lisbon" }
{ "observation": 1, "operation": "SELECT", "target": "6:1" }          // Stay category → Design
```

If the page moved between the read and the click, the answer is a refusal that hands back the
current observation:

```text
Nothing was executed: The page changed since that observation. Choose from the new one.

Page … — …
Observation 3. Targets below are valid only for this observation.
```

The engine reads a page over a single CDP connection that this server's session owns. Every tool —
`browser_eval` included — uses that one connection. Starting a second client yourself (a raw
websocket, a puppeteer/playwright script, another `browser-harness` daemon) is how Chrome 144+'s
per-connection "Allow remote debugging?" prompt turns into a stack of prompts, and how two loops end
up driving one page.

## How it differs from selector-based browser MCPs

| | Selector-based browser MCP | `browser-use-mcp` |
| --- | --- | --- |
| What the model sends | A selector, a coordinate, or code | One operation on an index from the table it just read |
| What happens when the page moved | The selector may miss, or hit the wrong element | The action is **refused**, and the fresh table is returned |
| Retries | Up to the client or the model | **Never** — a refusal is the retry point, not an automatic replay |
| What the model knows is possible | It has to guess | Each line lists that element's targets and operations, dropdown options included |
| CDP connections | Depends on the implementation | Exactly one per browser session, shared by every tool |
| Token cost per step | Often a screenshot or the whole DOM | Structured text: visible text plus the element table |

`browser_eval` is the one deliberate exception: it evaluates a single JavaScript expression over
the same connection, returns a value as data, and produces **no observation** — so the next guarded
action still refers to the last table. It exists so a model that needs a programmatic read does not
start a second CDP client. `--no-eval` withdraws it.

---

## Quick start

**Requires** Node.js `^22.19.0 || >=24.0.0`, Chrome or Chromium, and a way to get Python 3.12+:
either `python3.12`–`python3.14`, `python3` (3.12 or newer) on `PATH`, or [uv](https://docs.astral.sh/uv/),
which can fetch the Python itself. The executable checks the runtime it was started with: if a client
starts it on an older Node, it looks for a supported one on `PATH` and in the usual
nvm/fnm/mise/asdf trees and restarts itself with it; if there is none, it exits with a message naming
the required range instead of failing inside a dependency.

**Which browser it drives.** The default mode is **attach**: the server drives the Chrome you already
use, so its logins and tabs are the ones the agent sees. Enable remote debugging once in that Chrome
(`chrome://inspect/#remote-debugging` → allow); on macOS the application that runs the server also
needs **Full Disk Access** (System Settings → Privacy & Security → Full Disk Access). Prefer an
isolated browser? Pass `--mode launch` and the server starts its own Chrome with a profile under the
state root instead.

**Install.** The package is published on npm as
[`@ricardochen1996/browser-use-mcp`](https://www.npmjs.com/package/@ricardochen1996/browser-use-mcp).
Run the latest release without installing anything:

```bash
npx -y @ricardochen1996/browser-use-mcp@latest --version
```

or install the `browser-use-mcp` command, which is what the terminals below assume:

```bash
npm install -g @ricardochen1996/browser-use-mcp@latest
browser-use-mcp --version
```

Both forms run the same server: `npx -y @ricardochen1996/browser-use-mcp@latest` can stand in for
`browser-use-mcp` in every command below. Client configs work with either `npx` or the installed
command; if a GUI client cannot find them on its short `PATH`, give it the absolute path from
`command -v browser-use-mcp` (or `command -v npx` for the `npx` form); per-client snippets are in
[docs/clients.md](docs/clients.md).

Then check the machine (on a fresh machine the first browser call builds the environment;
`install` does it eagerly). Its output looks like this, with machine-specific paths shortened:

The example below asks for a dedicated browser (`--mode launch`); with the default attach mode the
`Connection:` line names the Chrome you browse with instead, and `Status: ready` requires that
browser to answer its debugging endpoint.

```bash
browser-use-mcp doctor --mode launch
```

```text
browser-use-mcp v0.1.4 — self-check (Node v22.23.2, darwin-arm64)

Transport: stdio (MCP over stdin/stdout)
Connection: launch Chrome/Chromium, profile "default" at /Users/you/.browser-use-mcp/profiles/default
State   : /Users/you/.browser-use-mcp (managed Python environment)
Timeouts: 180s per browser request
Logging : info (stderr)
Jev     : on, typesafe decider: default endpoint (model default), key unset; …
Tools   : browser_open, browser_page, browser_act, browser_eval, browser_screenshot, browser_console, browser_goal, browser_close, browser_doctor
Session : idle (this transport has no browser session yet)

Engine   : /Users/you/.browser-use-mcp/env/bin/python (Python 3.12.14, chosen by managed environment)
           jev_ultrafast 0.1.2 at …/env/lib/python3.12/site-packages/jev_ultrafast
           browser-harness 0.1.13
Install  : none in this process; the engine is already importable
Sidecar  : /…/node_modules/@ricardochen1996/browser-use-mcp/sidecar/bridge.py
Browser  : /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
Goal mode: enabled: browser_goal and browser_act intents spend model quota; …
Status   : ready
```

`Status: ready` means the browser tools work. `Jev … NOT READY` is expected until a policy key is
configured: only `browser_goal` and `browser_act`'s `intent` need one; everything else works.

To build the environment ahead of time instead of during the first browser call:

```bash
browser-use-mcp install
# or, without a global install:
npx -y @ricardochen1996/browser-use-mcp@latest install
```

That creates `<state root>/env` (default `~/.browser-use-mcp/env`) with the bundled engine wheel and
`browser-harness`, and records what it built in `<state root>/install.json`. It is safe to re-run.
A browser tool that runs before the install finished waits for it instead of failing.

### Put it in front of your agent

The snippets below start the published package through `npx`, so they need no global install.
Replace `npx -y @ricardochen1996/browser-use-mcp@latest` with `browser-use-mcp` (or its absolute
path) if you installed the command. Every client, including launch-mode variants, is wired in
**[docs/clients.md](docs/clients.md)**.

Claude Code:

```bash
# Use the Chrome you already browse with (the default attach mode):
claude mcp add --scope user browser-use \
  -- npx -y @ricardochen1996/browser-use-mcp@latest

# Or give the agent a dedicated, unseen browser instead:
claude mcp add --scope user browser-use \
  --env BROWSER_USE_MCP_MODE=launch --env BROWSER_USE_MCP_HEADLESS=1 \
  -- npx -y @ricardochen1996/browser-use-mcp@latest
```

Generic `mcpServers` JSON (Claude Desktop, Cursor, and most hosts accept this shape):

```json
{
  "mcpServers": {
    "browser-use": {
      "command": "npx",
      "args": ["-y", "@ricardochen1996/browser-use-mcp@latest"],
      "env": { "BROWSER_USE_MCP_MODE": "launch", "BROWSER_USE_MCP_HEADLESS": "1" }
    }
  }
}
```

The `env` block uses launch mode so the example is self-contained; drop it to drive the Chrome you
already use. A client can also run the installed command directly (`"command": "browser-use-mcp"`);
pin a version instead of `@latest` when the whole team should run the same release. A GUI client with
a short `PATH` needs the command's absolute path (`command -v browser-use-mcp`; for Homebrew Node
that is usually `/opt/homebrew/bin/browser-use-mcp`).

Then ask the agent to `browser_open` a URL. A first call on a fresh machine may take a minute or two
while the environment is installed; later calls start at once.

### From source

To run a commit that is not released yet, or to develop:

```bash
git clone https://github.com/ricardochen1996/browser-use-mcp.git
cd browser-use-mcp
npm install
node bin/browser-use-mcp.mjs doctor --mode launch
```

`npm link` in the checkout puts a `browser-use-mcp` command on your `PATH` that runs that checkout.
The published package and a checkout contain the same files; the commands above only differ in
whether `browser-use-mcp` comes from npm or from `node bin/browser-use-mcp.mjs`.

---

## The nine tools

| Tool | Parameters | What it does |
| --- | --- | --- |
| `browser_open` | `url` (required) | Start (or reuse) the session's browser, open the page, return the first action-space table and observation number. |
| `browser_page` | — | Re-read the current page under a **new** observation number. Use it when the page changed on its own, or after a refusal. |
| `browser_act` | `observation` (required), `operation`, `target`, `text`, `intent` | Run one operation on one target from that observation: `CLICK`, `TYPE_TEXT`, `SELECT`, `SCROLL_UP`, `SCROLL_DOWN`, `WAIT`. A stale page is refused with the fresh table. With Jev on, an `intent` (and no operation) delegates that one decision to the policy. |
| `browser_eval` | `expression` (required), `timeout_ms` | Evaluate one JavaScript expression over the session's CDP connection; returns a value as data and produces no observation. Hidden by `--no-eval`. |
| `browser_screenshot` | — | The visible viewport as an MCP image (JPEG). Target boxes are not drawn into it. Hidden by `--no-screenshots`. |
| `browser_console` | — | Console messages, uncaught exceptions, failed requests and `4xx`/`5xx` responses since the last read. Each read drains the buffer. |
| `browser_goal` | `url`, `goal` | Hand one goal to the policy in its own tab; it chooses every operation and target itself. Spends model quota. Hidden by `--no-jev`. |
| `browser_close` | — | Close the session's tab. In launch mode the browser stays for the next `browser_open`; in attach mode the attached browser is never closed. |
| `browser_doctor` | `install` (optional bool) | Self-check: interpreter, engine, browser, attach target, config, live session, and a fix per problem. `install: true` builds a missing environment first. |

A missing policy key, an unsupported target, missing `TYPE_TEXT` text and a stale page are
**refusals** in normal tool results. A broken browser or environment is a failed call (`isError`).
An agent should report a failure, not retry it blindly.

---

## Transports and concurrency

| Transport | What one agent gets | What two agents get |
| --- | --- | --- |
| **stdio** (default) | One server process, one browser session | Two processes; in attach mode both drive the same browser in their own tabs, in launch mode two browsers |
| **Streamable HTTP** | One MCP session, one browser session | One long-running server; attach mode shares the running browser, launch mode gives each session its own tab of a dedicated browser |

Start an HTTP endpoint when several agents should share one installed server:

```bash
browser-use-mcp \
  --transport http --host 127.0.0.1 --port 7331 --path /mcp
```

The endpoint is `http://127.0.0.1:7331/mcp` by default. Each MCP `initialize` session gets its own
browser session; in the default attach mode all of them drive the Chrome you already use (see
`--attach-sharing` below), while `--mode launch` gives every session its own tab of a dedicated
browser. A session that goes quiet for 15 minutes has its browser closed and its anonymous profile
removed (`BROWSER_USE_MCP_HTTP_IDLE_MS` overrides the timeout). There is no authentication: the
default bind is loopback, and a non-loopback bind logs a warning at startup. Put it behind a tunnel
or proxy you control if it must leave the machine.

**Named profiles (launch mode).** In launch mode an anonymous HTTP session gets a throwaway profile
that is deleted when the session ends. A client that wants its logins to survive reconnects names its
profile on the initialize request:

```text
http://127.0.0.1:7331/mcp?profile=claude      (or header X-Browser-Use-Profile: claude)
```

The named profile lives at `<state root>/profiles/<server profile>-<name>` and is kept when the
session ends; the next session with the same name reuses it. Different names run at the same time on
different profiles, and two live sessions with the same name are refused by the profile lock rather
than silently sharing one browser. Names are 1–32 characters from `[A-Za-z0-9_-]`.

Two servers configured for the **same browser profile** are refused rather than silently sharing a
browser: the first holds a lock in the profile directory and the second gets a tool error naming
`--profile` and the fix. A lock left behind by a crashed process is reclaimed.

### Which browser: attach (default) or launch

**`attach` (default)** drives the Chrome you already use:

- With no endpoint, the server finds that browser through the `DevToolsActivePort` Chrome publishes
  in its profile. Turn remote debugging on in that Chrome first
  (`chrome://inspect/#remote-debugging`). On macOS that file is privacy-protected, so the
  application running this server needs **Full Disk Access** (System Settings → Privacy & Security →
  Full Disk Access), then must be restarted.
- **`--cdp-endpoint http://127.0.0.1:9333`** (or a `ws://…` endpoint) drives a specific browser you
  started with remote debugging on.
- `--attach-sharing shared` (default) lets several MCP sessions — and several server processes —
  drive that browser at once, each in its own tab over its own CDP connection. Chrome 144+ asks
  "Allow remote debugging?" once per connection, so two agents mean at least two prompts; approve
  each once and never retry an unanswered one. `--attach-sharing exclusive` refuses the second live
  holder instead, with a fix, which is the safer choice when two agents must never touch the same
  browser.
- `browser_close` stops the session's tab and daemon and never closes the attached browser.

**`--mode launch`** starts a dedicated Chrome with its own profile under the state root, so your
everyday browser and its logins stay out of automation. `browser_close` keeps that browser for the
next `browser_open`; the server closes it when the connection ends. It is the right mode for a
headless CI machine, or for an agent that should not see your real sessions.

---

## Configuration highlights

Every server setting is a flag with an environment-variable twin (the policy uses
`TYPESAFE_*`/`TEXT_MODEL_*`; a couple of extras are environment-only), and the flag wins when both
are present. The exhaustive tables, parsing rules, defaults and exit codes are in
**[docs/config.md](docs/config.md)**.

| Setting | Flag(s) | Env | Default |
| --- | --- | --- | --- |
| Transport | `--transport`, `--host`, `--port`, `--path` | `BROWSER_USE_MCP_TRANSPORT`, `BROWSER_USE_MCP_HOST`, `BROWSER_USE_MCP_PORT`, `BROWSER_USE_MCP_PATH` | `stdio`, `127.0.0.1`, `7331`, `/mcp` |
| Own or attach | `--mode`, `--cdp-endpoint` | `BROWSER_USE_MCP_MODE`, `BROWSER_USE_MCP_CDP_ENDPOINT` | `attach` |
| Attach sharing | `--attach-sharing` | `BROWSER_USE_MCP_ATTACH_SHARING` | `shared` (attach only) |
| Browser window | `--headless` | `BROWSER_USE_MCP_HEADLESS` | visible window |
| Profile | `--profile`, `--user-data-dir` | `BROWSER_USE_MCP_PROFILE`, `BROWSER_USE_MCP_USER_DATA_DIR` | `default` under the state root |
| State root | `--home` | `BROWSER_USE_MCP_HOME` | `~/.browser-use-mcp` |
| Interpreter | `--python` | `BROWSER_USE_MCP_PYTHON` | managed environment |
| Tool surface | `--no-eval`, `--no-screenshots`, `--no-jev` | `BROWSER_USE_MCP_NO_EVAL`, `…_NO_SCREENSHOTS`, `…_NO_JEV` | all tools offered |
| Policy | `--jev-decider` and the `--typesafe-*` / `--text-model-*` flags | `JEV_DECIDER`, `TYPESAFE_*`, `TEXT_MODEL_*` | `typesafe` decider |
| Request budget | `--request-timeout-ms` | `BROWSER_USE_MCP_REQUEST_TIMEOUT_MS` | `180000` ms |
| Logging | `--log-level` | `BROWSER_USE_MCP_LOG_LEVEL` | `info`, always stderr |

State root layout:

```text
~/.browser-use-mcp/
├── env/                        managed Python virtualenv (engine + browser-harness)
├── install.json                what was installed, with which strategy and Python
├── profiles/<name>/            launched Chrome profiles (logins, tabs); named HTTP profiles too
└── attachments/<hash>.lock     exclusive attach-mode claims, one per DevTools endpoint
```

### The Jev policy

`browser_goal` runs a whole decision loop inside the engine; `browser_act` with an `intent` (and no
operation) delegates exactly one decision to the same policy. Both spend model quota. Who answers
is configuration:

- **`--jev-decider typesafe`** (default): Jev at the TypeSafe endpoint. Needs `TYPESAFE_API_KEY`;
  optional `TYPESAFE_BASE_URL`, `TYPESAFE_MODEL`, `TYPESAFE_FALLBACK_URL`.
- **`--jev-decider chat`**: the engine serves its System One protocol on loopback and a chat model
  answers it. Needs `TEXT_MODEL_BASE_URL` and `TEXT_MODEL` (plus `TEXT_MODEL_API_KEY` if the
  endpoint needs one).

`TEXT_MODEL_*` is also what writes a `TYPE_TEXT` value when the agent gives an intent but no text.
Without either setup the rest of the tool surface is unchanged; the policy tools refuse with one
sentence naming the variable to set. `--no-jev` withdraws `browser_goal` and the `intent` parameter
entirely.

Put credentials in the client's `env` block (or the flags), never in `args`:

```json
"env": {
  "TYPESAFE_API_KEY": "…",
  "TEXT_MODEL_BASE_URL": "https://your-endpoint/v1",
  "TEXT_MODEL": "your-model",
  "TEXT_MODEL_API_KEY": "…"
}
```

The server passes those variables only with the request that spends quota, never leaves them in the
sidecar's environment, and the doctor prints `set`/`unset` instead of a value.

---

## Troubleshooting

**Start with `browser_doctor`.** The tool and the CLI run the same self-check; each problem line
carries the command that fixes it.

```bash
browser-use-mcp doctor
```

- **A profile is already in use.** The message names the profile and `--profile`: stop the other
  server, or give this one its own `--profile <name>`. Two servers driving one browser profile is
  the one configuration the server refuses on purpose.
- **Attach mode cannot find the browser.** This is the default mode: open
  `chrome://inspect/#remote-debugging` in the Chrome you use and allow remote debugging, correct
  `--cdp-endpoint`, or start the server with `--mode launch` for a dedicated browser. The doctor
  reports `attach mode drives …` with the reason. On macOS, allowing this app Full Disk Access is
  what lets it read your Chrome's profile.
- **The engine is not installed yet.** The first use installs it into the state root; run
  `browser-use-mcp install` (or `npx -y @ricardochen1996/browser-use-mcp@latest install`) to do it
  eagerly, or `browser_doctor` with `install: true` from the agent. Behind a proxy, set
  `HTTPS_PROXY` for the process that runs the server.
- **`Jev … NOT READY`.** Set `TYPESAFE_API_KEY` (or use `--jev-decider chat` with `TEXT_MODEL_*`).
  The browser tools do not need it.
- **No tools in the client.** The client's `env`/`args` did not reach the server, or it was not
  restarted. Run the same command in a terminal and read stderr; a configuration error exits with
  code `2` and names the field.
- **Chrome asks "Allow remote debugging?".** Something started a second CDP client. Approve that one
  prompt once, never retry, and use `browser_eval` instead of another driver.
- **`browser_eval('document.body')` returns `{}`.** A DOM node cannot cross the CDP boundary by
  value. Return something serialisable instead, for example `document.body.innerText` or
  `JSON.stringify(document.body.getAttribute('class'))`.

---

## Security notes

- **Page content is untrusted data.** Text the table quotes is something to read, never an
  instruction to follow. The server never executes anything a page returns on the agent's behalf.
- **`browser_eval` is code execution by design.** It runs one expression in the page, over the
  session's own connection, with no user gesture. Withdraw it with `--no-eval` for a surface where
  model output can never become code; the rest of the tools still work.
- **The HTTP transport has no authentication.** Bind it to loopback (the default). Any non-loopback
  bind is logged as a warning; only expose it on a trusted network or behind a tunnel you control.
- **Keys stay out of logs and tools.** The doctor prints only `set`/`unset`; credentials are handed
  to the sidecar per model-spending request and are not inherited by unrelated calls.
- **The default mode drives your own Chrome**, logins included — that is what attach mode is for.
  Use `--mode launch` when an agent should work in an isolated browser whose profile lives under the
  state root instead.
- **One connection, one driver.** Do not start another CDP client against the same browser; Chrome
  approves each connection separately and two drivers race each other.

---

## License and attribution

MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

This project is built on [`dsh-browser-use`](https://github.com/ricardochen1996/dsh-browser-use)
(MIT): `sidecar/bridge.py` is vendored from it, and the action-space rendering, the freshness rule,
the one-connection rule and the direct-mode tool descriptions follow it. The browser engine is
[`jev-ultrafast`](https://github.com/ricardochen1996/jev-ultrafast) (MIT), bundled as a pinned wheel;
browser access is [`browser-harness`](https://github.com/browser-use/browser-harness) (MIT). The
design and rationale are in [docs/architecture.md](docs/architecture.md).

## Development

```bash
npm test            # fast unit tests (node --test)
npm run test:e2e    # real headless Chrome through the real MCP protocol
                    # (stdio, HTTP, attach mode, Jev intent against a loopback stub,
                    #  and a hand-written JSON-RPC client)
npm run test:e2e:local  # the same suites on this machine, inside a temporary state root with a
                        # --no-sandbox Chrome wrapper (works in sandboxes; `-- http attach` picks suites)
npm run release:check  # manifest + changelog + the exact packed file list
npm run release:pack   # build the tarball, verify it and record its integrity in dist/
npm run doctor      # the CLI self-check
```

The default suites spend no model calls and need no credentials; the e2e tests install the engine
into a test state root on their first run. `npm run test:e2e:local` supplies its own
`BROWSER_USE_MCP_TEST_HOME`, `BH_RUNTIME_DIR` and `BROWSER_USE_MCP_TEST_CHROME`, so it needs no
environment setup and leaves no browser or daemon behind.

CI runs the unit matrix on Node 22.19 and 24 plus the release gate for every push and pull request;
the real-browser e2e job runs on `main` and for a release. Each e2e suite is retried once when it
fails on timing (the failure is annotated first), while a unit test is never retried: that is a
defect, not a flake. Release history is in [CHANGELOG.md](CHANGELOG.md).

**Releases** are tagged `vX.Y.Z` on `main`; the [release workflow](.github/workflows/release.yml)
validates the annotated tag against `package.json`, reruns CI (unit plus real-browser e2e), publishes
to npm with provenance, and creates the GitHub Release with the verified tarball attached. It accepts
either an `NPM_TOKEN` repository secret (an automation or publish-capable granular token) or npm
**Trusted Publishing**: name this repository and `.github/workflows/release.yml` as the package's
trusted publisher and the OIDC token of the job is used instead. An already-published version is
skipped, so a re-run only refreshes the GitHub Release. Bump the version, add its `CHANGELOG.md`
section, then `git tag -a vX.Y.Z -m "vX.Y.Z"` and push the tag.

---

[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

TDQS

A4/5.0

Scored across 9 tools

Disambiguation4/5

Tools mostly target distinct browser operations: open, re-observe, act, evaluate, screenshot, console, goal, close, and doctor are separable. The main overlap is browser_act's intent mode versus browser_goal, both policy-driven model actions, though goal is scoped to its own tab and an overall objective.

Naming Consistency4/5

All tools use a consistent browser_ prefix, making them easy to recognize as one family. Suffixes mix nouns (browser_page, browser_screenshot, browser_console) and verbs (browser_open, browser_close, browser_act), which is a minor deviation but still readable and predictable.

Tool Count5/5

Nine tools is well-scoped for a browser automation server. Each tool covers a meaningful part of the browser-control lifecycle without obvious redundancy or filler.

Completeness4/5

The surface covers opening, observing, acting, evaluating JavaScript, screenshotting, console inspection, autonomous goals, closing, and diagnostics. Minor gaps exist around explicit navigation/history controls such as back, forward, or direct URL navigation separate from browser_open, but core workflows are covered.

Maintenance

ActivityMaintained
ResponsivenessOutdated data