# 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`

```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`

```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`

## 运行测试

```bash
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](LICENSE)