C64 Bridge

Your AI Command Bridge for the Commodore 64.

Overview

C64 Bridge is a Model Context Protocol (MCP) server that drives a real Commodore 64 Ultimate or Ultimate 64 over their REST APIs.

It is based on the official TypeScript @modelcontextprotocol/sdk and supports both stdio (for local AI integration) and HTTP (for remote access by other applications).

Features

• Program runners for BASIC, 6510 assembly, and PRG/CRT
• Full memory access — read/write operations and text monitoring
• System integration covering drives, files, and printers
• SID audio tools for composition, playback, and analysis
• Built-in knowledge base for smarter AI prompting using local examples and docs
• Multiple backends: hardware C64 Ultimate (primary) and experimental VICE runner

Quick Start

1. Install Node.js 24+ and npm

• Linux (Ubuntu/Debian)

  • Recommended:

    sudo apt update
    sudo apt install -y curl ca-certificates
    curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
    sudo apt install -y nodejs

  • Fallback (may be older): sudo apt install -y nodejs npm

• macOS

  brew install node@24
  brew link --overwrite node@24

• Windows

  # winget
  winget install OpenJS.NodeJS.LTS
  # or Chocolatey
  choco install nodejs-lts -y

Verify: node --version → v24.x

2. Run the server (choose one)

• npx (zero setup)

  npx -y c64bridge@latest

• npm (project‑local)

  mkdir -p ~/c64bridge && cd ~/c64bridge
  npm init -y
  npm install c64bridge
  node ./node_modules/c64bridge/dist/index.js

• From source (contributing/testing)

  git clone https://github.com/chrisgleissner/c64bridge.git
  cd c64bridge
  npm install
  npm start

On start, the server probes your target (REST + zero‑page read) and prints diagnostics before announcing that it is running on stdio.

Configure

Configuration is a JSON file resolved in this order (first match wins):

1. C64BRIDGE_CONFIG → absolute path
2. ~/.c64bridge.json
3. ./c64bridge.json

No file? Defaults to host=c64u, port=80.

Hardware (C64U) example:

{
  "c64u": { "host": "<hostname or IP>", "port": 80 }
}

Experimental VICE runner:

{
  "vice": { "exe": "/usr/bin/x64sc" }
}

Backend selection:

• C64_MODE=c64u|vice forces a choice
• Otherwise: if only one is configured, it’s used; with both, prefer c64u; with none, probe http://c64u then fall back to VICE

Logging: set LOG_LEVEL=debug (logs go to stderr; stdout is reserved for MCP).

GitHub Copilot Chat (VS Code)

VS Code (1.102+) and Copilot Chat (1.214+) support MCP. Either let VS Code auto‑discover, or add the server explicitly under Settings → GitHub Copilot → Experimental → MCP Servers (see AGENTS.md).

Example explicit entry:

{
  "github.copilot.chat.experimental.mcp": {
    "servers": [
      {
        "name": "c64bridge",
        "command": "node",
        "args": ["./node_modules/c64bridge/dist/index.js"],
        "type": "stdio"
      }
    ]
  }
}

Tips:

• If you’re in this repo, open .vscode/mcp.json and click Start to launch the server.
• In Chat, pick the “C64” chat mode and try: “Print a greeting on the screen”.

Screenshots:

Example

Compose a children’s song with ChatGPT + VS Code:

Then render PETSCII art for it:

HTTP Invocation

• Preferred transport is stdio. The HTTP bridge is disabled by default; enable it only for manual testing
• These curl commands are illustrative to show what happens under the hood when tools run.

# Upload and run BASIC
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"op":"upload_run_basic","program":"10 PRINT \"HELLO\"\n20 GOTO 10"}' \
  http://localhost:8000/tools/c64_program | jq

# Read current screen (PETSCII→ASCII)
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"op":"read_screen"}' \
  http://localhost:8000/tools/c64_memory | jq

# Reset the machine
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"op":"reset"}' \
  http://localhost:8000/tools/c64_system

Build & Test

