jdb-mcp

🚀 JDB - MCP：Java调试器MCP服务器

JDB - MCP是一个基于Java调试接口（JDI）的模型上下文协议（MCP）服务器。它使AI代理（如Claude、Cline、Trae）能够对Java应用程序进行深度运行时调试。

🚀 快速开始

安装与构建

前提条件

• JDK 17+（包含JDI模块）

构建胖JAR

# 构建所有模块并在 `release/` 目录下生成JAR文件
mvn clean package

# 或者为特定的JDK版本进行构建：

# 对于JDK 17+（推荐）
mvn clean package -pl jdb-mcp-jdk17 -am

# 对于JDK 7（旧版本支持）
mvn clean package -pl jdb-mcp-jdk7 -am

可执行的JAR文件将位于 release/ 目录下：

• release/jdb-mcp.jar（JDK 17+）
• release/jdb-mcp-jdk7.jar（JDK 7）

配置与使用

启动选项

• --transport <stdio|http>：设置传输模式（默认：stdio）。
• --notifications <true|false>：启用AI实时通知（默认：true）。

如需详细的工具参数分析，请参考参数指南。

在VSCode（Cline/Claude Dev）中使用

在您的MCP设置中添加以下配置：

{
  "mcpServers": {
    "jdb-debugger": {
      "command": "java",
      "args": [
        "-jar",
        "path/to/jdb-mcp.jar"
      ]
    }
  }
}

调试方法（附加模式）

⚠️ 重要提示

您必须手动启动启用了JDWP的目标Java应用程序。

1. 启动您的项目：

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

2. 在AI聊天中请求：Attach to localhost:5005 and debug...

✨ 主要特性

• 多传输支持：支持 stdio（标准VSCode集成）和 http（用于远程/curl调试）。
• 全功能调试（仅附加模式）：
  • 附加到正在运行的进程（debug_attach） - 支持任何启用了JDWP的Java应用程序（SpringBoot、Maven、Gradle等）。
  • 断点管理（debug_set_breakpoint，debug_set_watchpoint）
  • 流程控制（单步跳过、单步进入、单步跳出、继续执行）
  • 状态检查（堆栈跟踪检查、深度结构化变量遍历）
  • 线程和类检查（debug_list_threads，debug_list_classes）
  • 动态修改（在运行时更改变量值）
• 简化设计：目前专注于单会话调试，无需复杂的 sessionId 管理。
• 需要手动调试模式：目标Java应用程序必须手动以启用JDWP选项启动。
• 实时感知：利用MCP通知，当断点命中时，AI代理会立即收到通知。

💻 使用示例

工具列表

• debug_attach：通过套接字附加到现有的调试端口。
• debug_list_threads：列出所有线程及其状态。
• debug_list_classes：列出已加载的类，支持可选过滤。
• debug_list_methods：列出特定类中的方法。
• debug_source：检索类的源代码（需要源根目录）。
• debug_set_method_breakpoint：在方法入口处设置断点。
• debug_set_method_entry：监控方法进入事件。
• debug_set_method_exit：监控方法退出事件。
• debug_list_vars：列出变量（支持 threadName、frameIndex 和 scope 过滤）。
• debug_get_var：获取特定变量的详细信息。
• debug_set_var：修改运行时变量（支持 threadName 和 frameIndex）。
• ...更多工具请查看 tools/list。

📚 详细文档

待办事项列表

• [ ] 实现 debug_launch：允许用户通过MCP直接启动和调试Java程序，实现“开箱即用”的体验。
• [ ] 实现 debug_calc：支持在调试上下文中计算任意Java表达式（表达式求值）。
• [ ] 多会话支持：重构以允许一个MCP实例同时管理和调试多个目标程序。
• [ ] 包前缀过滤：支持按包前缀（如 com.example.*）过滤方法进入/退出和断点。
• [ ] 批量类过滤：支持一次传递多个类名或通配符模式以过滤事件。
• [ ] 增强断点控制：支持条件断点和线程过滤，以实现更精确的调试中断。
• [ ] 待添加：根据社区反馈添加更多功能。

📄 许可证

本项目根据MIT许可证开源。

🔍 演示