ui-debugger-mcp

UI Debugger MCP

UI を自律的にデバッグする MCP サーバーです。アプリを書いた AI がテストも行うため、人間がすべてのフローをクリックして確認する必要はありません。

問題

AI コーディングエージェント（Claude など）は、コードを書くのは得意ですが、UI が実際に動作するかどうかを判断するのは苦手です。バックエンドのコードにはユニットテストや統合テストがあります。UI の場合は、今でも人間がアプリを開いてログインし、操作して、問題を報告する必要があります。このヒューマン・イン・ザ・ループは遅く、退屈で、製品全体を AI が構築する際の主なボトルネックです。

アイデア

MCP サーバーを使って、UI のデバッグループから人間を排除します。

• スマートエージェント（Claude Code、Cursor、…）が PR を仕上げ、UI の検証を求めます。
• このサーバーにストーリーを渡します。「ウェブでログインして、X、Y、Z を実行してください。問題が起きたら教えてください。」
• 小型で高速なエージェントがこのサーバー内で実行されます（Vercel AI SDK 経由）。ブラウザーまたはデスクトップを操作し、コンソールとネットワークを監視して、スクリーンショットを撮影します。
• 構造化された調査結果（合格／不合格、問題の内容、証拠）を返します。
• スマートエージェントがコードを修正して再度依頼します。UI が動作するまでループします。

playwright-mcp では、スマートモデルがクリックを一つずつ指示しますが、こちらではスマートモデルは高レベルの指示にとどまり、クリック操作のループ全体を小型エージェントに委任します。

playwright-mcp との違い

	playwright-mcp	UI Debugger MCP
誰がクリックするか	スマートモデルが呼び出しごとに 1 アクション	小型エージェントが自律的に実行
公開されるツール	多数（クリック、入力、スナップショット…）	少数（ストーリーを渡して、調査結果を取得）
スマートモデルのコスト	高い（やり取りが多い）	低い（高レベルの指示）
出力	生のページ状態	構造化された調査結果と証拠

アーキテクチャ — 3 つの役割

上司、高速で目の見えないドライバー、目を持つ説明役をイメージしてください。

   ┌─────────────┐   MCP conversation    ┌──────────────────────────────────────┐
   │ smart agent │  start_debug ───────▶ │        UI Debugger MCP server         │
   │  (Claude)   │  send_message (live)  │                                       │
   │             │ ◀─────── get_findings │   ┌────────────┐     ┌────────────┐   │
   │ sets goals  │                       │   │  fast guy  │ look│ vision guy │   │
   │ fixes code  │                       │   │  (driver)  │────▶│  (eyes)    │   │
   │ loops       │                       │   │ deepseek   │◀────│  glm 5v    │   │
   └─────────────┘                       │   │ text·blind │ desc│ image      │   │
          ▲                              │   └─────┬──────┘     └────────────┘   │
          │ "works + looks nice"         │     observe / act (SQL-like)          │
          │ findings + screenshots       │         │ shared adapter contract     │
          └──────────────────────────────│─────────┼─────────────────────────────│
                                          └─────────┼─────────────────────────────┘
                                                    ▼
                              ┌──────────────┬──────────────┬──────────────┐
                              │  web (CDP)   │ desktop      │ android      │
                              │  browser     │ X11/Wayland  │ ADB          │
                              └──────────────┴──────────────┴──────────────┘

• スマートエージェント — 上司（Claude／呼び出し元）です。目標を送り、調査結果を読み、コードを修正して、ループを繰り返します。高レベルにとどまり、クリックはしません。
• 高速担当 — ドライバーです。高速で低コストですが、テキストのみで、目は見えません。構造（DOM／a11y ツリー／ビュー階層）に基づいてクリック操作のループを実行します。デフォルトは deepseek です。
• ビジョン担当 — 目の役割です。マルチモーダルです。ドライバーが look を呼び出して、*「これは正しく見えますか？ボタンは中央にありますか？」*と尋ねると、説明が返されます。デフォルトは glm です。視覚的な判断が必要な場合にのみ使用します。

