web-ui-tester

AIがWebページを高速に操作・調査できるようにするMCPサーバーです。ブラウザセッションはツール呼び出し間も維持されます。

高速である理由は2つあります。ページはスクリーンショットや生のHTMLではなく、要素参照を備えたアクセシビリティツリーとして公開されます。これにより、モデルはマークアップでコンテキストを消費したりビジョンAIを待ったりせずに、要素を見つけてクリックできます。また、セッションは永続化されます。cookie、ページ状態、履歴が呼び出しをまたいで保持されるため、長い対話も毎回コールドスタートの繰り返しではなく、小さなステップの連続になります。

さらに、DevTools並みの診断情報（コンソール、レスポンス本文を含むネットワーク、JS評価、計算済みスタイル）を取得できるため、AIは「壊れている」という事実だけでなくなぜ壊れているのかを突き止められます。

クイックスタート

claude mcp add web-ui-tester -- npx -y web-ui-tester

組み込みエージェント用のキーがある場合（run_taskを参照）：

claude mcp add web-ui-tester \
  -e GOOGLE_GENERATIVE_AI_API_KEY=your-key \
  -- npx -y web-ui-tester

または、任意のMCPクライアントの設定ファイルで：

{
  "mcpServers": {
    "web-ui-tester": {
      "command": "npx",
      "args": ["-y", "web-ui-tester"],
      "env": { "GOOGLE_GENERATIVE_AI_API_KEY": "your-key" }
    }
  }
}

ChromiumはPlaywrightから取得されます。まだインストールされていない場合：

npx playwright install chromium

セッションの仕組み

browser_start          → sessionId, kept alive across calls
browser_navigate       → page state + snapshot with [ref=eN] handles
browser_click ref=e12  → act on what the snapshot showed you
browser_snapshot       → fresh refs after the page changes
browser_close          → done (or let it idle out after 30 minutes)

browser_start 以降は、すべてその sessionId を使います。スナップショットもこれに慣れることが大切です：

- generic [ref=e1]:
  - heading "Signup" [level=1] [ref=e2]
  - textbox "Name" [ref=e5]:
    - /placeholder: Your name
  - combobox "Plan" [ref=e7]
  - button "Create account" [ref=e10]
  - link "Go to second page" [ref=e12] [cursor=pointer]:
    - /url: /second.html

これらのrefは、そのまま browser_click、browser_type などに渡せます。refはそれが生成されたページ状態に紐づいています。遷移やDOMの変更後は、再度スナップショットを取得してください。ツールがrefの無効を通知したときは、リトライではなくスナップショットを再取得しましょう——メッセージにもその旨が明示されます。

要素を指定するツールでは、セレクタをすでに知っていてスナップショットを省略したい場合は、css または role + name も受け付けます。

ツール

セッション — browser_start（オプション: userAgent、viewportWidth、viewportHeight、headless、baseUrl、url、model）、browser_list、browser_close。

操作 — browser_navigate、browser_click、browser_type、browser_press_key、browser_hover、browser_select_option、browser_scroll、browser_wait_for、browser_go_back、browser_handle_dialog。

各操作は、起きた結果（ナビゲーション、新しいコンソールエラー、リクエスト数、表示されたダイアログなど）を結果として報告します。つまり、クリックが静かに何かを壊しても、それが成功のように見えることはありません。

ダイアログには注意が1点必要です。alert/confirm/prompt は答えるまでページをブロックするため、ダイアログを開いたアクション自体が答えることはできません。未回答のダイアログはクリックを止める代わりに自動的に閉じられ、その旨が結果に表示されます。ダイアログを受け入れる場合、または prompt に値を入力する場合は、そのダイアログを発生させるアクションの前に browser_handle_dialog を呼び出してください。その回答が、次のダイアログで使用されます。

調査 — browser_snapshot（要素によるスコープ指定、depth 制限、interactiveOnly、offsetページング対応）、browser_query（role/name、テキスト、またはCSSで検索し、refと状態を返す）、browser_read_text（ページまたはツリーの表示テキスト）、browser_screenshot（利用可能ですが、通常はツリーのほうが適しています）。

