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 Servers