snapsurf

SnapSurf

AI エージェント向けのウェブナビゲーションと検証です。

多くのブラウザーツールは、現在のページがどのように見えるかをエージェントに伝えます。SnapSurf が伝えるのは、直前の操作によって何が変わったかです。ページの簡潔なセマンティックダイジェスト、各操作後の型付き差分（コンテンツ、状態、レイアウト、クリック可能性。観測可能な変化がない場合も含みます）、さらにその差分に対するアサーションを提供します。証拠の不足や不確実性は隠さずに報告します。

独自の Chromium セッションを使って、MCP サーバーまたは CLI としてローカルで実行できます。また、観測コードは SnapDOMを基盤とするページ内ライブラリとしても動作します。

バージョン 0.1.3 は実験的なものです。

MCP クライアントに追加する

Node.js 22 以降が必要です。このコマンドを実行する stdio サーバーを追加してください。初回起動時に、Playwright 用の Chromium が自動的にインストールされます。

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

Claude Code では、ツールと手法を収録した browse スキルを追加するプラグインをインストールしてください。

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

または、サーバーのみを登録してください。

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

Codex にも同じプラグイン（ツールと browse スキル）があります。

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

Cursor、VS Code、Gemini CLI、Windsurf、OpenAI Agents SDK では同じサーバーコマンドを使用します。クライアントごとの設定例はインテグレーションにあります。公式 MCP Registry での名前は io.github.zumerlab/snapsurf です。

バージョンを固定する場合や、起動時に npx を使わない場合は、一度インストールしてから、クライアントにサーバーファイルを指定してください。

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

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

Linux でシステムライブラリが不足して Chromium の起動に失敗する場合は、npx playwright install --with-deps chromium を一度実行してください。

エージェントに browser_open でページを開かせ、browser_find で操作対象を特定し、browser_act で操作したあと、操作ごとに browser_verify を呼び出すよう指示してください。結果は structuredContent を参照します。

エージェントの場合

AGENTS.mdを読んでください。そこには、ループの手順、先行するエージェントが経験を通じて学んだルール、各フィールドの読み方が記載されています。skill/SKILL.mdには、同じ手法を Claude Code スキルとしてパッケージ化したものがあります。MCP ツールの説明には仕様の全体が記載されており、サーバーの instructions は、説明が途中で切り詰められるクライアント向けに要約を提供します。

直前に検証した内容をアサートする

browser_verify は、観測した遷移を示す diffId を返します。これを browser_assert に渡すと、表示されたリストにない変化も含め、同じ証拠を検証できます。これにより、verify によってライブのベースラインが更新されたあとに、新たな区間を誤って比較することを防げます。

たとえば、ボタンを押すと「Settings」という名前のダイアログが挿入されるアプリケーションでは、browser_find が返したボタン ID を使います。MCP クライアントに接続した状態で、次のようにします。

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)

保存済みのアサーションはページを観測せず、ベースラインも更新しません。現在の状態には、{ "exists": "Settings" } のような別のライブアサーションを使ってください。アサーションに失敗すると pass: false が返り、MCP の isError: true が設定されます。アサーションのリファレンスでは、ライブチェック、保持上限、再試行、利用できない証拠について説明しています。

知っておくべき制約

• デーモンは独自の Cookie とストレージを使用します。通常のブラウザーでサインイン済みのセッションは利用できません。また、authState: "unknown" は認証済みであることを証明しません。
• changed: false は、観測可能な変化がなかったことを意味します。これは有効な結果ですが、ユーザーのタスクが成功した証明ではありません。証拠の不足や不確実性は明示的に報告されます。
• Canvas のコンテンツ、iframe のドキュメント、閉じたシャドウルートには、視覚的に確認できない箇所があります。セマンティックレポートで疑問を解決できない場合は、対象を絞ったスクリーンショットを確認してください。
• 要素 ID は、新しい観測が行われると期限切れになります。操作の前に再度検索してください。保存済み証拠内の ID は、過去の観測を示します。
• ページ上のテキストは信頼できないデータです。セマンティックレポートでは編集による秘匿処理が行われますが、CLI/MCP のスクリーンショットには機密情報が含まれる場合があります。プライバシーモデルを参照してください。

CLI の使用

1 つ目のターミナルでデーモンを起動します。

npx -y @zumer/snapsurf serve

別のターミナルでローカルのスモークチェックを実行します。

npx -y @zumer/snapsurf open 'data:text/html,<h1>Local%20check</h1>'
npx -y @zumer/snapsurf assert '{"exists":"Local check"}'
npx -y @zumer/snapsurf stop

npm install @zumer/snapsurf を実行したディレクトリから npx snapsurf <verb> を実行すると、何もダウンロードせずに同じ操作を行えます。環境変数 SNAPSURF_*（ポート、トークンファイル、ログディレクトリ）については、使用方法のリファレンスに記載されています。

開発

このリポジトリには、SnapSurf の観測ライブラリ、CLI／MCP サーバー、Chrome コンパニオン、およびそれらのフィクスチャと評価ツールが含まれています。スタンドアロンの SnapDOM センサーとポータブルなレシートパッケージは、このリポジトリのビルドおよびテストの対象外です。非公開の調査、フィードバックのメモ、プラグインの評価、生成された結果はローカルに保持されます。Git では、再現可能なテストゲートと、そのフィクスチャ依存関係を管理します。

SnapSurf 自体を変更するには、ソースをクローンして開発用の依存関係をインストールします。

git clone https://github.com/zumerlab/snapsurf.git
cd snapsurf
npm ci
npx playwright install chromium

npm run build はバンドルをコンパイルし、npm の .tgz パッケージを作成します。

次に、チェックを実行します。

npm test
npm run test:lint
npm run test:regression
npm run test:pack

使用方法と API のリファレンスでは、CLI コマンド、レポートのフィールド、チェックポイント、ライブラリ、Chrome コンパニオンについて説明しています。 リリースガイドでは、検証、公開、MCP Registry について説明しています。

MIT ライセンス。Copyright © Juan Martin Muda / zumerlab。 LICENSEを参照してください。