嵌入式调试器服务

嵌入式调试器MCP服务器

嵌入式调试器MCP是一个Rust服务器，用于通过以下方式进行嵌入式调试 探测器rs（本机）或OpenCD（通过GDB远程串行协议）。它暴露了一个 用于AI助手的单个MCP工具集——探测发现、目标控制、内存、， 断点、闪存、RTT和面向AI的崩溃诊断，以及一个小型CLI和 无需设置MCP客户端即可实现命令驱动工作流的捆绑技能 第一。

语言版本： 英语 | 中文

它提供了什么

• 一个MCP工具集位于两个可互换后端（探头本地或 通过GDB RSP打开CD），在连接时选择。在真实的ESP32-S3上验证。
• 用于探测发现、目标连接、核心控制、内存访问的MCP工具， 断点、闪存编程、RTT通信和崩溃诊断 (diagnose_fault, unwind_exception).
• 用于环境检查、配置检查、探测器列表、， MCP服务和技能提示切换。
• Codex/Claude Code兼容技能 skills/embedded-debugger.
• 发布检查涵盖了rustfmt、clippy、测试、文档、包装和STM32 演示构建。

建筑学

MCP client or CLI
        |
        v
embedded-debugger-mcp  (one MCP tool set)
        |
        v
DebugBackend:  probe-rs (native)  |  OpenOCD (GDB RSP)
        |
        v
debug probe / openocd  ->  target MCU

需求

• 防锈工具链。
• 探针兼容调试探针，如ST-Link、J-Link、DAPLink、Black Magic Probe或支持的基于FTDI的探头。或者，跑步 openocd 暴露其GDB端口（例如esp32的openocd-esp32）以使用 openocd 后端。
• 支持的目标芯片和用于硬件操作的SWD/JTAG布线。
• 夜锈加 rust-src 用于捆绑STM32演示固件检查。

构建

git clone https://github.com/adancurusul/embedded-debugger-mcp.git
cd embedded-debugger-mcp
cargo build --release

二进制是 target/release/embedded-debugger-mcp.

MCP模式

显式运行服务器：

embedded-debugger-mcp serve

为了兼容性，运行 embedded-debugger-mcp 也没有子命令 通过stdio为MCP提供服务。

MCP客户端配置示例：