目標は 1 つです。**UI が動作し、見た目もよいこと。**設計全体は docs/idea/ をご覧ください。

実行ごとにスクリーンショットを保存し、それらをつなぎ合わせて短いキャプション付きのリプレイ動画を作成します。Claude はこれを PR に添付するため、レビュアーは約 10 秒で動作中のフローを確認できます（docs/idea/workspace.md）。

ターゲット

1 つのプロジェクトで、複数のデバッグターゲットを公開できます。大規模なアプリでは、3 つすべてを利用できます。

ターゲット	プロトコル／操作方法	読み取るもの
web	CDP（Chrome DevTools Protocol）、デフォルトでヘッドレス	DOM
desktop	X11／Wayland 入力 + AT-SPI	a11y ツリー／ビジョン
mobile	ADB（uiautomator + screencap）、Android、デフォルトでヘッドレス	ビュー階層／ビジョン

3 つのアダプターで、共通のコントラクトを 1 つ共有します。それぞれ、ターゲットをサーバーが起動する managed モード、または実行中のターゲットに cdpUrl／adbSerial で接続する attach モードで実行できます。まずは Linux が対象です。Linux では iOS は対象外です（macOS 専用ツールが必要です）。

managed モードの Android 実行では、エミュレーターをウィンドウなしで起動します。ディスプレイのないマシンでは、-no-window だけだとホストの GL コンテキストが開いたまま終了するため、-no-window と -gpu swiftshader_indirect -no-audio を指定します。ウィンドウで確認するには、ターゲットに "headless": false を設定します。それ以外の引数は emulatorArgs に追加してください。

セットアップ

ほかのローカル MCP サーバーと同じように、.mcp.json にエントリを 1 つ追加してインストールします。

{
  "mcpServers": {
    "ui-debugger": {
      "command": "npx",
      "args": ["-y", "@developerz.ai/ui-debugger-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_BASE_URL": "https://openrouter.ai/api/v1"
      }
    }
  }
}

複数のリポジトリを接続する場合、通常 .mcp.json はコミットされるため、各リポジトリにキーを貼り付けないでください。シェルで一度だけ環境変数に設定して参照すれば、すべてのリポジトリで同じエントリを使え、シークレットも含まれません。

"env": {
  "OPENAI_API_KEY": "${UI_DEBUGGER_API_KEY}",
  "OPENAI_BASE_URL": "${UI_DEBUGGER_BASE_URL:-https://openrouter.ai/api/v1}"
}

公式の MCP レジストリ にも io.github.developerz-ai/ui-debugger-mcp として公開されています。手書きの .mcp.json エントリではなくレジストリを参照するクライアントなら、名前で検索してインストールできます。

続いて、デバッグするアプリを説明するプロジェクトごとの設定（モデル、ターゲット、URL）を追加します。リポジトリでエージェント設定を .dz/ 以下に置いている場合は .dz/ui-debugger/ui-debugger-mcp.json（こちらが優先されます）、それ以外の場合はルートの .ui-debugger-mcp.json（旧形式）を使用します。最も手早い方法は init コマンドです。

npx @developerz.ai/ui-debugger-mcp@latest init   # in your project root

ui-debugger-mcp init はデバッグ用のプロジェクトを作成します（詳細は docs/idea/config.md を参照してください）。

• ワークスペースディレクトリ ./tmp/ui-debugger-mcp/ を作成します
• まだ存在しない場合は、初期設定を書き込みます（デフォルトの deepseek/glm モデル、web ターゲットのスタブ）。リポジトリに .dz/ ディレクトリがすでにある場合は .dz/ui-debugger/ui-debugger-mcp.json に、それ以外の場合はルートの .ui-debugger-mcp.json に書き込みます
• .gitignore に tmp/ を追加します
• 貼り付ける .mcp.json のスニペットを表示します（API キーを書き込むことはありません）

設定ファイル：

