jev-ultrafast-mcp

English · 简体中文

Hand the browser work off — an MCP server that drives the page for your agent.

Your agent should not be opening the browser at all. A browser task goes over whole — the URL, the goal, and the check that proves it — and the loop runs on the server. One tool call instead of twenty. Three seconds instead of a minute. A cent instead of a frontier model's context. And it never invents a target: it picks from what the page actually has, and the server refuses rather than guesses.

What it cost. A cent for the whole day, and a cent is all of it:

Quick start

Three commands, then restart your client.

git clone https://github.com/jiawei686/jev-ultrafast-mcp.git
cd jev-ultrafast-mcp
python3 -m venv .venv
.venv/bin/pip install -e .          # Windows: .venv\Scripts\pip install -e .

python scripts/install.py           # finds your MCP clients and writes their config

install.py looks for WorkBuddy, Claude Code, Claude Desktop, Codex CLI, Cursor, VS Code, Cline, Windsurf and Gemini CLI, and writes the format each one expects — merging into your existing config and saving a .bak first. Needs Python ≥ 3.10 and any Chromium-family browser.

Restart the client, and then just say what you want:

You: Set this form to 3 adults, tick Nonstop only, then submit it. Your agent: browser_goal(goal=…, url=…, verify=[…]) — one call; the page is opened and the loop runs server-side, and the result is checked by code afterwards. (what that costs)

You: Open example.com and tell me what the page says. Your agent: browser_open → reads the element table → answers — a look is not a task, so it does not need the model. (verbatim run)

Restarted and the tools are not there? Some clients make you approve the server once. In WorkBuddy that is Connectors → Custom connectors → Trust. The approval is remembered against the config itself, so if you later edit the config it asks once more.

Installation

No checkout needed if you would rather install it as a package. It is on PyPI, so the name is enough:

uvx jev-ultrafast-mcp                  # run it straight from PyPI, nothing installed
pip install jev-ultrafast-mcp          # or install it yourself

A client config wants a stable interpreter path rather than uvx's cache, so:

python3 -m venv ~/.jev-ultrafast-mcp/venv
~/.jev-ultrafast-mcp/venv/bin/pip install jev-ultrafast-mcp

That gives you a jev-ultrafast-mcp console script and a stable interpreter path to put in a client config — verified against the latest mcp SDK on Python 3.13, every one of the ten tools listed.

scripts/install.py is the other half: it finds your MCP clients and writes the config each one expects, merging into the existing file and saving a .bak first.

python scripts/install.py --list              # what is installed, and the file each one reads
python scripts/install.py --print             # show the config it would write, change nothing
python scripts/install.py -c cursor,codex     # only these two
python scripts/install.py --headed            # keep a visible browser window
python scripts/install.py --allow-domains example.com,*.example.org
python scripts/install.py --uninstall         # take the entry back out

Runtime dependencies: mcp, websockets, httpx. No Playwright, no Selenium, no browser-harness.

Cheap and fast, and here is the bill

A three-step goal on a real page, driven by browser_goal. This is everything your agent sent and everything it got back — one turn, and the page never entered its context:

browser_goal(
  goal="On this flight search form: set Passengers to 3 adults, tick the 'Nonstop only' "
       "checkbox, then submit the search. Do not type into any city field.",
  verify=[{"type": "text_contains", "text": "3 adults · nonstop"}],
)

goal: On this flight search form: set Passengers to 3 adults, …
status: done
steps: 3
turbo: 4 decisions · 14,626 tokens · 1.8s model + 1.1s page · 3.3s wall
trace:
  1. SELECT e6 Passengers → ok (759ms model / 30ms browser)
  2. TOGGLE e7 Nonstop only → ok (336ms model / 692ms browser)
  3. CLICK e8 Search → ok (370ms model / 410ms browser)
  4. DONE (conf 0.93)
verified: PASS
  ok text_contains: '3 adults · nonstop' found in page text

What the second time costs. Nothing. The second time is a recorded macro, and a macro makes no model calls at all — it does not even need a key.

How long it took. 3.3 s wall for the whole goal: 1.8 s of model, 1.1 s of page. Every run prints that line itself, so the numbers are checkable rather than persuasive.

That run is not a mock-up. scripts/turbo_check.py reproduces it against a real Chrome and the real model, and then checks the page with code rather than trusting the model's account of its own work. The three actions — plus the reading and re-reading between them — all happened on the server. Your agent spent one turn and never saw an element table.

The division of labour is the whole design decision, so it is yours to make per task:

What it is

Browser automation usually makes the agent do the driving: read the page, pick one element, act, read again to see whether that worked. Ten clicks is ten turns, the page passes through the agent's context every time, and a mis-click rarely announces itself.

This server can take that job instead. browser_goal is one tool call from your agent; the loop runs here, server-side, with Jev — TypeSafe's decision model — choosing each step. The model never writes a selector: it picks among the elements the page actually has, and the server refuses anything that is not on the page rather than guessing. When it stops, browser_assert checks the page it left behind in code, and a passing assertion outranks the model's own account of what it did.

Four things follow from that:

• One call, not one per click. The run above took a 3-step goal on a real page through 4 decisions, 14,626 tokens, 1.8 s model + 1.1 s page, 3.3 s wall — for one turn of your agent's context.
• Accurate by construction. A target is a ref from a numbered table of what is on the page, not a selector or a coordinate the model invented, and the action is re-checked against the page before it runs.
• Free after the first run. Record the path once; replay costs zero model calls, works with no key at all, and refuses to proceed when the page no longer matches.
• Text, not pixels. No screenshots, no HTML dumps. It speaks CDP straight to a Chrome you already have — no Playwright, no Selenium, no screenshot pipeline.

Everything except browser_goal — browser_open, browser_observe, browser_act, browser_assert, browser_macro — needs no key, no account, and no network beyond the page itself, from any MCP client: WorkBuddy, Claude Code, Codex, Cursor or VS Code. If you would rather keep your hands on the wheel, that whole surface is still here.

browser_open  →  element table  →  browser_act [refs]  →  browser_assert

Inspired by browser-use/jev-ultrafast and TypeSafe's typed-question API. Independent project, not affiliated with either — see docs/DESIGN.md for what is different and why.

Contents · Quick start · Cheap and fast · What it is · What a session looks like · Connecting an agent · What you can ask it to do · What the agent reads · Why another browser MCP? · Tools · Configuration · FAQ · Try it without an agent · See also

What a session actually looks like

You say:

Open example.com and tell me what the page says.

Your agent does this, and this is everything it sees:

browser_open("https://example.com")
  [obs#1] https://example.com/  "Example Domain"  scroll=0/216  reachable=1/1
  e1   lnk    More information...

browser_observe()
  [delta#2] … 1 element
    = no change (1 element)