GitHub - barryw/ViceMCP: AI-Powered Commodore Development Bridge

AI-Powered Commodore Development Bridge

MCP Tools Reference • Quick Start • Examples

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

Memory Operations (click to expand)

`read_memory`

Read bytes from memory and display in hex format.

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

`write_memory`

Write bytes to memory.

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

`copy_memory`

Copy memory from one location to another.

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

`fill_memory`

Fill memory region with a byte pattern.

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

`search_memory`

Search for byte patterns in memory.

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

`compare_memory`

Compare two memory regions.

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

CPU Control (click to expand)

`get_registers`

Get all CPU register values.

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

`set_register`

Set a CPU register value.

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

`step`

Step CPU by one or more instructions.

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

`continue_execution`

Resume execution after breakpoint.

Returns: "Execution resumed"

`reset`

Reset the emulated machine.

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

Breakpoint Management (click to expand)

`set_checkpoint`

Set a breakpoint/checkpoint.

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

`list_checkpoints`

List all checkpoints.

Returns: List with status, address range, hit count

`delete_checkpoint`

Delete a checkpoint.

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

`toggle_checkpoint`

Enable or disable a checkpoint.

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

File Operations (click to expand)

`load_program`

Load a PRG file into memory.

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

`save_memory`

Save memory region to file.

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

System Control (click to expand)

`start_vice`

Launch a VICE emulator instance.

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

`get_info`

Get VICE version information.

Returns: VICE version and SVN revision

`ping`

Check if VICE is responding.

Returns: "Pong! VICE is responding"

`get_banks`

List available memory banks.

Returns: List of bank numbers and names

`get_display`

Capture current display.

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

`quit_vice`

Quit the VICE emulator.

Returns: Confirmation of quit

`send_keys`

Send keyboard input to VICE.

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

`execute_batch` ⚡

Execute multiple VICE commands in a single operation for significantly improved performance.

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

🚀 Performance Tip: Always use batch execution for multiple related operations. Setting up a sprite display can be 10x faster using batch vs individual commands. See batch_examples/ for examples.

💡 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

🎯 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

Fork the repository
Create a feature branch
Make your changes with tests
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

Made with ❤️ for the Commodore community

Name		Name	Last commit message	Last commit date
Latest commit History 89 Commits
.claude		.claude
.github		.github
Images		Images
TestViceBridge		TestViceBridge
ViceMCP.Tests		ViceMCP.Tests
ViceMCP		ViceMCP
batch_examples		batch_examples
examples		examples
test-scripts		test-scripts
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
KNOWN_ISSUES.md		KNOWN_ISSUES.md
LICENSE		LICENSE
README.md		README.md
ViceMCP.sln		ViceMCP.sln
codecov.yml		codecov.yml
compose.yaml		compose.yaml
global.json		global.json
release-notes.md		release-notes.md
test_mcp.sh		test_mcp.sh
test_program.bas		test_program.bas

License

barryw/ViceMCP

Folders and files

Latest commit

History

Repository files navigation

Overview

✨ Key Features

⚡ Batch Commands - 10x Performance Boost!

Installation

📦 Download Release

🐳 Docker

Quick Test

Using with Claude Code CLI

Manual Configuration for Docker

Docker Compose Setup

🔧 Build from Source

Quick Start

1️⃣ Start VICE with Binary Monitor

2️⃣ Configure your MCP Client

Using Claude Code CLI (Recommended)

Manual Configuration

3️⃣ Start Debugging with AI

📚 MCP Tools Reference

read_memory

write_memory

copy_memory

fill_memory

search_memory

compare_memory

get_registers

set_register

step

continue_execution

reset

set_checkpoint

list_checkpoints

delete_checkpoint

toggle_checkpoint

load_program

save_memory

start_vice

get_info

ping

get_banks

get_display

quit_vice

send_keys

execute_batch ⚡