debugai-mcp

@debugai/mcp

コーディングエージェントに grep の繰り返しではなく、デバッガーを使わせましょう。

エージェントがエラーを debug_error に渡すと、根本原因、正確なファイルと行、そしてすぐに適用できる編集案として、優先度順に最大 3 件の修正案が返されます。各修正案には、機械的なチェックに実際に合格したかどうかが示されるため、エージェントはチェック済みのものと、モデル独自の推定によるものを区別できます。

その前に、lookup_error がプロジェクトのメモリを調べ、このエラーが以前ここで発生したことがあるか、どの修正が有効だったかを確認します。モデルへの呼び出しは行わず、利用上限にもカウントされないため、エージェントは失敗するたびに安心して実行できます。Claude Code では、フックがエージェントの記憶に頼らず、コマンドが失敗するたびにこれを実行します。

Claude Code、Claude Desktop、Cursor、Windsurf、Zed、Gemini CLI、Cline を自動設定します。手動で設定すれば、ほかの MCP クライアントでも使えます。Node 18.14.1 以降が必要です。

2.7.0 の新機能： 機械的に適用できる編集案で、コードが実際に記述されているファイルを示すようになりました。ツールは、エラーを貼り付けるのを待たずに、問題が発生した時点ですぐ呼び出すよう案内します。また、更新が遅れているサーバーは、診断のたびにではなく、セッションごとに 1 回だけそのことを伝えます。ホームフォルダー、その上位フォルダー、またはファイルシステムのルートから起動したサーバーは、それらをプロジェクトとして扱わなくなりました。エージェントが projectRoot を指定するまでは、ローカルファイルを読み込みません。変更履歴をご覧ください。

修正がうまくいかなかったら教えてください。こちらで直します。 このリリースの大半は、うまくいかなかった修正をもとに作られました。 送信したエラーと、修正によって実際に起きたことを添えて、 **ダッシュボード → メッセージ**からお知らせください。開発者に直接届きます。

セットアップ

npx -y @debugai/mcp setup

これだけです。ブラウザーを使ってサインインし（キーを探したりコピーしたりする必要はありません）、このマシンで見つかったすべての MCP クライアントの設定を書き込み、すべてが実際に動作することを確認します。

表示されたクライアントを再起動すると、エージェントがツールを使えるようになります。

先に説明を読みたい場合は、debugai.io/start?src=npmでクライアントごとの同じ手順を確認できます。

このコマンドがマシンに対して行うこと

エディターの設定を書き換えるコマンドを実行する前に、知っておくとよいこと：

• ブラウザーで確認する短いコードを使ってサインインします。無料アカウントで、1 日 10 回までデバッグでき、カード情報は不要です。
• キーは ~/.debugai/config.json に 0600 の権限で保存されます。キーが保存されるのは、このファイルだけです。
• 検出された各 MCP クライアントの設定に debugai エントリーを追加します。各ファイルは事前にバックアップされ（<file>.debugai-backup-<timestamp>）、ファイル内のほかの設定はすべて保持されます。解析できないファイルは変更せず、その旨を報告します。注意点を明記すると、設定にコメントが含まれている場合、書き換えによってコメントは削除されます。JSON にはコメントを格納できないためです。install は先に書き込み、その後で通知します。バックアップにはコメントが残っています。install --dry-run を使えば、書き込み前に内容を確認できます。
• 既定では VS Code をスキップします。DebugAI 拡張機能がすでにこのサーバーを登録しているため、エントリーを重複させるとすべてのツールが 2 回ずつ表示されるからです。拡張機能なしでサーバーを使いたい場合は、install --client=vscode を指定すれば設定できます。
• キーをクライアント設定に書き込むことはありません。クライアント設定はリポジトリにコミットされますが、キーはそうすべきではありません。

何も書き込まずに内容を確認します：

npx -y @debugai/mcp install --dry-run

すべての変更を元に戻します：

npx -y @debugai/mcp uninstall   # removes the entry from every client config
npx -y @debugai/mcp logout      # removes the stored key

コマンド

コマンド	説明
setup	login、install の順に実行し、最後に検証します。これを使ってください。
login	ブラウザーでサインインします。代わりにキーを貼り付ける場合は --key dbg_… を指定します（CI、ネットワークから隔離された環境向け）。再リンクするには --force を指定します。
logout	保存されたキーを削除します。
status	現在有効なキーとアカウントを確認します。
install	クライアントの設定を書き込みます。--list、--client=cursor、--all、--dry-run、--remove を指定できます。
uninstall	すべてのクライアント設定からエントリーを削除します。
doctor	壊れたセットアップを診断します。キー、APIへの到達性、クライアントごとの接続設定、バージョンのない設定エントリー、クライアント設定内に平文で保存されたキーを確認します。
hook	Claude Code のフックです。失敗したコマンドを標準入力から読み取り、プロジェクトのメモリにある情報を出力します。Claude Code のフックを参照してください。

npx -y @debugai/mcp install --list を実行すると、サポートされているすべてのクライアント、OS 上での設定ファイルの場所、DebugAI がすでに設定に含まれているかどうかが表示されます。

チャット内からサインインする

サインインする前にエージェントが DebugAI のツールを呼び出すと、エラーの代わりに短いコードと URL が返されます。ブラウザーで確認し、エージェントにもう一度試すよう伝えると、呼び出しが成功します。キーは呼び出しのたびに再読み込みされるため、設定の編集もクライアントの再起動も必要ありません。

ツール

想定されている一連の流れは、コマンドが失敗すると lookup_error が1秒以内にメモリから回答し、確認済みの修正を適用してコマンドを再実行する、というものです。メモリに情報がない場合は debug_error が分析します。どちらの場合も report_outcome が何が起きたかを記録し、その内容を次回の検索で読み取ります。

lookup_error

