sbl调试器
用于ARM Cortex-M目标的嵌入式调试MCP服务器。让AI编码助手直接控制GDB和OpenCD——连接到硬件、设置断点、遍历代码、检查寄存器和内存，所有这些都在对话中完成。
安装
创建虚拟环境并安装软件包：
python3 -m venv .venv
source .venv/bin/activate
# Install
pip install -e .
# Or with test dependencies
pip install -e ".[dev]"系统要求
gdb-multiarch（支持ARM目标的GDB）openocd（0.12.0+推荐）- SWD调试探针（ST-LINK、CMIS-DAP等）
在Debian、Ubuntu和Raspberry Pi操作系统上：
sudo apt install gdb-multiarch openocdMCP配置
在MCP客户端的配置中注册服务器。对于大多数客户，添加 .mcp.json 在项目根目录中：
{
"mcpServers": {
"sbl-debugger": {
"type": "stdio",
"command": "/absolute/path/to/.venv/bin/python",
"args": ["-m", "sbl_debugger"]
}
}
}重要提示： 在虚拟环境中使用Python二进制文件的绝对路径。 例如： /home/you/sbl-debugger-mcp/.venv/bin/python重新启动MCP客户端，工具立即可用。
工具
会话管理
| 工具 | 说明 |
|---|---|
debug_attach | 连接到目标——启动OpenCD+GDB，通过SWD连接 |
debug_detach | 彻底关闭调试会话 |
debug_sessions | 列出所有活动的调试会话 |
debug_status | 获取当前目标状态（暂停/运行、停止原因、当前帧） |
debug_targets | 列出可用的预定义目标配置文件 |
执行控制
| 工具 | 说明 |
|---|---|
halt | 停止运行目标 |
continue_execution | 恢复执行 |
wait_for_halt | 阻塞直到目标停止（断点命中等） |
step | 步进源代码线（进入函数） |
step_over | 步骤源代码行（通过函数调用） |
step_out | 退出当前功能 |
step_instruction | 踏步机说明书 |
run_to | 运行到某个位置（设置临时断点+继续） |
reset | 重置目标（重置后停止或运行） |
检查
| 工具 | 说明 |
|---|---|
read_registers | 读取CPU寄存器（所有核心寄存器或特定子集） |
write_register | 写入CPU寄存器 |
read_memory | 读取内存（十六进制、u8、u16、u32格式） |
write_memory | 写入内存 |
backtrace | 获取调用堆栈 |
read_locals | 列出当前帧中的局部变量 |
print_expr | 在目标上下文中计算C/C++表达式 |
disassemble | 在某个地址或当前电脑上拆卸 |
断点
| 工具 | 说明 |
|---|---|
breakpoint_set | 按函数名、文件行或地址设置断点 |
breakpoint_delete | 删除断点 |
breakpoint_list | 列出所有断点和观察点 |
watchpoint_set | 设置硬件数据观察点（写/读/访问） |
外围寄存器（SVD）
| 工具 | 说明 |
|---|---|
list_peripherals | 列出带基址和寄存器计数的SVD外围设备 |
list_registers | 显示外围设备的所有寄存器和位字段定义 |
read_peripheral_register | 从硬件读取寄存器并解码所有位字段 |
read_peripheral | 读取具有解码位字段的外围设备的所有寄存器 |
需要cecrops（可选依赖关系）和SBL_HW_PATH指向sbl硬件的环境变量。 安装方式：pip install -e ".[svd]"
快照和高级
| 工具 | 说明 |
|---|---|
debug_snapshot | 一次调用中的完整目标状态（帧、寄存器、回溯、本地、源） |
load | 将固件闪存到目标 |
monitor | 发送原始OpenCD监视器命令 |
目标配置文件
预定义的配置文件消除了记住OpenCD配置的需要：
| 配置文件 | 硬件 | 调试探测器 |
|---|---|---|
daisy | 电史密斯Daisy Seed（STM32H750，Cortex-M7） | ST-LINK |
pico | Raspberry Pi Pico（RP2040，Cortex-M0+） | CMIS-DAP调试探针 |
pico2 | Raspberry Pi Pico 2（RP2350，Cortex-M33） | CMIS-DAP调试探针 |
custom | 任何目标 | 提供 interface 和 target_cfg 明确 |
自定义目标适用于任何支持OpenCD的硬件：
debug_attach(target="custom", interface="jlink.cfg", target_cfg="stm32f4x.cfg", elf="firmware.elf")建筑
sbl_debugger/
├── server.py # FastMCP server, tool wiring
├── targets.py # Target profiles (daisy, pico, pico2)
├── session/
│ ├── manager.py # Thread-safe session registry
│ └── session.py # DebugSession (owns OpenOCD + GDB)
├── process/
│ ├── openocd.py # OpenOCD subprocess lifecycle
│ └── ports.py # GDB server port allocation
├── bridge/
│ ├── mi.py # GDB/MI wrapper (pygdbmi + lock)
│ └── types.py # FrameInfo, StopEvent, MiResult
├── svd/
│ ├── peripheral_db.py # SVD lookup/decode (wraps cecrops Device)
│ └── loader.py # SBL_HW_PATH resolution, cecrops import guard
└── tools/
├── session.py # attach, detach, sessions, status, targets
├── execution.py # halt, continue, step, reset
├── inspection.py # registers, memory, backtrace, locals
├── breakpoints.py # breakpoint/watchpoint management
├── snapshot.py # combined state dump
├── advanced.py # load (flash), monitor (raw OpenOCD)
└── peripheral.py # SVD peripheral register decoding关键设计决策：
- 管理子流程 --OpenCD和GDB由服务器启动、监控和清理。一
debug_attach电话什么都做。 - GDB/MI通过pygdbmi --结构化命令/响应接口，GDB CLI输出无字符串解析
- 单命令锁 --一次一个MI命令可防止响应交织
- 显式轮询 —
wait_for_halt和debug_status按需检查目标状态，匹配MCP的请求/响应模型 - 错误字典，而非异常 --工具归还
{"error": "..."}而不是使服务器崩溃
运行测试
pytest # 275 tests (all mocked, no hardware needed)
pytest -v # verbose
pytest tests/test_tools.py # just tool tests依赖项
mcp--官方Python MCP SDK（FastMCP）pygdbmi--GDB机器接口协议cecrops--SVD寄存器定义（可选，用于外围工具）- Python>=3.11