• .mcp.json → サーバーの起動方法（コマンドとシークレットキー）。Gitignore 対象です。
• .dz/ui-debugger/ui-debugger-mcp.json（またはルートの .ui-debugger-mcp.json）→ このアプリのデバッグ方法（モデル、ターゲット）。コミット対象です。両方ある場合は .dz/ 側が優先され、無視されたルートのファイル名を示す通知がツールから表示されます。

両ファイルのすべてのキーについては docs/idea/config.md に、各ツールの正確な入出力形式については docs/idea/mcp-tools.md に記載されています。

サーバーはプロジェクトのセッションを選ぶために現在のディレクトリを読み取ります。リポジトリ内でサーバーを開けば、そのリポジトリをデバッグします。

クイックスタート

# 1. Scaffold the project (run once in your app's root)
npx @developerz.ai/ui-debugger-mcp@latest init

これにより ./tmp/ui-debugger-mcp/ が作成され、初期設定（.dz/… またはルート）が書き込まれ、貼り付ける .mcp.json のスニペットが表示されます。

// 2. Paste into your project's .mcp.json (add your API key)
{
  "mcpServers": {
    "ui-debugger": {
      "command": "npx",
      "args": ["-y", "@developerz.ai/ui-debugger-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_BASE_URL": "https://openrouter.ai/api/v1"
      }
    }
  }
}

// 3. Edit the project config (.dz/ui-debugger/ui-debugger-mcp.json or root
//    .ui-debugger-mcp.json) — set your app's URL
{
  "targets": {
    "web": { "adapter": "browser", "url": "http://localhost:3000" }
  }
}

// 4. In Claude Code (or any MCP client):
start_debug { target: "web", goal: "log in and add item 3 to the cart", url: "http://localhost:3000" }

// 5. Poll until done:
get_findings { session_id: "...", wait: 30000 }

// 6. Read bugs[] + visual[] + summary. Fix code, repeat.

使い方

これはリモートコントロールではなく、会話です。クリックごとに 1 つではなく、5 つの多機能ツールを使います。

ツール	機能
start_debug	実行を開始します：{ target, goal, url?, as?, replace?, criteria?, timeout? }。ターゲットに設定済みの url がない場合は url が必須です。as はログインするユーザー像を指定し、replace: true はすでに実行中のプロジェクトを引き継ぎます。小型のエージェントが自律的に操作します。{ session_id } を返します。
get_findings	ステータス、構造化された検出結果（機能上のバグと視覚的な問題）、証拠を取得します。wait を指定するとロングポーリングします。オブジェクト全体を読み取る場合、各リストは 20 件までに制限され、その旨が truncated（フィールドごとの {returned, total}）に示されます。完全なリストを取得するには fields を指定します。
send_message	実行中のエージェントに途中でメッセージを送ります。作業の追加、方向転換、質問への回答ができます。
describe	このプロジェクトで設定されているターゲットとモデルを一覧表示します。各ターゲットの認証用 personas[] と notes に加えて、プロジェクトが現在保持している実行を示す session も含まれます。
end_session	実行を終了し、ブラウザーとプロファイルを解放します。

実行には必ず時間制限があります。start_debug の timeout（秒）はデフォルトの 300s を上書きするため、セッションがいつまでも終了しないことはありません。制限時間に達すると自動的に終了し、プロファイルのロックが解放されます。

ログイン — 名前付きペルソナ

興味を引く画面のほとんどはログイン後に表示されます。実際の目標に取り組む前に、すべての goal 文字列でログイン手順を説明し直すと、ドライバーのステップを消費してしまいます。ターゲットで一度だけ指定します。

"targets": {
  "dashboard": {
    "adapter": "browser",
    "url": "http://localhost:5173",
    "auth": {
      "admin": { "path": "/login", "fields": { "email": "[email protected]", "password": "admin" }, "submit": "Sign in" },
      "user":  { "path": "/login", "fields": { "email": "[email protected]",  "password": "user"  }, "submit": "Sign in" }
    }
  }
}

start_debug { target: "dashboard", as: "admin", goal: "open Audit and check the table renders" }