診断 — browser_console（スタック付きの未処理エラーを含むメッセージ）、browser_network（ステータス、サイズ、タイミング）、browser_request_detail（ヘッダー、タイミング内訳、リクエスト・レスポンス本文）、browser_evaluate（ページ上でJSを実行）、browser_inspect_element（計算済みスタイル、ボックスモデル、フォーム状態）。

すべての結果は文字数上限で制限されますが、大きな結果（browser_snapshot、browser_read_text、本文）は黙って切り捨てず、offset によるページングができます。

組み込みエージェント

run_task は、ブラウザを自分で操作して報告する高速なモデルにセッションを渡します：

run_task(sessionId, "Log in as demo@example.com / hunter2 and check the
                     dashboard loads without errors")

レポートこそ重要です。 単なる文章ではなく、構造化された判定を返します：

status: success
model: google:gemini-flash-lite-latest

Logged in and opened the dashboard. The revenue widget rendered empty.

findings (3):
  [error] Request failed: GET 500 [observed by the harness]
      where: https://app.example.com/api/revenue
      evidence: HTTP 500
  [error] Console exception on the page [observed by the harness]
      where: app.js:214:9
      evidence: TypeError: Cannot read properties of undefined (reading 'total')
  [warning] The revenue widget shows no empty state, just blank space
      where: #revenue-card
      evidence: card is present but contains no text

検出結果は2つの情報源から得られ、その区別が重要です。エージェントは進行中に report_finding を呼び出すため、ステップ上限に達した実行でも、その時点までに見つけたすべての情報が返されます。一方で、ハーネスは実行中のすべてのコンソールエラー、失敗したリクエスト、ダイアログを記録し、それらをエージェントが言及したかどうかには関係なく、[observed by the harness] というラベル付きで報告します。モデルが500エラーを見逃したり、例外に触れ忘れたりしても、隠すことはできません。

同じレポートは、宣言された出力スキーマに基づいて structuredContent としても返されるため、呼び出し元のAIはテキストを解析せずに、findings[].severity で分岐できます。タスクは成功してもfindingsが存在する場合があります。success は「タスクが達成されたかどうか」を示すものであり、「ページがクリーンかどうか」ではありません。

APIキーが必要なのはこの部分だけです。レイテンシを優先し、デフォルトはGemini Flash Liteです。Anthropicでも使えます。

WUT_MODEL を設定して選択します（anthropic、google:gemini-flash-latest、任意の provider:modelId）。セッションでは browser_start の model で、特定の呼び出しでは run_task の model で上書きできます。その他のツールはすべてキーなしで動作します。

HTTPモード

web-ui-tester --port 7399
claude mcp add --transport http web-ui-tester http://127.0.0.1:7399/mcp

このモードでは、ブラウザセッションはクライアント側ではなく長期間起動しているサーバーに存在するため、クライアントの再起動や再接続をまたいでセッションが生存します。同じ sessionId を渡せば、ページはそのまま存在します。GET /health でセッション数と接続数を確認できます。

デフォルトでは 127.0.0.1 にバインドされ、DNSリバインディング保護が有効です。--host で範囲を広げると、サーバーが警告します。認証はなく、ポートに到達できる人は誰でもブラウザを操作し、JavaScriptを実行できるため、プロキシやファイアウォールの背後に置いてください。

設定

CLIフラグ: --port、--host、--headless / --no-headless、--idle-timeout、--version、--help。

Playwrightが期待するChromiumリビジョンがインストールされていなくても、他のものが見つかればサーバーは失敗せずにそれを使います。プリビルドコンテナで便利です。WUT_EXECUTABLE_PATH を設定すると検索は完全に上書きされます。

開発

npm install
npm run build
npm test          # agent loop (mocked model) + full end-to-end suite
npm run typecheck

npm test は、スクリプト化されたモックモデルでエージェントループを実行し、次に実際のMCPクライアントとしてビルド済みサーバーを両方のトランスポートでローカルフィクスチャアプリに対して駆動します。スタイル、スタイル-ref処理、診断、再接続をまたいだセッション永続化、アイドル・リーピングなどをカバーします。npm run test:agent:live はさらに実プロバイダーに対して run_task を実行し、キーが設定されていない場合は自動的にスキップします。

ライセンス

MIT