java-ai-debugger (TypeScript)

Java AI Debugger 的 TypeScript 版 MCP server，与 Python 版 mcp-server 功能完全一致： 通过 JDWP/JDI 远程调试运行中的 JVM。内置 debug-core JAR，安装后自包含，无需 Maven。

安装

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

快速上手

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 端口则直接复用。

使用

# 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 工具（34 个）

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

环境变量

| 变量 | 说明 | 默认 | |---|---|---| | 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 |

开发

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