実行では、ドライバーの最初のステップより前にアウトオブバンドでサインインします。ドライバーのステップは消費せず、認証情報がモデルのコンテキストに入ることもありません。プロンプトに伝わるのは、*「admin としてすでにサインインしています」*ということだけです。値は実行が書き込むすべてのログで秘匿され、describe が報告するのはペルソナの名前だけです。間違った as を指定すると、有効な名前の一覧を示してエラーになります。また、ログインに失敗した場合は、すべてのページが空だと報告するセッションを返すのではなく、実行自体が失敗します。開発用／シード用の認証情報を使用してください。このファイルはコミットされています。詳細は docs/idea/config.mdを参照してください。

期待する内容を伝える — notes

シードデータがない、マイグレーション直後のアプリでは、あらゆる場所に空の状態が表示され、ドライバーは「テーブルが空です」と実行の主なバグとして報告します。それは正しいものの、役に立ちません。ターゲットで一度だけ、期待する内容を指定します。

"targets": {
  "dashboard": {
    "adapter": "browser",
    "url": "http://localhost:5173",
    "notes": "needs seeded data — empty tables are expected on /new\nfirst load shows an onboarding modal; dismiss it\ndark mode is the default theme"
  }
}

1行に1つの事実を、任意のターゲット（Web、デスクトップ、Android）に指定します。実行ごとの goal と異なり、notes は設定です。ドライバーのプロンプトに独立した「このアプリについて既知のこと」セクションとして一度組み込まれます。これらは期待される内容として扱い、欠陥として報告しないでください。一方、それに矛盾する画面は報告する価値があります。同じ前提条件は、スクリーンショットを判定する別のビジョンモデルにも渡されるため、期待される空の状態を設定しておけば、それが視覚的な欠陥として報告されるのを防げます。一方、それに矛盾する画面は引き続き報告する価値があります。 上限は1000文字で、設定の読み込み時に適用されます（これを含むプロンプトは各ステップでモデルに再送信されるため、ここに長文を書くとステップごとにコストがかかります）。

実行がすでに開いている場合

プロジェクト（cwd）ごとに実行は1つだけなので、end_session を忘れると、以前は実行が詰まってしまいました。今はその心配はありません。describe は、このプロジェクトが保持している実行を （session: { id, status, goal }）として報告するため、session_id を失った呼び出し元（コンテキストが圧縮された場合や、クライアントを再起動した場合など）は、実行を確認したり、終了したり、start_debug({ …, replace: true }) で引き継いだりできます。拒否されるのが引き続きデフォルトであり、拒否時には3つすべての呼び出し方法が明示されます。黙って引き継ぐと、ほかの誰かが監視している正常な実行を終了させてしまうためです。

すべてのツールの結果には、整形済みテキストブロックと、宣言済みの outputSchema に対して検証された型付きの structuredContent ペイロードの両方が含まれます。テキストを解析するのではなく、構造化データを解析してください。また、ツールはMCPアノテーション（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）を宣言しているため、クライアントは適切に表示したり、使用を制御したりできます。さらに、証跡のパス（スクリーンショット、replay.mp4、ログ）は、インライン文字列ではなく resource_link コンテンツ項目として渡されます。完全な構造はdocs/reference.mdを参照してください。

スマートエージェントでの一般的なループ：

start_debug { target: "web", goal: "log in and add item 3 to the cart" }
→ poll get_findings (wait) until status is passed | failed
→ read bugs[] + visual[] + summary, fix the code, start_debug again

claude -p を使ったスクリプトから、ヘッドレスで操作することもできます。CLI の設定例（MCP の設定、許可するツール、出力形式）は docs/claude/SKILL.mdを参照してください。

実行で記録される内容（ウェブ）

調査結果が得られますが、エージェントの証拠があってこそ、実際に活用できます。

