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.

Configuration

The server reads configuration in this order:

1. C64BRIDGE_CONFIG environment variable containing the path of the config file

2. .c64bridge.json in the project root

3. ~/.c64bridge.json in your home directory

C64 Ultimate

Use this for a C64 Ultimate:

{
  "c64u": {
    "host": "c64u",
    "port": 80,
    "networkPassword": "secret"
  }
}

• If no file is found, it defaults to c64u:80 and no network password.
• A networkPassword is only required if you specified one in the C64 Ultimate menu under Network Settings.

VICE

Use this for VICE:

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

VS Code MCP Setup

If this repository is checked out locally, simply open the prepared .vscode/mcp.json. Otherwise, put the following text in your .vscode/mcp.json:

{
  "servers": {
    "c64bridge": {
      "command": "npx",
      "args": [
        "-y",
        "c64bridge@latest"
      ]
    }
  }
}

Then click the "Start" icon that appears above the c64bridge server entry.

Your C64 Bridge MCP server should now be running:

For more details, see the official VS Code MCP Server documentation.

Enable The C64 Agent

After the MCP server is running, switch to the C64 agent in VS Code.

This agent is useful because it is preconfigured for Commodore 64 tasks. It steers Copilot toward c64bridge workflows for BASIC, 6502 assembly, SID audio, VIC-II graphics, memory inspection, disk operations, printing, streaming, and device control.

Optional Overrides

You can add env entries in .vscode/mcp.json to select a config file or force a backend:

{
  "servers": {
    "c64bridge": {
      "command": "npx",
      "args": [
        "-y",
        "c64bridge@latest"
      ],
      "env": {
        "C64BRIDGE_CONFIG": "/home/you/.c64bridge.json",
        "C64_MODE": "c64u",
        "LOG_LEVEL": "debug",
      }
    }
  }
}

• C64BRIDGE_CONFIG points to a specific config file.
• C64_MODE forces c64u or vice.
• LOG_LEVEL=debug enables verbose logging.

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 (minimum 90%)

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.

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