Snapsurf MCP server

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.2 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:

{
  "command": "npx",
  "args": ["-y", "-p", "@zumer/snapsurf@latest", "snapsurf-mcp"]
}

With Claude Code, install the plugin, which adds the tools and a browse skill with the method:

/plugin marketplace add zumerlab/snapsurf
/plugin install snapsurf@zumerlab

or register the server alone:

claude mcp add --scope user snapsurf -- npx -y -p @zumer/snapsurf@latest snapsurf-mcp

Codex has the same plugin (tools plus the browse skill):

codex plugin marketplace add zumerlab/snapsurf
codex plugin add snapsurf@zumerlab

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:

mkdir snapsurf && cd snapsurf
npm install @zumer/snapsurf

{
  "command": "node",
  "args": ["/ABS/PATH/snapsurf/node_modules/@zumer/snapsurf/mcp/server.mjs"]
}

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 browseropen, locate controls with browserfind, act with browseract, then call browserverify 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

browserverify returns a diffId for the observed transition. Pass it to browserassert 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:

await client.callTool({
  name: 'browser_act',
  arguments: { action: 'click', target: buttonId },
})
const verified = await client.callTool({ name: 'browser_verify', arguments: {} })
const { diffId } = verified.structuredContent
if (!diffId) throw new Error('No retained diff; inspect the verify result')

const checked = await client.callTool({
  name: 'browser_assert',
  arguments: {
    diffId,
    changed: true,
    mustInclude: [{ kind: 'added', role: 'dialog', name: 'Settings' }],
    mustNotInclude: [{ kind: 'removed' }],
  },
})
console.log(checked.structuredContent.pass, checked.structuredContent.checks)

Shortened. The full README is on GitHub.