HTTP	リクエストとレスポンスの全体（メソッド、url、ステータス、durationMs。また、fetch／xhr ではリクエストとレスポンスの本文およびヘッダーを含みます）。4xx にはステータスだけでなく、サーバー独自の理由（{"error":"password too short"}）も記録されます。認証情報を含むヘッダーの値は <redacted, N chars> に置き換えられます。存在の有無は診断に使えますが、秘密情報がモデル、ログ、会話記録に渡ることはありません。
DOM	ロール、名前、境界、フォームコントロールの現在の value／checked、data-testid、テキストノードごとの WCAG コントラストを記録します。これにより、視覚機能を使わずに「ボックスにチェックが入っているか」「このテキストは読みやすいか」を構造的に判断できます。
iframe	埋め込みドキュメントも読み取ります。ノードには frame が付き、境界の座標はページ基準なので、ほかの場所と同様にクリックできます。
タブ	target="_blank" のクリックを検出して追跡できます。「何も起きなかった」と誤認することはありません。
コンソール	エラーと捕捉されなかった例外を、ソースの位置とともに記録します。
フレーム	各アクションのスクリーンショットを時系列順に並べて、replay.mp4 に結合します。

静的アセットは、デフォルトのネットワーク読み取りから除外されます。Vite 開発サーバーでは、静的アセットの数は実際の API 呼び出しの約 15 倍に上るためです。非表示にした件数と、それらを確認するためのフィルターも記録されます。種類を問わず、失敗したリクエストが非表示になることはありません。

CLI — 実行の確認または停止

ui-debugger-mcp バイナリは、アクティブな実行を操作する CLI としても使えます （state.json を読み取り、API キーは不要です）。

ui-debugger-mcp status   # which run is active, server pid, verdict, finding counts
ui-debugger-mcp stop     # gracefully end the run (frees the browser + profile)

トラブルシューティング

Chrome が見つからない Web アダプターはシステムの PATH 経由で Chrome を起動します。Chrome／Chromium をインストールするか、プロジェクト設定（.dz/… またはルート）で executablePath を設定してください。

"web": { "adapter": "browser", "url": "...", "executablePath": "/usr/bin/chromium-browser" }

セッションがロックされている — 「別の実行がアクティブです」 Chrome プロファイル 1 つにつき、実行は 1 つです。前回の実行がクリーンアップされずにクラッシュした場合：

npx @developerz.ai/ui-debugger-mcp@latest stop   # graceful teardown

または ./tmp/ui-debugger-mcp/<project>/state.json を削除し、MCP サーバーを再起動してください。

検出結果がないまま実行がタイムアウトする デフォルトの上限は 300 秒です。呼び出しごとに引き上げてください：

start_debug { target: "web", goal: "...", timeout: 600 }

エージェントがログインで停止している場合は、アプリのログインルートに ?debug-ai=true を追加して（ALLOW_AI_DEBUG_LOGIN で制御）、CAPTCHA をスキップしてください。パターンについては CLAUDE.md を参照してください。

get_findings が空の bugs[]／visual[] を返す 実行がまだ進行中の可能性があります。wait（ms）を使ってロングポーリングしてください：

get_findings { session_id: "...", wait: 30000 }

エージェントのトレースは ./tmp/ui-debugger-mcp/<project>/sessions/<id>/logs/agent.log で確認してください。 セッション ID はローカルのタイムスタンプ（2026-07-27_14-30-05-0001）なので、最新の実行が並び順の最後になります。保持されるのは直近 5 件のセッションのみです。実行するたびに残りは削除されるため、6 件前の実行の証拠は仕様上残りません。

実行が即座に失敗する：「… は有効なモデル ID ではありません」 プロジェクト設定のモデル文字列がカタログ ID ではありません。OpenRouter では provider/model を指定し、オプションで :floor／:nitro のルーティングサフィックスを付けます。#… サフィックスは無条件に拒否されます。プレーンな ID（deepseek/deepseek-v4-flash）を使用してください。

アップグレード後も古いバージョンが実行される npx -y <pkg> はキャッシュ済みのインストールがある場合、それを再利用します。そのため、.mcp.json に "@developerz.ai/ui-debugger-mcp" をそのまま記述すると、~/.npm/_npx に最初にインストールされたバージョンが起動し続けます。古いバージョンであることを知らせる通知もありません。自動更新はなく、サーバーがレジストリを確認することもありません。すべてのコールドスタートで再解決されるよう、args に @latest を指定してください（現在 init が出力する内容です）。