このプロジェクトで以前に同じエラーが発生したことはありますか？そのとき、どの修正が有効でしたか？（2.6）

入力	必須	説明
errorText	はい	debug_error に渡すときと同じ形式のエラーまたはスタックトレースです。
projectRoot	いいえ	エージェントの起動場所が別の場合に指定する、エラーが発生したリポジトリの絶対パスです。
filePath	いいえ	そのリポジトリ内の絶対パスです。このパスの git ルートがプロジェクトを特定します。

小規模なデータベース読み取りを2回行うだけで、モデル呼び出しはないため無料です。デバッグ上限にはカウントされません（適切な利用を保つため、別途、余裕のあるレート制限が設けられています）。このプロジェクトでエラーが何回、いつ発生したか、保存された修正とその状態、さらにこのプロジェクトで最近失敗が報告された修正を返します。

• confirmed：誰かが修正を適用し、動作したと報告しています。回答には、稼働中のセッションでエラーが解消するのを確認したのか、単に修正が受け入れられただけなのかが示されます。これらは証拠の強さが異なります。
• unproven：修正は適用されましたが、その後エラーが一度再発しています。現在のコードに照らして確認してください。
• anti-pattern：修正後にエラーが2回以上再発しています。回答では、避けるべきものとして明示されます。

該当する情報がない場合はその旨を示し、debug_error を案内します。エラーのテキストは、デバッグ時とまったく同じ方法で準備され、まず認証情報が伏せられるため、ある失敗について検索とデバッグを行うと、同じメモリ行が参照されます。検索では何も書き込まれません。デバッグでもなく、発生記録でもありません。

debug_error

エラーを渡すと、分析結果が返されます。

入力	必須	説明
errorText	はい	エラーメッセージ、例外、またはスタックトレースの全文です。エラー文がないバグでも構いません。その場合は、期待していたこと、実際に起きたこと、その間に関係するコードを記載してください。
language	いいえ	auto（デフォルト）、または言語名を指定します：javascript、typescript、python、java、csharp、go、rust、cpp、c、php、ruby、kotlin、swift、lua、shell、powershell、sql、html、css、scala、dart、elixir、r、perl。理由がない限り auto のままにしてください。サーバーはエラー文を読み取り、ほぼ常に正しく判定します。この一覧にない名前（markdown、cobol）を指定してもエラーにはならず、auto として扱われます。
codeSnippet	いいえ	通常は不要です。下記を参照してください。指定すると、ローカルでの読み取りより優先されます。
snippetStartLine	いいえ	codeSnippet と併用します。スニペットの先頭行がファイルの何行目かを指定します。ファイルの途中から切り出したスニペットの場合に渡してください。指定しない場合、行番号は1から数えられるため、15行のスニペットでは Line 44 と示されたエラーを照合できません。（2.7）
filePath	いいえ	エラーを発生させたファイルのパスです。絶対パスを指定すると、そのエラーが属するリポジトリも示せます。
projectRoot	いいえ	エージェントを別の場所で起動した場合に、リポジトリの絶対パスを指定します。プロジェクトメモリとローカルの読み取りは、このパスの範囲に限定されます。（2.6）
reproCommand	いいえ	失敗を再現するコマンドです。テスト、スクリプト、curl などを指定します。修正案 #1 はこのコマンドが成功するように作成され、各修正案の確認方法も構文チェックではなくこのコマンドになります。DebugAI がこのコマンドを実行することはありません。最大500文字です。（2.6）
expected	いいえ	バグが修正された後に reproCommand が出力または実行すべき内容です。最大500文字です。（2.6）

根本原因、確度順に最大3件の修正案、検出されたフレームワーク、回答がキャッシュから取得されたかどうかが返されます。各修正案には、導出できる場合、edits（エージェントの編集ツールで直接適用できる、正確な変更前／変更後の文字列）、unified_diff、および適用後に実行する確認方法 verify_with も含まれます。reproCommand を指定した場合、確認方法はそのコマンドと、期待される結果になります。指定しない場合は、構文レベルのチェックになります。ファイルへの書き込みや、再現コマンドの実行は行いません。修正を適用するかどうかは、エージェントであるあなたが決めます。

API が受け付ける3,000文字を超えるエラーは拒否されず、切り詰められます。先頭（JavaScript、Java、.NET がエラーを出力する部分）と末尾（Python がエラーを出力する部分）は残り、中間部分は省かれます。その旨は回答にも記載されます。lookup_error とフックでも同じ切り詰めが行われるため、3つすべてが1件の失敗について同じメモリ行を読み取ります。（2.6）

すべての回答のフッターには、記録されたプロジェクト名、そのプロジェクトでメモリが無効だった場合はその旨と理由、回答に使われたサーバーのバージョンとエンジンのビルドが記載されます。古いコピーで動作しているセッションでもそれを確認でき、回答を生成したコードを追跡できます。（2.6）

すべての修正案には検証状態のラベルが付きます。状態は2種類ではなく、次の3種類です：検証済み（機械的なチェックに合格。現在は解析とインポートのクラスが対象）、チェック失敗（確度に厳しい上限が設定されます）、未検証（確度の数値はモデル自身の推定であり、チェックされていません）。3つ目のケースも隠さず、ラベルを付けています。

トレースバックに記載されたソースを読み取ります（2.2）

生のトレースバックだけを貼り付けてください。このサーバーはお使いのマシン上で動作するため、スタックトレース内のファイルを特定し、関連するコードを送信します。2.2 より前はこれができず、コードなしで貼り付けたエラーには、信頼度 20% で 「具体的な修正に必要なコンテキストが不足しています」 と返していました。これは例外的なケースではなく、よくあるケースでした。

レスポンスには、読み取ったすべてのファイルが記載されます（Read locally: src/api.ts, src/db.ts と、構造化ペイロード内の local_files_read）。そのため、誤った推測は気づかれないままになるのではなく、目に見える形で示されます。

