🚀 ESP32 WebSerial MCP Bridge

通过Claude Code进行AI驱动的ESP32 MicroPython开发

这是一个完整的模型上下文协议（MCP）桥接器，它使Claude Code能够通过浏览器中的WebSerial API在ESP32设备上开发、上传和管理MicroPython程序。

🏗️ 架构

Claude Code ──► MCP客户端 ──► WebSocket ──► 浏览器 ──► WebSerial API ──► ESP32
                     ▲                           │
                     └───────── 响应 ────────┘

✨ 特性

🔧 MCP集成

• 完整的MCP v1.0.0支持 - 完整的JSON-RPC 2.0实现
• 5个核心工具 - 上传、执行、读取、重置和列出文件
• 实时通信 - 基于WebSocket的双向数据流
• 错误处理 - 全面的错误传播和恢复

🌐 现代网络界面

• 类似VS Code的UI - 熟悉的开发环境
• WebSerial API - 直接从浏览器到ESP32的通信
• 实时控制台 - 实时REPL输出和交互
• 代码编辑器 - 语法高亮和项目模板

🧪 测试与开发

• 模拟ESP32 - 无需硬件的开发和测试
• 单元测试 - 使用pytest达到95%以上的测试覆盖率
• 集成测试 - 端到端工作流程验证
• 性能测试 - 并发请求处理

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 启动桥接服务器

python esp32_bridge_server.py

服务器运行在 http://localhost:3000

3. 打开浏览器界面

导航至 http://localhost:3000 在Chrome或Edge中（需要WebSerial）

4. 连接ESP32

1. 在网页界面点击“连接ESP32”
2. 从列表中选择你的ESP32设备
3. 选择波特率（默认：115200）

5. 配置Claude Code

添加到你的Claude Code MCP配置中：

{
  "mcpServers": {
    "esp32-bridge": {
      "command": "python",
      "args": ["/workspace/mcp_client.py", "ws://localhost:3000"],
      "env": {}
    }
  }
}

📋 MCP工具

🔧 可用工具

工具	描述	参数
upload_code	将MicroPython代码上传到ESP32	code (字符串), filename (可选)
execute_command	在REPL中执行命令	command (字符串)
read_console	获取最近的控制台输出	lines (可选，默认值：110)
reset_device	软重启ESP32	无
list_files	列出文件系统文件	无

📝 在Claude Code中的示例使用

将这段LED闪烁代码上传到我的ESP32：

import time
from machine import Pin

led = Pin(2, Pin.OUT)

while True:
    led.on()
    time.sleep(0.5)
    led.off()
    time.sleep(0.5)

Claude Code将自动：

1. 将代码作为main.py上传
2. 验证上传
3. 展示如何运行它
4. 监控输出

🧪 测试

单元测试

# 运行所有测试
pytest tests/ -v

# 运行特定测试文件
pytest tests/test_mcp.py -v

# 使用覆盖率运行
pytest tests/ --cov=mcp_handler --cov-report=html

集成测试

# 启动桥接服务器（终端1）
python esp32_bridge_server.py

# 启动模拟ESP32（终端2）
python tests/mock_esp32.py

# 运行集成测试（终端3）
pytest tests/test_integration.py -v

模拟开发

# 为开发启动模拟ESP32
python tests/mock_esp32.py --port 3001 --debug

# 使用curl测试
curl http://localhost:3001/health

🏗️ 项目结构

esp32-webserial-bridge/
├── esp32_bridge_server.py      # 主Flask WebSocket服务器
├── mcp_handler.py              # MCP协议实现
├── mcp_client.py               # Claude Code入口点
├── claude_code_config.json     # MCP服务器配置
├── requirements.txt            # Python依赖
├── templates/
│   └── esp32_bridge.html       # 网络界面
├── tests/
│   ├── test_mcp.py            # 单元测试
│   ├── test_integration.py     # 集成测试
│   └── mock_esp32.py          # 模拟ESP32服务器
└── README.md                   # 此文件

⚙️ 配置

环境变量

• FLASK_DEBUG - 启用Flask调试模式
• WEBSOCKET_URL - WebSocket服务器URL（默认：ws://localhost:3000）
• MCP_TIMEOUT - MCP请求超时时间（秒，默认：30）

浏览器要求

• 需要Chrome 89+ 或 Edge 89+ 以支持WebSerial API
• 生产环境中需要HTTPS （使用ngrok进行测试）

🔧 开发

添加新的MCP工具

1. 在mcp_handler.py的_handle_tools_list()中添加工具定义
2. 在_handle_tools_call()中实现处理器
3. 添加WebSocket通信逻辑
4. 更新测试和文档

扩展网络界面

• 编辑templates/esp32_bridge.html
• 使用CSS中的VS Code样式组件
• 在JavaScript中添加WebSocket事件处理器

模拟ESP32功能

• 模拟MicroPython REPL
• 文件系统操作
• 带有历史记录的控制台输出
• 程序执行模拟

🐛 故障排除

MCP配置

🔧 检查当前MCP配置

# 列出所有已配置的MCP服务器
claude mcp list

# 获取关于esp32-bridge服务器的详细信息
claude mcp get esp32-bridge

🔧 更新MCP服务器端口 如果您的ESP32桥接器配置了错误的端口：

# 移除现有配置
claude mcp remove esp32-bridge -s local

# 使用正确的端口（3000）添加
claude mcp add esp32-bridge /workspace/venv/bin/python /workspace/mcp_client.py http://localhost:3000

🔧 MCP服务器状态

• ✅ 已连接：服务器正在运行且可访问
• ✗ 无法连接：检查桥接服务器是否在正确端口上运行
• MCP配置位置：~/.claude.json（本地项目范围）

常见问题

🔴 WebSerial API不支持

• 使用Chrome 89+ 或 Edge 89+
• 生产环境中确保HTTPS
• 检查浏览器兼容性

🔴 ESP32未被检测到

• 安装ESP32 USB驱动（CP2102, CH340, FTDI）
• 检查设备管理器/系统报告
• 尝试不同的USB端口

🔴 WebSocket连接失败

• 验证桥接服务器是否在3000端口上运行
• 检查防火墙设置
• 确保没有端口冲突

🔴 MCP客户端无响应

• 检查配置中的WebSocket URL
• 验证Python依赖项已安装
• 检查Claude Code日志

调试模式

# 启用调试日志
python mcp_client.py --debug ws://localhost:3000

# 检查服务器健康状况
curl http://localhost:3000/health

# 查看WebSocket连接
curl http://localhost:3000/api/connections

🤝 贡献

1. 分叉仓库
2. 创建功能分支：git checkout -b feature/awesome-feature
3. 为新功能添加测试
4. 运行测试套件：pytest tests/ -v
5. 提交拉取请求

代码风格

• Python：遵循PEP 8，使用类型提示
• JavaScript：ES6+，一致的格式化
• 测试：高覆盖率，清晰描述

📜 许可证

MIT许可证

🙏 致谢

• Anthropic - Claude Code和MCP协议
• Espressif - ESP32和MicroPython支持
• Web Serial API - 浏览器到设备的通信
• Flask-SocketIO - 实时WebSocket通信

---

为ESP32和AI开发社区制作 ❤️