• npm install (or bun install) — install deps
• npm start — dev server (ts-node)
• npm run build — type‑check and build
• npm test — integration tests (mock)
• npm test -- --real — target real hardware (reuses your config)
• npm run coverage — coverage via Bun harness

Documentation

• doc/developer.md — development workflow and RAG details
• data/context/bootstrap.md — primer injected ahead of prompts
• doc/c64u/c64-openapi.yaml — REST surface (OpenAPI 3.1)
• AGENTS.md — LLM-facing quick setup, usage, and personas

MCP API Reference

This MCP server exposes 12 tools, 25 resources, and 7 prompts for controlling your Commodore 64.

Tools

c64_config

Grouped entry point for configuration reads/writes, diagnostics, and snapshots.

| Operation | Description | Required Inputs | Notes | | --- | --- | --- | --- | | batch_update | Apply multiple configuration updates in a single request. | — | — | | diff | Compare the current configuration with a snapshot. | path | — | | get | Read a configuration category or specific item. | category | — | | info | Retrieve Ultimate hardware information and status. | — | — | | list | List configuration categories reported by the firmware. | — | — | | load_flash | Load configuration from flash storage. | — | — | | read_debugreg | Read the Ultimate debug register ($D7FF). | — | — | | reset_defaults | Reset firmware configuration to factory defaults. | — | — | | restore | Restore configuration from a snapshot file. | path | — | | save_flash | Persist the current configuration to flash storage. | — | — | | set | Write a configuration value in the selected category. | category, item, value | — | | shuffle | Discover PRG/CRT files and run each with optional screen capture. | — | — | | snapshot | Snapshot configuration to disk for later restore or diff. | path | — | | version | Fetch firmware version details. | — | — | | write_debugreg | Write a hex value to the Ultimate debug register ($D7FF). | value | — |

c64_disk

Grouped entry point for disk mounts, listings, image creation, and program discovery.

| Operation | Description | Required Inputs | Notes | | --- | --- | --- | --- | | create_image | Create a blank disk image of the specified format. | format, path | — | | file_info | Inspect metadata for a file on the Ultimate filesystem. | path | — | | find_and_run | Search for a PRG/CRT by name substring and run the first match. | nameContains | — | | list_drives | List Ultimate drive slots and their mounted images. | — | — | | mount | Mount a disk image with optional verification and retries. | drive, image | supports verify | | unmount | Remove the mounted image from an Ultimate drive slot. | drive | — |

c64_drive

Grouped entry point for drive power, mode, reset, and ROM operations.

| Operation | Description | Required Inputs | Notes | | --- | --- | --- | --- | | load_rom | Temporarily load a custom ROM into an Ultimate drive slot. | drive, path | — | | power_off | Power off a specific Ultimate drive slot. | drive | — | | power_on | Power on a specific Ultimate drive slot. | drive | — | | reset | Issue an IEC reset for the selected drive slot. | drive | — | | set_mode | Set the emulation mode for a drive slot (1541/1571/1581). | drive, mode | — |

c64_extract

Grouped entry point for sprite/charset extraction, memory dumps, filesystem stats, and firmware health checks.

| Operation | Description | Required Inputs | Notes | | --- | --- | --- | --- | | charset | Locate and extract 2KB character sets from RAM. | — | — | | firmware_health | Run firmware readiness checks and report status metrics. | — | — | | fs_stats | Walk the filesystem and aggregate counts/bytes by extension. | — | — | | memory_dump | Dump a RAM range to hex or binary files with manifest metadata. | address, length, outputPath | — | | sprites | Scan RAM for sprites and optionally export .spr files. | address, length | — |

c64_graphics

Grouped entry point for PETSCII art, sprite previews, and future bitmap generation.

| Operation | Description | Required Inputs | Notes | | --- | --- | --- | --- | | create_petscii | Generate PETSCII art from prompts, text, or explicit bitmap data. | — | — | | generate_bitmap | Reserved high-resolution bitmap generator (coming soon). | — | — | | generate_sprite | Build and run a sprite PRG from raw 63-byte sprite data. | sprite | — | | render_petscii | Render PETSCII text with optional border/background colours. | text | — |

