java-debug

事前確認：IntelliJ Debug MCP

このスキルはSpring Agent Toolkitの一部であり、IntelliJ Debug MCP サーバー（Amplicode IntelliJ プラグインによって、メインの Spring MCP とともに提供されます）と連携するよう設計されています。ほかの操作を行う前に、ツール一覧にデバッグ MCP ツールがあるか確認してください。これらのツールは intellij-debug MCP サーバーの下に公開されています（例：toggle_breakpoint、evaluate_expression、get_stack_trace）。MCP ツールをツール一覧に統合するハーネスでは、同じ名前の先頭に mcp__intellij-debug__ が付きます。

• デバッグツールが1つ以上利用できる場合 — MCP は接続されています。以下のスキルに進んでください。
• 利用できるものがない場合 — 中断して、amplicode-install スキル（Spring Agent Toolkit に同梱）を実行してください。このスキルは Amplicode プラグインをインストールし、ウェルカム画面の**「Настроить Spring Agent」**ボタンのクリックと、MCP クライアントの再起動を案内します。完了するとデバッグ MCP ツールが利用可能になるため、このスキルに戻って続行してください。
• amplicode-install がスキル一覧に登録されていない場合は、ユーザーの言語で次のように伝えてください：「このスキルには Amplicode IntelliJ プラグインとそのデバッグ MCP サーバーが必要です。https://amplicode.ru/marketplace から IntelliJ IDEA Ultimate/Community または GigaIDE にインストールし、任意のプロジェクトを開いて、Amplicode のウェルカム画面にある『Настроить Spring Agent』をクリックしてから、MCP クライアントを再起動してください。」

---

IntelliJ Debug MCP でのデバッグ

このスキルでは、IntelliJ Debug MCP サーバーを介してアプリケーションをデバッグする方法を説明します。MCP サーバーは IntelliJ IDEA 内で動作し、デバッガーをプログラムから操作できます。

安全に関するルール — 最初にお読みください

以下のルールは、処理がいつまでも終わらなくなったり、デバッグのコンテキストが失われたりするのを防ぐためのものです。デバッグ対象のアプリケーションは、いつでもブレークポイントで一時停止する可能性があり、その場合、すべてのリクエストに応答できなくなるためです。

一時停止したプロセスの落とし穴

アプリがブレークポイントに到達すると、スレッドが停止します。そのアプリに対する HTTP リクエスト、curl 呼び出し、ネットワーク通信はすべて永久にハングします。アプリは再開するまで応答できません。これは最もよくあるミスです。

ルール1：デバッグ対象のアプリと通信する際は、必ずタイムアウトを設定してください。 curl には --max-time 5 を使用するか、Bash ツールの呼び出しで run_in_background: true を設定してください。アプリが動作中だと確認した直後であっても、確認からリクエストまでの間にブレークポイントに到達する可能性があるため、必ず設定してください。

ルール2：ネットワークリクエストの前に、一時停止状態を確認してください。 list_debug_sessions を呼び出して、isSuspended を確認してください。アプリが一時停止している場合は、先に resume を呼び出すか、リクエストがブロックされることを了承してください。

ルール3：ステップ実行の後は、必ず現在位置を確認してください。 step_over、step_into、step_out の後には、get_current_position を呼び出してください。実行がどこに到達したかを決して推測しないでください。予期しない行や、別のファイルに移動していることもあります。

ルール4：再開後は状態を確認してください。 resume の呼び出し後、アプリがすぐに別のブレークポイントに到達する場合があります。list_debug_sessions または get_current_position を必ず呼び出し、セッションが実行中なのか、再び一時停止しているのかを確認してください。

ルール5：式の評価には副作用があります。 evaluate_expression はデバッグ対象の JVM で実際のコードを実行します。意図した操作でない限り、状態を変更する式（セッターや System.exit(0) など）は避けてください。

はじめに

デバッグツールを使用する前に、セッションを初期化してください。

1. projectPath にプロジェクトルートの絶対パスを設定して initialize を呼び出します。
2. 「project not found」と表示された場合、応答に開いているプロジェクトの一覧が表示されます。正しいプロジェクトを選んで再試行してください。
3. 以降のツール呼び出しはすべて、このプロジェクトを対象とします。

ツールのリファレンス

セッション

ツール	パラメーター
initialize	projectPath（文字列、必須）— プロジェクトルートの絶対パス

実行構成

ツール	パラメーター
list_run_configurations	(なし)
debug_run_configuration	configurationName (string、必須) — 実行構成の正確な名前
list_debug_sessions	(なし) — セッション名と isSuspended の状態を返します
stop_debug_session	sessionName (string、必須)

ブレークポイント

ツール	パラメーター
list_breakpoints	(なし)
add_breakpoint	filePath (string、必須)、line (int、必須、1-based)、condition (string、任意)
remove_breakpoint	filePath (string、必須)、line (int、必須、1-based)
toggle_breakpoint	filePath (string、必須)、line (int、必須、1-based)、enabled (bool、任意 — 省略すると切り替えます)
set_breakpoint_condition	filePath (string、必須)、line (int、必須、1-based)、condition (string、必須 — 空文字列を指定すると削除します)

実行制御

ツール	パラメーター
resume	sessionName (string、任意 — 既定では最初のアクティブなセッション)
pause	sessionName (string、任意)
step_over	sessionName (string、任意)
step_into	sessionName (string、任意)
step_out	sessionName (string、任意)

