Vuda (visual Ui Debug Agent)

MCP 対応の AI クライアントに、実際のブラウザー、スクリーンショット、DOM 検査、ワークフロー検証、コンソール記録、API チェック、視覚的比較を提供します。
_{MCP ツール 29 個 · ローカル、Browserbase、Anchor、または任意の CDP ブラウザー · Node.js 20+}

VUDA の機能

VUDA（Visual UI Debug Agent）は、Playwright を使用して Web インターフェースを検査・テストするためのModel Context Protocolサーバーです。MCP サーバーは標準入力／出力を介してローカルで動作し、ブラウザーはローカル、Browserbase、Anchor Browser、または既存の CDP エンドポイントで実行できます。すべてのツールで、選択した同じブラウザーランタイムを使用します。

• ページ全体、ビューポート、要素、ローカルファイル、および複数のスクリーンショットを撮影します。
• インタラクティブ要素を特定し、レンダリングされた DOM と計算済みスタイルを検査します。
• ブラウザーの状態を維持しながら、複数ステップの UI ワークフローを実行します。
• コンソール出力を監視し、ページのパフォーマンスを分析します。
• 2 つのレンダリング状態を比較し、視覚的な差分を返します。
• サイトマップをクロールし、API エンドポイントをテストします。
• Playwright でサポートされているデバイスをエミュレートします。

クイックスタート

1. VUDA を実行する

npx -y visual-ui-debug-agent-mcp

デフォルトの local モードには、Chromium 互換のブラウザーが必要です。まだ利用できない場合は、対応するブラウザーを一度インストールしてください。

npx playwright install chromium

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

{
  "mcpServers": {
    "vuda": {
      "command": "npx",
      "args": ["-y", "visual-ui-debug-agent-mcp"]
    }
  }
}

MCP 設定を変更した後は、クライアントを再起動してください。サーバーはプロトコルメッセージを標準出力に書き込み、診断情報を一時ログファイルに記録します。

ローカルモードではプロバイダーのアカウントは不要です。

Docker を使用する場合も、同じ stdio トランスポートを利用できます。

{
  "mcpServers": {
    "vuda": {
      "command": "docker",
      "args": ["run", "--interactive", "--rm", "ghcr.io/samihalawa/visual-ui-debug-agent-mcp:latest"]
    }
  }
}

Docker でファイル内のプロバイダー認証情報を使用するには、args 配列の "run" の直後に "--env-file", "/absolute/path/to/.env" を追加してください。

3. 試してみる

クライアントに次のように依頼してください。

Use VUDA to inspect https://example.com, capture a screenshot, list the
interactive elements, and report console errors and obvious layout issues.

ツールリファレンス

分析とキャプチャ

ツール	目的
enhanced_page_analyzer	スクリーンショット、コンソール、パフォーマンス、インタラクティブ要素の分析
screenshot_url	URL、ビューポート、ページ全体、または選択した要素をキャプチャ
batch_screenshot_urls	複数の URL をキャプチャし、並べて確認
screenshot_local_files	ローカル HTML ファイルをレンダリングしてキャプチャ
dom_inspector	要素のプロパティ、子要素、計算済みスタイルを返す
visual_comparison	レンダリングされた 2 つのページまたは要素を比較

ワークフロー、診断、API

ツール	用途
ui_workflow_validator	説明されたユーザージャーニーを実行して検証します
navigation_flow_validator	一連のブラウザー操作を検証します
console_monitor	指定した時間にわたってブラウザーのコンソールメッセージを取得します
performance_analysis	ナビゲーションとページのパフォーマンス指標を収集します
api_endpoint_tester	複数の HTTP エンドポイントをテストします
sitemap_crawler	サイトマップからページを検出して調査します
tunnel_helper	リモートトンネルの URL とセットアップガイダンスを保存または取得します
debug_memory	1 回のサーバーセッション中に短いデバッグメモを保持します

Playwright の直接操作

playwright_navigate、playwright_click、playwright_iframe_click、playwright_fill、playwright_select、playwright_hover、playwright_evaluate、playwright_console_logs、playwright_get_visible_text、playwright_get_visible_html、playwright_go_back、playwright_go_forward、playwright_press_key、playwright_drag、playwright_screenshot。

設定

VUDA は通常どおり環境変数を読み込み、作業ディレクトリの .env を自動的に読み込みます。ソースをチェックアウトして実行する場合は、.env.example をコピーしてください。npx でインストールする場合は、MCP プロセスの作業ディレクトリに .env を置くか、クライアント設定で変数を渡すか、DOTENV_CONFIG_PATH に絶対パスの .env を設定してください。

ブラウザーを選択する

モード	必要な設定	アカウントの状態
ローカル（デフォルト）	VUDA_BROWSER_PROVIDER=local	VUDA_STORAGE_STATE_PATH、Cookie JSON、または Cookie ファイル
Browserbase	VUDA_BROWSER_PROVIDER=browserbase、BROWSERBASE_API_KEY	BROWSERBASE_CONTEXT_ID を再利用するか、Cookie を注入します
Anchor Browser	VUDA_BROWSER_PROVIDER=anchor、ANCHOR_API_KEY	VUDA_ANCHOR_SESSION_JSON の Anchor プロファイルを使用するか、Cookie を注入します
既存のブラウザー	VUDA_BROWSER_PROVIDER=cdp、VUDA_CDP_URL	そのブラウザーコンテキストを使用します。Cookie の注入は任意です

