DebugMcp

让 AI 真正「上手」IntelliJ IDEA 的调试器。

DebugMcp 是一个 IntelliJ IDEA 插件，内嵌一个 MCP（Model Context Protocol）server，把 IDE 的调试能力——断点 / 步进 / 读变量 / 表达式求值 / 读控制台——通过 MCP 协议暴露给 AI 客户端 （Claude Code / Claude Desktop）。

装好后，你用自然语言对 Claude 说「在这行设断点、我去触发、停下后看这个变量」，它就驱动你真实运行中的 调试会话完成排查——而不是凭空猜测代码。

它能做什么

• 断点管理：设 / 删 / 列 / 启停行断点，含接管你在 IDE 里手动建的断点。
• 状态感知：三态判定（无会话 / 运行中 / 已暂停）、读调用栈。
• 执行控制：继续 / 暂停 / 单步（over / into / out），异步落点带超时轮询。
• 数据检查（只读）：读当前帧局部变量、按名展开单变量、求表达式，深度 / 广度双上限防撑爆客户端。
• 控制台读取：枚举运行 / 调试 tab，读尾部输出（找端口、异常栈、日志）。
• 多工程 / 多会话定向：开多个工程或会话时用 project / session / target 参数显式指定。

共 19 个 MCP 工具： ping · list_projects · set_breakpoint · remove_breakpoint · list_breakpoints · toggle_breakpoint · list_sessions · get_debug_status · get_stack_trace · resume · pause · step_over · step_into · step_out · read_variables · read_variable · evaluate_expression · list_consoles · read_console

⚠️ 人类在环：启动 / 重启被调试程序、触发代码路径让断点命中，这些只能你在 IDE 里做，AI 无法代劳。 典型节奏是 AI 帮你设好断点 → 提示你去触发 → 你操作让程序停在断点 → AI 接着读变量 / 单步。

快速开始

1. 装插件：Settings → Plugins → ⚙️ → Install Plugin from Disk… 选中 debug-mcp-<版本>.zip，重启 IDEA。

2. 确认 server 起来：Settings → Tools → Debug MCP，「状态」行应显示 「运行中 — http://127.0.0.1:8765/mcp」，并提供只读的 MCP 配置片段与「复制配置」按钮。

3. 在 Claude 端配 MCP（端口以设置面板实际显示为准）：

   claude mcp add debug-mcp --transport sse http://127.0.0.1:8765/mcp
   

4. 重连刷新工具列表，让 Claude 调一次 ping 拿到 pong 即链路通。 5.（推荐）装 intellij-debugging Skill：把 skills/intellij-debugging/ 拷到 ~/.claude/skills/，让 Claude 用高层意图编排这套工具。

完整步骤见 INSTALL.md，使用总览与示例见 USAGE.md。

现成发布包：release/ 下有打好的插件 zip + Skill + 用户级安装说明，可整体分发 release/debug-mcp-<版本>-bundle.zip。

核心调试闭环

连接自检        ping / list_projects / list_sessions
   │
设断点          set_breakpoint(file=绝对路径, line=1-based)
   │
▶ 你来运行 / 触发   ← 人类在环：让程序命中断点
   │
判定是否命中     get_debug_status  → paused | running | no_session
   │ (paused)
检查（只读）     get_stack_trace / read_variables / read_variable / evaluate_expression
   │
推进            step_over / step_into / step_out / resume   （或 pause 打断运行中的程序）
   │
   └─→ 回到「判定命中」，循环至定位问题

架构概览

整个 IDE 进程只跑一个 MCP server，默认监听 http://127.0.0.1:8765/mcp（首选端口来自持久化配置， 缺省 8765）；被占时在 [首选端口, 首选端口+20) 内探测落到其它空闲端口。传输层是 Ktor CIO + SSE。