c64_memory

Grouped entry point for memory I/O, screen reads, and screen polling.

| Operation | Description | Required Inputs | Notes | | --- | --- | --- | --- | | read | Read a range of bytes and return a hex dump with address metadata. | address | — | | read_screen | Return the current 40x25 text screen converted to ASCII. | — | — | | wait_for_text | Poll the screen until a substring or regex appears, or timeout elapses. | pattern | — | | write | Write a hexadecimal byte sequence into RAM. | address, bytes | supports verify |

c64_printer

Grouped entry point for Commodore and Epson printing helpers.

| Operation | Description | Required Inputs | Notes | | --- | --- | --- | --- | | define_chars | Define custom printer characters (Commodore DLL mode). | firstChar, chars | — | | print_bitmap | Print a bitmap row via Commodore (BIM) or Epson ESC/P workflows. | printer, columns | — | | print_text | Generate BASIC that prints text to device 4. | text | — |

c64_program

Grouped entry point for program upload, execution, and batch workflows.

| Operation | Description | Required Inputs | Notes | | --- | --- | --- | --- | | batch_run | Run multiple PRG/CRT programs with post-run assertions. | programs | — | | bundle_run | Capture screen, memory, and debug registers into an artifact bundle. | runId, outputPath | — | | load_prg | Load a PRG from Ultimate storage without executing it. | path | — | | run_crt | Mount and run a CRT cartridge image. | path | — | | run_prg | Load and execute a PRG located on the Ultimate filesystem. | path | — | | upload_run_asm | Assemble 6502/6510 source, upload the PRG, and execute it. | program | supports verify | | upload_run_basic | Upload Commodore BASIC v2 source and execute it immediately. | program | supports verify |

c64_rag

Grouped entry point for BASIC and assembly RAG lookups.

| Operation | Description | Required Inputs | Notes | | --- | --- | --- | --- | | asm | Retrieve 6502/6510 assembly references from the local knowledge base. | q | — | | basic | Retrieve BASIC references and snippets from the local knowledge base. | q | — |

c64_sound

Grouped entry point for SID control, playback, composition, and analysis workflows.

| Operation | Description | Required Inputs | Notes | | --- | --- | --- | --- | | analyze | Automatically analyze SID playback when verification is requested. | request | — | | compile_play | Compile SIDWAVE or CPG source and optionally play it immediately. | — | — | | generate | Generate a lightweight SID arpeggio playback sequence. | — | — | | note_off | Release a SID voice by clearing its gate bit. | voice | — | | note_on | Trigger a SID voice with configurable waveform, ADSR, and pitch. | — | — | | pipeline | Compile a SIDWAVE score, play it, and analyze the recording. | — | supports verify | | play_mod_file | Play a MOD tracker module via the Ultimate SID player. | path | — | | play_sid_file | Play a SID file stored on the Ultimate filesystem. | path | — | | record_analyze | Record audio for a fixed duration and return SID analysis metrics. | durationSeconds | — | | reset | Soft or hard reset of SID registers to clear glitches. | — | — | | set_volume | Set the SID master volume register at $D418 (0-15). | volume | — | | silence_all | Silence all SID voices with optional audio verification. | — | supports verify |

c64_stream

Grouped entry point for starting and stopping Ultimate streaming sessions.

| Operation | Description | Required Inputs | Notes | | --- | --- | --- | --- | | start | Start an Ultimate streaming session toward a host:port target. | stream, target | — | | stop | Stop an active Ultimate streaming session. | stream | — |

c64_system

Grouped entry point for power, reset, menu, and background task control.

