ViceMCP

Overview

ViceMCP bridges the gap between modern AI assistants and retro computing by exposing the VICE Commodore emulator's powerful debugging capabilities through the Model Context Protocol (MCP). This enables AI assistants like Claude to directly interact with running Commodore 64, VIC-20, PET, and other 8-bit Commodore computer emulations.

✨ Key Features

• 🤖 AI Integration - Use Claude or other MCP clients to debug Commodore programs
• 🔍 Memory Operations - Read, write, search, and analyze memory in real-time
• 🐛 Advanced Debugging - Set breakpoints, step through code, examine registers
• ⚡ Batch Commands - Execute multiple operations in one shot for 10x performance
• 📦 Zero Dependencies - Native AOT builds available - no .NET runtime needed!
• 🚀 Cross-Platform - Works on Windows, macOS, and Linux
• 🎮 Multi-Machine Support - C64, C128, VIC-20, PET, Plus/4, and more

⚡ Batch Commands - 10x Performance Boost!

Execute multiple VICE operations in a single command for massive performance gains:

execute_batch [
  {"command": "write_memory", "parameters": {"startHex": "0xD020", "dataHex": "00"}},
  {"command": "write_memory", "parameters": {"startHex": "0xD021", "dataHex": "05"}},
  {"command": "fill_memory", "parameters": {"startHex": "0x0400", "endHex": "0x07E7", "pattern": "A0"}},
  {"command": "write_memory", "parameters": {"startHex": "0x0400", "dataHex": "08 05 0C 0C 0F"}}
]

Result: Set border/background colors, clear screen, and write "HELLO" in ~1.4 seconds instead of ~14 seconds!

Check out the batch_examples/ directory for ready-to-use JSON files.

Installation

📦 Download Release

Download the latest release for your platform from the releases page.

Native AOT Builds Available! 🚀 No .NET runtime required - just download and run:

• vicemcp-linux-x64 - Linux x64 native executable
• vicemcp-windows-x64 - Windows x64 native executable
• vicemcp-macos-x64 - macOS Intel native executable
• vicemcp-macos-arm64 - macOS Apple Silicon native executable

🐳 Docker

Quick Test

docker run -it ghcr.io/barryw/vicemcp:latest

Using with Claude Code CLI

# Using Docker image directly
claude mcp add vicemcp "docker run -i --rm ghcr.io/barryw/vicemcp:latest"

# With VICE binary path mounted (if you have VICE installed locally)
claude mcp add vicemcp "docker run -i --rm -v /usr/local/bin:/vice:ro ghcr.io/barryw/vicemcp:latest" --env VICE_BIN_PATH=/vice

Manual Configuration for Docker

{
  "mcpServers": {
    "vicemcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/barryw/vicemcp:latest"],
      "env": {
        "VICE_MONITOR_PORT": "6502"
      }
    }
  }
}

Docker Compose Setup

# docker-compose.yml
version: '3.8'
services:
  vicemcp:
    image: ghcr.io/barryw/vicemcp:latest
    stdin_open: true
    tty: true
    environment:
      - VICE_MONITOR_PORT=6502
      - VICE_STARTUP_TIMEOUT=5000

Then configure with:

claude mcp add vicemcp "docker-compose run --rm vicemcp"

🔧 Build from Source

git clone https://github.com/barryw/ViceMCP.git
cd ViceMCP
dotnet build

Quick Start

1️⃣ Start VICE with Binary Monitor

x64sc -binarymonitor -binarymonitoraddress 127.0.0.1:6502

2️⃣ Configure your MCP Client

Using Claude Code CLI (Recommended)

# If you downloaded the release binary
claude mcp add vicemcp ~/Downloads/vicemcp-osx-arm64/ViceMCP

# Or if you built from source
claude mcp add vicemcp ~/RiderProjects/ViceMCP/ViceMCP/bin/Release/net9.0/ViceMCP

# Or using Docker (no installation needed!)
claude mcp add vicemcp "docker run -i --rm ghcr.io/barryw/vicemcp:latest"

With VICE path configured (if not in system PATH):

claude mcp add vicemcp ~/Downloads/vicemcp-osx-arm64/ViceMCP --env VICE_BIN_PATH=/Applications/vice-x86-64-gtk3-3.8

Manual Configuration

Add to your Claude Desktop or other MCP client configuration:

{
  "mcpServers": {
    "vicemcp": {
      "command": "/path/to/vicemcp",
      "env": {
        "VICE_BIN_PATH": "/path/to/vice/bin"
      }
    }
  }
}

3️⃣ Start Debugging with AI

Ask your AI assistant to:

• "Read memory from $C000 to $C100"
• "Set a breakpoint at $0810"
• "Show me the current CPU registers"
• "Find all JSR $FFD2 instructions in memory"

📚 MCP Tools Reference

Parameters:
  - startHex: Start address (e.g., "0x0400" or "0400")
  - endHex: End address
Returns: Hex string like "08-05-0C-0C-0F"

Parameters:
  - startHex: Start address
  - dataHex: Space-separated hex bytes (e.g., "A9 00 8D 20 D0")
Returns: Confirmation with bytes written

Parameters:
  - sourceHex: Source start address
  - destHex: Destination start address
  - length: Number of bytes to copy
Returns: Confirmation of copy operation

Parameters:
  - startHex: Start address
  - endHex: End address
  - pattern: Hex bytes to repeat (e.g., "AA 55")
Returns: Confirmation with pattern used