"args": ["-y", "@developerz.ai/ui-debugger-mcp@latest"]

すでに古いバージョンで止まっている場合は、rm -rf ~/.npm/_npx を実行してから、サーバーを再接続してください（Claude Code では /mcp）。現在のバージョンは npx @developerz.ai/ui-debugger-mcp@latest --version で確認できます。

設定の編集が反映されないように見える 設定は MCP サーバーの起動時に一度だけ読み込まれるため、編集しても実行中のサーバーには反映されません。v1.3 以降、サーバーはファイルが変更されている場合に実行の開始を拒否し、古い設定で黙って実行するのではなく、サーバーを再接続するよう案内します（Claude Code では /mcp → ui-debugger を再接続）。

「別のサーバーがすでにセッションを持っています」と表示され、そのセッションが見つからない その実行は、同じプロジェクト上の別の MCP サーバープロセスに属しています。現在はそのセッションを読み取れます。get_findings { session_id: "<the id in the error>" } でディスク上の検出結果を取得できるため、実行中のセッションと、完了して閉じられるのを待っているだけのセッションを区別できます。プロジェクトの実行権を取得するには、ui-debugger-mcp stop を実行してください。

バグがなく、説明もないまま実行が failed で終了する これはドライバーが report を呼び出さず、ステップ予算を使い切ったことを意味します。サマリーに明記されます。これはクラッシュでも、問題のない実行でもありません。目標を絞るか、timeout を引き上げてください。logs/agent.log とスクリーンショットで、実際に行われた操作を確認してください。

replay.mp4 が生成されない ffmpeg はオプションです。インストールして再試行するか、無視してください。なくても検出結果とスクリーンショットは保存されます。

スタック

• Bun + TypeScript（npm として配布、npx／bunx で実行）
• Vercel AI SDK — エージェントのループ（高速ドライバー + ビジョン記述）
• OpenAI 互換の任意のルーター（デフォルトは OpenRouter） — 役割ごとにモデルを切り替えられます。 デフォルト：deepseek（テキスト）が操作し、glm（画像）が認識します。
• Web には CDP、デスクトップには X11/Wayland、Android には ADB
• stdio MCP トランスポート

ステータス

3 つすべてのアダプターが v1 で提供されています：

対象	状態
web	✅ 提供済み（CDP、ヘッドレス + アタッチ）
desktop	✅ 提供済み（X11/Wayland、AT-SPI + xdotool）
android	✅ 提供済み（ADB、uiautomator）

リプレイ動画（replay.mp4、キャプション付き静止画から ffmpeg で mp4 を生成）は Web アダプターで提供されています。 ffmpeg はオプションです。インストールされていなくても問題なく、検出結果は保存されます。

設計メモについては docs/idea/ を参照してください。

ドキュメント

• docs/idea/overview.md — 問題とアイデア
• docs/idea/architecture.md — システム設計
• docs/idea/adapters.md — アダプターの契約と対象
• docs/idea/desktop-control.md — Linux の制御ツール（X11/Wayland/モバイル）
• docs/idea/agent-loop.md — ストーリーから調査結果へ至るループ
• docs/idea/mcp-tools.md — 2 層のツール、SQL のようなパラメーター、リポジトリ内のプロンプト
• docs/idea/models.md — 3 つの役割（スマートエージェント／高速担当／ビジョン担当）
• docs/idea/config.md — 設定ファイル
• docs/idea/workspace.md — プロジェクトごとの領域とログ
• docs/claude/SKILL.md — ヘッドレス CLI ツールとしての claude の操作（汎用）
• CLAUDE.md — このリポジトリで作業する AI エージェント向けの指示

クレジット／影響を受けたもの

• ai-task-master — ビルド用テンプレート（オーケストレーターとサブエージェント）、参考リポジトリ、未公開
• gold-standards-in-ai — MCP とコード規約、参考リポジトリ、未公開
• claude-code-bible — エージェントファーストのパターン（sebyx07/claude-code-bible）
• Model Context Protocol