| Operation | Description | Required Inputs | Notes | | --- | --- | --- | --- | | list_tasks | List known background tasks with status metadata. | — | — | | menu | Toggle the Ultimate menu button for navigation. | — | — | | pause | Pause the machine using DMA halt until resumed. | — | — | | poweroff | Request a controlled shutdown via the Ultimate firmware. | — | — | | reboot | Trigger a firmware reboot to recover from faults. | — | — | | reset | Issue a soft reset without cutting power. | — | — | | resume | Resume CPU execution after a DMA pause. | — | — | | start_task | Start a named background task that runs on an interval. | name, operation | — | | stop_all_tasks | Stop every running background task and persist state. | — | — | | stop_task | Stop a specific background task and clear its timer. | name | — |

Resources

| Name | Summary | | --- | --- | | c64://docs/index | Explains how to approach each knowledge bundle and when to consult it. | | c64://context/bootstrap | Step-by-step rules for safe automation, verification, and rollback on the C64. | | c64://specs/basic | Token definitions, syntax rules, and device I/O guidance for BASIC v2. | | c64://docs/basic/pitfalls | Quickref covering quotation handling, line length, tokenization, variable names, and other BASIC traps. | | c64://specs/assembly | Official opcode matrix, addressing modes, and zero-page strategy for the 6510 CPU. | | c64://specs/sid | Register map, waveform behaviour, and ADSR envelopes for expressive SID playback. | | c64://specs/sidwave | Defines the SIDWAVE interchange format used by the SID composer workflow. | | c64://docs/sid/file-structure | Explains PSID/RSID headers, metadata blocks, and compatibility notes for imported music. | | c64://docs/sid/best-practices | Captures proven waveforms, ADSR presets, phrasing, and verification workflow for pleasant SID music. | | c64://specs/vic | Covers raster timing, sprite control, colour RAM, and bitmap modes on the VIC-II. | | c64://specs/charset | Character code table mapping PETSCII codes to screen codes, glyphs, and keyboard input. | | c64://docs/petscii-style | Documents colour palette, readability presets, dithering patterns, and best practices for creating artistic and readable PETSCII displays. | | c64://docs/sprite-charset-workflows | Documents sprite and charset workflows, memory layout, VIC-II configuration, common pitfalls, and proven techniques for hardware-accelerated graphics. | | c64://specs/memory-map | Page-by-page breakdown of the 64 KB address space with hardware, ROM, and RAM regions. | | c64://specs/memory-low | Documents zero-page variables, BASIC pointers, and KERNAL workspace addresses. | | c64://specs/memory-kernal | Lists KERNAL ROM vectors and service routines for OS-level functionality. | | c64://specs/io | Covers VIC-II, SID, CIA, and system control registers with address ranges and usage notes. | | c64://specs/cia | Details CIA 1/2 registers, timers, interrupts, and keyboard matrix layout. | | c64://specs/printer | Covers device setup, control codes, and Ultimate 64 integration for printers. | | c64://docs/printer/guide | Quick-look workflow covering setup, troubleshooting, and sample jobs for both printer families. | | c64://docs/printer/commodore-text | Character sets, control codes, and formatting for Commodore MPS text output. | | c64://docs/printer/commodore-bitmap | Details bitmap modes, graphics commands, and data layout for MPS bitmap printing. | | c64://docs/printer/epson-text | Lists ESC/P control codes and formatting advice for Epson FX text output. | | c64://docs/printer/epson-bitmap | Explains bit-image modes, density options, and data packing for Epson bitmap jobs. | | c64://docs/printer/prompts | Reusable prompt templates that drive complex printer jobs through the MCP server. |

Prompts

| Name | Description | | --- | --- | | assembly-program | Author 6502/6510 assembly routines with precise hardware guidance. | | basic-program | Plan, implement, and verify Commodore BASIC v2 programs safely. | | drive-manager | Mount, create, or power drives while preserving running workloads. | | graphics-demo | Create VIC-II graphics demos with safe setup and validation steps. | | memory-debug | Inspect or patch memory ranges with reversible steps and logging. | | printer-job | Send formatted output to Commodore or Epson printers with safe teardown steps. | | sid-music | Compose SID music with expressive phrasing and iterative audio verification. |