Java Debug MCP Server

一个基于 Model Context Protocol (MCP) 的 Java 调试服务器，允许 LLM 通过 MCP 协议与 Java 虚拟机进行交互，实现断点调试、变量监控等功能。

📚 文档

文档	说明
QUICKSTART.md	快速入门 - 5 分钟快速开始
USER_GUIDE.md	使用指南 - 完整的安装和使用文档
TEST.md	测试指南 - 如何测试 MCP 服务器

架构

┌─────────────────┐     stdio/HTTP      ┌──────────────────────┐
│   Claude/LMM    │ ◄──────────────────► │   MCP Server (Java)  │
└─────────────────┘                      └──────────────────────┘
                                                     │
                                                     │ JDI (JDWP)
                                                     ▼
                                            ┌──────────────────────┐
                                            │   Target JVM         │
                                            │   (debuggee)         │
                                            └──────────────────────┘

构建

cd E:/java_workspace/debug_mcp
mvn clean package

构建完成后，JAR 文件位于 target/debug-mcp-1.0.0.jar

使用方法

1. 启动可调试的 Java 程序

首先启动目标程序并启用 JDWP 调试:

java -agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y -cp /path/to/classes com.example.Main

JDWP 参数说明:

• transport=dt_socket: 使用 socket 传输
• server=y: JVM 作为服务器等待连接
• address=8000: 监听端口 8000
• suspend=y: 启动时等待调试器连接 (使用 suspend=n 立即启动)

2. 配置 Claude Desktop

编辑 Claude Desktop 配置文件:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "java-debugger": {
      "command": "java",
      "args": [
        "-jar",
        "E:/java_workspace/debug_mcp/target/debug-mcp-1.0.0.jar"
      ],
      "env": {}
    }
  }
}

3. 重启 Claude Desktop

重启后，在对话中可以使用调试工具。

可用工具

工具名称	功能	参数
connect_attach	附加到运行中的 JVM	host (默认: localhost), port
connect_launch	启动并调试新进程	mainClass, classpath, vmArgs, programArgs
disconnect	断开连接	-
set_breakpoint	设置断点	className, lineNumber
clear_breakpoint	清除断点	breakpointId
list_breakpoints	列出所有断点	-
continue_execution	继续执行	threadId (可选)
step_over	单步跳过	threadId (可选)
step_into	单步进入	threadId (可选)
step_out	单步跳出	threadId (可选)
get_local_variables	获取局部变量	threadId (可选), frameIndex (默认: 0)
get_fields	获取对象字段	objectId
list_threads	列出所有线程	-
list_classes	列出已加载的类	pattern (可选)
list_stacktrace	获取线程堆栈	threadId (可选)
get_status	获取调试器状态	-

使用示例

对话示例

用户: 请连接到 localhost:8000 的 Java 程序并设置断点

Claude: [调用 connect_attach, host=localhost, port=8000]
       已连接到 localhost:8000
       [调用 list_classes]
       ... 找到类 com.example.Main ...
       [调用 set_breakpoint, className=com.example.Main, lineNumber=42]
       断点已设置: bp-1: com.example.Main:42

测试

创建测试目标程序

// src/test/java/com/example/TestApp.java
package com.example;

public class TestApp {
    public static void main(String[] args) {
        int sum = 0;
        for (int i = 1; i <= 10; i++) {
            sum += i;
            System.out.println("Sum: " + sum);
        }
        System.out.println("Final: " + sum);
    }
}

编译并运行测试程序

# 编译
javac -d target/test-classes src/test/java/com/example/TestApp.java

# 启动可调试的程序
java -agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y \
  -cp target/test-classes com.example.TestApp

项目结构

E:/java_workspace/debug_mcp/
├── pom.xml                          # Maven 配置
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/debugger/mcp/
│   │   │       ├── Main.java                 # 入口
│   │   │       ├── McpServer.java            # MCP 服务器
│   │   │       ├── handler/
│   │   │       │   └── ToolHandler.java      # 工具处理器
│   │   │       ├── debugger/
│   │   │       │   ├── JdiDebugger.java      # 核心调试器
│   │   │       │   ├── BreakpointManager.java # 断点管理
│   │   │       │   ├── VariableInspector.java # 变量查看
│   │   │       │   └── StepController.java    # 单步控制
│   │   │       └── model/
│   │   │           ├── McpMessage.java       # MCP 消息
│   │   │           ├── ToolCallResult.java   # 工具结果
│   │   │           ├── Tool.java             # 工具定义
│   │   │           └── InitializeResult.java # 初始化结果
└── README.md

技术栈

• 语言: Java 17+
• MCP 协议: JSON-RPC 2.0 over stdio
• 调试 API: JDI (Java Debug Interface)
• 构建工具: Maven
• JSON 处理: Jackson

故障排除

无法连接到 JVM

确保目标程序以调试模式启动:

java -agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y ...

断点不生效

确保编译时包含调试信息:

javac -g ...

Maven 确保使用:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <debug>true</debug>
        <debuglevel>lines,vars,source</debuglevel>
    </configuration>
</plugin>

参考资料

• MCP 文档
• Oracle JPDA 文档
• JDI API 参考