GadgetFactory/papilio_mcp_server

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)

Available MCP Tools

RGB LED Control

Wishbone Bus Access

Board Management

Screenshot Capture

Video Mode Control

Video modes:

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

Text Mode

Wishbone Address Map

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