Papilio Arcade MCP Server

An MCP (Model Context Protocol) server and debug firmware that allows AI assistants like GitHub Copilot to directly control the Papilio Arcade FPGA board.

Components

This library contains:

1. MCP Server (Python) - Runs on host PC, translates MCP tool calls to serial commands
2. PapilioMCP.h (Arduino) - Header-only library to add MCP debug to any sketch
3. Example Firmware - Ready-to-use debug firmware sketches

Quick Start - Adding MCP Debug to Any Sketch

The easiest way to add MCP debug capability is with the header library:

// Add BEFORE setup() - comment out to disable
#define PAPILIO_MCP_ENABLED
#include <PapilioMCP.h>

void setup() {
  Serial.begin(115200);
  // ... your setup code ...
  
  PapilioMCP.begin();  // Initialize MCP (does nothing if disabled)
}

void loop() {
  PapilioMCP.update();  // Process MCP commands (does nothing if disabled)
  
  // ... your loop code ...
}

When PAPILIO_MCP_ENABLED is NOT defined, PapilioMCP.begin() and PapilioMCP.update() compile to empty stubs - zero overhead.

Quick Start - Using the Debug Firmware

1. Upload the Debug Firmware

# From project root
pio run -e mcp_debug_firmware -t upload

Or use the Makefile:

make mcp_debug_firmware-upload

2. Configure VS Code MCP

The .vscode/mcp.json should already be configured. If not, add:

{
  "servers": {
    "papilio": {
      "type": "stdio",
      "command": "python",
      "args": ["libs/papilio_mcp_server/server/papilio_mcp_server.py", "--port", "COM4"]
    }
  }
}

3. Install Python Dependencies

pip install pyserial opencv-python

PlatformIO Build Environments

In your platformio.ini, you can add MCP debug to any environment via build flags:

; Normal build - MCP disabled
[env:my_project]
extends = env:papilio_arcade

; Debug build - MCP enabled
[env:my_project_debug]
extends = env:papilio_arcade
build_flags = ${env:papilio_arcade.build_flags}
              -DPAPILIO_MCP_ENABLED

Features

• RGB LED Control: Set and read RGB LED colors
• Wishbone Bus Access: Read/write to any Wishbone bus address
• FPGA Status: Get debug dumps and status information
• Serial Port Management: List ports and connect to the board
• Screenshot Capture: Capture webcam images of HDMI output
• Video Mode Control: Switch between test patterns, text mode, and framebuffer
• Text Mode: Write text to 80x26 text display
• JTAG Bridge: Enable USB JTAG passthrough for FPGA programming

Serial Commands (via PapilioMCP.h)

Command	Description
H	Help
W AAAA DD	Write DD to Wishbone address AAAA
R AAAA	Read from Wishbone address AAAA
M AAAA NN	Read NN bytes starting at AAAA
D	Dump debug registers
J [1|0]	Enable/disable JTAG bridge

Available MCP Tools

RGB LED Control

Tool	Description
set_rgb_led	Set the RGB LED color (0-255 per channel)
get_rgb_led	Read the current RGB LED color values

Wishbone Bus Access

Tool	Description
wishbone_read	Read a byte from a Wishbone bus address
wishbone_write	Write a byte to a Wishbone bus address

Board Management

Tool	Description
list_serial_ports	List available serial ports
connect_board	Connect to board on specific port
disconnect_board	Disconnect from board (free serial port)
get_fpga_status	Get debug status and register dump
send_raw_command	Send raw command with streaming output

Screenshot Capture

Tool	Description
capture_screenshot	Capture webcam image of HDMI monitor
list_cameras	List available camera indices
set_camera	Select which camera to use
set_screenshot_crop	Set crop region for screenshots
clear_screenshot_crop	Clear crop region

Video Mode Control

Tool	Description
set_video_mode	Set video mode (0-4)
get_video_mode	Get current video mode

Video modes:

• 0: Color bars
• 1: Grid pattern
• 2: Grayscale gradient
• 3: Text mode (80x26)
• 4: Framebuffer (160x120 RGB332)

Text Mode

Tool	Description
text_clear	Clear text screen
text_set_cursor	Set cursor position
text_set_color	Set text color (CGA 16-color palette)
text_write	Write text at cursor
text_write_at	Write text at specific position with color

Wishbone Address Map

Address Range	Peripheral
0x8010	Video mode register
0x8020-0x802B	Text mode control
0x8100-0x8103	RGB LED Controller
0x0000-0x4B00	Framebuffer (160x120 RGB332)

Usage Examples

Once the MCP server is configured, you can ask Copilot:

• "Set the RGB LED to red"
• "Make the LED blue"
• "Read the current LED color"
• "Write 0xFF to address 0x8100"
• "Switch to text mode"
• "Write 'Hello World' at position 10,5"
• "Capture a screenshot"
• "Run raw command H"

File Structure

papilio_mcp_server/
├── library.json           # PlatformIO library manifest
├── README.md              # This file
├── src/
│   └── PapilioMCP.h       # Header-only library for sketches
├── server/
│   └── papilio_mcp_server.py  # Main MCP server
└── examples/
    ├── mcp_debug_simple/      # Minimal debug firmware
    └── mcp_debug_firmware_full/  # Full-featured debug firmware