Debugg AI

公式

コード生成エージェントが、Debugg AIテストプラットフォームを介してリモートブラウザ上で新しいコード変更に対する0設定のエンドツーエンドテストを作成・実行できるようにします。

GitHub

Debugg AI MCPで何ができますか？

任意のURLに対してAIブラウザエージェントを実行 — テスト内容を自然言語で記述すると、check_app_in_browserがページ遷移や操作を行い、合格/不合格とスクリーンショットを返します。
LLMコストをかけずに複数ページを調査 — 最大20個のURLをprobe_pageに送信し、高速なスクリーンショット、コンソールエラー、ネットワークサマリーを一括取得します。
ナレッジグラフクロールを起動 — trigger_crawlを使用してAIエージェントにアプリを探索させ、プロジェクトのナレッジグラフを構築します。
テストスイートとテストケースを管理 — test_suiteでテストスイートの作成、一覧表示、実行、結果確認を行い、test_caseで個別のケースを定義します。
実行アーティファクトを検査 — executionsを通じて実行詳細、スクリーンショット、HARトレース、コンソールログを取得し、障害をデバッグします。
プロジェクト、環境、実行をリソースとして参照 — ツールを呼び出さずにコンテキストを取得するため、debugg-ai:// URIでエンティティを直接参照します。

ドキュメント

Debugg AI — MCP Server

Model Context Protocol を利用した AI 駆動のブラウザテストです。任意の URL (または localhost) を指定し、テスト内容を記述するだけで、AI エージェントがアプリをブラウジングし、スクリーンショット付きで合否を返します。

セットアップ

Node.js 20.20.0 以降が必要です (posthog-node@^5.26.0 からの推移的要件)。

debugg.ai で API キーを取得し、MCP クライアント設定に追加してください:

{
  "mcpServers": {
    "debugg-ai": {
      "command": "npx",
      "args": ["-y", "@debugg-ai/debugg-ai-mcp"],
      "env": {
        "DEBUGGAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

または Docker を使用:

docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-mcp

ツール

サーバーは 8 つのツールを公開します: 3 つの Browser ツールと、管理対象エンティティごとに 1 つの アクションベース ツールです。主要ツールは check_app_in_browser (フル AI エージェント) と probe_page (LLM 不使用の軽量ページプローブ) です。その他 — project、environment、test_suite、test_case、executions — は、操作を選択する action 識別子 (例: {"action":"list"}) をそれぞれ受け取ります。破壊的な delete アクションには確認が必要です (サポートされている場合は確認プロンプト、それ以外は confirm: true)。

Browser

`check_app_in_browser`

AI ブラウザエージェントをアプリに対して実行します。エージェントはナビゲートし、操作し、スクリーンショット付きでレポートします。Localhost URL は ngrok 経由で自動トンネリングされます。

パラメータ	型	説明
`description`	string 必須	テスト内容 (自然言語)
`url`	string 必須	対象 URL — `http://localhost:3000` は自動トンネリング
`environmentId`	string	特定の環境の UUID
`credentialId`	string	特定の認証情報の UUID
`credentialRole`	string	ロールで認証情報を選択 (例: `admin`、`guest`)
`username`	string	ログイン用ユーザー名 (一時的 — 保存されません)
`password`	string	ログイン用パスワード (一時的 — 保存されません)
`repoName`	string	自動検出された git リポジトリ名を上書き (例: `my-org/my-repo`)

1 回の呼び出しにつき 1 つのチェックに集中してください。エージェントには約 25 ステップの内部バジェットがあります。より広範なスイートは複数回の呼び出しに分割してください。

成功した実行では、スクリーンショットと共に browserSession ブロックが返されます — キャプチャされた HAR (完全なネットワークトレース) と コンソールログ (すべての JS コンソールメッセージ) のための署名付き S3 URL です。これらを使用して、型チェックやユニットテストを通過する再フェッチループ、ハイドレーションエラー、その他のランタイム問題を検出します:

"browserSession": {
  "harUrl": "https://...session_18139.har?X-Amz-...",
  "consoleLogUrl": "https://...session_18139_console.json?X-Amz-...",
  "recordingUrl": "https://...session_18139_recording.webm?X-Amz-...",
  "harStatus": "downloaded",
  "consoleLogStatus": "downloaded",
  "harRedactionStatus": "redacted",
  "consoleLogRedactionStatus": "redacted"
}

URL は有効期限付きの署名付き S3 です — executions {action:"get", uuid} を介して親の実行を再取得し、更新してください。harStatus / consoleLogStatus は 'downloaded' (URL 取得可能)、'not_available' (ページが何も出力しなかった)、'failed' (キャプチャが壊れた) を明確に区別します。新しい実行では、エージェント終了後にキャプチャが非同期でアップロードされるため、URL は通常 null です — ステータスが 'downloaded' に達するまで executions {action:"get", uuid: executionId} をポーリングしてください。Authorization / Cookie / token/secret/api_key ヘッダーは、アーティファクトが永続化される前にサーバー側で除去されます。

`trigger_crawl`

サーバー側のブラウザエージェントクロールを実行し、プロジェクトのナレッジグラフを構築します。Localhost URL は自動的にトンネリングされます。取り込み成功時に knowledgeGraph.imported === true を含む {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} を返します。完了したクロールには browserSession ブロック (上記と同じ形式の HAR + コンソールログ URL) も含まれます。

`probe_page`

LLM 不使用の軽量バッチページプローブ。 1～20 の URL を渡します。各 URL はナビゲートし、ロードを待ち、レンダリングされた状態 (スクリーンショット + ページメタデータ + 構造化されたコンソールエラー + ネットワークサマリー) を返します。エージェントループ、LLM コスト、シナリオアサーションはありません。「/settings を壊してしまったか？」、リファクタ後のマルチルートスモークテスト、CI の PR ごとのスイープ、check_app_in_browser の 60～150 秒のエージェントループが過剰な場合のクイック稼働確認に使用します。

パラメータ	型	説明
`targets`	array 必須	1～20 エントリ: `[{url, waitForSelector?, waitForLoadState?, timeoutMs?}]`
`targets[].url`	string 必須	公開 URL または localhost (自動トンネリング)
`targets[].waitForLoadState`	enum	`'load'` (デフォルト) / `'domcontentloaded'` / `'networkidle'`
`targets[].waitForSelector`	string	ナビゲーション後に待機するオプションの CSS セレクタ
`targets[].timeoutMs`	number	URL ごとのタイムアウト、1000～30000 (デフォルト 10000)
`includeHtml`	boolean	各結果に生の HTML を返す (デフォルト false)
`captureScreenshots`	boolean	ターゲットごとに 1 つの PNG を返す (デフォルト true)

バッチ全体で 1 つのバックエンド実行 + ブラウザセッション + トンネルを共有します — 1 回の呼び出しで 5 つの URL を処理する方が、5 つの並列単一 URL 呼び出しよりも大幅に高速です。URL ごとの error フィールドはバッチの回復力を保持します: 1 つのターゲットが失敗しても他のターゲットは失敗しません。

networkSummary 集約キーは origin + pathname です — 再フェッチループ (?n=0..4 が同じエンドポイントを繰り返しヒットする) は、カウント付きの単一エントリにまとめられます。そのため、/api/poll が count: 47 と共に表示されることは、ユーザーが元々求めていた実用的な「無限再フェッチループ」シグナルです。

パフォーマンスバジェット: 1 URL で 10 秒未満、20 URL で 25 秒未満。Localhost のデッドポートは、ワークフロー実行を消費せずに 2 秒未満で LocalServerUnreachable を返します。

`project`

アクション	パラメータ	結果
`get`	`{uuid}`	キュレーションされたプロジェクト詳細
`list`	`{q?, page?, pageSize?}`	ページネーションされたサマリー
`create`	`{name, platform, (teamUuid\|teamName), (repoUuid\|repoName)}`	作成されたプロジェクト

チームとリポジトリは、uuid または名前 (大文字小文字を区別しない完全一致。該当なしの場合は NotFound、複数該当の場合は AmbiguousMatch) のいずれかで解決されます。update/delete はありません — プロジェクトの名前変更または削除は DebuggAI Web アプリから行ってください。

`environment`

アクション	パラメータ	結果
`get`	`{uuid, projectUuid?}`	認証情報がインライン化された環境 (パスワードは返されません)
`list`	`{projectUuid?, q?, page?, pageSize?}`	ページネーションされた環境 (それぞれに認証情報配列付き)
`create`	`{name, url, description?, projectUuid?, credentials?}`	作成された環境 (オプションで認証情報をシード)
`update`	`{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}`	パッチされた環境。認証情報操作は削除 → 更新 → 追加の順で実行
`delete`	`{uuid, projectUuid?, confirm?}`	環境を削除 (認証情報もカスケード) — 確認が必要

projectUuid は省略時に git リポジトリから自動解決されます。認証情報ごとの失敗は、環境操作をブロックせずに credentialWarnings[] に表示されます。

`test_suite`

アクション	パラメータ	結果
`list`	`{projectUuid\|projectName, search?, page?, pageSize?}`	ステータス + 合格率付きのページネーションされたスイート
`create`	`{name, description, projectUuid\|projectName}`	作成されたスイート
`run`	`{suiteUuid\|(suiteName+project), targetUrl?}`	すべてのテストを非同期でトリガー
`results`	`{suiteUuid\|(suiteName+project)}`	スイート + テストごとの結果
`delete`	`{suiteUuid\|(suiteName+project), confirm?}`	論理削除 — 確認が必要

`test_case`

アクション	パラメータ	結果
`create`	`{name, description, agentTaskDescription, suiteUuid\|(suiteName+project), relativeUrl?, maxSteps?}`	作成されたテストケース (自動実行されません)
`update`	`{testUuid, name?, description?, agentTaskDescription?}`	パッチされたテストケース
`delete`	`{testUuid, confirm?}`	論理削除 — 確認が必要

`executions`

アクション	パラメータ	結果
`get`	`{uuid}`	完全な詳細 (`nodeExecutions` + 状態 + errorInfo) + スクリーンショット/gif アーティファクト
`list`	`{status?, projectUuid?, page?, pageSize?}`	ページネーションされたサマリー

バックエンドからの 404 は {error: 'NotFound', message, uuid} を含む isError: true として表示されます。認証情報は常にパスワードなしで返されます。

ページネーション

すべてのフィルターモードレスポンスはページネーションされます。レスポンス形式:

{
  "filter": { "...echoed query params..." },
  "pageInfo": { "page": 1, "pageSize": 20, "totalCount": 47, "totalPages": 3, "hasMore": true },
  "<items>": [ ... ]
}

オプションの page (1 始まり、デフォルト 1) と pageSize (デフォルト 20、最大 200。大きすぎる値はクランプされます) を渡します。レスポンスが暗黙的に切り捨てられることはありません。

リソース

ツールに加えて、サーバーは読み取り専用エンティティを MCP リソース として公開するため、クライアントはそれらを参照し、コンテキストとして @-メンションできます:

URI	内容
`debugg-ai://projects`	すべてのプロジェクト (最初のページ)
`debugg-ai://environments`	自動検出されたプロジェクトの環境
`debugg-ai://executions`	最近の実行 (最初のページ)
`debugg-ai://project/{uuid}`	1 つのプロジェクト、完全な詳細
`debugg-ai://environment/{uuid}`	1 つの環境 (認証情報インライン、パスワードはマスク)
`debugg-ai://execution/{uuid}`	1 つの実行、完全なノード詳細 + アーティファクトリンク

読み取りは project / environment / executions ツールと同じハンドラにディスパッチされるため、データと認証は同一です。リソースは付加的です — リソースをサポートしていないクライアントは引き続きツールを使用できます。

セキュリティ不変条件

パスワードは書き込み専用です。どのツールのレスポンス本文にも決して表示されません。
トンネル URL (*.ngrok.debugg.ai) は、エージェントが作成したテキストを含むすべてのブラウザエージェントレスポンスから除去されます。
バックエンドからの 404 は、例外としてスローされることなく、{error: 'NotFound', ...} を含む isError: true として表示されます。
DEBUGGAI_API_KEY がない場合は、最初の呼び出し時に構造化されたツールエラーとして表示されます — サーバーは引き続き正常に登録され、ツールを一覧表示します。

v3.0.0 への移行 (アクションベースのツール)

v3 では、20 の動詞ごとのツールが 8 つのアクションベースのツールに統合されました。古いツール → 新しい tool {action}:

削除されたもの	代替
`search_projects`	`project {action:"get"}` / `project {action:"list"}`
`create_project`	`project {action:"create"}`
`update_project`, `delete_project`	削除 — DebuggAI Web アプリを使用してください
`search_environments`	`environment {action:"get"}` / `{action:"list"}`
`create_environment` / `update_environment` / `delete_environment`	`environment {action:"create"\|"update"\|"delete"}`
`create_test_suite` / `search_test_suites` / `run_test_suite` / `get_test_suite_results` / `delete_test_suite`	`test_suite {action:"create"\|"list"\|"run"\|"results"\|"delete"}`
`create_test_case` / `update_test_case` / `delete_test_case`	`test_case {action:"create"\|"update"\|"delete"}`
`search_executions`	`executions {action:"get"\|"list"}`
`trigger_crawl` `headless` パラメータ	削除 — 常にヘッドレス

delete アクションに確認が必要になりました (確認プロンプト、または confirm: true)。クライアントは MCP 再起動時に新しいサーフェスを取得します。

v1.x からの移行 (v2.0.0 での破壊的変更)

v2 では、22 ツールのサーフェスが 11 に縮小されました。古いツール → 新しいツールのマッピング:

削除されたもの	代替
`list_projects`, `get_project`	`search_projects` (uuid モード vs フィルターモード)
`list_environments`, `get_environment`	`search_environments`
`list_credentials`, `get_credential`	`search_environments` — 各環境に認証情報がインライン化
`create_credential`	`create_environment({credentials: [...]})` シード、または `update_environment({addCredentials: [...]})`
`update_credential`	`update_environment({updateCredentials: [{uuid, ...patch}]})`
`delete_credential`	`update_environment({removeCredentialIds: [uuid]})`
`list_teams`, `list_repos`	`create_project({teamName, repoName})` — あいまいさ処理付きの名前解決
`list_executions`, `get_execution`	`search_executions`
`cancel_execution`	削除 — バックエンドのスピンダウンは自動

レスポンス形式の変更: リストレスポンスの裸の count フィールドはなくなりました — pageInfo.totalCount を使用してください。

設定

環境変数	必須	目的
`DEBUGGAI_API_KEY`	はい	バックエンド API キー。エイリアス: `DEBUGGAI_API_TOKEN`、`DEBUGGAI_JWT_TOKEN`。
`DEBUGGAI_API_URL`	いいえ	バックエンドベース URL。デフォルトは `https://api.debugg.ai`。
`DEBUGGAI_TOKEN_TYPE`	いいえ	`token` (デフォルト) または `bearer`。
`LOG_LEVEL`	いいえ	`error` / `warn` / `info` (デフォルト) / `debug`。
`POSTHOG_API_KEY`	いいえ	埋め込みテレメトリプロジェクトキーを上書き (例: プライベートフォーク)。
`DEBUGGAI_TELEMETRY_DISABLED`	いいえ	`1` / `true` / `yes` / `on` に設定してテレメトリを完全に無効化。

DEBUGGAI_API_KEY=your_api_key

リモート / HTTP トランスポート (オプション)

デフォルトでは、サーバーは stdio (ローカル npx) で通信します。代わりに、ステートレス Streamable HTTP + OAuth を介した、ホスト型のマルチユーザーリモート MCP として実行することもできます:

DEBUGGAI_MCP_TRANSPORT=http PORT=3000 DEBUGGAI_TOKEN_TYPE=bearer npx -y @debugg-ai/debugg-ai-mcp@latest

これは OAuth リソースサーバーです。すべての POST /mcp には Authorization: Bearer <token> が必要です。トークンがない、または無効な場合は、RFC 9728 メタデータを指す WWW-Authenticate を含む 401 が返され、クライアントはアドバタイズされた認可サーバーに対して OAuth フローを実行します。ベアラートークンはリクエストスコープであり、 api.debugg.ai がそれを検証します。

エンドポイント	目的
`POST /mcp`	MCP Streamable HTTP (ベアラートークン保護)
`GET /.well-known/oauth-protected-resource`	RFC 9728 メタデータ (認可サーバー検出)
`GET /health`	ロードバランサー / ECS ヘルスチェック

環境変数	デフォルト	目的
`DEBUGGAI_MCP_TRANSPORT`	`stdio`	リモートトランスポート用に `http` に設定
`PORT`	`3000`	HTTP リッスンポート
`DEBUGGAI_MCP_PUBLIC_URL`	`https://mcp.debugg.ai`	このサーバーの公開リソース URL (RFC 9728 `resource`)
`DEBUGGAI_OAUTH_ISSUER`	`https://auth.debugg.ai`	クライアントにアドバタイズされる認可サーバー
`DEBUGGAI_TOKEN_TYPE`	`token`	OAuth トークンを `Authorization: Bearer` として転送するために `bearer` に設定

stdio インストールでは、これらのいずれも必要ありません。

テレメトリ

MCP サーバーはデフォルトでテレメトリが有効になって出荷されます。組み込みの書き込み専用 PostHog プロジェクトキー (phc_*) により、チームはインストールベース全体でキャッシュヒット率、ポーリング周期、トンネルの信頼性、その他の運用メトリクスを観測できます。取得されるイベント:

イベント	発生タイミング
`tool.executed` / `tool.failed`	ツール呼び出しごと
`workflow.executed`	ブラウザエージェント実行ごと (`pollCount`、`durationMs`、`finalIntervalMs` を含む)
`tunnel.provisioned` / `tunnel.provision_retry` / `tunnel.stopped`	トンネルライフサイクルイベントごと
`template.lookup` / `project.lookup`	キャッシュヒット/ミス (コールドコール時は `durationMs` を含む)

プライバシーに関する姿勢:

識別 ID は SHA-256(api_key).slice(0, 16) であり、生のキーや個人情報は含まれません。
phc_* キーは PostHog の慣例により書き込み専用であり、ソースに埋め込んでも安全です。
DEBUGGAI_TELEMETRY_DISABLED=1 を設定すると完全にオプトアウトできます (何もしないプロバイダーに解決され、プロセス外にイベントは送信されません)。

アクティブモードは起動時にログ出力されます:

Telemetry enabled (PostHog, DebuggAI default project). Set DEBUGGAI_TELEMETRY_DISABLED=1 to opt out.
Telemetry enabled (PostHog, custom POSTHOG_API_KEY)
Telemetry disabled (DEBUGGAI_TELEMETRY_DISABLED is set)

ローカル開発

npm install
npm run build
npm run test:e2e        # real end-to-end evals against the backend

評価スイートは、ビルドされた MCP サーバーをサブプロセスとして起動し、実際のバックエンドに対してすべてのツールを実行し、フローごとのアーティファクトを scripts/evals/artifacts/<timestamp>/ に書き込みます。個別のシナリオについては scripts/evals/flows/ を参照してください。

MCP 登録: `debugg-ai-local` と `debugg-ai`

このリポジトリは、node dist/index.js (ビルドしたてのローカルコード) を指す プロジェクトスコープ のサーバー debugg-ai-local を登録する .mcp.json を同梱しています。これは Claude Code の作業ディレクトリがこのリポジトリである場合にのみ有効になります。

他のプロジェクトでは、公開された npm パッケージから取得する ユーザースコープ の debugg-ai 登録を使用する必要があります:

npm run mcp:global      # registers debugg-ai in ~/.claude.json to npx -y @debugg-ai/debugg-ai-mcp

ここでコードを編集した後は、npm run mcp:local (再ビルドのみ) を実行することで、次回の debugg-ai-local の呼び出しで変更が反映されます。

リンク

ダッシュボード · ドキュメント · 課題 · Discord