jdwp-mcp

JDWPを通じて稼働中のJVMをデバッグ — あらゆるMCP互換エージェントから利用可能。

実行中のJavaプロセスにアタッチし、スレッドの一時停止、スタックやオブジェクトの調査、ブレークポイントの設定、状態の評価を自然言語で行います。1つのプロンプトで、ライブのランタイムデータを用いたエージェント主導の診断ループを開始できます。

Claude Code、Codex、Cursor、その他MCP互換エージェントで動作します。

動作の様子

サービスへのクエリがハングしています。根本原因を特定します：

> Attach to localhost:5005 and find out why a query is stuck.

エージェントがアタッチし、すべてのスレッドを一時停止して問題をスキャンします：

connected localhost:5005
paused
24 threads, 2 blocked

Thread pool-3-thread-7 is waiting for a monitor lock:
#0 RolapResult.loadMembers:142
  monitor=@3f2a  state=BLOCKED
#1 RolapResult.execute:89

Lock is held by pool-3-thread-2, which is running:
#0 SqlStatement.execute:218
  sql="SELECT ... FROM fact_table"   -- full scan on 36M rows

Root cause: the query bypassed the aggregate table and fell back to
a full fact-table scan. Thread-7 is waiting for thread-2 to finish.

1つのプロンプト。6つのツール呼び出し。ロック競合と根本原因が特定されました。

クイックスタート

1. インストール

pip install jdwp-mcp

# Pre-built binary
curl -fsSL https://raw.githubusercontent.com/dronsv/jdwp-mcp/main/install.sh | sh

# Cargo (requires Rust)
cargo install --git https://github.com/dronsv/jdwp-mcp

# From source
git clone https://github.com/dronsv/jdwp-mcp && cd jdwp-mcp && cargo build --release

2. エージェントの設定

claude mcp add jdwp jdwp-mcp

Codex、Cursor、またはその他のMCP互換エージェントの場合は、.mcp.json に以下を追加してください：

{
  "mcpServers": {
    "jdwp": {
      "command": "jdwp-mcp"
    }
  }
}

3. JDWPを有効にしてJavaアプリを起動

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar

4. デバッグ

Attach to localhost:5005 and set a breakpoint at com.example.MyService line 42

5. 自動承認（オプション）

デバッグには多数の迅速なツール呼び出しが含まれます。自動承認により確認プロンプトを省略できます：

# Allow all jdwp tools for this project
claude config set --project allowedTools 'mcp__jdwp__*'

claude config set allowedTools 'mcp__jdwp__*'

信頼できるプロジェクトに対してのみ有効にしてください。jdwpツールはスレッドの一時停止、変数の変更、ターゲットJVM上でのメソッド呼び出しが可能です。

プロンプトパック

状況に合わせてパックを選択してください：

アプリがハングまたは低速

Attach to localhost:5005
Pause the JVM and find all blocked or waiting threads
Show the stack for the blocked thread with variables
Who holds the lock? Show their stack too

ログに例外が発生

Attach to localhost:5005
Set an exception breakpoint for NullPointerException
Wait for the exception to fire
Show the stack and all local variables at the throw site

コードパスを理解する必要がある

Attach to localhost:5005
Trace method calls on com.example.service
[send your HTTP request]
Show the trace result — which methods were called?

ブレークポイント主導のデバッグ

Attach to localhost:5005
Find classes matching UserService
List methods of UserService with line numbers
Set a breakpoint at UserService line 45
When it hits, show the stack with all variables
Step over to the next line

Claude Codeコマンド

このリポジトリをクローンすると、すぐに使えるスラッシュコマンドが利用できます：

• /investigate-hang — ハングしたJVMを診断（一時停止、ブロックされたスレッドの検索、ロックのトレース）

• /investigate-exception — ライブ例外をキャッチしてスロー箇所を調査

• /trace-request — リクエストが通過するメソッドをトレース

また、ハング、デッドロック、例外、予期しないコードパスを診断するために起動できる自律型調査エージェント（.claude/agents/jdwp-investigator.md）も含まれています。

推奨される自動承認および更新チェックの設定については、.claude/settings.example.json を参照してください。

推奨される最初のユースケース

• ハングしたリクエストとデッドロック

• ブロックされたスレッドプール

• 不審なSQLやランタイム状態の不一致

• IDEアクセスなしでのブレークポイント主導の診断

• kubectl port-forward を介したリモートデバッグ

なぜjstackやIDEではなくこれを使うのか？

• エージェント内で動作 — ツールの切り替えや別のデバッガーウィンドウは不要

• アタッチ + 調査 + 推論を1つのループに統合 — エージェントが次に何を調べるべきかを判断

• 会話型 — 問題を説明すれば、エージェントがデバッグセッションを実行

• 大規模コードベースの真実のソース — Spring、Hibernate、OLAPエンジンなどの深いフレームワークスタックを持つ複雑なプロジェクトでは、エージェントが静的にコードパスを追跡すると迷子になることがあります。ライブデバッグにより、どのスレッドがロックを保持しているか、どのようなSQLが生成されたか、変数の現在の値は何かといった実際のランタイム状態をエージェントに提供できます。

ツール

接続と制御 attach, disconnect, pause, continue, step into/over/out

ブレークポイントとイベント set_breakpoint (条件付き), clear, list, exception_breakpoint, watch (フィールド変更), wait_for_event

調査 get_stack (オブジェクトを自動解決), get_variable, inspect, eval, set_value, snapshot, find_class, list_methods, list_threads, vm_info

トレース trace (パッケージに対してメソッドレベルのトレースを有効化), trace_result (呼び出しパスを取得)

向いていない用途

• ポストモーテム（事後）ヒープ分析

• 常時稼働のプロダクション監視

• JDWPのアタッチやスレッドの一時停止が運用上安全でない環境

運用上の注意

JDWPはランタイムの動作を変更します。スレッドの一時停止やブレークポイントの設定は、システムに影響を与える可能性があります。本番環境では慎重に使用し、ステージング環境や計画メンテナンス時間帯での使用を推奨します。

デプロイシナリオ

Maven、Gradle、Tomcat、Docker、Kubernetes（ポートフォワード）、SSHトンネルでのセットアップについては、docs/deploy.md を参照してください。

例

• ハングしたクエリのデバッグ — ロック競合、スレッド分析、根本原因特定までの完全なウォークスルー

• オブザーバビリティのデバッグ — Spring Boot ObservationRegistryの問題調査

アーキテクチャ

Agent  -->  MCP Server  -->  JDWP Client  -->  TCP  -->  JVM
              |
        Translates tool calls to JDWP,
        tracks session state, summarizes
        runtime objects for the agent.

ソースからのビルド

cargo build --release
cargo test

ライセンス

MIT