検査

ツール	パラメーター
get_current_position	sessionName (string、任意) — ファイル、行、isSuspended を返します
get_stack_trace	sessionName (string、任意) — ファイル、行、説明を含むフレームを返します
list_threads	sessionName (string、任意) — スレッド名とトップフレームの情報を返します
evaluate_expression	expression (string、必須)、sessionName (string、任意)、frameIndex (int、任意、0-based、既定値 0)

注: ブレークポイントツールの行番号はすべて 1-based です（ソースファイルに表示される番号と一致します）。絶対ファイルパス、またはプロジェクトルートからの相対パスを使用してください。

ワークフロー：場所が分かっているバグを調査する

バグのおおよその場所（特定のファイル、メソッド、行）が分かっている場合に使用します。

1. ソースファイルを読み、疑わしい箇所の周辺の状況を把握します
2. 調査したい行に add_breakpoint を設定します（特定のケースだけを対象にする場合は condition を使用します）
3. debug_run_configuration でアプリをデバッグモードで起動します
4. バグを発生させます — HTTP 経由の場合は、curl で --max-time 5 を使用するか、run_in_background: true を指定してください
5. get_current_position — ブレークポイントに到達し、想定した行にいることを確認します
6. evaluate_expression — 変数を調べ、メソッドを呼び出し、状態を確認します。簡単なもの（変数名）から始め、徐々に複雑な式にしていきます
7. get_stack_trace — 実行がどのようにこの箇所に到達したかを把握します
8. 次に行う操作を決めます：さらに追跡するには step_over／step_into、別の場所に add_breakpoint を設定するか、調査を終了します
9. 各ステップの後に get_current_position を呼び出し、現在位置を確認します
10. 完了したら、resume または stop_debug_session を実行し、その後 remove_breakpoint で後片付けをします

ワークフロー：未知のコードの実行時の動作を調べる

なじみのないコードが実際にどのように実行されるかを把握する必要がある場合に使用します。

1. list_run_configurations — アプリの適切な起動方法を確認します
2. エントリーポイント（コントローラーメソッド、main メソッド、イベントハンドラー）にブレークポイントを設定します
3. debug_run_configuration でデバッグを開始します
4. 実行をトリガーします（タイムアウトを設定した HTTP リクエスト、CLI コマンド、またはユーザーに説明された UI 操作）
5. 実行が一時停止したら、get_stack_trace で呼び出しチェーン全体を確認します
6. step_into でメソッド内の実行を追い、既知のコードをスキップするには step_over を使い、呼び出し元に戻るには step_out を使います
7. evaluate_expression を積極的に使い、メソッドの引数、戻り値、オブジェクトのフィールドを調べます
8. 各ステップの後に get_current_position を呼び出し、現在位置を把握します

式の評価に関するヒント

• 評価は、ブレークポイントで、またはステップ実行後にセッションが一時停止中の場合にのみ機能します
• frameIndexを使うと、異なるスタックフレームで評価できます：0 = 現在の（最上位）フレーム、1 = 呼び出し元、など
• まずは単純な変数名から始め、その後、メソッド呼び出しや複雑な式に進みます
• 副作用のある式には注意してください。対象のJVMで実際にコードが実行されます

エラーからの復旧

エラー	意味	対処方法
"Session not found"	その名前のセッションがないか、実行中のセッションがありません	list_debug_sessionsを実行して、利用可能なセッションを確認します。新しいセッションを開始する必要がある場合があります。
"Not suspended"	セッションは実行中で、ブレークポイントで一時停止していません	ブレークポイントにまだ到達していないか、すでに再開されています。トリガーを待つか、セッションをpauseします。
"Evaluator not available"	現在のフレームでは評価をサポートしていません	別のframeIndexを試してください。ネイティブフレームやフレームワークのフレームでは、評価できないことがよくあります。
セッションのクラッシュ／切断	デバッグ対象のアプリがクラッシュしたか、強制終了されました	IDEのログを確認します。list_debug_sessionsで状態を確認します。新しいデバッグセッションを開始します。

デバッグが完了したら、追加したブレークポイントはremove_breakpointで削除し、後片付けをしてください。ブレークポイントを残すと、今後のデバッグセッションが煩雑になります。

複数のデバッグセッション

複数のデバッグセッションがアクティブな場合は、ツールの呼び出しで常にsessionNameを指定してください。指定しない場合、ツールは最初のアクティブなセッションをデフォルトで使用するため、意図したセッションではない可能性があります。

操作する前にlist_debug_sessionsを呼び出し、すべてのアクティブなセッションとその状態を確認してください。

既知の制限事項

• コンソール出力にアクセスできません：MCP サーバーは、デバッグ対象アプリのstdout/stderrを公開しません。回避策：ログファイルを直接読む、evaluate_expressionで状態を確認する、またはIDEのコンソールに何が表示されているかユーザーに尋ねます。
• ブレークポイント到達の通知はありません：サーバーはブレークポイント到達時にイベントを送信しません。ブレークポイントをトリガーする可能性のある操作（resume、HTTPリクエスト、debug_run_configurationなど）の後は、list_debug_sessionsまたはget_current_positionで状態を確認してください。時間を指定したポーリングは行わず、関連する操作の後に毎回確認します。