vice-mcp/README.md

# 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

```bash
# 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)

```bash
npx @simen/vice-mcp
```

### From GitHub

```bash
npx github:simen/vice-mcp
```

### Local Development

```bash
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:**
```bash
x64sc -binarymonitor -binarymonitoraddress ip4://127.0.0.1:6502
```

**2. Add the MCP server:**
```bash
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`:

```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):

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

Or for local development:

```json
{
  "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:
```json
{
  "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

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

## Protocol Reference

vice-mcp implements the [VICE Binary Monitor Protocol](https://vice-emu.sourceforge.io/vice_13.html). 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