{
  "mcpServers": {
    "embedded-debugger": {
      "command": "/path/to/embedded-debugger-mcp/target/release/embedded-debugger-mcp",
      "args": ["serve"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

在Windows上，使用 .exe 路径和Windows路径分隔符。

CLI和技能模式

CLI模式对于安装检查、自动化和代理工作流非常有用 MCP客户端已配置。

embedded-debugger-mcp doctor
embedded-debugger-mcp doctor --json
embedded-debugger-mcp probes list
embedded-debugger-mcp probes list --json
embedded-debugger-mcp config generate
embedded-debugger-mcp config validate
embedded-debugger-mcp config show
embedded-debugger-mcp skill print-prompt
embedded-debugger-mcp skill install --target both

捆绑技能存在于：

skills/embedded-debugger/

它是作为一种简单的Codex技能编写的，也为Claude Code打包了 .claude-plugin/plugin.json该技能从CLI检查开始，并使用MCP 仅当MCP客户端可用时才使用工具。

安装Codex和Claude Code的技能：

embedded-debugger-mcp skill install --target both

使用JSON预览或自动安装：

embedded-debugger-mcp skill install --target both --dry-run --json
embedded-debugger-mcp skill install --target both --force --json

--target 接受 codex, claude，或 both。该命令安装Codex 技能下 ~/.codex/skills/embedded-debugger，克劳德代码技能 ~/.claude/skills/embedded-debugger，以及下面的本地Claude插件dir包 ~/.claude/plugins/local/embedded-debugger-mcp。现有目录不是 除非被替换 --force 已通过。

通过以下提示触发Codex技能：

Use $embedded-debugger to inspect my embedded target setup.

加载已安装的Claude Code插件包：

claude --plugin-dir ~/.claude/plugins/local/embedded-debugger-mcp --print '/embedded-debugger inspect my embedded target setup'

对于仅限技能的环境，同样 skills/embedded-debugger 目录可以 也可以复制到本地技能目录中。

验证技能包：

python3 .github/scripts/validate_skill.py skills/embedded-debugger
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/embedded-debugger
claude plugin validate .
embedded-debugger-mcp skill install --target both --home /tmp/embedded-debugger-skill-home --force --json

第一个命令验证存储库技能元数据，第二个命令验证 标准 SKILL.md 当Codex技能创建者验证器为 第三个验证Claude Code插件清单。

后端

这些工具在两个可互换发动机中的一个上运行，这两个发动机是在 connect:

• backend: "probe-rs" （默认）--本地探测器rs；全闪存和RTT支持。
• backend: "openocd" （实验）--连接到已运行的 openocd 通过其GDB端口(openocd_address，默认值 127.0.0.1:3333)使用GDB 远程串行协议。用于目标的探头不包括（例如。 Xtensa ESP32通过openocd-ESP32）。内存访问和暂停/运行/步进/重置 在真实的ESP32-S3上验证；flash和RTT只是探测器。注册读取 目前使用ARM gdb寄存器号，因此Xtensa上的PC/SP是错误的（已知 限制）； diagnose_fault 和 unwind_exception 是Cortex-M特有的。 使用以下命令启动openocd gdb_memory_map disable，否则它会探测到闪光 GDB连接失败并拒绝连接——例如。 openocd -f board/esp32s3-builtin.cfg -c "gdb_memory_map disable".

人工智能为两者看到了相同的工具集；仅 connect 争论变了。

MCP工具集

探头管理：

目标控制：

内存和断点：

诊断：

闪光灯：

RTT：

碰撞诊断

崩溃后，停止核心，让模型对证据进行推理：

1. halt那么 diagnose_fault --读取Cortex-M SCB故障寄存器 （CFSR/HFSR/MMFAR/BFAR/SHCSR/CPUID）加上PC/SP/LR在一个呼叫中，并返回 具有设定故障位的紧凑结构包。它报告了证据；它 没有断言根本原因。
2. unwind_exception 与 elf_path --将崩溃映射到源代码行。在 探测器后端这是一个完整的DWARF回溯（函数+ file:line 每 帧）；在OpenCD后端，它读取异常堆栈帧并映射 故障PC/呼叫者LR。

两者都是Cortex-M特定的（SCB寄存器、ARM异常帧），不适用 Xtensa（ESP32）目标。固件必须使用调试信息构建 (.debug_line)用于源映射。

安全须知

• 除非满足以下条件，否则禁用闪存擦除 security.allow_flash_erase 或 flash.allow_erase 已启用。
• 内存写入由以下方式控制 security.allow_memory_write.
• 可选的内存范围限制使用 配置。
• 固件文件路径已规范化，并进行了检查 security.allowed_file_paths 配置后，根据大小进行检查 限制。
• 拒绝任意地址的扇区擦除，直到目标特定扇区 实现了映射。
• flash_verify 支持原始数据比较。使用原始BIN文件或十六进制数据 基于文件的验证。

生成启动配置：

embedded-debugger-mcp config generate > embedded-debugger.toml
embedded-debugger-mcp --config embedded-debugger.toml config validate

STM32演示

STM32 RTT演示已发布 examples/STM32_demo.

cd examples/STM32_demo
CARGO_TARGET_DIR=/tmp/embedded-debugger-mcp-stm32-target cargo +nightly check --locked

演示固件显示了多通道RTT通信，旨在作为 硬件验证辅助工具。看 示例/STM32_demo/README.md.

放行检查

在剪切版本之前运行以下命令：

cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-targets --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --locked --all-features --no-deps
cargo package --locked
python3 .github/scripts/validate_skill.py skills/embedded-debugger
claude plugin validate .
embedded-debugger-mcp skill install --target both --home /tmp/embedded-debugger-skill-home --force --json
(cd examples/STM32_demo && CARGO_TARGET_DIR=/tmp/embedded-debugger-mcp-stm32-target cargo +nightly check --locked)

致谢

• 探头rs 用于嵌入式调试探针支持。
• rmcp 对于Rust MCP SDK。
• 东京 对于异步运行时。

许可证

该项目根据MIT许可证获得许可。看 许可证.