My Hardware Assistant · 嵌入式硬件知识库 MCP 服务

基于 FastMCP 构建的本地 MCP 服务，把开发板的 BSP（引脚 / 外设 / 编译约束）与工程示例结构化为 AI 可调用的知识库，让 Claude Code、Cursor 等 AI 编码助手在写硬件代码前先"读"到正确的硬件约束，避免幻觉引脚、错误外设配置。

为什么需要它

用 AI 写嵌入式代码最大的痛点：AI 不知道你这块板子的引脚定义与硬件约束，经常编造 GPIO 编号、用错 I2C 总线、引用不存在的外设。本服务把每块开发板的完整 BSP 写成结构化数据，通过 MCP 协议暴露给 AI IDE，AI 在生成代码前主动调用 get_board / get_sensor 拉取真实约束，生成的代码与硬件设计保持一致。

特性

• Tool + Resource 双协议：既可作为工具被 AI 主动调用（get_board 等），也可作为 MCP Resource 被 Client 端按 URI 读取（hardware://boards/{name}）
• 结构化 BSP：每块板卡含芯片型号、Flash/PSRAM 容量、主频、完整 pin_map、I2C 总线、编译宏等
• 配套开发文档：每块板卡另有一份 Markdown 开发说明（外设分模块、引脚功能、使用规则）
• 工程示例：每块板卡配套官方示例目录规范与初始化模板，新建工程时优先读取
• 零外部依赖：仅依赖 fastmcp，BSP 数据为纯 JSON / Markdown，易扩展

已支持开发板（7 款）

标识	板卡
esp32s3_touch_lcd_185b	ESP32-S3-Touch-LCD-1.85B（1.85" 圆屏）
esp32_s31_korvo_1	ESP32-S3 Korvo-1
lcszp_esp32_s3_szp	立创实战派 ESP32-S3-SZP
xiao_esp32s3_sense	XIAO ESP32-S3 Sense
lushan_pi_k230	庐山 K230（视觉 SoC）
tspi_rk3566	TSPI RK3566（ARM Cortex-A55）
tspi_rk3576	TSPI RK3576

目录结构

hardware-mcp/
├── server.py              # FastMCP 服务入口（6 个 Tool + 3 个 Resource）
├── pyproject.toml         # FastMCP 配置
├── fastmcp.json
└── docs/
    ├── boards/            # 结构化 BSP（JSON）：pin_map / i2c_buses / 编译宏
    │   ├── esp32s3_touch_lcd_185b.json
    │   └── ...
    ├── sensors/           # 每块板卡的完整开发说明（Markdown）
    │   ├── esp32s3_touch_lcd_185b_board.md
    │   └── ...
    └── examples/          # 每块板卡的工程示例与初始化模板（Markdown）
        ├── esp32s3_touch_lcd_185b_samples.md
        └── ...

暴露的能力

Tools（AI 主动调用）

工具	作用
list_boards()	列出所有可用开发板标识与名称
list_sensors()	列出所有可用硬件开发文档
list_examples()	列出所有可用工程示例文档
get_board(board_name)	读取开发板完整 BSP：引脚定义、I2C 设备、编译宏、硬件约束
get_sensor(sensor_name)	读取硬件 / 开发板配套完整开发说明、外设使用规则
get_example(example_name)	读取官方完整工程示例、目录规范、初始化模板
hello_hardware()	测试服务运行状态

Resources（按 URI 读取）

• hardware://boards/{board_name}
• hardware://sensors/{sensor_name}
• hardware://examples/{example_name}

安装与配置

# 1. 安装依赖
pip install fastmcp

# 2. （可选）安装为本地包
cd hardware-mcp && pip install -e .

接入 Claude Code（~/.workbuddy/mcp.json 或对应 IDE 的 MCP 配置）：

{
  "mcpServers": {
    "hardware-assistant": {
      "command": "python",
      "args": ["/绝对路径/hardware-mcp/server.py"]
    }
  }
}

接入 Cursor：在 Settings → MCP 中添加同样的 server 配置。

使用示例

接入后，在 AI 对话中直接说：

帮我基于 ESP32-S3-Touch-LCD-1.85B 写一个 LVGL 时钟 Demo，用到屏幕和触控。

AI 会自动调用 list_boards → get_board("esp32s3_touch_lcd_185b") 拉取真实引脚（LCD_CS=21、TOUCH_SDA=11 等），再调用 get_sensor 读取外设使用规则，然后生成符合硬件约束的代码。

扩展自己的板卡

1. 在 docs/boards/ 新增 <your_board>.json，参考现有 JSON 填写 board_name / chip / flash_size / psram_size / core_freq / pin_map / i2c_buses 等字段
2. 在 docs/sensors/ 新增 <your_board>_board.md，写外设分模块说明与使用规则
3. 在 docs/examples/ 新增 <your_board>_samples.md，写工程目录规范与初始化模板
4. 重启服务，AI 即可识别新板卡

技术栈

Python · FastMCP · MCP 协议 · JSON / Markdown 结构化知识库

---

本服务为个人项目，用于验证 AI 辅助嵌入式开发工作流。