Parameters:
  - startHex: Search start address
  - endHex: Search end address
  - pattern: Hex bytes to find (e.g., "A9 00" for LDA #$00)
  - maxResults: Maximum matches to return (default: 10)
Returns: List of addresses where pattern found

Parameters:
  - addr1Hex: First region start
  - addr2Hex: Second region start
  - length: Bytes to compare
Returns: List of differences or "regions identical"

Returns: A, X, Y, PC, SP, and status flags

Parameters:
  - registerName: Register name (A, X, Y, PC, SP)
  - valueHex: New value in hex
Returns: Confirmation of register update

Parameters:
  - count: Instructions to step (default: 1)
  - stepOver: Step over subroutines (default: false)
Returns: Number of instructions stepped

Returns: "Execution resumed"

Parameters:
  - mode: "soft" or "hard" (default: "soft")
Returns: Reset confirmation

Parameters:
  - startHex: Start address
  - endHex: End address (optional)
  - stopWhenHit: Stop execution on hit (default: true)
  - enabled: Initially enabled (default: true)
Returns: Checkpoint number and address range

Returns: List with status, address range, hit count

Parameters:
  - checkpointNumber: Checkpoint # to delete
Returns: Confirmation of deletion

Parameters:
  - checkpointNumber: Checkpoint # to toggle
  - enabled: true to enable, false to disable
Returns: New checkpoint state

Parameters:
  - filePath: Path to PRG file
  - addressHex: Override load address (optional)
Returns: Load address and size information

Parameters:
  - startHex: Start address
  - endHex: End address
  - filePath: Output file path
  - asPrg: Save as PRG with header (default: true)
Returns: Confirmation with bytes saved

Parameters:
  - emulatorType: x64sc, x128, xvic, xpet, xplus4, xcbm2, xcbm5x0
  - arguments: Additional command line arguments
Returns: Process ID and monitor port

Returns: VICE version and SVN revision

Returns: "Pong! VICE is responding"

Returns: List of bank numbers and names

Parameters:
  - useVic: Use VIC (true) or VICII/VDC (false)
Returns: Display dimensions and image data size

Returns: Confirmation of quit

Parameters:
  - keys: Text to type (use \n for Return)
Returns: Confirmation of keys sent

Parameters:
  - commandsJson: JSON array of command specifications
  - failFast: Stop on first error (default: true)
Returns: JSON with results of all commands

💡 Examples

Debugging a Crash

AI: Let me examine what caused the crash...
> read_memory 0x0100 0x01FF  // Check stack
> get_registers              // See CPU state
> read_memory 0xC000 0xC020  // Examine code at PC

Finding Code Patterns

AI: I'll search for all JSR instructions to $FFD2...
> search_memory 0x0800 0xBFFF "20 D2 FF"

Interactive Development

AI: Let me load your program and set a breakpoint...
> load_program "game.prg"
> set_checkpoint 0x0810      // Break at start
> continue_execution
> step 10 true              // Step over subroutines

Memory Analysis

AI: I'll check if the sprite data was copied correctly...
> compare_memory 0x2000 0x3000 64

Batch Operations for Speed ⚡

AI: I'll create a red heart sprite in the center of the screen...
> execute_batch [
    {"command": "write_memory", "parameters": {"startHex": "0xD020", "dataHex": "00"}, "description": "Black border"},
    {"command": "write_memory", "parameters": {"startHex": "0xD021", "dataHex": "00"}, "description": "Black background"},
    {"command": "fill_memory", "parameters": {"startHex": "0x0400", "endHex": "0x07E7", "pattern": "20"}, "description": "Clear screen"},
    {"command": "write_memory", "parameters": {"startHex": "0x0340", "dataHex": "00 66 00 01 FF 80 03 FF C0 07 FF E0 0F FF F0..."}, "description": "Heart sprite data"},
    {"command": "write_memory", "parameters": {"startHex": "0x07F8", "dataHex": "0D"}, "description": "Set sprite pointer"},
    {"command": "write_memory", "parameters": {"startHex": "0xD015", "dataHex": "01"}, "description": "Enable sprite 0"},
    {"command": "write_memory", "parameters": {"startHex": "0xD000", "dataHex": "A0"}, "description": "Center X position"},
    {"command": "write_memory", "parameters": {"startHex": "0xD001", "dataHex": "86"}, "description": "Center Y position"},
    {"command": "write_memory", "parameters": {"startHex": "0xD027", "dataHex": "02"}, "description": "Red color"}
  ]
// Result: Beautiful red heart sprite in 1.4 seconds! (vs 14+ seconds individually)

🏗️ Architecture

ViceMCP is built with:

• .NET 9.0 - Modern, cross-platform runtime
• Model Context Protocol - Standardized AI tool interface
• vice-bridge-net - Robust VICE binary monitor implementation
• Async/await patterns - Efficient concurrent operations

🧪 Development

Prerequisites

• .NET 9.0 SDK
• VICE emulator
• Git

Building

dotnet build
dotnet test
dotnet run --project ViceMCP/ViceMCP.csproj

Testing

dotnet test

Tests use mocking to run without VICE, ensuring fast CI/CD.

📖 Documentation

• Contributing Guidelines
• Known Issues

🎯 Use Cases

• 🎮 Game Development - Debug crashes, optimize routines, trace execution
• 🔍 Reverse Engineering - Analyze vintage software behavior
• 📚 Education - Learn 6502 assembly with AI assistance
• 🛠️ Tool Development - Automate debugging workflows
• 🏆 Demoscene - Profile and optimize demo effects

⚠️ Known Limitations

See KNOWN_ISSUES.md for any current limitations.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

📜 License

This project is licensed under the MIT License - see LICENSE for details.

🙏 Acknowledgments

• VICE Team - The amazing Commodore emulator
• Anthropic - Model Context Protocol
• Miha Markic - vice-bridge-net library
• The Commodore community for keeping the 8-bit dream alive