内容
# jdwp-mcp
**通过JDWP和模型上下文协议为大型语言模型调试Java**
一个MCP服务器，使Claude Code和其他大型语言模型工具能够通过Java调试线协议（JDWP）调试Java应用程序。附加到正在运行的JVM，设置断点，检查变量，逐步执行代码——所有这些都可以通过自然语言。
## 功能
- **远程调试**：连接到任何启用了JDWP的JVM
- **断点管理**：按类+行设置/列出/清除断点，可选**命中次数**（停止在第N次命中）和**线程过滤器**，或按**方法名称**（第一行）设置
- **堆栈检查**：具有类型化局部变量和已解析的**源代码行**的堆栈帧
- **执行控制**：**跳过/进入/退出**，继续，暂停
- **表达式求值**：`localVar`/`this`带有`.field`和`.method(args)`链，解析重载的arity和遍历超类链。参数：int，long，boolean，null，“string”
- **值渲染**：字符串，类型化对象（尽力而为的`toString()`），和**数组内容**
- **设置值**：在暂停的帧中写入局部变量
- **线程管理**：工具默认为最后一个命中断点的线程
- **结构化事件**：`get_last_event`发出一个机器可读的`[event]`行（线程，类.方法：行）
- **安全性**：一个`panic`工具（清除所有+恢复）和一个**监视器**，自动恢复长时间暂停的VM（`JDWP_WATCHDOG_SECS`，默认为120），以防止忘记的断点冻结共享实例
> 此分支实现了`debug.evaluate`和`debug.step_*`（存根上游）以及上述安全性、结构化事件、数组、设置值和断点修改器功能。
## 快速入门
### 1. 启动Java应用程序并启用JDWP
```bash
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar myapp.jar
```
### 2. 构建MCP服务器
```bash
cargo build --release
```
### 3. 配置Claude Code
启用MCP服务器的最简单方法：
```bash
# 从您的Java项目目录
claude mcp add --scope project jdwp /path/to/jdwp-mcp/target/release/jdwp-mcp
```
调整路径以匹配您克隆此存储库的位置。`--scope project`标志使调试器仅在您的当前Java项目中可用。
**替代**：通过`.mcp.json`进行手动配置：
```json
{
"mcpServers": {
"jdwp": {
"command": "/path/to/jdwp-mcp/target/release/jdwp-mcp"
}
}
}
```
### 4. 使用自然语言调试
```
> 连接到localhost:5005的JVM
> 在com.example.HelloController第65行设置断点
> 当它命中时，显示给我堆栈和requestCount的值
```
## 可用工具
| 工具 | 描述 |
|------|-------------|
| `debug.attach` | 通过JDWP连接到JVM |
| `debug.set_breakpoint` | 按类+行或方法名称设置断点；可选`hit_count`和线程过滤器 |
| `debug.list_breakpoints` | 列出活动断点 |
| `debug.clear_breakpoint` | 删除断点 |
| `debug.continue` | 恢复执行 |
| `debug.step_over` | 跳过当前行（默认为最后一个命中的线程） |
| `debug.step_into` | 进入方法调用 |
| `debug.step_out` | 退出当前方法 |
| `debug.get_stack` | 具有类型化变量和源代码行的堆栈帧 |
| `debug.evaluate` | 在帧中求值`var`/`this` + `.field` / `.method(args)`链 |
| `debug.set_value` | 在暂停的帧中设置局部变量 |
| `debug.get_last_event` | 最后一个事件，带有机器可读的`[event]`行（线程，类.方法：行） |
| `debug.list_threads` | 列出所有线程 |
| `debug.pause` | 暂停执行（暂停所有线程） |
| `debug.panic` | 安全：清除所有断点并恢复所有线程 |
| `debug.disconnect` | 结束调试会话 |
大多数工具接受`thread_id`作为可选的十六进制字符串（例如`"0x2"`）；如果省略，则默认为最后一个命中的线程。监视器自动恢复长时间暂停的VM（`JDWP_WATCHDOG_SECS`，默认为120）。
## 示例：使用kubectl port-forward调试
适用于Kubernetes部署的Java应用程序：
```bash
# 从pod转发JDWP端口
kubectl port-forward pod/my-app-pod 5005:5005
```
然后在Claude Code中：
```
> 连接到localhost:5005
> 在processRequest方法中设置断点
```
## 架构
```
Claude Code → MCP服务器 → JDWP客户端 → TCP套接字 → JVM
↓
总结 &
上下文过滤
```
MCP服务器处理：
- **协议转换**：MCP JSON-RPC ↔ JDWP二进制协议
- **智能总结**：截断大对象，限制深度
- **状态管理**：跟踪断点，线程，会话
## 开发
### 项目结构
```
jdwp-mcp/
├── jdwp-client/ # JDWP协议实现
│ ├── connection.rs # TCP + 握手
│ ├── protocol.rs # 数据包编码/解码
│ ├── commands.rs # JDWP命令常量
│ ├── types.rs # JDWP类型定义
│ └── events.rs # 事件处理
├── mcp-server/ # MCP服务器
│ ├── main.rs # 标准输入输出传输
│ ├── protocol.rs # MCP JSON-RPC
│ ├── handlers.rs # 请求路由
│ ├── tools.rs # 工具定义
│ └── session.rs # 调试会话状态
└── examples/ # 使用示例
```
### 测试
使用配套的[java-example-for-k8s](../java-example-for-k8s)作为测试目标：
```bash
cd ../java-example-for-k8s
mvn clean package
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 \
-jar target/probe-demo-0.0.1-SNAPSHOT.jar
```
然后使用此正在运行的应用程序测试MCP工具。
### 构建
```bash
# 调试构建
cargo build
# 发布构建
cargo build --release
# 运行测试
cargo test
```
## 状态
✅ **功能完整** — 16个调试工具，已集成并针对实时JVM进行验证。
### 已实现
- [x] JDWP协议（握手，数据包，编码/解码）
- [x] 具有16个调试工具的MCP服务器（标准输入输出传输）
- [x] 虚拟机命令（版本，ID大小，所有线程，暂停/恢复，创建字符串）
- [x] ClassesBySignature，ReferenceType.Methods/Fields/Signature，ClassType.Superclass
- [x] 方法.LineTable / VariableTable
- [x] EventRequest.Set/Clear/ClearAllBreakpoints — 具有位置，**计数**和**线程**修饰符的断点
- [x] ThreadReference.Frames，StackFrame.GetValues/SetValues/ThisObject
- [x] ObjectReference.ReferenceType/GetValues/**InvokeMethod**，ArrayReference.Length/GetValues，StringReference.Value
- [x] **事件循环**，用于异步断点/步骤通知
- [x] **逐步执行**（跳过/进入/退出）
- [x] **表达式求值** — `var`/`this` + `.field` / `.method(args)`链，类型感知重载解析，超类遍历
- [x] **字符串和对象取消引用**，数组内容，尽力而为的`toString()`，源代码行解析
- [x] **条件断点** — 在命中帧中求值`condition`（`expr OP literal`或布尔链）；当为假时自动恢复
- [x] **多个并发会话** — `debug.attach`返回一个`session_id`；工具接受一个可选的`session_id`（默认为当前）
- [x] `evaluate` / 条件中的**参数文字**：int，long（`123L`），boolean，null，`"string"`
- [x] **安全性**：`panic` + 空闲监视器自动恢复
- [x] 架构独立性（大端协议；Intel和ARM）
## 参考
- [JDWP规范](https://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html)
- [模型上下文协议](https://modelcontextprotocol.io/)
- [Claude Code MCP文档](https://docs.claude.com/claude-code)
## 许可证
MIT
