内容
# 嵌入式MCP
> 让AI助手读取、命令和调试你的微控制器 — 通过普通的串行端口。
[](https://github.com/atillab1/embedded-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
**embedded-mcp** 是一个 [模型上下文协议](https://modelcontextprotocol.io/) 服务器。
它为支持MCP的客户端（Claude Desktop，Claude Code等）提供了一组小工具，以便通过串行端口与真正的板子进行通信。
当你调试固件时，你的AI配对现在可以 **看到板子打印的内容** 并 **向其发送命令** — 而不是你手动复制粘贴串行监视器。
```
┌─────────────┐ MCP (stdio) ┌───────────────┐ UART / USB-串行 ┌──────────────┐
│ AI 客户端 │ ◄────────────────► │ embedded-mcp │ ◄────────────────────► │ 你的板子 │
│ (Claude) │ │ (此仓库) │ (pyserial) │ STM32 / ... │
└─────────────┘ └───────────────┘ └──────────────┘
```
## 为什么
嵌入式调试是一个循环：*烧录 → 查看串行监视器 → 发送命令 → 读取转储 → 根据数据手册解码寄存器*。这个循环正是AI擅长的 — **如果你给它硬件的眼睛和手**。这个服务器就是那些眼睛和手。
## 工具
| 工具 | 功能 |
| --- | --- |
| `list_serial_ports` | 发现可用的端口（COM5，/dev/ttyACM0，…）。 |
| `read_serial` | 被动读取固件打印的内容 *N* 秒。 |
| `send_command` | 向设备的UART shell发送一行命令并捕获回复。 |
| `decode_register` | 将原始值（例如 `0x4002`）转换为命名位字段。 |
| `decode_register_svd` | 直接从供应商CMSIS-SVD文件中按名称解码寄存器。 |
| `list_flashers` | 报告已安装的烧录器（st-flash / probe-rs / openocd）。 |
| `flash_firmware` | 将固件映像烧录到板子（默认为 dry-run）。 |
## 安装
```bash
git clone https://github.com/atillab1/embedded-mcp.git
cd embedded-mcp
pip install -e .
```
## 与Claude Desktop一起使用
将以下内容添加到你的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"embedded-mcp": {
"command": "embedded-mcp"
}
}
}
```
重启Claude Desktop。然后直接询问：
> *"列出我的串行端口，然后读取COM5在115200下打印的内容，持续5秒。"*
> *"向COM5上的板子发送 `status` 命令，并告诉我它回复了什么。"*
> *"寄存器RCC->CR读取回0x4002。解码它：位0是HSION，位17是HSEON，位25是PLLRDY。"*
## 示例：解码寄存器
`decode_register(value=0x4002, fields=[{"name":"HSION","bit":0},{"name":"HSEON","bit":17}], width=32)`
```json
{
"value": 16386,
"hex": "0x00004002",
"binary": "00000000000000000100000000000010",
"fields": [
{ "name": "HSION", "bits": "[0]", "value": 0 },
{ "name": "HSEON", "bits": "[17]", "value": 0 }
]
}
```
## 现在试试看（无需硬件）
寄存器解码器完全离线工作 — 给它们快速试试：
```bash
python examples/demo.py
```
## 烧录
`flash_firmware` 默认是 dry-run — 它返回它将运行的确切命令，以便您可以审查它，然后再由它实际烧录：
> *"dry-run 将 build/app.bin 烧录到我的STM32，使用 st-flash。"*
将 `dry_run=False` 设为实际烧录。支持：`st-flash` (.bin)，`probe-rs` (.elf，需要 `chip`)，`openocd` (.elf，需要 `openocd_target`)。
## 安全注意事项
- 工具仅在调用期间打开端口，然后关闭它 — 它们不持有端口，因此您的普通IDE串行监视器可以与其共享（一次一个）。
- 读取持续时间限制为30秒，因此调用永远不会挂起客户端。
- `flash_firmware` 是破坏性的；它默认为 dry-run，并且除非您明确传递 `dry_run=False`，否则永远不会烧录。
- 这会与端口上的板子通信。不要指向您不拥有的东西。
## 路线图
- [x] 单元测试 + GitHub Actions CI
- [x] 从SVD文件加载寄存器映射 (`decode_register_svd`)
- [x] 烧录钩子 (`flash_firmware` via st-flash / probe-rs / openocd)
- [ ] 流媒体/连续监视器（通知代替固定窗口）
- [ ] 从连接的芯片ID自动发现SVD
欢迎贡献 — 打开问题或PR。
## 开发
```bash
pip install -e .
pip install pytest
pytest -q
```
## 许可证
MIT © Atilla — 见 [LICENSE](LICENSE)。