| 文件 | 职责 | |---|---| | McpServerService.kt | 应用级单例，server 生命周期 + 全部工具注册（startIfNeeded 幂等） | | McpAppLifecycleListener.kt / McpStartupActivity.kt | 主触发 / 兜底触发，互为兜底拉起 server | | McpToolSupport.kt | 跨工具公共件：ToolException / toolResult / 参数读取 / 工程解析 | | DebugSessionSupport.kt | 会话解析、状态守卫、异步→协程桥、EDT 桥、控制动作落点 | | DataInspectionSupport.kt | 帧解析、值 / 子节点 / 求值的回调→协程桥、富文本翻译、递归展开 | | ConsoleSupport.kt | 跨工程枚举 tab、包装型 console 解包、取尾部 N 行 | | McpSettings.kt / McpConfigurable.kt / McpNotifications.kt | 持久化配置 / 设置面板 / 启动通知 | | *Registry.kt | 字符串 id（bp-1 / s1 / c1）↔ 平台对象的双向映射 |

两条硬性约定：① 工具体跑在 Ktor IO 协程上，不阻塞、不直接碰平台对象（读用 readAction、 写断点用 edtWriteAction、触发调试动作用 onEdt，异步事件用协程桥挂起等待）； ② 状态 / 执行 / 数据类工具都接受可选 session 参数，解析统一走 DebugSessionSupport。

架构与构建约束的权威说明见 CLAUDE.md。

从源码构建

Windows + PowerShell 下用 wrapper：

.\gradlew.bat compileKotlin  # 只编译 Kotlin（最快的语法/依赖校验）
.\gradlew.bat build          # 编译 + 构建插件
.\gradlew.bat runIde         # 启动带本插件的沙箱 IDEA，免安装验证
.\gradlew.bat buildPlugin    # 打包可分发的插件 zip（build/distributions/）
.\scripts\make-release.ps1 -Build   # 重建 release/ 发布包

没有测试代码：验证手段是 runIde 起沙箱 IDEA 后做联调。

构建约束（改 build 配置前必读）

版本是一条连锁约束链，不能单独升降其中一环：

MCP SDK 0.12.0 → Kotlin 2.3 → IntelliJ 2026.1 平台 → 高版本 JDK

• 本地平台依赖：build.gradle.kts 用 local("D:/WindowsApp/JetBrains/IntelliJ IDEA 2026.1") 指向本地已装 IDEA，避免下载约 1.5GB 平台。换机器需改这个硬编码路径。
• 编译 toolchain = IDEA 自带 JBR 25：必须用 JBR 25 才能读取 2026.1 平台的高版本字节码； 系统 JDK 17 无法编译本插件。
• 产出 target = JVM 21：Kotlin 暂不支持 target 25。
• Gradle 9.1.0+：JDK 25 需要，8.x 在 JDK 25 上会崩。
• 必须 exclude kotlinx-coroutines：统一用 IntelliJ 平台自带协程，避免重复 / 冲突的协程类。

平台锁定 untilBuild = "261.*"（2026.1 全系列）：宁「拒绝加载」不「加载即崩」。

技术栈

• Kotlin 2.3.20 · IntelliJ Platform Gradle Plugin 2.16.0
• MCP Kotlin SDK 0.12.0 · Ktor 3.3.3（CIO server + SSE）
• 目标平台 IntelliJ IDEA 2026.1（since-build = 261）

文档导航

| 文档 | 面向谁 / 内容 | |---|---| | INSTALL.md | 人 — 三段式安装：装插件 → Claude 端配 MCP → 装 Skill | | USAGE.md | 人 — 使用总览、工具一览、典型示例、避坑要点 | | CLAUDE.md | 架构、源文件分工、关键构建约束 | | PHASES.md | 五阶段路线图与进度 | | skills/intellij-debugging/ | AI — 调试工作流 Skill（核心闭环 + 工具速查 + 渐进披露 reference） | | openspec/ | 各能力的当前规格（specs）与变更提案（changes） |

状态

阶段一~四（脚手架链路、断点管理、状态感知 + 执行控制、数据检查）均已完成并经 runIde 联调； 阶段五打磨中（多会话、健壮性、易用性配置、MCP 专属 Skill、使用说明、打包安装构建侧均已完成）， 余「IDEA 从磁盘安装」的人类在环验证。详见 PHASES.md。