# java-ai-debugger (TypeScript)

Java AI Debugger 的 **TypeScript 版 MCP server**，与 Python 版 `mcp-server` 功能完全一致：
通过 [JDWP/JDI](https://docs.oracle.com/en/java/javase/21/docs/api/jdk.jdi/com/sun/jdi/package-summary.html)
远程调试运行中的 JVM。内置 `debug-core` JAR，安装后自包含，无需 Maven。

## 安装

```bash
npm install -g @unclesaliva/java-ai-debugger
```

## 快速上手

```bash
java-ai-debugger init       # 一次性：JDK 检查 + MCP 配置 + 保存配置
java-ai-debugger start      # 启动 debug-core（后台）
java-ai-debugger status     # 查看运行状态
# 打开 AI 工具开始调试 ...
java-ai-debugger stop       # 清理进程
```

### 命令说明

| 命令 | 说明 |
|------|------|
| `init` | 一次性配置：检测 JDK（JAVA_HOME / PATH，≥ 21），选择 AI 工具并写入 MCP 配置，保存到 `~/.java-ai-debugger/config.json` |
| `start` | 启动 debug-core（随机空闲端口），端口写入配置文件 |
| `stop` | 停止 debug-core 和 MCP server 进程，清理配置 |
| `status` | 显示当前状态：debug-core 是否运行、目标 JDWP 端口、MCP server 进程、活跃 session 数 |
| `detach` | 强制解除所有 debug session 的 attach（调试卡住时先 detach 再 start） |
| `--help` | 帮助 |
| `--version` | 版本 |

> AI 工具通过 stdio 自动拉起 MCP server（MCP 配置写 `"command": "java-ai-debugger"`），启动后
> 检测到 `~/.java-ai-debugger/config.json` 中已有运行的 debug-core 端口则直接复用。

## 使用

```bash
# 1) 让 Java 程序以调试模式启动
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 -jar your-app.jar

# 2) 配置并启动（只需一次 init）
java-ai-debugger init
java-ai-debugger start

# 3) 在 AI 工具中直接要求调试 Java 程序
```

> `address=5005` 是**被调试 JVM 的 JDWP 端口**，默认 5005，`init` 时可自定义。

## MCP 工具（45 个，默认全暴露）

> **JAD_MODE=harness**（`java-ai-debugger init --harness`）时缩减到 **14 个聚合工具**（生命周期 6 + 诊断流水线 5 + 探查 3），隐藏低层原子工具（断点管理/单步/eval/观察点等 31 个）。详见 `docs/harness-architecture-map.md` §8。

`create_debug_session` · `get_debug_session_state` · `close_debug_session` ·
`attach_to_jvm` · `detach_from_jvm` · `set_line_breakpoint` · `remove_line_breakpoint` ·
`list_line_breakpoints` · `resume_vm` · `pause_vm` · `step_into` · `step_over_method` ·
`step_out_of_method` · `get_local_variables` · `list_all_threads` · `get_thread_stack` ·
`inspect_object_snapshot` · `inspect_eval` · `list_loaded_classes` · `list_class_methods` ·
`set_method_breakpoint_tool` · `remove_method_breakpoint_tool` · `list_method_breakpoints_tool` ·
`get_last_watchpoint_hit` · `set_field_watchpoint` · `list_field_watchpoints` ·
`remove_field_watchpoint` · `set_exception_breakpoint_filter` ·
`list_exception_breakpoint_filters` · `find_exception_origin` · `report_root_cause` ·
`set_call_limit` · `trigger_target` · `list_all_breakpoints` · `inspect_eval_batch` ·
`get_suspended_thread` · `collect_debug_context` · `suggest_breakpoint_bundle` ·
`deploy_breakpoint_bundle` · `summarize_stop_context` · `wait_for_breakpoint_hit` ·
`probe_object_graph` · `discover_runtime_objects` · `probe_runtime_value`

## 环境变量

| 变量 | 说明 | 默认 |
|---|---|---|
| `DEBUG_CORE_URL` | debug-core 地址（设置后跳过自动启动） | 配置文件中的 debugCorePort |
| `NO_AUTO_START` | 设置后不自动启动 debug-core（需配合 DEBUG_CORE_URL） | 无 |
| `JAVA_HOME` | JDK 21+ 路径 | 自动探测 |
| `JDWP_PORT` | 被调试 JVM 的 JDWP 端口（`attach_to_jvm` 默认连接此端口） | `5005` |

## 开发

```bash
cd mcp-server-ts
npm install
npm run build     # tsc → dist/
npm start         # 运行 server（NO_AUTO_START=1 可跳过自动启动）
npm run setup     # 运行配置命令
```