Descartes Java REPL and Deep Introspection For Your Java Apps

Descartes MCP

Claude Code、Codex、Gemini CLI などの MCP クライアントから、実行中の JVM をデバッグできます。

Descartes には、次の 2 つの動作モードがあります。

• JDWP を有効にした JVM を外部からデバッグするプロキシモード。
• JShell、プロファイラー、ホットリロード、リソースなど、プロセス内で実行されるすべてのランタイムツールを利用できる組み込みモード。

セキュリティ：信頼できる開発／テスト環境でのみ実行してください。JDWP とデバッガーツールを使うと、メモリの検査、コードの評価、アプリケーションスレッドの一時停止が可能です。

---

Descartes を使う理由

• アプリケーションコードを再起動せずに、JDWP を有効にした JVM をデバッグできます。
• デバッガーのスレッド／スタックツール（debugger_threads、debugger_stacktrace）を使って、ブロック中や待機中の実行パスを調査できます。
• AI 支援エージェントツールを使って、再現可能なデバッグワークフローを共有できます。
• 必要に応じて、プロキシを使ったデバッグから、ランタイム全体を調査できる組み込みモードへ移行できます。

---

試してみる

前提条件：JDK 17 以上、Maven 3 以上、Node.js。

以下のシナリオから 1 つ選んでください。どちらのシナリオでも、意図的に 6 つのバグ（オフバイワン、NPE、整数オーバーフロー、条件式の誤り、エッジケースの処理、ビジネスロジックの入れ替わり）を含む、同梱の BuggyCalculator サンプルアプリを使用します。

以下のいずれかのシナリオを試す前に、まず下記の MCP 登録を確認してください。

シナリオ A -- エージェントにすべて任せる（無人実行）

エージェントが手動操作なしで、ビルド、起動、接続、デバッグを行います。プロンプトを入力するだけです。

ステップ 1 -- 別のターミナルでプロキシを起動する

./scripts/run-remote-proxy-from-maven.sh

MCP をポート 9090 で公開し、JDWP の接続先として localhost:5005 を設定します（実際の JDWP 接続は、エージェントがデバッグセッションを開始したときに行われます）。デフォルトでは pom.xml のバージョンを使用します。特定のリリース成果物を指定するには、--version <version> を渡してください。

開発中にローカルのソースビルドを使用する場合は、代わりに ./scripts/run-remote-proxy.sh を使用してください。

ステップ 2 -- エージェントにデバッグを依頼する

このリポジトリから Claude Code、Codex、または Gemini CLI を開き、次の内容を貼り付けます。

mvn clean package -DskipTests でビルドし、 com.bitsapplied.descartes.example.debugger.DebuggerWorkflowExample を JDWP を有効にした --interactive モードで起動してから、 com.bitsapplied.descartes.example.debugger.scenarios.BuggyCalculator にある 6 つのバグを見つけてください。

デバッグスキルが起動方法（スクリプト、JDWP フラグ、ポート）を処理します。エージェントは自律的に接続し、6 つのバグすべてをステップ実行して調査します。

リポジトリに同梱されているクライアント設定は、プロキシ用にあらかじめ設定されています。このリポジトリでは、追加の MCP やスキルのインストールは不要です。

シナリオ B -- アプリを自分で起動し、エージェントに接続させる

対象アプリは自分で起動します（特定の状態を再現する場合や、アプリの手動セットアップが必要な場合に便利です）。エージェントは接続してデバッグするだけです。

ステップ 1 -- JAR をビルドする（1 回のみ）

mvn clean package -DskipTests

ステップ 2 -- 別のターミナルでプロキシを起動する

./scripts/run-remote-proxy-from-maven.sh

ステップ 3 -- 別のターミナルで JDWP を有効にしてサンプルアプリを起動する

mkdir -p .pids
scripts/launch-managed-nontty.sh \
  --name buggy-calc \
  -- java \
     -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=localhost:5005 \
     -cp target/descartes-mcp-*-jar-with-dependencies.jar \
     com.bitsapplied.descartes.example.debugger.DebuggerWorkflowExample \
     --interactive </dev/null 2>&1 | tee .pids/buggy-calc.log

続行する前に、Listening for transport dt_socket at address: 5005 が表示されるまで待ちます。

launch-managed-nontty.sh には、TTY ではないファイルディスクリプターが必要です。</dev/null 2>&1 | tee によるリダイレクトで条件を満たせます。標準入力は /dev/null から読み込まれ、標準エラーは標準出力に統合されます。また、tee へのパイプによって標準出力が TTY ではなくなり、ターミナルへの表示は維持されます。

ステップ 4 -- エージェントにデバッグを依頼する