読み取るものと読み取らないものは、正確には次のとおりです。

• プロジェクト内のみです。 境界は Git リポジトリのルート、またはリポジトリでない場合は作業ディレクトリです。それがホームディレクトリの場合、その上位フォルダーやファイルシステムのルートには読み取り可能な境界がないため、ローカルファイルは何も読み取らず、その旨を返信します。projectRoot を渡してプロジェクトを指定してください。シンボリックリンクの解決後にチェックされるため、エラーメッセージ内のパスを使ってプロジェクトの外に移動することはできません。../../.ssh/id_rsa と、外部を指すシンボリックリンクは、どちらも同じチェックで拒否されます。
• ソースファイルのみです。 拡張子の許可リストで判定します（.ts .tsx .js .jsx .mjs .cjs .py .pyi .go .rs .rb .java .kt .kts .scala .groovy .gradle .php .cs .swift .dart .c .cc .cpp .h .hpp .ps1 .psm1 .psd1 .vue .svelte）。.env、.pem、鍵ファイル、ダンプ、画像は含まれないため、候補になることはありません。
• 上限があります。 ファイルは最大 3 件、各ファイルは 2 MB 以下、合計で 50,000 文字までです。大きなファイルは全体ではなく、エラー行の前後 ±40 行を送信します。ウィンドウ化されたブロックには、その旨が記載されます。
• ベンダー提供のコードはスキップします。 node_modules、site-packages、dist、.venv などが対象です。説明が必要なのはお客様のコードです。
• 指定したスニペットが常に優先されます。 codeSnippet を渡すと、ソースファイルは読み取られません。マニフェストは読み取られます（制限と誠実性を参照）。

読み取られた内容は、エラーテキストと同様に、分析のため DebugAI の API に送信されます。特定のソースファイルを送信したくない場合は、codeSnippet を明示的に渡してください。ソースファイルは読み取られません。制限と誠実性で説明されているプロジェクトのマニフェストは、プロジェクトルートが指定されたすべての debug_error 呼び出しで読み取られます。

report_outcome

回答後の状況を DebugAI に伝えます。修正を使わなかった場合も報告してください。

入力	必須	説明
debugLogId	はい	debug_error の応答に含まれる debug_log_id です。
result	はい	worked、worked_modified、failed、または unused です。
fixRank	いいえ	適用した修正の順位（1～3）です。どの順位の修正でも、記憶される修正になります。
finalFix	worked_modified の場合	変更後に実際に機能したコードです。提案ではなく、この内容が記憶されます。最大4,000文字です。（2.6）
newError	いいえ	failed の場合、適用後に発生したエラーです。説明ではなく、エラーメッセージを指定してください。最大4,000文字です。
actualFix	いいえ	DebugAI の回答以外で実際に問題を解決した方法です。最大4,000文字です。
toolFeedback	いいえ	今回の呼び出しで、ツールがどう改善されていればもっと役立ったかを伝えます。最大2,000文字です。

各判定が意味する内容は異なります。

• worked：修正を適用し、エラーが解消しました。この修正は、このプロジェクトで確認済みの修正になります。
• worked_modified：修正は変更を加えた場合にのみ機能しました。finalFix が必須で、提案内容に代わって記憶されるため、次の人には実際に機能した内容が提示されます。（2.6）
• failed：修正を適用しましたが、効果はありませんでした。このプロジェクトで以降の分析や検索を行う際、同じ修正を繰り返さないよう、参考情報として表示されます。エラーが再発した場合に限り、保存済みの修正の評価が下がります。報告しただけでは評価は下がりません。
• unused：こちらの修正は何も実行されませんでした。また、以前の debugLogId ですでに報告したエラーについて再度呼び出した場合も、修正が二重に数えられないよう、これを選んでください。

VS Code 拡張機能からのフィードバックと同じパイプラインを通ります。エージェントには、debug_error の回答ごとに1回呼び出すよう指示されています。

Claude Code での例：

トレースバックを貼り付けて、「なぜ失敗するのですか？」と尋ねます。Claude は debug_error を呼び出し、次のような応答を受け取ります。

根本原因： リクエストコンテキストが閉じた後に db.session が使われています。 修正1（確信度94%）： クエリをリクエストハンドラー内に移動します……

エージェントがこれを使うようにする

サーバーは接続するエージェントにこのツールの用途を伝えますが、プロジェクトファイルにルールを記述すれば、確実に呼び出させることができます。CLAUDE.md、.cursorrules、またはエージェントが読み込むファイルに次の内容を追加してください。

When a command fails, call the debugai lookup_error tool first: it is
instant and free. If it has no confirmed fix, call debug_error before
attempting your own, and pass the command that reproduces the failure
as reproCommand. After applying a fix, call report_outcome so the
project's error memory stays accurate.

Claude Code フック

ルールだけでは、エージェントがエラーを問い合わせる価値があると判断するかどうかに左右されます。エージェントは、明らかに見えるエラーを見過ごすことがあります。質問せずに修正したエラーについて、あるエージェント自身がこう述べています。「メッセージを見れば修正方法は明らかでした。問い合わせでネットワークを往復するより、修正するほうが速く感じました。」 こうしたエラーは繰り返し発生します。

debugai-mcp hook を使えば、その判断を取り除けます。Claude Code の PostToolUseFailure フックとして設定すると、終了コードが 0 以外の Bash または PowerShell コマンドの実行後に毎回動作し、このプロジェクトのメモリを検索して、エージェントが反応する前にエラーの横に回答を表示します。（2.6）

