Snapsurf

What snapsurf MCP server does

snapsurf MCP server provides browser navigation and verification for AI agents through a local Chromium session. Rather than returning only a snapshot of the current page, it records the transition caused by an action and describes observable differences in content, state, layout, and clickability. A result can also explicitly report that no observable change occurred or that evidence is unavailable.

The server fits the Browser Automation category and is useful for workflows where an agent must confirm that a click, input, or other browser action produced a specific result. It can run as an MCP server or through the accompanying command-line interface. The observation code can also be used as an in-page library built on SnapDOM.

How it works

A typical agent loop opens a page with browser_open, searches for controls with browser_find, performs an operation with browser_act, and then calls browser_verify. Verification returns structured content describing the latest transition and may include a diffId. That identifier can be supplied to browser_assert to check the exact retained evidence without observing the page again or moving the live baseline forward.

Assertions can test whether something changed, require specified additions such as a dialog, or reject specified removals. A separate live assertion can check current page state. Failed checks report pass: false and return an MCP error. Element identifiers belong to an observation and can expire after a new observation, so agents should locate controls again when needed.

Setup and configuration

The snapsurf MCP server requires Node.js 22 or newer. A standard stdio configuration can run it through npx:

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

Chromium for Playwright is installed automatically on first startup. On Linux systems missing required libraries, install Chromium and its dependencies with npx playwright install --with-deps chromium. To avoid downloading at startup or to pin a package version, install @zumer/snapsurf locally and point the client at mcp/server.mjs.

The package also supports a CLI daemon. Start it with npx -y @zumer/snapsurf serve, then use commands such as open, assert, and stop from another terminal. The README refers to SNAPSURF_* settings for the port, token file, and log directory, but does not list the individual variable names.

Tools and capabilities

• browser_open opens a page in the managed Chromium session.
• browser_find locates controls for later actions.
• browser_act performs browser actions against a located target.
• browser_verify produces a semantic digest and typed diff for the latest transition.
• browser_assert checks retained evidence or evaluates current state.

Reports distinguish content, state, layout, and clickability changes. They can include structured content for programmatic handling, including assertion results and retained diff identifiers.

Limitations and notes

The snapsurf MCP server uses its own cookies and storage, so it cannot reuse signed-in sessions from a user's normal browser. An authState value of unknown is not proof that authentication succeeded. Canvas content, iframe documents, and closed shadow roots may not be fully represented in semantic reports; a scoped screenshot may be needed in those cases.

A changed: false result means that no observable change was detected, not that the requested task succeeded. Page text is treated as untrusted data. Semantic reports support redaction, but screenshots from the CLI or MCP server may still contain sensitive content. Version 0.1.3 is experimental.