chrisgleissner/c64bridge

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

• — development workflow and RAG details
• — primer injected ahead of prompts
• — REST surface (OpenAPI 3.1)
• — 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.

c64_disk

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

c64_drive

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

c64_extract

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

c64_graphics

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

c64_memory

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

c64_printer

Grouped entry point for Commodore and Epson printing helpers.

c64_program

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

c64_rag

Grouped entry point for BASIC and assembly RAG lookups.

c64_sound

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

c64_stream

Grouped entry point for starting and stopping Ultimate streaming sessions.

c64_system

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

Resources

Prompts