メモリに対処できる情報がある場合にのみ応答します。つまり、保存済みの修正（確認済み、未検証、またはアンチパターン）か、このプロジェクトで失敗したと報告されたアドバイスがある場合です。見つからない場合、タイムアウト、ネットワーク未接続、キー未設定、コマンドの中断、出力のないコマンドのいずれでも何も出力せず、どの経路でも終了コードは 0 になるため、ツールの呼び出しを妨げることはありません。保存済みの login キーを使用し、サインインは開始しません。フックではサインインへの応答ができないためです。

すべてのプロジェクトに適用する場合は ~/.claude/settings.json に、1 つのリポジトリに適用する場合はそのリポジトリの .claude/settings.json に、次の内容を追加します。

{
  "hooks": {
    "PostToolUseFailure": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          { "type": "command", "command": "npx -y @debugai/mcp@latest hook", "timeout": 20 }
        ]
      }
    ]
  }
}

その後、Claude Code 内で /hooks を実行すると、フックが読み込まれていることを確認できます。

• 失敗したコマンドごとのコスト。 npx は毎回 @latest を解決します。ある Linux マシンでの計測では、ウォーム時に 1.5～1.9 秒、コールド時に 6.7 秒かかり、検索そのものの時間は含まれていません。約 3 分の 1 秒で済ませるには、npm i -g @debugai/mcp@latest で一度インストールし、"command": "debugai-mcp hook" を使用してください。グローバルインストールは自動更新されないため、新しいバージョンがリリースされたらこのコマンドを再実行してください。
• タイムアウト。 Claude Code のコマンドフックのデフォルトは 600 秒です。フック自体には制限があり（入力の読み取りに 5 秒、検索に 8 秒）、20 を設定することで、ネットワークが停止してもエージェントがそれ以上待たされないようにします。
• マシンから送信される情報。 失敗したコマンドの出力（最大 3,000 文字。これを超える場合は先頭と末尾）と、リポジトリのパスからハッシュ化したプロジェクト ID です。出力は表示されたとおりに送信されます。このパッケージは出力をマスキングしません。API は出力を受信すると、検索で読み取られる前に認証情報をマスキングします。情報は何も保存されません。コマンドライン自体は送信されません。
• 対象のプロジェクト。 コマンドを実行した Git リポジトリを使います。debug_error が projectRoot を解決するのと同じ方法で特定するため、フックと同じエラーのデバッグでは同一のメモリを参照します。リポジトリの外では、そのフォルダー自体がプロジェクトとなり、その出力が送信されます。拒否されるのはホームディレクトリ、その親フォルダー、ファイルシステムのルート、および WSL では /mnt/c/Users/<name> などの Windows プロファイルのみです。この場合、フックは何も出力しません。

VS Code

このパッケージは必要ありません。DebugAI extension が MCP サーバーを自動的に登録し（VS Code 1.101 以降）、ワンクリックでの修正適用、プロアクティブスキャン、コードベースのインデックス作成を追加します。Open VSX でも公開されており、Cursor、Windsurf、VSCodium で利用できます。

2 つのサーバーは同じプロトコルの機能を提供し、両方のコピーをテキストとして読み取るテストによって同期を保っています。「同期を保つこと」というコメントだけでは、以前ここでうまくいかなかったためです。拡張機能の 2.8.1 以降、バンドルされたサーバーでもローカルのソース解決ができるようになりました。このパッケージでは 2.2.0 から対応しています。それまでは、バンドルされたサーバーを使うエージェントが、インデックス未作成のワークスペースにトレースバックを貼り付けると、確信度 20% で「具体的な修正を提示するにはコンテキストが不十分です」と返されていました。まさにこの機能が取り除こうとしている回答です。

手動でのセットアップ

setup で対応できます。また、クライアントが通常とは異なる場所にインストールされている場合は、install --client=<id> で対応できます。それでも自分でファイルを編集したい場合、エントリーはどのクライアントでも同じです。

{
  "mcpServers": {
    "debugai": {
      "command": "npx",
      "args": ["-y", "@debugai/mcp@latest"]
    }
  }
}

@latest はそのままにしてください。バージョンを指定しないと、npx は最初に見つけたコピーを実行するため、古いグローバルインストールが最新リリースより優先されます。あるエージェントは、プロジェクトを送信しない7月の2.1.1でセッション全体を実行したため、すべての呼び出しでプロジェクトメモリが無効になっていました。エントリーにバージョンが指定されていない場合、debugai-mcp doctor が警告します。

設定先：

Claude Codeでは、重要なのは --scope user の指定です。 claude mcp add のデフォルトは --scope local で、サーバーを projects."/your/dir".mcpServers に書き込みます。その場合、そのディレクトリでしか動作せず、 ほかの場所では動作しません。そのため、DebugAIはリポジトリごとにセットアップが必要だと 誤解されやすくなります。debugai-mcp install は常にユーザースコープに書き込みます。 すでにローカルスコープ版を実行している場合は、debugai-mcp doctor がどちらを使っているか 知らせてくれます。

クライアント	ファイル
Claude Code	~/.claude.json、トップレベルの mcpServers（または claude mcp add --scope user debugai -- npx -y @debugai/mcp@latest）
Claude Desktop	macOS ~/Library/Application Support/Claude/claude_desktop_config.json、Windows %APPDATA%\Claude\claude_desktop_config.json
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Zed	macOSおよびLinux ~/.config/zed/settings.json（設定されている場合は $XDG_CONFIG_HOME）、Windows %APPDATA%\Zed\settings.json。キーが異なります。詳細は以下を参照してください
Gemini CLI	~/.gemini/settings.json
Cline	VS CodeのglobalStorage、saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Zedでは異なるキーと、ネストされたコマンドを使用します。

{
  "context_servers": {
    "debugai": {
      "source": "custom",
      "command": { "path": "npx", "args": ["-y", "@debugai/mcp@latest"] }
    }
  }
}

