内容
# Papilio 游戏机 MCP 服务器
MCP（模型上下文协议）服务器和调试固件，允许 GitHub Copilot 等 AI 助手直接控制 Papilio 游戏机 FPGA 开发板。
## 组件
此库包含：
1. **MCP 服务器**（Python）- 在主机 PC 上运行，将 MCP 工具调用转换为串行命令
2. **PapilioMCP.h**（Arduino）- 头文件库，为任何草图添加 MCP 调试功能
3. **示例固件** - 随时可用的调试固件草图
## 快速入门 - 将 MCP 调试添加到任何草图
添加 MCP 调试功能的最简单方法是使用头文件库：
```cpp
// 在 setup() 之前添加 - 注释掉以禁用
#define PAPILIO_MCP_ENABLED
#include <PapilioMCP.h>
void setup() {
Serial.begin(115200);
// ... 您的设置代码 ...
PapilioMCP.begin(); // 初始化 MCP（如果禁用则不执行任何操作）
}
void loop() {
PapilioMCP.update(); // 处理 MCP 命令（如果禁用则不执行任何操作）
// ... 您的循环代码 ...
}
```
当 `PAPILIO_MCP_ENABLED` 未定义时，`PapilioMCP.begin()` 和 `PapilioMCP.update()` 编译为空存根 - 零开销。
## 快速入门 - 使用调试固件
### 1. 上传调试固件
```bash
# 从项目根目录
pio run -e mcp_debug_firmware -t upload
```
或使用 Makefile：
```bash
make mcp_debug_firmware-upload
```
### 2. 配置 VS Code MCP
`.vscode/mcp.json` 应已配置。如果没有，请添加：
```json
{
"servers": {
"papilio": {
"type": "stdio",
"command": "python",
"args": ["libs/papilio_mcp_server/server/papilio_mcp_server.py", "--port", "COM4"]
}
}
}
```
### 3. 安装 Python 依赖项
```bash
pip install pyserial opencv-python
```
## PlatformIO 构建环境
在您的 `platformio.ini` 中，您可以通过构建标志将 MCP 调试功能添加到任何环境中：
```ini
; 正常构建 - MCP 禁用
[env:my_project]
extends = env:papilio_arcade
; 调试构建 - MCP 启用
[env:my_project_debug]
extends = env:papilio_arcade
build_flags = ${env:papilio_arcade.build_flags}
-DPAPILIO_MCP_ENABLED
```
## 功能
- **RGB LED 控制**：设置和读取 RGB LED 颜色
- **Wishbone 总线访问**：读取/写入任何 Wishbone 总线地址
- **FPGA 状态**：获取调试转储和状态信息
- **串口管理**：列出端口并连接到开发板
- **截图捕获**：捕获 HDMI 输出的网络摄像头图像
- **视频模式控制**：在测试图案、文本模式和帧缓冲区之间切换
- **文本模式**：在 80x26 文本显示上写入文本
- **JTAG 桥接**：启用用于 FPGA 编程的 USB JTAG 直通
## 串行命令（通过 PapilioMCP.h）
| 命令 | 描述 |
|---------|-------------|
| `H` | 帮助 |
| `W AAAA DD` | 将 DD 写入 Wishbone 地址 AAAA |
| `R AAAA` | 从 Wishbone 地址 AAAA 读取 |
| `M AAAA NN` | 读取从 AAAA 开始的 NN 字节 |
| `D` | 转储调试寄存器 |
| `J [1\|0]` | 启用/禁用 JTAG 桥接 |
## 可用的 MCP 工具
### RGB LED 控制
| 工具 | 描述 |
|------|-------------|
| `set_rgb_led` | 设置 RGB LED 颜色（每个通道 0-255） |
| `get_rgb_led` | 读取当前 RGB LED 颜色值 |
### Wishbone 总线访问
| 工具 | 描述 |
|------|-------------|
| `wishbone_read` | 从 Wishbone 总线地址读取字节 |
| `wishbone_write` | 向 Wishbone 总线地址写入字节 |
### 开发板管理
| 工具 | 描述 |
|------|-------------|
| `list_serial_ports` | 列出可用的串行端口 |
| `connect_board` | 连接到特定端口上的开发板 |
| `disconnect_board` | 从开发板断开连接（释放串行端口） |
| `get_fpga_status` | 获取调试状态和寄存器转储 |
| `send_raw_command` | 发送原始命令并带有流输出 |
### 截图捕获
| 工具 | 描述 |
|------|-------------|
| `capture_screenshot` | 捕获 HDMI 显示器的网络摄像头图像 |
| `list_cameras` | 列出可用的摄像头索引 |
| `set_camera` | 选择要使用的摄像头 |
| `set_screenshot_crop` | 设置截图的裁剪区域 |
| `clear_screenshot_crop` | 清除裁剪区域 |
### 视频模式控制
| 工具 | 描述 |
|------|-------------|
| `set_video_mode` | 设置视频模式（0-4） |
| `get_video_mode` | 获取当前视频模式 |
视频模式：
- 0：彩色条纹
- 1：网格图案
- 2：灰度渐变
- 3：文本模式（80x26）
- 4：帧缓冲区（160x120 RGB332）
### 文本模式
| 工具 | 描述 |
|------|-------------|
| `text_clear` | 清除文本屏幕 |
| `text_set_cursor` | 设置光标位置 |
| `text_set_color` | 设置文本颜色（CGA 16 色调色板） |
| `text_write` | 在光标处写入文本 |
| `text_write_at` | 在特定位置写入文本并设置颜色 |
## Wishbone 地址映射
| 地址范围 | 外设 |
|--------------|------------|
| 0x8010 | 视频模式寄存器 |
| 0x8020-0x802B | 文本模式控制 |
| 0x8100-0x8103 | RGB LED 控制器 |
| 0x0000-0x4B00 | 帧缓冲区（160x120 RGB332） |
## 使用示例
配置 MCP 服务器后，您可以询问 Copilot：
- “将 RGB LED 设置为红色”
- “使 LED 变为蓝色”
- “读取当前 LED 颜色”
- “向地址 0x8100 写入 0xFF”
- “切换到文本模式”
- “在位置 10,5 处写入 'Hello World'”
- “捕获截图”
- “运行原始命令 H”
## 文件结构
```
papilio_mcp_server/
├── library.json # PlatformIO 库清单
├── README.md # 此文件
├── src/
│ └── PapilioMCP.h # 草图的头文件库
├── server/
│ └── papilio_mcp_server.py # 主 MCP 服务器
└── examples/
├── mcp_debug_simple/ # 最小调试固件
└── mcp_debug_firmware_full/ # 全功能调试固件
```
