zumerlab/snapsurf

Web navigation and verification for AI agents.
Most browser tools tell an agent what a page looks like now. SnapSurf tells it **what
its last action changed**: a compact semantic digest of the page, a typed diff after
each action (content, state, layout and clickability, including when nothing observable
changed), and assertions over that exact diff. Missing evidence and uncertainty are
reported, not hidden.
It runs locally as an MCP server or CLI with its own Chromium session. The observation
code also works as an in-page library built on
SnapDOM.
Version 0.1.3 is experimental.
Add it to your MCP client
Requires Node.js 22 or newer. Add a stdio server that runs this command; Chromium for
Playwright is installed automatically the first time it starts:
With Claude Code, install the plugin, which adds the tools and a browse skill with the
method:
or register the server alone:
Codex has the same plugin (tools plus the browse skill):
Cursor, VS Code, Gemini CLI, Windsurf and the OpenAI Agents SDK take the same server
command; per-client snippets are in Integrations. Its name in the
official MCP Registry is io.github.zumerlab/snapsurf.
To pin a version or avoid npx at startup, install once and point the client at the
server file:
On Linux, if Chromium fails to start for lack of system libraries, run
npx playwright install --with-deps chromium once.
Ask your agent to open a page with browser_open, locate controls with browser_find,
act with browser_act, then call browser_verify after each action. Read
structuredContent for the result.
If you are an agent
Read AGENTS.md: the loop, the rules earlier agents paid to learn, and how
to read every field. skill/SKILL.md is the same method packaged as a
Claude Code skill. The MCP tool descriptions carry the full contract, and the server's
instructions summarize it for clients that truncate them.
Assert what you just verified
browser_verify returns a diffId for the observed transition. Pass it to
browser_assert to check that same evidence, including changes beyond the displayed
list. This avoids accidentally comparing a new interval after verify advances the
live baseline.
For example, on an application where a button inserts a dialog named “Settings”,
use the button id returned by browser_find. With a connected MCP client:
A stored assertion does not observe the page or advance its baseline. Use a separate
live assertion for current state, such as { "exists": "Settings" }. Failed
assertions return pass: false and MCP isError: true. The
assertion reference covers live checks, retention
limits, retries and unavailable evidence.
Boundaries to know
- The daemon has its own cookies and storage. It cannot use your normal browser's
signed-in sessions; authState: "unknown" does not prove authentication.
- changed: false means no observable change. It is a valid result, not proof that
the user's task succeeded. Missing evidence and uncertainty are reported explicitly.