dbgprobe-mcp-server

Debug Probe MCP 服务

一款有状态的调试探针模型上下文协议（MCP）服务，用于开发者工具和 AI Agent。 开箱即用，兼容 Claude Code、集成 Copilot 的 VS Code，以及任何兼容 MCP 的运行时。通过 stdio 通信，并驱动芯片上的调试探针（优先支持 J-Link，计划支持 OpenOCD 和 pyOCD），以烧录、调试和检查嵌入式目标。

示例： 让 Claude Code 列出已连接的 J-Link 探针，连接到你的 nRF52840，烧录新固件，读取内存并重置目标设备——整个过程都通过对话完成。

演示

视频演示 ——连接到 J-Link 探针、烧录固件、加载 ELF 和 SVD 以进行符号感知调试、RTT 日志记录，以及设置断点。

---

为什么要开发它

如果你曾经手动输入过 J-Link Commander 命令，在数据手册和终端之间复制粘贴内存地址，在一次调试过程中对同一固件反复烧录 20 次，还要在多个工具窗口之间来回切换——那么这正是为你准备的。

你有一块连接着调试探针的微控制器。你希望 AI Agent 能与它交互——连接、烧录固件、读写内存、重置、暂停、继续。这个服务让这一切成为可能。

它为任何兼容 MCP 的 Agent 提供一整套调试探针工具。Agent 调用这些工具并获得结构化 JSON 响应，然后据此判断下一步操作——无需你为每项操作都手动驱动 JLinkExe。

Agent 可以用它做什么：

• 烧录并迭代——构建固件、烧录、重置、检查行为，全程在一次对话中完成
• 检查内存——读取外设寄存器、检查 RAM 内容、验证闪存写入
• 交互式调试——暂停、单步执行、设置断点、检查状态、继续运行
• 自动化测试流程——烧录 → 重置 → 读取输出 → 验证
• 多探针设置——同时连接多个探针，每个探针都有自己的会话

---

适用于哪些人？

• 嵌入式工程师——更快迭代：通过对话烧录、调试、检查内存
• 业余爱好者和创客——无需学习 JLinkExe 命令语法即可与微控制器交互
• QA 和测试工程师——在多块开发板上自动执行烧录和测试流程
• 研究人员——系统地探索嵌入式系统、检查寄存器

---

快速开始（Claude Code）

pip install dbgprobe-mcp-server

# Register the MCP server with Claude Code
claude mcp add dbgprobe -- dbgprobe_mcp

# Or with explicit J-Link path
claude mcp add dbgprobe \
  -e DBGPROBE_JLINK_PATH=/Applications/SEGGER/JLink/JLinkExe \
  -- dbgprobe_mcp

然后在 Claude Code 中试试：

“列出已连接的调试探针，连接到 J-Link，并读取地址 0x20000000 处的 16 个字节。”

---

支持的后端

后端	状态	探针硬件
J-Link	可用（v0）	SEGGER J-Link（EDU、EDU Mini、PLUS、PRO 等）
OpenOCD	计划支持	ST-Link、CMSIS-DAP 以及许多其他设备
pyOCD	计划支持	CMSIS-DAP、ST-Link、J-Link（通过 pyOCD）

该服务与后端无关——无论使用哪种探针，工具名称（dbgprobe.*）都保持不变。

J-Link 要求

安装 SEGGER J-Link Software Pack。服务会自动在 PATH 或常见安装位置中检测 JLinkExe：

• macOS： /Applications/SEGGER/JLink/
• Linux： /opt/SEGGER/JLink/、/usr/bin/
• Windows： C:\Program Files\SEGGER\JLink\

或者设置 DBGPROBE_JLINK_PATH，使其指向该可执行文件。

本项目与 SEGGER 无关，也未获得其赞助。使用 J-Link 是因为它应用广泛且支持良好。

---

工具

类别	工具
探测器	dbgprobe.probes.list、dbgprobe.connect、dbgprobe.erase、dbgprobe.disconnect、dbgprobe.reset、dbgprobe.halt、dbgprobe.go、dbgprobe.step、dbgprobe.status、dbgprobe.flash、dbgprobe.mem.read、dbgprobe.mem.write、dbgprobe.breakpoint.set、dbgprobe.breakpoint.clear、dbgprobe.breakpoint.list
内省	dbgprobe.connections.list
ELF	dbgprobe.elf.attach、dbgprobe.elf.info、dbgprobe.elf.lookup、dbgprobe.elf.symbols
SVD	dbgprobe.svd.attach、dbgprobe.svd.info、dbgprobe.svd.read、dbgprobe.svd.write、dbgprobe.svd.set_field、dbgprobe.svd.update_fields、dbgprobe.svd.list_peripherals、dbgprobe.svd.list_registers、dbgprobe.svd.list_fields、dbgprobe.svd.describe
RTT	dbgprobe.rtt.start、dbgprobe.rtt.stop、dbgprobe.rtt.read、dbgprobe.rtt.write、dbgprobe.rtt.status
插件	dbgprobe.plugin.list、dbgprobe.plugin.template、dbgprobe.plugin.load、dbgprobe.plugin.reload
跟踪	dbgprobe.trace.status、dbgprobe.trace.tail