このリポジトリから Claude Code、Codex、または Gemini CLI を開き、次のように依頼します。

BuggyCalculator アプリは、JDWP をポート 5005 で有効にしてすでに実行中です。デバッガーを接続し、BuggyCalculator のバグを見つけてください。

エージェントは既存の JDWP セッションに接続してデバッグし、何かを起動しようとはしません。

ステップ 5 -- 完了したら後片付けする

PID ファイルを使ってアプリを停止します。

kill "$(cat .pids/buggy-calc.pid)"

MCP の登録

このチェックアウトには、サポート対象の各クライアント向けにネイティブなプロジェクト設定が含まれています。

クライアント	MCP 設定	スキルの検出
Claude Code	.mcp.json	.claude/skills/descartes-debug シンボリックリンク
Codex	.codex/config.toml	標準の .agents/skills/descartes-debug
Gemini CLI	.gemini/settings.json	標準の .agents/skills/descartes-debug

3 つの設定はいずれも、長時間のデバッガー待機を有効にした状態で、MCP ポート 9090 に対して config/mcp/mcp-tcp-adapter.js を起動します。プロキシを起動し、このリポジトリからクライアントを開いて、descartes-debug スキルを使用してください。ユーザー全体に適用されるスキルのインストール手順はありません。

自分のアプリをデバッグする

アプリを JDWP で起動し、エージェントに接続を依頼します。

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

すべてのインターフェースで待ち受ける（リモートデバッグ）には、address=*:5005 を使用します。シェルが zsh の場合は、グロブ展開を防ぐためにフラグを引用符で囲んでください：'-agentlib:jdwp=...,address=*:5005'。

デバッグスキル（エージェントに推奨）

構造化されたデバッグワークフローを利用できるよう、標準のスキルを対象プロジェクトにコピーしてから、Claude の検出用シンボリックリンクを追加します。

mkdir -p .agents/skills .claude/skills
cp -R /path/to/descartes-mcp/.agents/skills/descartes-debug .agents/skills/
ln -s ../../.agents/skills/descartes-debug .claude/skills/descartes-debug

Codex と Gemini は .agents/skills を直接検出します。検証方法と Windows 向けの説明は、doc/debug-skill.md を参照してください。

---

仕組み

プロキシモード：

flowchart LR
  A[Claude Code / Codex / Gemini] <--> B[mcp-tcp-adapter.js]
  B <--> C[Descartes MCP Proxy]
  C <--> D[Target JVM via JDWP]

組み込みモード：

flowchart LR
  A["Claude Code / Codex / Gemini"] <--> B["mcp-tcp-adapter.js"]

  subgraph APP["Your app JVM"]
    C1["MCPServer + Descartes tools/resources + shared application context"]
  end

  B <--> C1

JDWP を介した外部からのエージェント主導の検査を行う場合は、プロキシモードを使用してください。 プロセス内で Descartes の全機能を利用する場合は、組み込みモードを使用してください。

---

モード：最初に選ぶモード

方法	セットアップ	最適な用途
プロキシモード	数分	アプリケーションコードを変更せず、JDWP が有効な既存の JVM をデバッグする
組み込みモード	依存関係の変更が必要	JShell、プロファイリング、ホットリロード、より詳細なイントロスペクション

---

既知の制限事項

1 つのプロキシインスタンスが同時に対象にできる JVM は 1 つです。複数の JVM を扱うワークフローでは、対象 JVM ごとにプロキシを 1 つ実行するか、異なるポートを選択してください。

doc/restrictions.md を参照してください。

---

簡単なヒント

• 正しく停止する：MCP の使用を終了し、Ctrl+C でプロキシを停止してから、対象の JVM を停止します。
• ポートの設定：アダプターの MCP ポート（MCP_PORT）を、プロキシの --mcp-port と一致させます。対象 JVM の JDWP ホストとポートは別途設定してください。
• エージェントが起動する対象には、TTY を使用しない起動方法を使い、手動での起動時と同じ JDWP フラグを指定します。
• JDK 21 以降の仮想スレッドを使う対象では、スレッド一覧のスナップショットに仮想スレッドを表示する必要がある場合、対象 JVM の JDWP フラグに includevirtualthreads=y を追加します。
• Descartes 自体をデバッグするときは、DESCARTES_FORCE_PLATFORM_THREADS=true または -Dtools.executor.virtualThreads.enabled=false を設定して、共有ツールタスクを上限付きのプラットフォームスレッドで実行します。

---

詳細情報

• doc/quick-start.md
• doc/adapter.md
• doc/debugger.md
• doc/how-to-embed.md
• doc/debug-skill.md
• doc/restrictions.md