Skip to content

Latest commit

 

History

History
511 lines (373 loc) · 11.7 KB

USER_GUIDE.md

File metadata and controls

511 lines (373 loc) · 11.7 KB

Java Debug MCP Server - 使用指南

完整的 Model Context Protocol (MCP) Java 调试服务器使用说明


目录

  1. 简介
  2. 系统要求
  3. 安装步骤
  4. 配置 Claude Desktop
  5. 基本使用
  6. 可用的调试工具
  7. 使用示例
  8. 常见问题
  9. 高级用法

简介

Java Debug MCP Server 是一个基于 Model Context Protocol 的调试服务器,允许 Claude(或其他支持 MCP 的 LLM)直接调试 Java 程序。

主要功能

  • 🔌 附加到运行中的 JVM 进行调试
  • 🚀 启动新的 Java 进程并调试
  • 📍 设置和管理断点(支持智能短类名后缀匹配及消歧报错)
  • ⚠️ 异常断点拦截(可在任意指定的 Java 异常抛出位置自动暂停)
  • 📢 控制台输出实时转发(将调试目标的 stdout/stderr 实时流式推送至客户端)
  • 👀 查看局部变量和对象字段(支持防止循环引用的深度递归展示)
  • 📊 查看线程和堆栈信息
  • ⏮️ 单步执行(Step Over/Into/Out)
  • 🔄 继续执行控制

系统要求

必需软件

软件 最低版本 推荐版本
Java 17 17+
Maven 3.6+ 3.9+
Claude Desktop 最新版 最新版

操作系统

  • Windows 10/11
  • macOS 11+
  • Linux (主流发行版)

安装步骤

步骤 1: 获取源码

# 克隆或下载项目到本地
cd /path/to/workspace
# 项目位于: E:/java_workspace/debug_mcp

步骤 2: 编译项目

cd E:/java_workspace/debug_mcp
mvn clean package

编译成功后会生成 JAR 文件:

target/debug-mcp-1.0.0.jar  (约 2.3 MB)

步骤 3: 验证安装

java -jar target/debug-mcp-1.0.0.jar

应该看到启动信息:

========================================
Java Debug MCP Server v1.0.0
========================================
...

配置 Claude Desktop

Windows 配置

编辑配置文件: %APPDATA%\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": {}
    }
  }
}

macOS/Linux 配置

编辑配置文件: ~/Library/Application Support/Claude/claude_desktop_config.json

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

重启 Claude Desktop

配置完成后,必须完全重启 Claude Desktop:

  1. 完全退出 Claude Desktop
  2. 重新启动应用程序
  3. 检查 MCP 连接状态

基本使用

准备调试目标

方式 A: 启动可调试的 Java 程序

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

方式 B: 通过 MCP 启动新进程

在 Claude 对话中使用工具启动。

在 Claude 中使用

配置完成后,在 Claude Desktop 对话中直接使用调试功能:

用户: 请帮我调试这个 Java 程序

Claude: 我来连接到你的 Java 程序并设置断点...

可用的调试工具

连接管理工具

工具名称 功能 参数
connect_attach 附加到运行中的 JVM host (默认: localhost), port
connect_launch 启动并调试新进程 mainClass, classpath, vmArgs, programArgs
disconnect 断开连接 -
get_status 获取调试器状态 -

断点管理工具

工具名称 功能 参数
set_breakpoint 设置断点 className (类名,支持短类名后缀匹配), lineNumber (行号)
clear_breakpoint 清除断点 breakpointId (断点 ID)
list_breakpoints 列出所有断点 -
set_exception_breakpoint 设置异常断点 exceptionClassName (异常类全名或短类名), caught (是否捕获时触发,可选,默认 true), uncaught (是否未捕获时触发,可选,默认 true)
clear_exception_breakpoint 清除异常断点 breakpointId (异常断点 ID)

执行控制工具

工具名称 功能 参数
continue_execution 继续执行 threadId (可选)
step_over 单步跳过 threadId (可选)
step_into 单步进入 threadId (可选)
step_out 单步跳出 threadId (可选)

信息查询工具

工具名称 功能 参数
get_local_variables 获取局部变量 threadId (可选), frameIndex (默认: 0)
get_fields 获取对象字段 objectId (对象 ID)
list_threads 列出所有线程 -
list_classes 列出已加载的类 pattern (可选过滤)
list_stacktrace 获取线程堆栈 threadId (可选)

使用示例

示例 1: 调试一个简单的 Java 程序

步骤 1: 创建测试程序

// com/example/App.java
package com.example;

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

步骤 2: 编译并启动

# 编译 (带调试信息)
javac -g -d bin src/com/example/App.java

# 启动 (可调试模式)
java -agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y \
  -cp bin com.example.App

步骤 3: 在 Claude 中调试

用户: 请帮我调试 com.example.App,我想看看 sum 变量的变化

Claude: 好的,我来连接到你的程序...

[连接到 localhost:8000]
[设置断点在 App.java:6]
[继续执行]
[断点命中]
[当前局部变量:
  int sum = 0
  int i = 1]

变量 i 当前是 1,sum 是 0。继续单步执行吗?

示例 2: 调试 Spring Boot 应用

# 启动 Spring Boot 应用 (可调试模式)
java -agentlib:jdwp=transport=dt_socket,server=y,address=5005,suspend=y \
  -jar target/myapp-1.0.0.jar

