mcp-stm32cubeide-server

An MCP (Model Context Protocol) server that lets AI coding agents (Claude Code / opencode / Claude Desktop) drive the full STM32 development loop — wire up → request → AI writes code → build → flash → debug → diagnose faults — end to end.

让 AI 编程助手（Claude Code / opencode / Claude Desktop 等）直接操控 STM32 开发全流程：接线 → 提需求 → AI 自己改代码 / 编译 / 烧录 / 验证。

中文文档为主。所有工具返回结构化 JSON，失败时携带明确错误信息，便于 AI 精确处理。

---

功能一览（17 个工具）

类别	工具	说明
环境	discover_tools	扫描 CubeIDE / CubeMX / CubeProgrammer / GDB / OpenOCD 安装路径，排查"工具未找到"
工程	list_projects	扫描目录自动识别 STM32 工程（AI 无需手动填路径）
工程	get_project_info	读取 MCU 型号、构建配置、源文件数
代码生成	generate_code	从 .ioc 调用 CubeMX CLI 生成初始化代码
构建	build_project / clean_project	CubeIDE headless 编译（Clean Build / 增量 / 仅清理）
烧录	flash_firmware	CubeProgrammer 烧录 .bin / .hex
烧录	debug_flash	通过 GDB 精确烧录 .elf 到目标
Flash 操作	read_flash / erase_flash	读取芯片 Flash 验证 / 备份、整片擦除
串口	list_serial_ports / serial_monitor	枚举 COM 口；采集 UART 日志验证固件行为
调试	debug_run	烧录运行，自动捕获 HardFault / BusFault / UsageFault / MemManage 并解析故障寄存器原因
调试	debug_status / debug_halt / debug_resume	OpenOCD 状态查询、暂停 / 恢复目标
OLED 字库	oled_add_zh_font	调用波特律动（led.baud-dance.com）官方取模接口给工程 font.c 追加汉字点阵，自动去重并更新 Font.len；接口不可用时回退本地 PIL 渲染

oled_add_zh_font 与波特律动取模助手/串口助手的字模完全一致（文泉驿点阵字，16x16 列行式阳码），无需再打开浏览器取模，取到的字模可直接用 OLED_PrintString 显示。

环境要求

• Python 3.10+，pip install -r requirements.txt（mcp>=1.0.0、pyserial>=3.5）
• 至少安装一个 ST 工具（CubeIDE / CubeMX / CubeProgrammer 任意组合）

工具链自动发现

按顺序查找：环境变量 → PATH → Windows 注册表 → 常见安装位置。大部分情况无需配置。

工具	环境变量
STM32CubeIDE	CUBEIDE_PATH
STM32CubeMX	CUBEMX_PATH
STM32CubeProgrammer	CUBEPROG_PATH
arm-none-eabi-gdb	ARM_GDB_PATH
OpenOCD	OPENOCD_PATH
OpenOCD 脚本目录	OPENOCD_SCRIPTS_PATH

安装 / 注册

opencode — opencode.json

{
  "mcp": {
    "stm32cubeide": {
      "type": "local",
      "command": ["python", "D:\\path\\to\\mcp-stm32cubeide-server\\server.py"],
      "enabled": true
    }
  }
}

Claude Code / Claude Desktop — .mcp.json / claude_desktop_config.json

{
  "mcpServers": {
    "stm32cubeide": {
      "command": "python",
      "args": ["D:\\path\\to\\mcp-stm32cubeide-server\\server.py"]
    }
  }
}

路径请替换为你克隆仓库后的实际路径。建议 command 使用 Python 绝对路径（避免 PATH 混入其他版本）。

典型自主编程流程

1. list_projects 找到工程
2. AI 直接修改源码 / 修改 .ioc 后 generate_code
3. build_project 编译（出错则读错误信息修到通过）
4. flash_firmware 或 debug_flash 烧录
5. serial_monitor 采集串口日志验证行为；崩溃则 debug_run 拿到故障寄存器诊断
6. 需要显示新汉字时，oled_add_zh_font 自动取模并集成进 font.c

运行测试

python -m unittest test_server -v

项目结构

server.py            # MCP 注册与工具路由（入口）
tools.py             # 各工具的 async 实现（含命令构造）
discovery.py         # 工具链路径发现（env / PATH / 注册表 / 浅层扫描 + 缓存）
process.py           # 子进程执行（超时杀进程树）+ OpenOCD 会话管理
mcu.py               # MCU 型号识别 + 故障寄存器诊断解析
project.py           # .ioc / .elf 查找、工程信息、工程扫描
serial_monitor.py    # 串口采集（pyserial，后台线程）
fontgen.py           # 汉字字模生成（波特律动官方取模接口 + 本地 PIL 兜底）
test_server.py       # 单元测试 / 冒烟测试

实现要点

• 全 async：所有工具为 async def，无嵌套 asyncio.run()，支持并发调用
• 进程树清理：Windows 超时用 taskkill /T /F，不残留 CubeIDE / OpenOCD
• OpenOCD 就绪探测：TCP 轮询端口而非固定 sleep；端口冲突自动避让
• 编码兼容：工具输出按 UTF-8 / GBK 自动解码，中文路径可用
• 安全：所有命令用参数列表传入（无 shell 注入面）；工具发现仅查已知位置
• 日志走 stderr：stdout 是 MCP 传输通道，不得污染

许可证

MIT