内容
# Papilio 加载器 MCP 服务器
用于在网络上加载 FPGA 位文件和 ESP32 固件的 MCP（模型上下文协议）服务器。该服务器在 Windows 上运行，直接访问 USB/串行端口，同时允许远程客户端（例如 WSL 或 Linux 机器）通过网络编程设备。
## 🎉 新功能：桌面应用程序现已可用！
Papilio 加载器现已作为**桌面应用程序**提供，支持系统托盘集成！适用于希望使用简单、易于使用的界面的终端用户。
**[👉 下载桌面应用程序安装程序](https://github.com/Papilio-Labs/papilio-loader-mcp/releases)**
参阅 [DESKTOP_APP.md](documentation/DESKTOP_APP.md) 获取安装和使用说明。
## 功能
- **桌面应用程序**（新！）：具有一键安装程序的系统托盘应用程序，适用于 Windows
- **OTA 更新**（新！）：无需 USB 连接，通过 WiFi/网络闪存设备
- 在本地网络上发现支持 OTA 的设备
- 无线闪存 ESP32 固件和 FPGA 位流
- 支持具有 HTTP OTA 端点（端口 3232）的设备
- **Web 界面**：用于终端用户手动设备闪存的现代化基于浏览器的 UI
- **已保存文件库**：保存常用固件文件，并附带描述，以便轻松重用
- **MCP 服务器**：与 Claude Desktop 和其他 MCP 客户端集成，提供 AI 辅助设备编程
- **REST API**：基于 FastAPI 的 HTTP API，用于远程网络访问
- **双重编程工具**：
- 官方 esptool，用于 ESP32 编程（安全稳定）
- pesptool（GadgetFactory 分叉），仅用于 FPGA 编程
- **Gowin FPGA 支持**：使用 pesptool 通过 .bin 文件闪存 Papilio 板（Gowin FPGA）
- **ESP32 支持**：使用官方 esptool 闪存 ESP32 设备，支持多分区闪存，文件类型为 bin/elf
- **基于网络**：在 Windows 上运行，访问串行端口，从 WSL/Linux 通过网络控制
## 快速入门
### 选项 1：桌面应用程序（最简单）
1. 从 [Releases](https://github.com/Papilio-Labs/papilio-loader-mcp/releases) 下载并安装 `PapilioLoader-Setup-x.x.x.exe`
2. 从开始菜单启动 Papilio 加载器
3. 系统托盘图标出现 - 右键单击并选择“打开 Web 界面”
参阅 [DESKTOP_APP.md](documentation/DESKTOP_APP.md) 获取详细信息。
### 选项 2：Web 界面（Python）
```powershell
# 1. 安装依赖项
uv pip install -e .
# 2. 启动组合服务器（MCP + Web 界面）
.\start.ps1
# 3. 打开浏览器访问 http://localhost:8000/web/login
# 默认凭证：admin/admin
```
参阅 [WEB_INTERFACE_GUIDE.md](documentation/WEB_INTERFACE_GUIDE.md) 获取详细说明。
### 选项 3：仅 MCP 服务器
```powershell
# 安装和配置用于 Claude Desktop 或其他 MCP 客户端
# 参阅 documentation/QUICKSTART.md
```
## 架构
```
┌─────────────────┐ 网络 ┌──────────────────┐
│ Web 浏览器 │ ◄────────────────────► │ Windows 主机 │
│ WSL / Linux │ HTTP/MCP │ 组合服务器 │
│ 构建机器 │ │ │
│ - 手动上传 │ │ - Web UI │
│ - 构建 FPGA │ │ - MCP 服务器 │
│ - 构建 ESP32 │ │ - REST API │
│ - 发送文件 │ │ - pyserial │
│ │ │ - esptool (ESP32)│
│ │ │ - pesptool (FPGA)│
└─────────────────┘ └────────┬─────────┘
│ USB/串行
▼
┌─────────────────┐
│ FPGA / ESP32 │
│ 硬件 │
└─────────────────┘
```
## 安装
### 先决条件
1. **Python 3.12+**：运行服务器所需
2. **esptool**：用于 ESP32 编程的官方 Espressif 工具（通过 pip 自动安装）
3. **pesptool**：用于 FPGA 编程的 GadgetFactory 分叉（作为 git 子模块包含）
- 仅用于将 FPGA 位流编程到外部闪存
- ESP32 使用官方 esptool 以确保安全性和稳定性
### 设置
```bash
# 克隆仓库
git clone https://github.com/papilio-labs/papilio-loader-mcp.git
cd papilio-loader-mcp
# 初始化子模块
git submodule update --init --recursive
# 使用 uv 创建虚拟环境
uv venv
# 安装依赖项
uv pip install -e .
```
## 配置
设置环境变量以配置服务器：
```bash
# 网络设置
PAPILIO_BIND_ADDRESS=0.0.0.0 # 使用 0.0.0.0 进行远程访问，127.0.0.1 仅限本地访问
PAPILIO_PORT=8000
# 安全设置
PAPILIO_API_KEY=your-secret-key-here # 可选 API 身份验证
PAPILIO_CORS_ORIGINS=["http://localhost:3000"] # 以逗号分隔的列表
# 限制
PAPILIO_MAX_UPLOAD_SIZE=52428800 # 50 MB（字节）
PAPILIO_RATE_LIMIT=60 # 每分钟请求数
# 串行设置
PAPILIO_DEFAULT_BAUD_RATE=115200
PAPILIO_SERIAL_TIMEOUT=10
```
## 用法
### 作为独立的 HTTP/SSE 服务器（推荐用于远程访问）
HTTP/SSE 服务器作为独立的 Windows 进程运行，允许 VS Code（或其他 MCP 客户端）通过 HTTP 使用服务器发送事件（SSE）传输连接。
**优点：**
- 无需 VS Code 启动服务器进程
- 服务器独立于 VS Code 运行
- 可以设置为 Windows 服务
- 多个客户端可以连接到同一个服务器实例
- 适用于远程/网络访问场景
**启动服务器：**
```bash
# 使用启动脚本
python start_mcp_server.py
# 或直接运行模块
python -m papilio_loader_mcp.http_server --port 8765
# 或使用自定义主机/端口
python -m papilio_loader_mcp.http_server --host 0.0.0.0 --port 8765
```
服务器将在 `http://127.0.0.1:8000` 启动，SSE 端点位于 `/sse`。
**配置 VS Code：**
更新项目中的 `.vscode/mcp.json`：
```json
{
"servers": {
"papilio-loader": {
"type": "sse",
"url": "http://127.0.0.1:8000/sse"
}
}
}
```
**注意：** VS Code 在顶级使用 `"servers"`（不是 `"mcpServers"`，后者用于 Claude Desktop）。
对于来自其他机器的网络访问，请使用 `"url": "http://YOUR_WINDOWS_IP:8000/sse"`。
**设置为 Windows 服务（可选）：**
要在 Windows 启动时自动运行服务器，可以使用 NSSM（Non-Sucking Service Manager）或任务计划程序：
```powershell
# 从 https://nssm.cc/download 下载 NSSM
nssm install PapilioMCP "C:\Python314\python.exe" "C:\development\papilio-loader-mcp\start_mcp_server.py"
nssm start PapilioMCP
```
### 作为 MCP 服务器（GitHub Copilot 在 VS Code 中 - stdio 模式）
该项目预配置了 GitHub Copilot MCP 集成。安装后：
1. 重新加载 VS Code 窗口（`Ctrl+Shift+P` → “开发者：重新加载窗口”）
2. 打开 GitHub Copilot 聊天
3. MCP 工具将自动可用
参阅 [VSCODE_SETUP.md](VSCODE_SETUP.md) 获取详细设置说明。
### 作为 MCP 服务器（Claude Desktop）
1. 将以下内容添加到您的 Claude Desktop 配置中（`%APPDATA%\Claude\claude_desktop_config.json`）：
```json
{
"mcpServers": {
"papilio-loader": {
"type": "sse",
"url": "http://localhost:8000/sse"
}
}
}
```
**注意：** Claude Desktop 在顶级使用 `"mcpServers"`（不是 `"servers"`，后者用于 VS Code）。
2. 重启 Claude Desktop
3. 使用自然语言交互：
- “列出可用串行端口”
- “将此位文件闪存到 COM3”
- “获取 /dev/ttyUSB0 上的 ESP32 芯片信息”
### 作为 REST API 服务器
```bash
# 启动 API 服务器
python -m papilio_loader_mcp.api
# 或直接使用 uvicorn
uvicorn papilio_loader_mcp.api:api --host 0.0.0.0 --port 8000
```
### API 端点
#### 健康检查
```bash
curl http://localhost:8000/health
```
#### 列出串行端口
```bash
curl -H "X-API-Key: your-key" http://localhost:8000/ports
```
#### 获取设备信息
```bash
curl -X POST http://localhost:8000/device/info \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{"port": "COM3", "device_type": "esp32"}'
```
#### 闪存设备
```bash
curl -X POST http://localhost:8000/flash/upload \
-H "X-API-Key: your-key" \
-F "file=@firmware.bin" \
-F "port=COM3" \
-F "device_type=esp32" \
-F "address=0x1000" \
-F "verify=true"
```
## MCP 工具
服务器提供以下 MCP 工具：
### USB/串行编程
- `list_serial_ports`：列出所有可用的 COM 端口
- `get_device_info`：查询设备信息（FPGA/ESP32）
- `get_flash_status`：获取闪存状态和信息
- `flash_device`：使用 USB/串行端口将固件闪存到设备中，并进行验证
### OTA（空中编程）
- `discover_ota_devices`：扫描本地网络中的 OTA 设备（HTTP 端口 3232）
- `check_device_ip`：检查特定 IP 地址是否具有可用的 OTA 端点
- `flash_device_ota`：通过 WiFi/网络闪存 ESP32 固件或 FPGA 位流
### OTA 使用示例
**发现网络上的设备：**
```python
# 返回具有 IP 地址和端点的设备列表
discover_ota_devices(timeout=2, port=3232)
```
**检查特定设备：**
```python
# 验证已知 IP 的设备是否具有 OTA 能力
check_device_ip(ip="10.0.4.35", port=3232)
```
**通过 OTA 闪存：**
```python
# 闪存 ESP32 固件
flash_device_ota(
ip="10.0.4.35",
device_type="esp32",
file_path="build/fpga_companion.bin",
port=3232
)
# 闪存 FPGA 位流
flash_device_ota(
ip="10.0.4.35",
device_type="fpga",
file_path="impl/pnr/a2600nano_retrocade.bin",
port=3232
)
```
**注意：** OTA 闪存需要：
- 设备必须运行具有 HTTP OTA 服务器的固件，端口为 3232
- 设备必须连接到同一网络
- ESP32 OTA 端点：`POST http://IP:3232/update`
- FPGA OTA 端点：`POST http://IP:3232/fpga-update`
## 开发
### 项目结构
```
papilio-loader-mcp/
├── src/
│ └── papilio_loader_mcp/
│ ├── __init__.py
│ ├── server.py # MCP 服务器实现
│ ├── api.py # FastAPI REST API
│ ├── config.py # 配置管理
│ └── tools/ # 工具实现
│ ├── serial_ports.py
│ ├── device_info.py
│ ├── flash_status.py
│ ├── fpga_flash.py
│ └── esp_flash.py
├── tools/
│ └── pesptool/ # Git 子模块（GadgetFactory/esptool）
├── temp/ # 临时文件上传
├── logs/ # 应用程序日志
├── pyproject.toml
└── README.md
```
### 运行测试
```bash
# TODO: 添加测试
uv run pytest
```
## 客户端示例
### Python 客户端
```python
import requests
API_URL = "http://windows-host:8000"
API_KEY = "your-key"
headers = {"X-API-Key": API_KEY}
# 列出端口
response = requests.get(f"{API_URL}/ports", headers=headers)
print(response.json())
# 闪存 ESP32
with open("firmware.bin", "rb") as f:
files = {"file": f}
data = {
"port": "COM3",
"device_type": "esp32",
"address": "0x1000",
"verify": "true"
}
response = requests.post(
f"{API_URL}/flash/upload",
headers=headers,
files=files,
data=data
)
print(response.json())
```
### WSL/Linux 客户端
```bash
#!/bin/bash
# flash_from_wsl.sh
WINDOWS_HOST="192.168.1.100:8000"
API_KEY="your-key"
# 构建项目
make build
# 通过 Windows 主机闪存到设备
curl -X POST "http://${WINDOWS_HOST}/flash/upload" \
-H "X-API-Key: ${API_KEY}" \
-F "file=@build/firmware.bin" \
-F "port=COM3" \
-F "device_type=esp32" \
-F "address=0x1000"
```
### curl 示例
```bash
# 列出端口
curl http://localhost:8000/ports
# 获取设备信息
curl -X POST http://localhost:8000/device/info \
-H "Content-Type: application/json" \
-d '{"port": "COM3", "device_type": "fpga"}'
# 闪存 FPGA
curl -X POST http://localhost:8000/flash/upload \
-F "file=@design.bit" \
-F "port=COM3" \
-F "device_type=fpga"
```
## 故障排除
### 端口访问问题
- 确保没有其他程序正在使用串行端口
- 在 Windows 上，检查设备管理器中的 COM 端口分配
- 验证您的设备是否已安装 USB 驱动程序
### 权限错误
- 在 Windows 上，如果访问 USB 端口失败，请以管理员身份运行
- 检查网络访问的防火墙设置
### pesptool 未找到
- 确保 git 子模块已初始化：`git submodule update --init`
- 检查 `tools/pesptool/esptool.py` 是否存在
- pesptool 是用于 FPGA 和 ESP32 编程的统一工具
## 许可证
[在此添加您的许可证]
## 贡献
欢迎贡献！请提交问题或拉取请求。
## 参考
- [MCP（模型上下文协议）](https://github.com/anthropics/mcp)
- [Papilio FPGA](http://papilio.cc)
- [GadgetFactory pesptool](https://github.com/GadgetFactory/esptool)
- [ESP32 文档](https://docs.espressif.com/projects/esp-idf/)