次に、npx -y @debugai/mcp login を一度実行して、キーを保存します。クライアントごとにキーを設定したい場合は、そのクライアントの env ブロックにある DEBUGAI_API_KEY も引き続き使用でき、保存済みのキーより優先されます。

環境変数

変数	デフォルト	説明
DEBUGAI_API_KEY	(none)	APIキーです。設定ファイル内の api_key を上書きします。
DEBUGAI_API_BASE	DebugAI production	セルフホストまたはステージング環境で使用する値です。設定ファイル内の api_base にフォールバックします。
DEBUGAI_TIMEOUT_MS	150000	debug_error のみのタイムアウトです。詳細な分析には30～90秒かかることがあります。lookup_error は8秒、report_outcome は15秒待機し、フックはこの変数を無視します。
DEBUGAI_CONFIG_PATH	~/.debugai/config.json	代替の設定ファイルの場所です。通常は必要ありません。

制限と誠実性

• 無料プラン：1日あたり10回のデバッグ。Pro（月額12ドル）：月1,000回のデバッグが含まれ、その後はフェアユースが適用されます。1,000回はソフト上限のため、到達すると通知されますが、停止はされません。lookup_error とフックは、どちらの上限にもカウントされません。
• 1日の上限に達すると、ツールはその旨を伝えて停止します。通知なしに再試行することはありません。
• 単純なエラーは高速なモデルに回されます。複数ファイルにまたがる複雑なエラーは、有料プランではより高性能なモデルに回されます。各応答の Model: バッジで、どのモデルが回答したかを確認できます。
• 分析は DebugAI のサーバーで実行されます。エラーテキスト、渡したスニペット、（2.2以降）スタックトレースに記載されたプロジェクトのソースファイル、（2.5以降）以下で説明するプロジェクト情報が送信され、Claude（Anthropic）が分析します。Claude が利用できない場合は、OpenAI の GPT-4o-mini が分析します。また、プロジェクトのインデックスを検索するため、エラーテキストは Voyage AI によって埋め込みベクトルに変換されます。応答には、読み取られたファイルがすべて記載されます。範囲と制限については、debug_error をご覧ください。プライバシーポリシー：debugai.io/privacy。
• エラーはプロジェクトごとに記憶されるため、同じエラーが再発した場合は、すでに確認済みの修正から処理を開始します。プロジェクトの識別情報は、リポジトリのルートパスのハッシュです。プロジェクト ID にパスは含まれませんが、絶対パスの filePath は記載どおりに送信され、エラーテキスト内のパスも同様に送信されます。
• プロジェクトルートが指定された debug_error 呼び出しでは毎回、プロジェクトが宣言している内容も読み取って送信します。対象は package.json、requirements.txt、pyproject.toml、およびすべての .csproj、.fsproj、.vbproj です（プロジェクトルートから、深さと数に上限を設けて階層をたどって検出します）。送信されるのは、依存関係の名前とマニフェストに記載されたバージョン、検出されたマニフェストの種類（package.json や *.csproj など。保存場所は含みません）、プロジェクト内の Python モジュール名、仮想環境フォルダー名、node_modules フォルダーと .env ファイルの有無です。.env の内容が開かれることはありません。codeSnippet を渡した場合も同様です。これにより、エンジンはパッケージが宣言済みかどうかを判別できます。
• 送信されない情報は、どの Python インタープリターが選択されているかです。VS Code 拡張機能はエディターからこの情報を読み取れるため、「未インストール」と「別のインタープリターにインストール済み」を区別できます。このサーバーには同等の機能がないため、モジュールが見つからないエラーでは、一般的な回答と実行すべき確認方法が提示され、断定的な判定は行われません。シェルを使えるのはあなたであり、サーバーは使えません。そのため、確認はあなたが実行するのが適切です。

トラブルシューティング

まず npx -y @debugai/mcp doctor を実行してください。Node のバージョン、キーが保存されているかとその保存場所、キーが現在も API の認証に使えるか、設定ファイルの権限、検出されたクライアントのうち DebugAI のエントリーがないものを確認します。ほとんどの場合、必要な情報はこの出力に含まれています。

• 「authentication failed」：キーがローテーションされたか、取り消されています。npx -y @debugai/mcp login --force を実行してください。
• クライアントにツールが表示されない：クライアントが再起動されていないか、別の設定ファイルを読み込んでいます。install --list を実行すると、書き込まれたファイルを確認できます。
• npx @debugai/mcp を実行しても何も起きない：これは正常です。MCP クライアントからの通信を待機する stdio サーバーです。インストールを確認するには --help を使用してください。
• タイムアウトする：詳細な分析には最大90秒かかることがあります。クライアントに独自のツールタイムアウトがある場合は、それより長く設定してください。
• フックが何も表示しない：該当するものがない場合（ほとんどの失敗が該当します）は、何も表示しません。Claude Code の /hooks で読み込まれているかを確認でき、claude --debug には各実行が記録されます。また、保存済みのキーが必要です（npx -y @debugai/mcp login）。キーを要求することはありません。

変更履歴

更新について：分析は DebugAI のサーバーで実行されるため、 エラー解析、検索、根本原因の特定の改善は、この パッケージをアップグレードしなくても利用できます。クライアントのリリースは、お使いのマシン上で変更がある場合に限られます。 サーバー側の最近の改善です。各項目は、対応するエンジンリリースがデプロイされると、アップグレードなしでエージェントに反映されます。