完整的架构和示例请参阅 docs/tools.md。

---

安装（开发版）

# Editable install from repo root
pip install -e ".[test]"

# Or with uv
uv pip install -e ".[test]"

MCP 是一种协议——此服务可与任何兼容 MCP 的客户端配合使用。以下是最常见客户端的配置说明。

添加到 Claude Code

# Standard setup
claude mcp add dbgprobe -- dbgprobe_mcp

# With default target device
claude mcp add dbgprobe \
  -e DBGPROBE_JLINK_DEVICE=nRF52840_xxAA \
  -- dbgprobe_mcp

# Debug logging
claude mcp add dbgprobe -e DBGPROBE_MCP_LOG_LEVEL=DEBUG -- dbgprobe_mcp

添加到 VS Code / Copilot

添加到项目的 .vscode/mcp.json（或创建该文件）：

{
  "servers": {
    "dbgprobe": {
      "type": "stdio",
      "command": "dbgprobe_mcp",
      "args": [],
      "env": {
        "DBGPROBE_JLINK_DEVICE": "nRF52840_xxAA"
      }
    }
  }
}

根据目标设备调整 env——将 DBGPROBE_JLINK_DEVICE 设置为你的芯片型号，或移除该变量以便在连接时指定设备。

添加到 Cursor

添加到项目的 .cursor/mcp.json（或创建该文件）。Cursor 不支持工具名称中包含点号，因此必须将 DBGPROBE_MCP_TOOL_SEPARATOR 设置为 _：

{
  "mcpServers": {
    "dbgprobe": {
      "command": "dbgprobe_mcp",
      "args": [],
      "env": {
        "DBGPROBE_JLINK_DEVICE": "nRF52840_xxAA",
        "DBGPROBE_MCP_TOOL_SEPARATOR": "_"
      }
    }
  }
}

环境变量

服务端

变量	默认值	说明
DBGPROBE_BACKEND	jlink	调试探针后端。未来支持：openocd、pyocd。
DBGPROBE_MCP_LOG_LEVEL	WARNING	Python 日志级别（DEBUG、INFO、WARNING、ERROR）。日志输出到 stderr。
DBGPROBE_MCP_TRACE	已启用	对每次工具调用进行 JSONL 跟踪。设置为 0、false 或 no 可禁用。
DBGPROBE_MCP_TRACE_PAYLOADS	已禁用	在跟踪参数中包含内存数据负载（默认会剥除）。
DBGPROBE_MCP_TRACE_MAX_BYTES	16384	截断前的最大负载字符数（仅在启用 TRACE_PAYLOADS 时生效）。
DBGPROBE_MCP_TOOL_SEPARATOR	.	用于分隔工具名称各部分的字符。对于不接受工具名称中包含点号的 MCP 客户端（如 Cursor），设置为 _。
DBGPROBE_MCP_PLUGINS	已禁用	插件策略：all 或以逗号分隔的插件名称（如 nrf52,stm32）。

J-Link 后端

变量	默认值	说明
DBGPROBE_JLINK_PATH	自动检测	JLinkExe 的显式路径（Windows 上为 JLink.exe）。
DBGPROBE_JLINK_GDBSERVER_PATH	自动检测	JLinkGDBServerCLExe 的显式路径。
DBGPROBE_JLINK_DEVICE	（无）	默认目标设备字符串（如 nRF52840_xxAA）。可按会话覆盖。
DBGPROBE_INTERFACE	SWD	调试接口：SWD 或 JTAG。
DBGPROBE_SPEED_KHZ	4000	接口时钟速度，单位为 kHz。
DBGPROBE_GDB_TRACE	已禁用	将所有 GDB RSP 数据包记录到文件。设置为 1、true 或 yes 可启用。
DBGPROBE_GDB_TRACE_FILE	/tmp/gdb_trace.log	GDB RSP 跟踪日志的路径（仅在启用 GDB_TRACE 时生效）。

---

ELF 支持

将 ELF 文件附加到会话，即可启用符号感知调试：

• 符号查找 — 将函数名解析为地址，反之亦然
• 按名称设置断点 — 使用 breakpoint.set(symbol="main")，而不是原始地址
• 自动补充响应信息 — 附加 ELF 后，status、step 和 halt 会包含 symbol + symbol_offset
• 烧录集成 — 烧录 .elf 会自动附加该文件；烧录 .hex/.bin 会自动重新加载之前附加的 ELF；系统会通过提示建议使用同目录下的 .elf 文件

