内容
# ESP32 工具包 MCP 服务器
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
一个 MCP（模型上下文协议）服务器，为 AI 编程助手提供深入的 ESP32 知识。包含 5 种工具，涵盖引脚映射、框架检测、依赖分析、代码生成和错误解析。
## 功能
| 工具 | 描述 | 用例 |
|------|-------------|----------|
| `esp32_pin_map` | ESP32/ESP32-S3/ESP32-C3 的 GPIO 引脚映射 | 查找引脚功能、约束、ADC 通道 |
| `esp32_detect_framework` | 检测 ESP32 项目的构建框架 | 自动检测 Arduino vs ESP-IDF vs PlatformIO |
| `esp32_analyze_deps` | 分析依赖并检测冲突 | 查看 PlatformIO 库依赖 |
| `esp32_generate_code` | 生成样板代码模板 | WiFi STA/AP、MQTT、BLE、I2C、SPI、OTA、Web 服务器 |
| `esp32_parse_error` | 解析常见错误并提供可行的修复建议 | 修复编译、链接器、堆栈溢出问题 |
## 支持的芯片
- **ESP32 WROOM-32** — 双核 Xtensa LX6，WiFi + 经典蓝牙
- **ESP32-S3** — 双核 Xtensa LX7，USB OTG，LCD 接口支持
- **ESP32-C3** — 单核 RISC-V，紧凑型外壳
## 快速开始
```bash
# 安装依赖
npm install
# 启动服务器
npm start
```
## 配置
将以下内容添加到您的 MCP 客户端配置中：
```json
{
"mcpServers": {
"esp32-toolkit": {
"command": "node",
"args": ["path/to/esp32-mcp-server/index.js"]
}
}
}
```
支持的客户端：Codex CLI、Cursor IDE、VS Code MCP 扩展、任何 MCP 兼容工具。
## 工具详情
### esp32_pin_map
返回详细的 GPIO 信息，包括功能、ADC 通道、启动约束和仅输入警告。
```
输入：{ model: "esp32", pin: 2 }
输出：GPIO2 引脚映射，带有 I2C_STD 功能、ADC2_CH2 和启动约束信息
```
支持别名：`esp32wroom32`、`esp32s3devkitc`、`esp32c3` 等。
### esp32_detect_framework
分析项目目录以确定构建系统（PlatformIO/CMake）和框架（Arduino/ESP-IDF）。
```
输入：{ projectPath: "/path/to/esp32-project" }
```
检查：`platformio.ini`、`CMakeLists.txt`、`sdkconfig` 和 `components/` 目录。
### esp32_analyze_deps
从 PlatformIO 项目的 `platformio.ini` 中提取所有库依赖。
```
输入：{ projectPath: "/path/to/project" }
```
返回依赖列表和流行的库推荐。
### esp32_generate_code
为常见的 ESP32 任务生成可投入生产的样板代码。
可用模板：
- `wifi_sta` — WiFi 站点连接，自动重新连接
- `wifi_ap` — 接入点模式
- `mqtt_client` — MQTT 订阅者/发布者
- `ble_scanner` — BLE 设备发现
- `i2c_sensor` — I2C 总线扫描器
- `web_server` — HTTP 服务器
- `ota_update` — WiFi OTA 固件更新
- `spi_display` — ST7735 SPI 显示
```
输入：{ framework: "arduino", template: "wifi_sta", config: { ssid: "MyWiFi", password: "secret" } }
```
### esp32_parse_error
分析编译器/链接器错误消息并返回类别和修复建议。
```
输入：{ errorMessage: "stack overflow detected in task xyz" }
```
## 架构
```
esp32-mcp-server/
├── index.js # 主 MCP 服务器（240 行）
├── data/
│ ├── pins.json # GPIO 引脚定义（所有 3 个芯片）
│ ├── errors.json # 错误模式检测规则
│ └── templates.json # 代码生成模板
├── package.json # NPM 清单
├── .gitignore # node_modules, .env
├── LICENSE # MIT 许可证
└── README.md # 本文件
```
整个服务器都是一个单一的入口点（`index.js`）。所有静态数据都存放在 JSON 文件中，以便于维护和扩展。
## 安全
- 完全在本地运行，无外部网络请求
- 引脚数据和模板从本地文件加载
- 框架检测仅读取指定的项目目录
- 无凭证存储或外部 API 调用
## 贡献
欢迎贡献！请：
1. 分叉仓库
2. 创建功能分支
3. 提交拉取请求
对于新芯片支持，请将引脚数据添加到 `data/pins.json`，使用现有的格式。对于新代码模板，请扩展 `data/templates.json` 和模板替换助手。
## 许可证
MIT 许可证 - 参见 [LICENSE](LICENSE) 了解详情。