Browserbase の例：

VUDA_BROWSER_PROVIDER=browserbase
BROWSERBASE_API_KEY=your_api_key
BROWSERBASE_PROJECT_ID=your_project_id
BROWSERBASE_CONTEXT_ID=your_saved_context_id

永続的な認証済みプロファイルを使う Anchor Browser の例：

VUDA_BROWSER_PROVIDER=anchor
ANCHOR_API_KEY=your_api_key
VUDA_ANCHOR_SESSION_JSON={"browser":{"profile":{"name":"vuda","persist":true}}}

すべての 29 個のツールは、どのモードでも既存の名前と入力を維持します。MCP リソース browser://status を読み込み、選択されたプロバイダー、現在の接続状態、セッション ID、およびライブビューが利用可能かどうかを確認してください。CDP とライブビューの URL が返されることはありません。

Cookie またはローカル状態をインポートする

Cookie の注入はすべてのプロバイダーで機能します。Playwright の Cookie 配列をインラインまたはファイルで指定してください。

VUDA_COOKIES_FILE=/absolute/path/to/cookies.json
# VUDA_COOKIES_JSON=[{"name":"session","value":"...","domain":"example.com","path":"/"}]

ローカルモードでは、VUDA_STORAGE_STATE_PATH によって Playwright のストレージ状態ファイルが読み込まれます。VUDA の正常終了時に更新後の状態を書き戻すには、VUDA_PERSIST_STORAGE_STATE=true を設定します。複数のクラウドセッションをまたいで状態を保持する場合は、Browserbase Contexts と Anchor プロファイルがプロバイダー標準の選択肢です。

プロバイダー固有のセッションオプションは、別のラッパーや SDK を追加することなく引き続き利用できます。

• VUDA_BROWSERBASE_SESSION_JSON は Browserbase のセッション作成リクエストにマージされます。
• VUDA_ANCHOR_SESSION_JSON は Anchor のセッション作成リクエストとして送信されます。

タイムアウト

すべてのタイムアウト設定は任意です。

変数	デフォルト	用途
VUDA_DEFAULT_TIMEOUT	15000	Playwright の一般的なタイムアウト（ミリ秒）
VUDA_NAVIGATION_TIMEOUT	15000	ナビゲーションのタイムアウト
VUDA_SELECTOR_TIMEOUT	12000	セレクター待機のタイムアウト
VUDA_STABILITY_WAIT	5000	ナビゲーション後、キャプチャまでの待機時間
VUDA_UI_UPDATE_WAIT	1000	短時間の UI 更新を待つ時間
VUDA_PERFORMANCE_THRESHOLD	15000	遅いページと判定するしきい値
VUDA_INTERACTION_DELAY	500	直接操作の間隔

例：

{
  "mcpServers": {
    "vuda": {
      "command": "npx",
      "args": ["-y", "visual-ui-debug-agent-mcp"],
      "env": {
        "VUDA_NAVIGATION_TIMEOUT": "30000",
        "VUDA_STABILITY_WAIT": "2000"
      }
    }
  }
}

開発

git clone https://github.com/samihalawa/visual-ui-debug-agent-mcp.git
cd visual-ui-debug-agent-mcp
npm ci
npm test

npm test は TypeScript サーバーをビルドし、MCP stdio トランスポート経由で起動して、正確な29個のツールの一覧を検証し、同梱リソースを読み込み、状態を保持するツール呼び出しを実行し、実際のブラウザーのスクリーンショットを取得します。

また、Browserbase と Anchor のセッションリクエスト／クリーンアップの形式、CDP の選択、Cookie の読み込み、クローラーのブラウザー初期化も検証します。CI ではプロバイダー呼び出しに決定論的なモックを使用します。クラウドのライブセッションを利用する場合は、ご自身の .env を使用してください。

プルリクエストを作成する前に、次も実行してください。

npm audit
npm pack --dry-run

アーキテクチャ

VUDA は、すべてのプロバイダーで単一の Playwright コントロールプレーンを維持します。ローカルモードではページ単位の分析用に分離されたコンテキストを作成し、リモートモードではプロバイダーのコンテキストを再利用するため、認証済みの状態がツール間で維持されます。VUDA はスクリーンショットを MCP の画像コンテンツとして返し、生成されたスクリーンショット、ブラウザーのステータス、デバッグ用プロンプトを MCP リソースとして公開します。

コントリビューション

Issue と目的を絞ったプルリクエストを歓迎します。開発ワークフローとレビューのチェックリストについては、CONTRIBUTING.md をご覧ください。リリース履歴は CHANGELOG.md に記録されています。

ライセンス

ISC © 2023–2026 Sami Halawa およびコントリビューター。