> "Attach the ELF, set a breakpoint on main, run, and show me where it halted."

Agent 调用 elf.attach、breakpoint.set(symbol="main")、go，然后调用 status，收到的结果是 "halted at main+0"，而不是原始十六进制地址。

---

SVD 支持

将 SVD（系统视图描述）文件附加到会话，即可启用寄存器级外设访问：

• 按名称读取寄存器 — svd.read("GPIO.OUT") 会返回原始值以及所有带枚举名称的解码字段
• 读取字段值 — svd.read("GPIO.PIN_CNF[3].PULL") 会返回字段值和枚举名称（"PullUp"）
• 安全写入字段 — svd.set_field("GPIO.PIN_CNF[3].PULL", "PullUp") 会执行读-改-写
• 批量更新字段 — svd.update_fields("GPIO.PIN_CNF[3]", {"DIR": "Output", "PULL": "PullUp"}) — 读取一次，写入一次
• 写入原始寄存器 — svd.write("GPIO.OUT", 0x01) — 写入整个寄存器，不执行 RMW
• 发现 — 列出外设、寄存器和字段；提供带枚举值的说明
• 在 mem.read 时自动解码 — 附加 SVD 后，如果 mem.read 命中已知寄存器地址，响应会包含解码后的字段

> "Attach the SVD, read GPIO.PIN_CNF[3], and set PULL to PullUp."

Agent 调用 svd.attach、svd.read("GPIO.PIN_CNF[3]")，然后调用 svd.set_field("GPIO.PIN_CNF[3].PULL", "PullUp")，收到的是解码后的字段值，而不是原始十六进制值。

---

RTT（实时传输）

启动、停止、读取和写入 SEGGER RTT 通道。Agent 可以流式读取目标设备的日志输出，并向设备发送数据——适用于调试通过 RTT 而非 UART 输出信息的固件。

> "Start RTT and show me the output."

对于重复性流程，例如读取设备 ID、运行自检序列、验证校准结果，可以将其打包为插件：一种可公开自定义工具供 Agent 直接调用的 Python 模块。使用 DBGPROBE_MCP_PLUGINS=all 启用。请参阅 nrf52_info 示例。

---

跟踪

每次工具调用都会记录到 .dbgprobe_mcp/traces/trace.jsonl 和内存环形缓冲区（最近 2000 个事件）中。跟踪默认开启——设置 DBGPROBE_MCP_TRACE=0 即可禁用。

使用 dbgprobe.trace.status 和 dbgprobe.trace.tail 查看跟踪记录，无需直接读取文件。

---

不使用 Agent 试用

你可以使用 MCP Inspector 交互式测试服务：

npx @modelcontextprotocol/inspector python -m dbgprobe_mcp_server

---

路线图 / 待办事项

• OpenOCD 后端 — 通过 OpenOCD 子进程支持 ST-Link、CMSIS-DAP 和其他探针
• pyOCD 后端 — 通过 pyOCD 库原生访问探针
• 多核支持 — 在多核 SoC 上指定目标核心
• Cortex-A/R 支持 — ARM 模式断点（kind=4）；目前仅支持 Thumb 模式（Cortex-M）

---

已知限制

• 仅支持单客户端。 服务一次处理一个 MCP 会话（stdio 传输）。
• 仅支持 RTT 通道 0。 RTT 支持仅限于通道 0（终端）。多通道 RTT 将作为未来增强功能。
• 烧录会清除断点。 烧录新固件会使断点失效（这些地址处的代码可能已更改）。会话仍保持活动状态，但断点会被清除。
• 仅支持 Cortex-M。 断点使用 Thumb 模式（kind=2）。尚不支持 Cortex-A/R 目标（ARM 模式，kind=4）。
• 仅支持指令级单步执行。 dbgprobe.step 对一条 CPU 指令进行单步执行。不支持源码级单步执行（步入/步过/步出）。

---

安全

此服务将 AI Agent 连接到真实的调试硬件。这正是它的用途，也意味着其风险高于纯软件工具。

插件会执行任意代码。 启用插件后，Agent 可以在你的计算机上以完整的服务权限创建并运行 Python 代码。加载 Agent 生成的插件前，请先检查。

写入会影响真实硬件。 错误的内存写入或闪存操作可能会导致设备变砖、清除校准数据或触发意外行为。请考虑 Agent 能够访问哪些内容。

谨慎批准工具调用。 MCP 客户端提示你批准工具调用时，请考虑是仅允许这一次，还是始终允许。

本软件按原样提供，并依据 MIT License 授权。你需对 Agent 使用你的硬件所执行的操作负责。

---

许可证

本项目依据 MIT License 授权，详情请参阅 LICENSE。