Debugg AI
公式コード生成エージェントが、Debugg AIテストプラットフォームを介してリモートブラウザ上で新しいコード変更に対する0設定のエンドツーエンドテストを作成・実行できるようにします。
Debugg AI MCPで何ができますか？
- AIブラウザテストを実行 —
check_app_in_browserを使用して、任意のURLやlocalhostアプリを自然言語の指示でテストし、スクリーンショット付きで合格/不合格を返します。 - 複数ページを素早く調査 —
probe_pageを使用して、1〜20のURLを一括チェックし、コンソールエラー、ネットワーク問題、レンダリング状態をLLMコストなしで確認します。 - テスト環境を管理 —
environmentツールを使用して、認証情報と許可されたSSOホストを持つ環境を作成、更新、一覧表示します。 - サイトクロールをトリガー —
trigger_crawlを実行して、サーバーサイドのブラウザエージェントクロールでプロジェクトのナレッジグラフを構築します。 - テストスイートを実行・追跡 — スイートを作成し、非同期実行をトリガーし、
test_suiteアクションでテストごとの結果を取得します。 - 実行アーティファクトを検査 —
executionsを通じて、完全な実行詳細、HARネットワークトレース、コンソールログを取得し、ランタイムの問題をデバッグします。
ドキュメント
Debugg AI — MCP Server
AIを活用したブラウザテストをModel Context Protocol経由で実現します。任意のURL（またはlocalhost）を指定してテスト内容を記述するだけで、AIエージェントがアプリを操作し、スクリーンショット付きで合格/不合格を返します。
セットアップ
Node.js 20.20.0以降が必要です（posthog-node@^5.26.0からの推移的な要件）。
http://localhost:... URLのテストにはcaddyバイナリが必要です — check_app_in_browser、
probe_page、およびtrigger_crawlは、ローカルのCaddyリバースプロキシを通じてlocalhostターゲットをトンネリングします。
これは自動的にインストールされます：@radically-straightforward/caddy npm依存関係が
npm install/npxの際に、お使いのプラットフォーム向けの固定されたCaddyリリースをダウンロードします — 通常のケースでは自分でインストールする必要はありません。これはこのパッケージがダウンロードする唯一のバイナリとなりました。トンネルクライアント自体は
純粋なTypeScriptです — ngrokエージェントを取得していたngrokパッケージを置き換えました。
そのダウンロードが実行されなかった場合（npm install --ignore-scripts、オフライン/エアギャップ環境でのインストール）、CADDY_BINを
ご自身のインストール先に向けてください（brew install caddy / apt install caddy /
caddyserver.com/docs/installを参照）— 欠落している場合は、最初のlocalhost-URL呼び出しで
明確なエラーとして表示され、無言でハングすることはありません。パブリックURLの呼び出し、すべての
非ブラウザツール、およびtest_suite {action:"run"}（専用のトンネルを使用し、
Caddyを完全にバイパスします）は、いずれの場合もそれを必要としません。
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
Dockerfileのnpm installステップは、原則としてローカルインストールと同じ自動的な方法でcaddyを
取得します — ただし、本稿執筆時点ではDockerfileはビルドに必要な
いくつかのディレクトリ（handlers、tools、types、config）をCOPYせず、
もはや存在しないtunnels/ディレクトリを参照しているため、新しいビルドはその前に失敗する可能性が高いです。これは
Caddyとは無関係の既存のギャップです。現在公開されている quinnosha/debugg-ai-mcpイメージは
Caddy依存関係より前のものです — そのイメージ内の
check_app_in_browser/probe_page/trigger_crawlへのlocalhost-URL呼び出しは、
再ビルド（Dockerfile修正）および再公開されるまでCaddyBinaryNotFoundErrorで失敗します。あるいはCADDY_BINが
別途組み込まれたものを指すようにします。パブリックURLの呼び出し、非ブラウザツール、およびtest_suite {action:"run"}は
いずれの場合も影響を受けません。
ツール
サーバーは8つのツールを公開しています：3つのブラウザツールに加え、管理対象エンティティごとに1つのアクションベースツールです。代表的なツールはcheck_app_in_browser（フルAIエージェント）とprobe_page（軽量なLLM不要のページプローブ）です。残り — project、environment、test_suite、test_case、executions — はそれぞれ、操作を選択するaction判別子（例：{"action":"list"}）を受け取ります。破壊的なdeleteアクションには確認が必要です（サポートされている場合はelicitationプロンプト、それ以外の場合はconfirm: true）。
ブラウザ
check_app_in_browser
AIブラウザエージェントをアプリに対して実行します。エージェントはナビゲート、操作を行い、スクリーンショット付きで報告します。localhost URLはデバッグトンネルサーバーを通じて自動的にトンネリングされます。
| パラメータ | 型 | 説明 |
|---|---|---|
description | string 必須 | テスト内容（自然言語） |
url | string 必須 | ターゲットURL — http://localhost:3000は自動トンネリングされます |
environmentId | string | 特定の環境のUUID |
credentialId | string | 特定の認証情報のUUID |
credentialRole | string | ロールで認証情報を選択（例：admin、guest） |
username | string | ログイン用ユーザー名（一時的 — 永続化されません） |
password | string | ログイン用パスワード（一時的 — 永続化されません） |
loginCredentials | array | タスク中にエージェントが遭遇するログイン用アカウント — [{username, password, label?}] |
useEnvironmentCredentials | boolean | デフォルトtrue。falseは環境の保存済み認証情報の自動入力を禁止します。アカウントが指定されていない場合、まったくログインしないことを意味します |
freshSession | boolean | デフォルトfalse。trueはそのアカウントで保持されているウォームセッションを再利用する代わりに、実際のログインを強制します |
auth | object | 認証の前提条件 — {precondition, entryUrl, deepUrl, environmentId, username, password} |
repoName | string | 自動検出されたgitリポジトリ名を上書き（例：my-org/my-repo） |
1回の呼び出しにつき1つの焦点を絞ったチェック。エージェントには約25ステップの内部予算があります。より広範なスイートは複数の呼び出しに分割してください。
認証情報：散文ではなくパラメータとして渡す
descriptionでのみアカウントを指定しても、エージェントがそれを使用するわけではありません — 環境の保存済み認証情報にフォールバックし、誤ったアカウントがアプリに拒否された場合、アプリケーションの障害のように見えます。パラメータとして渡すものはすべて、実行中のすべてのログインで環境デフォルトよりも優先されます（最初のログインだけでなく）：
username/password（またはcredentialId/credentialRole）— 実行のアイデンティティ。auth.username/auth.password—auth.precondition: "login"も使用する場合、前提条件のログインを固定します。loginCredentials— タスクの途中でエージェントが到達するログインフォーム用のアカウント。これはパスワード設定 → サインインにリダイレクト → 作成したばかりのアカウントでログインのようなフロー用で、別々の呼び出しに分割するとブラウザの状態が失われる場合に使用します。
useEnvironmentCredentials: falseは、デフォルトのテストユーザーへの無言のフォールバックがチェックを無効にする場合に設定します。
クロスドメインSSO？ 実行はアプリ自身のホストとそのサブドメインでのみ認証情報を入力します。別のドメインのサインインページはoffscope_hostとして拒否されます。IDプロバイダーのホストを環境のauthorizedCredentialHostsに追加してください（environmentを参照）。
ログイン不要のページをチェックする場合？ useEnvironmentCredentials: falseを渡し、アカウントを指定しないでください。その組み合わせはまさにその意味 — ログインしない — であり、実行はログインフォームを探す代わりに認証を完全にスキップします。パブリックページ、マーケティングサイト、ドキュメント、および認証前のあらゆるものに使用してください。また、より高速です：デフォルト（auto）では、エージェントはページから「ログイン」リンクをたどり、何かを評価する前に環境の保存済みアカウントを試します。
セッション再利用：チェックが「ログインフォームなし」と報告する理由
実行は毎回ログインするわけではありません。検証済みログインの後、バックエンドはそのアカウントのセッションをキャプチャし、同じアイデンティティの次の実行で復元します。これによりログインが完全にスキップされます — これが、チェックが正当にsubmitted: falseとログインフォームなしで返される理由です：すでにサインイン済みだったのです。復元された実行はloginsでreason: "restored_session"とともに自身を報告するため、実際にフォームが見つからなかった実行と区別できます。
セッションはアカウントごとにキー設定されているため、別のアカウントを指定しても他人のセッションを再利用することはありません。再利用をバイパスする2つの方法：
- 単一の呼び出しで
freshSession: true— 今回だけ実際にログインし、再キャプチャします。ログインフロー自体をチェックしている場合、保存済みセッションが古いと疑われる場合、またはアプリのペルソナ間の唯一のルートがログアウトである場合に使用します。 environmentツール、action: "clearSessions"— 保存済みセッションを無効化して、後続の実行がログインするようにします。username/credentialIdで絞り込みます。スコープなしのクリアは、環境のすべてのアカウントが再認証されるため、確認が必要です。
action: "sessions"を使用して、環境が現在保持しているものと、それぞれが再利用されるかどうかを確認します。
結果は実際に使用されたアイデンティティを報告するため、誤ったアイデンティティは壊れたアプリとして偽装されるのではなく、可視化されます：
"logins": [
{ "username": "qa+invitefix@example.com", "source": "task", "submitted": true, "authenticated": true },
{ "username": "qatest123@example.com", "source": "env_default", "submitted": false, "authenticated": false,
"reason": "offscope_host", "detail": "refused to enter credentials on auth.idp.example: not part of this run's scope …" }
],
"credentialWarning": {
"requested": "qa+invitefix@example.com",
"used": ["qatest123@example.com"]
}
sourceはtask | explicit | credential_id（指定したアカウント）またはenv | env_default（環境の保存済みアカウント）です。submittedは認証情報が実際に入力され送信された場合にのみtrueです。reasonは何が起こったかを示し（例：offscope_host、restored_session）、detailは存在する場合、その人間が読める説明です — offscope_host拒否の場合、ホスト名と承認方法を示します。credentialWarningは、アカウントを指定し、異なるアカウントの環境デフォルトが実際に送信された場合にのみ表示されます — 拒否またはスキップされたログインでは表示されません。loginErrorは、指定されたアカウントを解決できず、実行が別のアカウントへの置き換えを拒否した場合に表示されます。
すべての成功した実行は、スクリーンショットとともに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は自動的にトンネリングされます。正常な取り込み時に{executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?}とknowledgeGraph.skipped === falseを返します。crawlSummaryとknowledgeGraphは、バックエンドのクロール/インポートノードが報告したキーのみを保持します — 欠落したカウントは存在しないのであって、埋められた0ではありません。browserSessionブロック（HAR + コンソールログURL、上記と同じ形状）も完了したクロールに存在します。
probe_page
軽量なLLM不要のバッチページプローブ。 1〜20個のURLを渡します。各URLはナビゲートし、コンテンツで安定します（DOMが静かになること — 境界あり。ライブアプリが到達しないネットワークの沈黙では決してありません）、レンダリングされた状態 — スクリーンショット + ページメタデータ + 構造化コンソールエラー + ネットワークサマリーを返します。エージェントループなし、LLMコストなし、シナリオアサーションなし。check_app_in_browserの60〜150秒のエージェントループが過剰な場合の「/settingsを壊したか？」、リファクタリング後のマルチルートスモーク、CIのPRごとのスイープ、および迅速な稼働確認に使用します。
| パラメータ | 型 | 説明 |
|---|---|---|
targets | array 必須 | 1〜20エントリ：[{url, waitForSelector?, waitForLoadState?, timeoutMs?}] |
targets[].url | string 必須 | パブリックURLまたはlocalhost（自動トンネリング） |
targets[].waitForLoadState | enum | 'domcontentloaded'（デフォルト、+ 境界のあるコンテンツ安定化）/ 'load'（サードパーティの埋め込みもブロック）/ 'networkidle'（受け入れられるが、発行されない — ライブサイトのネットワークはアイドルにならない） |
targets[].waitForSelector | string | ナビゲーション後に待機するオプションのCSSセレクタ |
targets[].timeoutMs | number | URLごとのタイムアウト、1000〜30000（デフォルト10000） |
includeHtml | boolean | 各結果に生のHTMLを返す（デフォルトfalse） |
captureScreenshots | boolean | ターゲットごとに1つのPNGを返す（デフォルトtrue） |
バッチ内のすべてのターゲットは1つのセッショントンネルを共有しますが、同じポート（またはすべてパブリック）のバッチのみが単一のバックエンド実行を共有します — 1つの呼び出しで1つのポート上の5つのURLは、5つの並列単一URL呼び出しよりも劇的に高速です。複数のローカルポートを混在させるバッチは、ポートグループごとに1つのシーケンシャルなバックエンド実行に分解されます（依然として1つの呼び出し、元の順序で1つのマージされたresults[]ですが、1つの代わりにN回のバックエンドラウンドトリップ — 遅いが拒否はされません）。URLごとのerrorフィールドはバッチの回復力を維持します：単一の失敗したターゲットは他を失敗させません。
networkSummary 集約キーは origin + pathname です — 再取得ループ（?n=0..4 が同じエンドポイントに繰り返しヒットする）はカウント付きの単一エントリにまとめられるため、/api/poll が count: 47 とともに表示されることが、ユーザーが元々求めていた実用的な「無限再取得ループ」シグナルとなります。
パフォーマンス予算: 1 URL で 10 秒未満、20 件で 25 秒未満。ローカルホストのデッドポートは、ワークフロー実行を消費せずに 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?, authorizedCredentialHosts?} | 作成された環境（オプションで認証情報をシード） |
update | {uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?, authorizedCredentialHosts?} | パッチ適用された環境。認証情報操作は 削除 → 更新 → 追加 の順で実行されます |
delete | {uuid, projectUuid?, confirm?} | 環境を削除（認証情報もカスケード削除）— 確認が必要です |
sessions | {uuid, username?, credentialId?} | 環境が保持するキャプチャ済みログインセッション。アカウントごとに、それぞれ独自の isUsable を持ちます |
clearSessions | {uuid, username?, credentialId?, confirm?} | それらを無効化し、次回の実行で実際にログインさせます — スコープなしのクリアには確認が必要です |
projectUuid は、省略時は git リポジトリから自動解決されます。認証情報ごとの失敗は、環境操作をブロックせずに credentialWarnings[] に表示されます。
authorizedCredentialHosts は、アプリ自身のホスト以外で、実行がこの環境の認証情報を入力できるホストを一覧表示します — クロスドメイン SSO の場合は、ここに IdP ホストを追加してください（例: ["auth.example.com"]）。ベアホスト名のみ: スキーム、パス、ポート、ワイルドカードは不可（アプリのホストのサブドメインは既にスコープ内です）。update ではリストを置き換え、[] ではクリアします。get/list は、サーバーがサポートしている場合にそれを返します。レスポンスは保存されたリストをエコーします。サーバーがそれを永続化しなかった場合（古いサーバーはフィールドを無視）、結果はサイレント成功ではなく authorizedCredentialHostsWarning: {requested, returned} を伴います。
sessions / clearSessions は、バックエンドがログインをスキップするために再利用するウォームな認証済みセッションを管理します（セッション再利用 を参照）。セッションの内容は決して返されません — セッションクッキーはベアラー認証情報です。clearSessions は行を削除するのではなくセッションを無効としてマークするため、キャプチャ履歴が読み取り可能なまま、再利用は即座に停止します。
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 として表面化します。認証情報は常にパスワードなしで返されます。
ページネーション
すべての list レスポンスはページネーションされています。レスポンスの形状:
{
"pageInfo": { "page": 1, "pageSize": 20, "totalCount": 47, "totalPages": 3, "hasMore": true },
"<items>": [ ... ]
}
オプションの page（1 始まり、デフォルト 1）と pageSize（デフォルト 20、最大 200。過大な値はクランプされます）を渡します。レスポンスがサイレントに切り詰められることは決してありません。
get は、単数形の名前の下に 1 つのオブジェクトを返します — {project}、{execution}、{project, environment} — pageInfo はありません。
リソース
ツールに加えて、サーバーは読み取り専用エンティティを 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（
*.tunnel.debugg.ai、および過去の実行がまだ参照する廃止された*.ngrok.debugg.ai）は、エージェント作成のテキストを含むすべてのブラウザエージェントレスポンスから削除されます。 - バックエンドからの 404 は、スローされた例外としてではなく、
{error: 'NotFound', ...}付きのisError: trueとして表面化します。 - 欠落している
DEBUGGAI_API_KEYは、最初の呼び出し時に構造化されたツールエラーとして表面化します — サーバーは通常どおりツールを登録・一覧表示します。
v6.0.0 への移行（バックエンド判定、MCP 作成テキストなし）
実行の判定は pass | fail | error で、バックエンドの reason がそのまま中継されます。テストを試みなかった実行は outcome: null、skipped: true、skipReason と読み取ります。
| 削除されたもの | 置き換え |
|---|---|
success | outcome |
failureCategory | outcome + reason |
stepsTaken / stepsBudget / stepsRemaining | budget: {maxSteps, usedSteps} |
failedNode | errorInfo |
get → projects[0] / executions[0] / environments[0] + pageInfo + filter | {project} / {execution} / {project, environment} |
警告と結果の message / note | 構造化フィールドのみ |
完全なリスト: CHANGELOG.md 6.0.0。
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。 |
DEBUGGAI_EVAL_TEMPLATE | いいえ | check_app_in_browser がディスパッチする App Evaluation ワークフローの スラッグ を上書きします。デフォルトは flow/e2es/app-eval。ディスパッチはこのスラッグに固定されるため、バックエンドのテンプレート名変更で壊れることはありません。 |
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 インストールにはこれらは必要ありません。
マルチレプリカデプロイメント（ロールアウト前のゴー/ノーゴー判断）: トンネル状態（セッショントンネル、その Caddy インスタンス、およびポートルートロック）はプロセス内にあり、ベアラートークンのハッシュによって呼び出し元ごとにキー設定されます — クロスプロセス調整はありません。プレーンなラウンドロビンロードバランサーの背後で複数のレプリカを実行すると、1 人の呼び出し元の呼び出しが異なるレプリカに到達し、セッション全体で 1 つではなく、ヒットしたレプリカごとに 1 つのトンネルを作成する可能性があります（レプリカ数で制限され、既存の 55 分間のアイドル自動シャットオフによる自己修復 — 単一のツール呼び出しはその全期間中 1 つのレプリカに留まるため、クロスセッションの正確性バグには決してなりません）。マルチレプリカ HTTP デプロイメントで意図した「セッションごとに 1 つのトンネル」動作を実現するには、ロードバランサーでセッションアフィンルーティングを設定してください（getSessionKey() が導出するのと同じ ID — 実際には呼び出し元の Authorization ベアラートークン — をキーとするスティッキー/一貫性ハッシュ）。完全な理由と、これが設定されていない場合の正直な劣化パスについては、docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.1 を参照してください。
テレメトリ
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)です。生のキーやPIIは決して含まれません。 phc_*キーはPostHogの規約により書き込み専用です。ソースに埋め込んでも安全です。DEBUGGAI_TELEMETRY_DISABLED=1を設定すると完全にオプトアウトできます（no-opプロバイダーに解決され、プロセス外にイベントは送信されません）。
アクティブモードは起動時にログ記録されます：
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
このリポジトリには .mcp.json が同梱されており、node dist/index.js を指す プロジェクトスコープ のサーバー名 debugg-ai-local を登録します。これはビルド直後のローカルコードです。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 呼び出しで変更が反映されます。
リンク
Dashboard · Docs · Issues · Discord
Apache-2.0 License © 2025 DebuggAI