vice-mcp

A Model Context Protocol (MCP) server for autonomous C64 debugging via the VICE emulator.

What is this?

vice-mcp bridges AI agents to the VICE Commodore 64 emulator, enabling autonomous debugging of 6502 assembly programs. Unlike raw protocol wrappers, it provides a semantic layer that interprets C64-specific data structures and returns meaningful, actionable information.

Why this exists:

AI agents need more than hex dumps—they need interpreted data with context
Debugging C64 code requires understanding VIC-II banks, PETSCII encoding, sprite pointers, and memory layouts
Every response includes hints suggesting next steps and related tools

Key differentiators:

Semantic output: readScreen returns text, not screen codes. readVicState explains graphics modes, not register bits.
Actionable hints: Every response suggests what to do next
Cross-references: Tools point to related tools for common workflows
Agent-friendly errors: Clear error codes and recovery suggestions

Prerequisites

Node.js 18 or later
VICE emulator with binary monitor enabled

Starting VICE with Binary Monitor

# x64sc is the accurate C64 emulator (recommended)
x64sc -binarymonitor -binarymonitoraddress ip4://127.0.0.1:6502

# Or with x64 (faster, less accurate)
x64 -binarymonitor -binarymonitoraddress ip4://127.0.0.1:6502

The binary monitor listens on port 6502 by default.

Installation

From npm (when published)

npx @simen/vice-mcp

From GitHub

npx github:simen/vice-mcp

Local Development

git clone https://github.com/simen/vice-mcp.git
cd vice-mcp
npm install
npm run build
npm start

Claude Code Installation

The quickest way to get started with Claude Code:

1. Start VICE with binary monitor:

x64sc -binarymonitor -binarymonitoraddress ip4://127.0.0.1:6502

2. Add the MCP server:

claude mcp add vice-mcp -- npx github:simen/vice-mcp

3. Restart Claude Code to load the new MCP server.

That's it! You can now ask Claude Code to debug your C64 programs.

Manual Configuration

Alternatively, add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vice-mcp": {
      "command": "npx",
      "args": ["github:simen/vice-mcp"]
    }
  }
}

Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Cursor, or custom agent):

