Papilio加载器MCP服务器
MCP（模型上下文协议）服务器，用于通过网络加载FPGA位文件和ESP32固件。该服务器在Windows上运行，可直接访问USB/串行端口，同时允许远程客户端（如WSL或Linux机器）通过网络对设备进行编程。
🎉 新增：桌面应用程序可用！
Papilio Loader现在可作为 桌面应用程序 与系统托盘集成！非常适合想要简单易用界面的最终用户。
看 桌面_APP.md 有关安装和使用说明。
特性
- 桌面应用程序 （新增！）：Windows系统托盘应用程序，一键安装
- OTA 更新 （新增！）：通过WiFi/网络无需USB连接的闪存设备
- 在本地网络上发现支持OTA的设备 - Flash ESP32固件和FPGA比特流无线传输 - 支持具有HTTP OTA端点（端口3232）的设备
- 网络界面：基于浏览器的现代用户界面，供最终用户手动设备闪烁
- 保存文件库：保存带有说明的常用固件文件，以便于重用
- MCP服务器：与Claude Desktop和其他MCP客户端集成，用于人工智能辅助设备编程
- REST API：用于远程网络访问的基于FastAPI的HTTP API
- 双编程工具:
- ESP32编程的官方esptool（安全稳定） - pesptool（GadgetFactory分支）仅用于FPGA编程
- Gowin FPGA支持：通过pesptool使用.bin文件的Flash Papilio板（Gowin FPGA）
- ESP32支持：使用官方esptool闪存ESP32设备，带有bin/elf文件，支持多分区闪存
- 基于网络：在具有串行端口访问的Windows上运行，通过网络从WSL/Linux进行控制
快速开始
选项1：桌面应用程序（最简单）
- 下载并安装
PapilioLoader-Setup-x.x.x.exe从 发布 - 从“开始”菜单启动Papilio Loader
- 系统托盘图标出现-右键单击并选择“打开Web界面”
看 桌面_APP.md 了解详情。
选项2：Web界面（Python）
# 1. Install dependencies
uv pip install -e .
# 2. Start the combined server (MCP + Web Interface)
.\start.ps1
# 3. Open browser to http://localhost:8000/web/login
# Default credentials: admin/admin看 WEBINTERFACE_GUIDE.md 详细说明。
选项3:仅限MCP服务器
# Install and configure for Claude Desktop or other MCP clients
# See documentation/QUICKSTART.md建筑
┌─────────────────┐ Network ┌──────────────────┐
│ Web Browser │ ◄────────────────────► │ Windows Host │
│ WSL / Linux │ HTTP/MCP │ Combined Server │
│ Build Machine │ │ │
│ - Manual Upload │ │ - Web UI │
│ - Build FPGA │ │ - MCP Server │
│ - Build ESP32 │ │ - REST API │
│ - Send files │ │ - pyserial │
│ │ │ - esptool (ESP32)│
│ │ │ - pesptool (FPGA)│
└─────────────────┘ └────────┬─────────┘
│ USB/Serial
▼
┌─────────────────┐
│ FPGA / ESP32 │
│ Hardware │
└─────────────────┘安装
先决条件
- Python 3.12+：运行服务器所需
- esptool：Espressif官方ESP32编程工具（通过pip自动安装）
- 比索托：GadgetFactory的FPGA编程分支（包含在git子模块中）
- 仅用于将FPGA比特流编程到外部闪存 - ESP32使用官方esptool确保安全性和稳定性
设置
# Clone the repository
git clone https://github.com/papilio-labs/papilio-loader-mcp.git
cd papilio-loader-mcp
# Initialize submodules
git submodule update --init --recursive
# Create virtual environment using uv
uv venv
# Install dependencies
uv pip install -e .配置
设置环境变量以配置服务器：
# Network settings
PAPILIO_BIND_ADDRESS=0.0.0.0 # Use 0.0.0.0 for remote access, 127.0.0.1 for local only
PAPILIO_PORT=8000
# Security
PAPILIO_API_KEY=your-secret-key-here # Optional API authentication
PAPILIO_CORS_ORIGINS=["http://localhost:3000"] # Comma-separated list
# Limits
PAPILIO_MAX_UPLOAD_SIZE=52428800 # 50 MB in bytes
PAPILIO_RATE_LIMIT=60 # Requests per minute
# Serial settings
PAPILIO_DEFAULT_BAUD_RATE=115200
PAPILIO_SERIAL_TIMEOUT=10用法
作为独立的HTTP/SSE服务器（建议用于远程访问）
HTTP/SSE服务器作为独立的Windows进程运行，并允许VS Code（或其他MCP客户端）通过HTTP与服务器发送事件（SSE）传输连接。
优点：
- 不需要VS Code来生成服务器进程
- 服务器持续运行，与VS代码无关
- 可以设置为Windows服务
- 多个客户端可以连接到同一服务器实例
- 更适合远程/网络访问场景
启动服务器：
# Using the startup script
python start_mcp_server.py
# Or run the module directly
python -m papilio_loader_mcp.http_server --port 8765
# Or with custom host/port
python -m papilio_loader_mcp.http_server --host 0.0.0.0 --port 8765服务器将于启动 http://127.0.0.1:8000 SSE端点位于 /sse.
配置VS代码：
更新 .vscode/mcp.json 在您的项目中：
{
"servers": {
"papilio-loader": {
"type": "sse",
"url": "http://127.0.0.1:8000/sse"
}
}
}注： VS代码使用 "servers" 在顶层（不是 "mcpServers" 用于克劳德桌面）。
对于来自其他计算机的网络访问，请使用 "url": "http://YOUR_WINDOWS_IP:8000/sse".
设置为Windows服务（可选）：
要在Windows启动时自动运行服务器，您可以使用NSSM（非吸吮服务管理器）或任务计划程序：
# Download NSSM from https://nssm.cc/download
nssm install PapilioMCP "C:\Python314\python.exe" "C:\development\papilio-loader-mcp\start_mcp_server.py"
nssm start PapilioMCP作为MCP服务器（VS Code-stdio模式下的GitHub Copilot）
此项目已为GitHub Copilot MCP集成进行了预配置。安装后：
- 重新加载VS代码窗口(
Ctrl+Shift+P→ “开发人员：重新加载窗口”） - 打开GitHub Copilot聊天
- MCP工具将自动可用
看 VSCODE_SETUP.md 有关详细的设置说明。
作为MCP服务器（克劳德桌面）
- 添加到您的Claude Desktop配置(
%APPDATA%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"papilio-loader": {
"type": "sse",
"url": "http://localhost:8000/sse"
}
}
}注： Claude Desktop使用 "mcpServers" 在顶层（不是 "servers" 用于VS码）。
- 重新启动克劳德桌面
- 使用自然语言进行交互：
- “列出可用串行端口” - “将此位文件闪存到COM3” - “在/dev/ttyUSB0上获取ESP32芯片信息”
作为REST API服务器
# Start the API server
python -m papilio_loader_mcp.api
# Or use uvicorn directly
uvicorn papilio_loader_mcp.api:api --host 0.0.0.0 --port 8000API终点
健康检查
curl http://localhost:8000/health列出串行端口
curl -H "X-API-Key: your-key" http://localhost:8000/ports获取设备信息
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"}'闪存设备
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的设备（端口3232上的HTTP端点）check_device_ip：检查特定IP地址是否有可用的OTA端点flash_device_ota：通过WiFi/网络闪存ESP32固件或FPGA比特流
OTA使用示例
发现网络上的设备：
# Returns list of devices with their IP addresses and endpoints
discover_ota_devices(timeout=2, port=3232)检查特定设备：
# Verify device at known IP has OTA capability
check_device_ip(ip="10.0.4.35", port=3232)通过OTA进行闪光：
# Flash ESP32 firmware
flash_device_ota(
ip="10.0.4.35",
device_type="esp32",
file_path="build/fpga_companion.bin",
port=3232
)
# Flash FPGA bitstream
flash_device_ota(
ip="10.0.4.35",
device_type="fpga",
file_path="impl/pnr/a2600nano_retrocade.bin",
port=3232
)注： OTA闪烁要求：
- 设备必须在端口3232上运行HTTP OTA服务器的固件
- 设备必须连接到同一网络
- 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 server implementation
│ ├── api.py # FastAPI REST API
│ ├── config.py # Configuration management
│ └── tools/ # Tool implementations
│ ├── serial_ports.py
│ ├── device_info.py
│ ├── flash_status.py
│ ├── fpga_flash.py
│ └── esp_flash.py
├── tools/
│ └── pesptool/ # Git submodule (GadgetFactory/esptool)
├── temp/ # Temporary file uploads
├── logs/ # Application logs
├── pyproject.toml
└── README.md运行测试
# TODO: Add tests
uv run pytest客户示例
Python客户端
import requests
API_URL = "http://windows-host:8000"
API_KEY = "your-key"
headers = {"X-API-Key": API_KEY}
# List ports
response = requests.get(f"{API_URL}/ports", headers=headers)
print(response.json())
# Flash 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客户端
#!/bin/bash
# flash_from_wsl.sh
WINDOWS_HOST="192.168.1.100:8000"
API_KEY="your-key"
# Build your project
make build
# Flash to device via Windows host
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示例
# List ports
curl http://localhost:8000/ports
# Get device info
curl -X POST http://localhost:8000/device/info \
-H "Content-Type: application/json" \
-d '{"port": "COM3", "device_type": "fpga"}'
# Flash FPGA
curl -X POST http://localhost:8000/flash/upload \
-F "file=@design.bit" \
-F "port=COM3" \
-F "device_type=fpga"故障排除
港口准入问题
- 确保没有其他程序正在使用串行端口
- 在Windows上，检查设备管理器中的COM端口分配
- 验证您的设备是否安装了USB驱动程序
权限错误
- 如果访问USB端口失败，请在Windows上以管理员身份运行
- 检查网络访问的防火墙设置
未找到比索托
- 确保git子模块已初始化：
git submodule update --init - 检查一下
tools/pesptool/esptool.py存在 - pesptool是FPGA和ESP32编程的统一工具
许可证
\[在此处添加您的许可证\]
贡献
欢迎投稿！请打开问题或拉取请求。