• エージェントが報告した失敗が、エンジンのエラー表現リストに該当の文言がなかったという理由で「エラーではない」として拒否されなくなりました。 No module named、Ubuntu の Command 'x' not found、ブラウザーの net::ERR_*、そして「error」という単語を使わずに Line 44: Undefined symbol と表示するコンパイラーは、これまでいずれも拒否されていました。プロンプト、パスだけの入力、またはスタブは、引き続き拒否されます。
• エラーが示す行を実際には受け取っていない場合、そのことが回答に明記されるようになりました。 19 行のスニペットに対して Line 528 と報告するエラーについて、以前は 1～19 行目をもとに説明していました。現在は、提供された行と報告された行を示す一文を添えて、低い信頼度で回答します。また、キャッシュされないため、要求された行を送れば新たに解析されます。
• 見つからないコマンドが、プロジェクト内のスクリプトだと決めつけられなくなりました。 PATH が削られて見つからなかった curl、winget、powershell は、インストールされるのではなく、フルパスで呼び出されます（これらは Windows に付属しています）。コマンドプロンプトに渡された PowerShell（$ws、Get-ChildItem）は、ツールが見つからないのではなく、シェルが違うと判定されます。不明な名前は、実行前に検索されます。
• Playwright のタイムアウトが、アプリのせいだと決めつけられなくなりました。 「表示され、有効で、安定するまで待機」は、ドライバーが操作できなかったことを示しています。回答では、「ページ上にない」のか「ページ上にあるが、覆われているか動いている」のかを判別するチェックを最初に案内し、force: true はラベル付きのテスト用回避策としてのみ提示します。
• package.json に関する npm の ENOENT ... package.json には、エラーですでに示されているフォルダーへの cd ではなく、npm --prefix を使った対処を案内します。何も指していないパスの場合は、何かを再インストールする前に、存在するフォルダーまで親フォルダーをたどります。localhost に対するブラウザーの ERR_CONNECTION_REFUSED も Node と同様に原因を判断し、最初の行を確認できる場所でサーバーを実行するよう案内します。
• ModuleNotFoundError の回答で、インストールコマンドを最初に提示しなくなりました。これまで回答したすべての事例を調べたところ、8 件中 5 件が受け取ったエージェントに拒否されており、その原因は 3 種類あり、それぞれ異なる対処が必要でした。別のインタープリターにパッケージがインストールされていた、名前がローカルファイルだった、または import 行の形式が誤っていた、のいずれかです。現在は、これらを判別するチェックが最初に提示されます。
• Python の SyntaxError が JavaScript のエラーとして診断されなくなり、フレームワークはリポジトリの内容ではなく、エラーテキストから判別されます。
• オペレーティングシステムのエラー（Access is denied.、No space left on device）がエラーとして認識されるようになりました。30 件を調べたところ、28 件が拒否されていました。
• 送信するテキストに含まれる認証情報は、保存されたりモデルに送られたりする前に置き換えられます。
• pytest、unittest、jest、vitest、mocha の出力から実際のファイルパスを取得できるため、失敗したテストに対して、ファイル間のコンテキストも含めて対応できるようになりました。

2.7.0 - 2 つ目のエージェントから寄せられた現場報告をもとに構築しました。今回は、どのモデルのトレーニングデータよりも新しいライブラリを使った新規プロジェクトからの報告です（2026-09-20 の報告）。

• ホームディレクトリはプロジェクトではありません。 リポジトリ外の ~ やファイルシステムのルートでサーバーを起動すると、そこがプロジェクトルートとして扱われていました。配下のファイルを示すスタックトレースが読み取られて送信され、配下のマニフェストも走査されていました。現在はプロジェクトルートがないと判断し、ローカルのファイルを読み取らず、プロジェクト情報も収集せず、その旨を返信で伝えます。プロジェクトを指定するには projectRoot を渡してください。同じ拒否動作は、ホームディレクトリの上位フォルダー、WSL では Windows のプロファイル（/mnt/c/Users/<name>）、Windows からはネットワーク共有または WSL ディストリビューション（\\server\share、\\wsl.localhost\Ubuntu）にも適用されます。ドットファイルのチェックアウトによって projectRoot が無効になることもなくなりました。指定したフォルダーが使われるため、上位のリポジトリがホームディレクトリでも問題ありません。

• debug_error の snippetStartLine。 渡したスニペットにはヘッダーがないため、常に1行目から数えられていました。そのため、ファイルの途中からの範囲を、エラーが示す行に対応付けられませんでした。開始行を指定してください。このサーバーが自ら読み取るファイルには、ヘッダーに開始行が記載されています。

• language は任意の文字列を受け取ります。 リストにない名前を指定すると、以前は呼び出しが失敗し、エージェントは auto で再試行する必要がありました。現在は auto として扱われます。特に markdown でこの問題がよく起きていました。lua、dart、elixir、r、perl もゲートウェイによって unknown にまとめられ、言語別の件数に表示されませんでしたが、現在はそのまま保持されます。

• 編集内容には、コードが存在するファイルが指定されます。 このサーバーは、スタックトレースで示されたすべてのファイルを解決してまとめて送信します。以前は、各修正の edits[].file に、修正対象が何であっても、そのうちの最初のファイルが指定されていました。差分ヘッダー、チェックコマンド、行番号も同様でした。これを確認せずに適用すると、あるファイルのコードが別のファイルに書き込まれたり、より多くの場合、照合に失敗して再読み込みが必要になったりしていました。行番号は現在、そのファイル固有の番号で返されます。また、2つのファイルにまたがる修正には、誤ったパスを自信満々に示すのではなく、編集内容が付かなくなりました。

• ツールの説明は、実際の状況に即したものになっています。 以前は、トリガーの説明はどれもユーザーが何かをすることを前提としていました。「ユーザーがエラーを貼り付けたときはいつでも使用する」のような説明です。エージェントのセッションでは、何かを貼り付ける人はいません。エージェントがビルドを実行しています。debug_error は、エージェント自身が失敗を引き起こした場合も含め、何かが失敗した時点で呼び出すようになりました。また、そのタイミングとして、型チェックがゼロ以外の値で終了したとき、リンターがエラーを報告したとき、テストスイートが失敗したときなどを明示しています。