然后在 Claude 中:

用户: 连接到 localhost:5005 的 Spring Boot 应用,在
  com.example.controller.UserController 的 getUser 方法设置断点

示例 3: 通过 MCP 启动新进程

用户: 请帮我启动并调试 com.example.Calculator 类

Claude: 好的,我来启动这个程序...

[调用 connect_launch:
  mainClass: "com.example.Calculator"
  classpath: "target/classes"]

程序已启动,正在调试...

常见问题

Q1: Claude Desktop 显示 MCP 连接失败

A: 检查以下事项:

  1. JAR 文件路径是否正确(使用绝对路径)
  2. 路径中的反斜杠需要转义为双反斜杠 (Windows) 或使用正斜杠
  3. 确认 Claude Desktop 已完全重启
  4. 查看 Claude Desktop 日志文件

Q2: 无法连接到调试目标

A: 确保:

  1. 目标程序正在运行并显示 "Listening for transport dt_socket..."
  2. JDWP 端口号正确(默认 8000)
  3. 没有防火墙阻止连接
  4. suspend=y 表示程序会等待调试器连接

Q3: 断点不生效

A: 检查:

  1. 编译时使用 -g 参数包含调试信息
  2. 行号是否正确
  3. 类名是否完全匹配(包括包名)
  4. 类是否已被加载

Q4: 找不到类

A: 确保:

  1. 使用完整的类名(包括包名)
  2. 类在 classpath 中
  3. 类已被 JVM 加载

Q5: 变量显示不正确

A: 可能原因:

  1. 变量被编译器优化掉
  2. 确保使用 -g 编译包含所有调试信息
    javac -g:lines,vars,source ...

高级用法

调试 Maven 项目

# 方式 1: 使用 mvnDebug
mvnDebug test

# 然后连接到 localhost:8000

# 方式 2: 使用 Maven 插件
mvn exec:exec -Dexec.executable="java" \
  -Dexec.args="-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y -cp %classpath com.example.Main"

调试 Gradle 项目

# 添加到 build.gradle
application {
    applicationDefaultJvmArgs = ['-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y']
}

# 然后运行
gradle run

远程调试

目标服务器 (Linux):

java -agentlib:jdwp=transport=dt_socket,server=y,address=*,suspend=y \
  -jar myapp.jar

本地机器:

在 Claude 中指定远程服务器地址:

用户: 连接到 192.168.1.100:8000 进行调试

调试 Docker 容器中的 Java 应用

# Dockerfile
FROM openjdk:17
EXPOSE 8000
ENTRYPOINT ["java", "-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y", "-jar", "app.jar"]
# 运行容器
docker run -p 8000:8000 myapp

# 在 Claude 中连接到 localhost:8000

JDWP 参数详解

完整参数格式

-agentlib:jdwp=<name1>=<value1>,<name2>=<value2>...

常用参数

参数 值 说明
transport dt_socket 使用 socket 传输
server y/n JVM 是否作为服务器
address 8000 或 *:8000 监听地址和端口
suspend y/n 启动时是否暂停
allow * 允许所有主机连接

常用组合

# 等待调试器连接
-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y

# 启动后不等待
-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=n

# 允许远程连接
-agentlib:jdwp=transport=dt_socket,server=y,address=*:8000,suspend=y

快速参考卡片

连接到程序

# 启动程序
java -agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y -cp bin com.example.Main

# 在 Claude 中
"连接到 localhost:8000"

设置断点

"在 com.example.Main 的第 15 行设置断点"

查看变量

"显示当前的局部变量"
"查看 objectId 为 123abc 的对象的字段"

单步调试

"单步执行"
"单步进入"
"单步跳出"
"继续执行"

项目文件结构

E:/java_workspace/debug_mcp/
├── pom.xml                          # Maven 配置
├── README.md                        # 项目说明
├── USER_GUIDE.md                    # 本文档
├── TEST.md                          # 测试指南
├── target/
│   ├── debug-mcp-1.0.0.jar         # 可执行 JAR
│   └── test-classes/                # 测试类
├── src/
│   ├── main/java/com/debugger/mcp/
│   │   ├── Main.java                # 入口
│   │   ├── McpServer.java           # MCP 服务器
│   │   ├── handler/ToolHandler.java # 工具处理器
│   │   ├── debugger/                # 调试器实现
│   │   └── model/                   # 消息模型
│   └── test/java/
│       └── com/example/             # 测试程序

获取帮助

  • 查看 README.md 了解项目概述
  • 查看 TEST.md 了解测试方法
  • 查看源代码中的注释了解实现细节

版本历史

  • v1.1.0 - 进阶功能版本 (当前最新)
    • 控制台输出转发:不再丢弃被调进程的标准输出和错误流,通过 MCP 协议通道(STDOUT/STDERR 事件类型)实时推送到客户端。
    • 异常断点支持:新增设置/清除异常断点工具,安全读取底层私有 detailMessage 规避死锁,能够在捕获或未捕获异常抛出时自动挂起。
    • 容错类名解析:设置行断点支持输入短类名(如 Calculator 而非完整的 com.example.Calculator),后缀模糊匹配;如匹配到多项则自动报错列出候选供消歧。
  • v1.0.0 - 初始版本
    • 支持附加到运行中的 JVM
    • 支持启动新进程调试
    • 断点管理
    • 变量查看
    • 单步执行
    • 线程和堆栈信息查询