{
  "mcpServers": {
    "vice": {
      "command": "npx",
      "args": ["@simen/vice-mcp"]
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "vice": {
      "command": "node",
      "args": ["/path/to/vice-mcp/dist/index.js"]
    }
  }
}

Tool Reference

Connection & Status

Tool	Description
`connect`	Connect to VICE (default: 127.0.0.1:6502)
`disconnect`	Disconnect from VICE
`status`	Get connection state and emulation status

Memory Operations

Tool	Description
`readMemory`	Read raw bytes with hex dump and ASCII
`writeMemory`	Write bytes to memory

CPU & Execution

Tool	Description
`getRegisters`	Get A, X, Y, SP, PC, and flags (interpreted)
`step`	Single-step execution (with step-over option)
`continue`	Resume execution
`reset`	Soft or hard reset
`runTo`	Run until specific address (temporary breakpoint)
`disassemble`	Disassemble 6502 code with KERNAL labels

Breakpoints & Watchpoints

Tool	Description
`setBreakpoint`	Set execution breakpoint
`deleteBreakpoint`	Remove breakpoint or watchpoint
`listBreakpoints`	List all breakpoints
`toggleBreakpoint`	Enable/disable breakpoint
`setWatchpoint`	Set memory read/write watchpoint
`listWatchpoints`	List all watchpoints

Semantic Layer (Interpreted C64 Data)

Tool	Description
`readScreen`	Get screen as text (PETSCII decoded) with summary mode
`readColorRam`	Get color RAM with color names and usage stats
`readVicState`	Full VIC-II state: graphics mode, colors, banks, sprites
`readSprites`	All 8 sprites: position, visibility, colors, pointers

Visual Feedback

Tool	Description
`screenshot`	Capture display buffer with palette
`renderScreen`	ASCII art rendering of display

State Management

Tool	Description
`saveSnapshot`	Save complete machine state to file
`loadSnapshot`	Load machine state from file
`loadProgram`	Load and optionally run PRG/D64/T64 files

Example Usage

Basic Debugging Session

1. connect()                    → Establish connection
2. loadProgram("game.prg")      → Load the program
3. setBreakpoint(0x0810)        → Break at main loop
4. continue()                   → Run until breakpoint
5. getRegisters()               → Check CPU state
6. readScreen()                 → See what's on screen
7. step(count: 5)               → Execute 5 instructions
8. disassemble()                → See code at current PC

Debugging Sprite Issues

1. readVicState()               → Check sprite enable bits
2. readSprites(enabledOnly: true) → Get enabled sprite details
   → Response includes visibility check and position analysis
3. If sprite not visible, hint tells you why (off-screen, wrong bank, etc.)

Memory Watchpoint Workflow

1. setWatchpoint(startAddress: 0x0400, type: "store")
   → Watch for writes to screen RAM
2. continue()
   → Execution stops when something writes to screen
3. getRegisters()
   → See PC to find the code that wrote
4. disassemble()
   → Understand what the code is doing

State Checkpoint Pattern

1. saveSnapshot("before-test.vsf")  → Save state
2. [Make changes, test things]
3. loadSnapshot("before-test.vsf")  → Restore to known state

Response Format

All responses include:

Structured data with value and hex representations
_meta block with connection state
hint field with contextual next steps

Example getRegisters response:

{
  "a": { "value": 65, "hex": "$41" },
  "x": { "value": 0, "hex": "$00" },
  "y": { "value": 0, "hex": "$00" },
  "sp": { "value": 243, "hex": "$f3", "stackTop": "$01f3" },
  "pc": { "value": 2049, "hex": "$0801" },
  "flags": {
    "negative": false,
    "overflow": false,
    "zero": false,
    "carry": false,
    "string": "nv-bdizc"
  },
  "hint": "CPU state looks normal",
  "_meta": {
    "connected": true,
    "running": false,
    "host": "127.0.0.1",
    "port": 6502
  }
}

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    MCP Client (Agent)                    │
└─────────────────────────────────────────────────────────┘
                            │
                            │ MCP Protocol (stdio)
                            ▼
┌─────────────────────────────────────────────────────────┐
│                     src/index.ts                         │
│                    (MCP Server)                          │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Tool Handlers (24 tools)            │    │
│  │  • Connection: connect, disconnect, status       │    │
│  │  • Memory: readMemory, writeMemory              │    │
│  │  • CPU: getRegisters, step, continue, reset     │    │
│  │  • Breakpoints: set, delete, list, toggle       │    │
│  │  • Watchpoints: set, list                       │    │
│  │  • Semantic: readScreen, readVicState, etc.     │    │
│  │  • Visual: screenshot, renderScreen            │    │
│  │  • State: saveSnapshot, loadSnapshot, loadPrg   │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘
                            │
                            │ Uses
                            ▼
┌─────────────────────────────────────────────────────────┐
│                 src/protocol/client.ts                   │
│                    (ViceClient)                          │
│  • TCP socket connection to VICE                        │
│  • Binary protocol encoding/decoding                    │
│  • Request/response correlation                         │
│  • Checkpoint (breakpoint/watchpoint) tracking          │
└─────────────────────────────────────────────────────────┘
                            │
                            │ TCP Socket
                            ▼
┌─────────────────────────────────────────────────────────┐
│                 VICE Binary Monitor                      │
│                   (Port 6502)                            │
└─────────────────────────────────────────────────────────┘

Key Files

File	Purpose
`src/index.ts`	MCP server, tool definitions, semantic layer
`src/protocol/client.ts`	VICE binary monitor client
`src/protocol/types.ts`	Protocol constants and types
`src/utils/c64.ts`	C64 utilities (PETSCII, colors, VIC banks)
`src/utils/disasm.ts`	6502 disassembler with all addressing modes

Design Principles

Semantic over raw: Return interpreted data, not just bytes
Hints everywhere: Every response suggests next actions
Cross-references: Tools reference related tools
Fail informatively: Errors explain what went wrong and how to fix it
Agent-first: Designed for autonomous operation, not human CLI use

Protocol Reference

vice-mcp implements the VICE Binary Monitor Protocol. Key commands used:

Code	Command	Purpose
0x01	MemoryGet	Read memory
0x02	MemorySet	Write memory
0x12	CheckpointSet	Create breakpoint/watchpoint
0x13	CheckpointDelete	Remove checkpoint
0x15	CheckpointToggle	Enable/disable checkpoint
0x31	RegistersGet	Read CPU registers
0x41	Dump	Save snapshot
0x42	Undump	Load snapshot
0x81	Continue	Resume execution
0x82	Step	Single-step
0x84	DisplayGet	Capture screen
0x91	PaletteGet	Get color palette
0xdd	AutoStart	Load and run program

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
src		src
test		test
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
test-binary-protocol.js		test-binary-protocol.js
tsconfig.json		tsconfig.json

simen/vice-mcp

Folders and files

Latest commit

History

Repository files navigation