Descartes Java REPL and Deep Introspection For Your Java Apps

Descartes MCP

从 Claude Code、Codex 和 Gemini CLI 等 MCP 客户端调试正在运行的 JVM。

Descartes 有两种运行模式：

• 代理模式：对启用了 JDWP 的 JVM 进行外部调试。
• 嵌入模式：提供完整的进程内运行时工具（JShell、分析器、热重载、资源等）。

安全提示：仅在可信的开发／测试环境中运行。JDWP 和调试器工具可以检查内存、评估代码并挂起应用线程。

---

为什么要使用 Descartes

• 无需重启应用代码，即可调试启用了 JDWP 的 JVM。
• 使用调试器线程／堆栈工具（debugger_threads、debugger_stacktrace）调查阻塞和等待的执行路径。
• 使用 AI 辅助 Agent 工具共享可重复的调试工作流。
• 根据需要，从代理优先的调试方式转为嵌入式的完整运行时内省。

---

试用

先决条件：JDK 17+、Maven 3+、Node.js。

选择下面的场景。两种场景都使用随附的 BuggyCalculator 示例应用，其中包含 6 个有意设置的 Bug（差一错误、NPE、整数溢出、条件错误、边界情况处理错误、业务逻辑颠倒）。

请先检查下方的 MCP 注册信息；尝试以下任一场景前，必须完成这一步

场景 A —— Agent 完成所有操作（无人值守）

Agent 会自行构建、启动、连接并调试，无需手动干预。你只需输入提示词。

步骤 1 —— 在单独的终端中启动代理

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

在端口 9090 上开放 MCP，并配置为连接 localhost:5005 上的 JDWP（实际的 JDWP 连接将在 Agent 启动调试会话后建立）。默认使用 pom.xml 中的版本；传入 --version <version> 可指定特定的发行制品。

在开发过程中从本地源码构建时，请改用 ./scripts/run-remote-proxy.sh。

步骤 2 —— 让 Agent 进行调试

在此仓库中启动 Claude Code、Codex 或 Gemini CLI，然后粘贴：

使用 mvn clean package -DskipTests 构建，启动 com.bitsapplied.descartes.example.debugger.DebuggerWorkflowExample 并在 --interactive 模式下启用 JDWP，然后找出 com.bitsapplied.descartes.example.debugger.scenarios.BuggyCalculator 中的 6 个 Bug。

调试技能会处理启动相关事宜（脚本、JDWP 标志、端口）。Agent 会连接并自主逐步排查全部 6 个 Bug。

仓库中已提交的客户端配置已预先配置好代理。在此仓库中无需额外安装 MCP 或技能。

场景 B —— 你启动应用，Agent 连接

你自行启动目标应用（适用于重现特定状态，或应用需要手动设置的情况）。Agent 只负责连接并调试。

步骤 1 —— 构建 JAR（一次即可）

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 —— 让 Agent 进行调试

在此仓库中启动 Claude Code、Codex 或 Gemini CLI，然后发送：

BuggyCalculator 应用已在端口 5005 上通过 JDWP 运行。连接调试器并找出 BuggyCalculator 中的 Bug。

Agent 会连接到现有的 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

这三种配置都会启动 config/mcp/mcp-tcp-adapter.js，连接 MCP 端口 9090，并启用较长的调试器等待时间。启动代理，从此仓库打开客户端，然后使用 descartes-debug 技能——无需执行用户全局技能安装步骤。

调试你自己的应用

使用 JDWP 启动应用，并让 Agent 连接：

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

使用 address=*:5005 可监听所有接口（远程调试）。如果你的 shell 是 zsh，请将该标志加引号以防止 glob 展开：'-agentlib:jdwp=...,address=*:5005'。

调试技能（推荐供 Agent 使用）

将规范技能复制到目标项目，以便使用结构化调试工作流，然后添加 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 进行外部 Agent 驱动的检查时，请使用代理模式。 需要在进程内使用完整的 Descartes 功能时，请使用嵌入模式。

---

模式：从哪种模式开始

路径	设置	适用场景
代理模式	几分钟	调试已启用 JDWP 的现有 JVM，无需更改应用代码
嵌入模式	需要更改依赖项	JShell、性能分析、热重载和更深入的内省

---

已知限制

一个代理实例一次只能连接一个 JVM。对于多 JVM 工作流，请为每个目标 JVM 运行一个代理，或选择不同的端口。

请参阅 doc/restrictions.md。

---

快速提示

• 正常停止：结束 MCP 使用，按 Ctrl+C 停止代理，然后停止目标 JVM。
• 端口设置：确保适配器 MCP 端口（MCP_PORT）与代理的 --mcp-port 一致。为目标 JVM 单独配置 JDWP 主机和端口。
• 对于由 Agent 启动的目标，请使用非 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