• report_outcome では、誤ったパッチと誤った診断を区別します。 根本原因が正しくても修正を適用できなかった場合は、failed ではなく unused になります。これを failed として記録すると、パッチの問題を診断のせいにすることになり、それぞれに必要な修正は正反対です。

• 古いクライアントには、冒頭で一度だけ通知します。 以前は、エージェントがユーザーに引用するフィールドである root_cause に、毎回通知が追加されていました。あるエージェントは、5リリース前のバージョンを実行しながら、それをセッション全体に共通する定型文だと解釈しました。現在は独立したフィールドになり、診断の前にプロセスごとに一度だけ表示されます。

• 同梱の VS Code サーバーにも、このサーバーと同じ説明が適用されます。 2つのサーバーの説明には差が生じており、同梱版では、スタックトレースで示されたソースファイルを読み取るという段落が抜けていました。

• より多くのツールチェーンでソースファイルが読み取られます。 MSBuild と tsc の file(line,col)、javac と Maven の [line,col]、.NET の in path:line N、PowerShell の At path:N、Gradle のビルドファイル、file:// パス、JVM フレームが、ファイルを示すようになりました。新たに対応したファイル形式：.c .cc .cpp .h .hpp .pyi .kts .scala .dart .groovy .ps1 .psm1 .psd1 .gradle。

• ディスクから読み取る内容が API の制限内に収まります。 以前は、長い行を含むファイルを3つ読み取ると、50,000文字の上限を超えて拒否され、コードを渡していないエージェントにその旨が返されていました。現在は、失敗箇所の前後にある行全体を保ちながら、残りの文字数に合わせて各ファイルを切り詰めます。最大2 MBのファイルはウィンドウ単位で読み取られるようになりました。以前の256 KBの上限では、行の途中で切れていました。

• 空の codeSnippet または filePath は、未指定として扱われます。 オプションのパラメーターに "" を設定したエージェントに対し、ファイルを読み取ったと伝えながら、コードを何も送信しないことがありました。

• 読み取られていないマニフェストは、何も宣言していないマニフェストとは異なります。 UTF-16 の requirements.txt、512 KBを超えるファイル、バイトオーダーマークを含む、または解析できない package.json、途中で停止した走査は、以前は完全だとする一覧を送信し、エンジンは「宣言されていない」と回答していました。現在はそれぞれ、一覧が不完全な可能性があることを示します。pyproject.toml はテーブルごとに読み取られるため、testpaths や作者名が依存関係として送信されることもなくなりました。

• エラーメッセージで、次に何をすべきかが分かります。 月間上限に達した場合や、API が認識しない debugLogId が指定された場合は、再試行する意味がないと報告します。短時間のレート制限では、待ち時間が示されます。障害が発生した場合は、エンジン独自の説明文がそのまま渡されます。API の代わりにプロキシやサインインページが応答した場合は、不正な JSON としてではなく、そのような応答として示されます。リクエストの期限は、ヘッダーを待つ時間だけでなく、応答全体に適用されるようになりました。

• サインインがより堅牢になりました。 短時間の API 障害があっても処理が継続し、設定ファイルに書き込めない場合も受け取ったキーを保持します。http(s) アドレスのみを開き、Windows では cmd を経由しなくなりました。また、固定値ではなく、サーバーが報告する無料利用枠を表示します。

• install は、設定ファイルを元の状態に保ちます。 ファイルのパーミッションを維持し、シンボリックリンクを置き換えずにそのリンク先へ書き込み、バイトオーダーマークで始まるファイルも読み取ります。uninstall は VS Code のエントリーと、Claude Code のディレクトリ単位のエントリーも削除します。

• Windows では、パスの表記にかかわらず、ホームフォルダーをプロジェクトとして使用できません。 2.6.0 - 2026-09-16 にまとめられた、あるエージェントが実際に1週間使用した際の現場レポートをもとに、問題をひとつずつ解決しました。

• lookup_error、新しいツールです。モデルを呼び出さず、料金も発生させずに、このプロジェクトのエラーに関するメモリーを検索します。レポートのエージェントは、分析をすべて実行するより修正するほうが速く感じられたため、5つのエラーで DebugAI を使いませんでした。そのたびに、エラーメモリーに記録される機会を逃していました。

• debugai-mcp hook は、Claude Code でシェルコマンドが失敗するたびにその検索を実行するため、呼び出すかどうかの判断をエージェントに委ねません。Claude Code hook をご覧ください。

• debug_error の reproCommand と expected。レポートにあった6つの回答はすべて、スキャンできないQRコードやループするモデルの修正を確認する方法として、python -m py_compile または node --check を提示していました。エージェントは毎回、実際に確認する方法を持っていました。修正 #1 はその確認方法を対象にするようになり、各修正の確認手順にもなります。DebugAI が実行することは、引き続きありません。

• report_outcome の worked_modified と finalFix。エージェントが変更した後にしか機能しなかった修正は、これまでは worked, rank 1 としてしか報告できなかったため、メモリーには実際に機能した修正ではなく、提案が保存されていました。ランク2やランク3の修正が機能した場合も記憶されるようになりました。

• projectRoot と、リポジトリを指定する絶対パスの filePath。あるフォルダーで起動し、別のフォルダーで作業していたエージェントは、すべてのエラーを誤ったプロジェクトに記録され、ローカルファイルの読み取りもすべて拒否されていました。各回答の末尾にプロジェクト名が表示されるようになり、メモリーが無効だった場合は、その理由も示されます。

• すべての回答に、このサーバーのバージョンとエンジンのビルドが表示されます。 レポートのエージェントは、受け取る情報にバージョンが含まれていなかったため、7月の 2.1.1 を使っていることに気づかないままセッションを過ごしました。インストーラーは @debugai/mcp@latest を書き込み、doctor はバージョンのない設定項目と、クライアント設定に平文で残されたキーを警告します。また、古いサーバーには新しいバージョンがあることを1日に1回通知します。

