jev-ultrafast-mcp

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)

Then it answers. No screenshot was taken, no HTML was dumped, and the page never entered a model's context: your agent read the table and answered.

A more realistic one — searching a real site, with your agent doing the driving:

browser_open("https://duckduckgo.com")

e4 cmb* Search with DuckDuckGo ▸ ""

browser_act([{type, ref: "e4", text: "python asyncio tutorial"}, {keys, key: "Enter"}]) → 2/2 ops ok, one round trip, page navigated

browser_observe() [delta#3] https://duckduckgo.com/?…&q=python+asyncio+tutorial reachable=9/59

• e5 lnk Python Asyncio Tutorial
• e6 lnk Async IO in Python: A Complete Walkthrough … 43 new, 0 changed, 0 gone

browser_assert([{url_contains, text: "q="}, {count_at_least, role: "link", min: 5}]) PASS

That is a verbatim run against the live web — scripts/live_check.py reproduces it end to end.

---

Connecting an agent

Manual setup — if you would rather not run the installer

Every client below needs the same three facts: an absolute interpreter path, the module, and one environment