• 大きなファイルからコードの一部を表示する際は、実際の行番号が付くようになりました。そのため、539行目についての回答が4行目として返されることはありません。

• 各修正の変更点は、説明文で一度だけ表示されます。差分全体は、構造化された結果にそのまま含まれます。

• 3,000文字を超えるエラーは、400エラーを返してエージェントに回避策を要求する代わりに、先頭と末尾を残して長さを調整します。

2.5.1 - language が、6種類ではなく24種類の言語を受け付けるようになりました。以前は javascript、 typescript、python、go、rust、auto のみが列挙されていたため、ほかの言語を指定したエージェントは 呼び出しを拒否され、auto で再試行する必要がありました。9月のログで最も利用の多かった10アカウントのうち4つが その状況にあり、java、csharp、css、lua の4言語でデバッグは合計52件でした。利用の少ない半数ではさらに深刻でした。 再試行が成功するため、そのすべての記録で language = unknown となり、Java のスタックトレースが 検出失敗のように見え、言語ごとの件数も、まさに欠落していた言語を過少に数えていました。auto は引き続き既定値であり、 ほとんどの場合、引き続き適切な選択肢です。

2.5.0 - サーバーが、プロジェクトで宣言されている内容を読み取り、依存関係の名前と、各マニフェストで固定されているバージョンをエラーとともに送信するようになりました。.NET の .csproj やモノレポ内の入れ子になったマニフェストも含まれます。エンジンはこれまでディスクを参照できなかったため、サードパーティ API を推測していました。今ではバージョンが正確に固定されている場合はそのことを把握し、何も固定されていない場合は不明であることを示します。.env を開くことはありません。存在することだけを報告します。

2.4.2：同梱サーバーが、通知するメモリーを表示するようになりました。このパッケージと VS Code 拡張機能に同梱されているものは同じサーバーですが、エージェントへの接続時に両方が約束している再発回数と確認済みの修正を表示していたのは、これまで片方だけでした。このセクションは、両方が呼び出す1つのモジュールになったため、手動で同期し続ける必要はなくなりました。

2.4.1：2つのツールの説明を修正しました。ダッシュを除去する処理によって、どちらも文の途中で切れていました。ツールの説明は、エージェントがこのサーバーを呼び出すかどうかを判断する前に目にする唯一の情報なので、これは見た目以上に重要です。 2.4.0：report_outcome に unused が追加されました。独自の方法で問題を解決したエージェントは、これまで failed を報告する必要がありました。しかし、これは自分たちのツールが一度も実行されていないのに、修正が試されて失敗したと記録されてしまいます。npm サーバーと VS Code 拡張機能に同梱されているサーバーの両方で、同じフィールドを受け取るようになりました。

2.3.0：エージェントが、エディターパネルと同じ4つのメモリ状態を利用できるようになりました。 debug_error には2つの分岐があり、試しても失敗し続けた修正と、まだ試されていない修正が同じように表示されていました。エージェントにとっては同じ文面なので、次にすべきこととして、すでに効果がなかった修正を提案してしまうのが自然でした。4つの状態がパネルと一致するようになりました：確認済み・検証済み、確認済み、未検証、アンチパターン。

2.2.0：告知されていたものの、実装されていなかった2つの機能が追加されました。

• ローカルソースの解決。 サーバーがスタックトレースに記載されたファイルを読み取り、リクエストとともに送信するようになりました。これまでは、トレースバックを貼り付けたエージェントに、信頼度20%で「具体的な修正に必要なコンテキストが不足しています」と返されていました。VS Code 拡張機能以外では何も情報を書き込まないインデックスしか、コードの情報源がなかったためです。対象はリポジトリのルート内、ソース拡張子のファイル、最大3ファイルです。レスポンスには読み取ったファイルが示されます。
• プロジェクト単位のエラーメモリ。 このパッケージから project_id が送信されていませんでした。エンジンはこれを使って再発回数と確認済みの修正を管理するため、すべてのエージェントリクエストで過去の記録が参照されず、新しい記録も保存されない一方で、サーバーの指示では参照・保存できるとエージェントに伝えていました。これからは、Git リポジトリのルートから ID が導出され、同じチェックアウトに対して VS Code 拡張機能と同じ ID が使われます。これにより、両方の環境で同じメモリを共有できます。該当する場合、debug_error に「以前に3回確認済み、修正は確認済み」と表示されます。

2.1.1：メタデータのみの更新です。公式 MCP レジストリの所有権確認用に mcpName を追加し、npm パッケージページのリポジトリリンクを修正しました。

2.1.0：ワンコマンドでセットアップできるようになりました。デバイスリンク経由のブラウザーサインイン（キーの貼り付けは不要）、バックアップを作成してクライアント設定を自動で書き込む機能、セットアップの問題を診断する doctor、アカウントを持つ前にエージェントがツールを呼び出した場合に会話内でサインインする機能が追加されました。

2.0.0：report_outcome ツール、すぐに適用できる修正ごとの edits、3状態の検証ラベルが追加されました。

開発

npm install
npm test        # builds, then runs unit + spawned-process e2e tests

ソース

github.com/1shizaan/debugai-mcp がこのパッケージのソースです。開発元のディレクトリからミラーされています。これらのファイルのコミット履歴がすべて含まれているため、git log と git blame は通常どおり機能します。

クライアントは MIT ライセンスの完全な実装です。stdio サーバー、デバイスリンクによるサインイン、設定ライター、テストがすべて含まれています。分析処理は DebugAI のサーバー上で実行され、このパッケージには含まれていません。

このリポジトリへのイシューやプルリクエストを歓迎します。

MIT © DebugAI