C64 Bridge

What is C64 Bridge about?

C64 Bridge provides an MCP server that gives AI agents a single entry point to drive program execution, read/write memory, render graphics, play SID music, manage drives, printers and more on a Commodore 64. It works with real C64 Ultimate/Ultimate 64 hardware and can switch at runtime to a VICE emulator, allowing the same workflow across both platforms.

How to use C64 Bridge?

1. Install Node.js (v24+) on your machine.
2. Start the server with the published npm package:

   npx -y c64bridge
   

3. Configure the backend – either via a JSON file (.c64bridge.json or ~/.c64bridge.json) or by setting environment variables such as C64_MODE, C64U_HOST, VICE_BINARY, etc.
4. Connect from an MCP client (VS Code Copilot, Claude Code, Cursor, etc.) using the standard stdio entry point. The client can then call tools like c64_program, c64_memory, c64_graphics, c64_sound, etc.

Key Features

• Run BASIC, 6510 assembly or PRG/CRT programs.
• Full RAM access: read, write, compare, disassemble, and screen polling.
• Graphics tools: frame capture, bitmap rendering, PETSCII art generation.
• SID music suite: generate, compile, play, capture samples, and verify audio.
• Disk and drive management: mount/unmount images, create disks, power control.
• Printer support for Commodore and Epson printers.
• Backend switching at runtime with c64_select_backend.
• Optional HTTP bridge for manual testing (disabled by default).
• Integrated RAG knowledge base for BASIC and assembly reference look‑ups.

Use Cases

• Automated generation of C64 demos or games driven by LLMs.
• Remote debugging of C64 hardware from VS Code.
• Educational tools that let students experiment with 6502 assembly via chat interfaces.
• Continuous‑integration pipelines that verify graphics or SID output across hardware and emulator.
• Batch processing of disk images, sprite extraction, or character‑set analysis.

FAQ

Q: Do I need a C64 Ultimate to use the server? A: No. The server works with VICE as a fully‑featured emulator. If a hardware device is present, you can switch to it at runtime.

Q: Which operating systems are supported? A: Linux, macOS and Windows. The npm package includes pre‑built binaries for VICE and works with the C64 Ultimate network API.

Q: How are environment variables used? A: Variables like C64_MODE, C64U_HOST, VICE_BINARY, LOG_LEVEL, etc., override corresponding JSON configuration fields, allowing quick per‑session changes without editing files.

Q: Can I integrate C64 Bridge into my own application? A: Yes. The server exposes a standard MCP stdio interface; you can spawn it as a child process and communicate using the generated tool schemas.

Q: Is there a way to run the server without installing Node globally? A: You can use npx which fetches the package on‑the‑fly, so no global install is required.

C64 Bridge

Your AI Command Bridge for the Commodore 64.

C64 Bridge is an MCP server for controlling and working with a Commodore 64 from an AI client.

It lets you run programs, read and write memory, render graphics, and play sound on a real Commodore 64 Ultimate or Ultimate 64. You can also switch to a VICE emulator session at any time, so the same MCP conversation works with both hardware and emulator.

It is built on the official TypeScript @modelcontextprotocol/sdk and supports both stdio for local AI integration and an optional HTTP bridge for manual inspection.

C64 Bridge is listed in the Official MCP Registry.

Contents

• C64 Bridge
  • Contents
  • Overview
  • Features
  • Quick Start
    • 1. Install Node.js 24+ and npm
    • 2. Start the Server
    • 3. Add Backend Configuration
    • 4. Connect from an MCP Client
  • Configuration
    • Configuration File Order
    • Configuration Merge Rules
    • Backend Configuration: C64 Ultimate
    • Backend Configuration: VICE
    • Runtime Backend Switching
  • VS Code MCP Setup
    • Enable the C64 Agent
    • Optional Overrides
    • Environment Variables in MCP Client Configs
    • Runtime Environment Variable Reference
      • Server Runtime
      • C64 Ultimate
      • VICE Runtime
      • VICE Audio Capture
      • SID Playback
      • RAG
      • Testing
  • Claude Code
  • Example Workflow
  • HTTP Invocation
  • Build and Test
  • Documentation
  • Static MCP Interface
  • MCP API Reference
    • Tools
      • c64_batch
      • c64_config
      • c64_debug
      • c64_disk
      • c64_drive
      • c64_extract
      • c64_graphics
      • c64_input
      • c64_memory
      • c64_printer
      • c64_program
      • c64_rag
      • c64_select_backend
      • c64_sound
      • c64_stream
      • c64_system
      • c64_vice
    • Resources
    • Prompts

Overview

C64 Bridge gives an AI agent one place to drive program execution, memory access, graphics, sound, storage, printer workflows, and knowledge retrieval for a Commodore 64 environment.

The core workflow is simple:

1. Start the MCP server.
2. Point it at C64 Ultimate hardware, VICE, or both.
3. Let the client call grouped MCP tools such as c64_program, c64_memory, c64_graphics, and c64_sound.
4. Switch backends at runtime with c64_select_backend when both are configured.

Features

• Program runners for BASIC, 6510 assembly, and PRG or CRT execution
• Full memory access, including raw reads and writes plus screen polling
• System integration for drives, files, printers, and task orchestration
• SID music tools for playback, composition, generation, and verification
• Built-in knowledge resources and prompts for safer LLM workflows
• Mixed runtime support for hardware c64u and emulator vice

Quick Start

If you want the shortest path, do these four things:

1. Install Node.js 24+ and npm.
2. Start the server.
3. Add backend configuration for C64 Ultimate, VICE, or both.
4. Connect from VS Code or another MCP client.

1. Install Node.js 24+ and npm

Linux (Ubuntu or 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:

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 the installation:

node --version

Expected result: v24.x

2. Start the Server

Use one of the following entry points.

Run from npx with zero setup:

npx -y c64bridge@latest

Run from a local npm install:

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

Run from source for development or testing:

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

On startup, the server probes the selected target, performs connectivity checks, and then announces that it is running on stdio.

3. Add Backend Configuration

The server can run against:

• only C64 Ultimate hardware
• only VICE
• both backends in one session, with runtime switching

The detailed lookup order, merge rules, backend examples, and override model are in the Configuration section below.

4. Connect from an MCP Client

C64 Bridge ships a single canonical stdio entry point that every MCP client uses:

• VS Code (GitHub Copilot) — see VS Code MCP Setup.
• Claude Code (CLI and VS Code plugin) — see Claude Code.
• Cursor, Visual Studio, VS Code Insiders — use the install badges at the top of this README.
• Any other MCP client — point it at the same stdio server, with the environment variables documented in Runtime Environment Variable Reference and the registry manifest in mcp.json.

The startup command is the same across clients: npx -y c64bridge@latest for the published package, or node scripts/start.mjs from a local checkout. Backend selection (c64u vs vice) and credentials live in the shared Configuration files and environment variables — clients only need to know the command.

Configuration

Configuration File Order

The server reads configuration in this order:

1. C64BRIDGE_CONFIG, if it points to a config file
2. .c64bridge.json in the project root
3. ~/.c64bridge.json in the home directory

Configuration Merge Rules

Configuration is merged per backend section while scanning those files in order.

• The first file that contains a c64u section supplies the C64 Ultimate configuration.
• The first file that contains a vice section supplies the VICE configuration.
• This allows a project-local .c64bridge.json to define c64u while ~/.c64bridge.json defines vice, with both backends available at runtime.

Backend Configuration: C64 Ultimate

Use this for a C64 Ultimate or Ultimate 64:

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

• If no file is found, the default target is c64u:80 with no network password.
• networkPassword is only needed when you enabled a password in the C64 Ultimate network settings.
• C64U_HOST, C64U_PORT, and C64U_PASSWORD override the configured host, port, and network password.

Backend Configuration: VICE

Use this for managed VICE launches:

{
  "vice": {
    "exe": "/usr/bin/x64sc",
    "directory": "/usr/local/share/vice"
  }
}

• directory is optional. When omitted, C64 Bridge auto-detects a VICE resource directory by looking for the standard C64 ROM set near the emulator binary and in common system locations.
• VICE_BINARY, VICE_DIRECTORY, VICE_HOST, VICE_PORT, VICE_VISIBLE, VICE_WARP, and VICE_ARGS override managed VICE startup without editing config files.
• If no explicit binary is configured, the runtime prefers /usr/local/bin/x64sc when present, then falls back to x64sc or x64 on PATH so the same setup remains portable across operating systems.

[!NOTE] VICE supports only the operations marked with a VICE checkmark in the MCP API Reference. Unsupported operations return unsupported_platform.

Runtime Backend Switching

When both c64u and vice are configured, C64 Bridge starts with one active backend and keeps the other available for runtime switching.

• C64_MODE chooses the initial backend: c64u or vice
• c64_select_backend switches backends without restarting the MCP server
• c64://platform/status reports the active backend and the full configured backend set
• In prompts, say things like use vice, vice: run this program, use c64u, or run this on the real machine
• In VS Code, include the backend preference in the same prompt when you want to force emulator versus hardware execution

Prompt illustration (issued via Copilot in VS Code, using GPT 5.4 Medium):

c64u: write a small BASIC program that clears the screen and prints HELLO C64U

vice: write a small BASIC program that clears the screen and prints HELLO VICE

The screenshots below were captured from actual backend bitmap responses after those prompts ran, using the same c64_graphics capture_frame MCP tool on both backends. The C64U implementation captures streamed video frames, while the VICE implementation captures and normalizes the emulator display frame. Both images were then verified optically against the expected text with the C64 character generator, and both matched exactly.

Backend	Screenshot
C64 Ultimate
VICE

VS Code MCP Setup

This section covers the GitHub Copilot integration that ships with VS Code. For the Claude Code VS Code plugin, see Claude Code — it reads .mcp.json, not .vscode/mcp.json.

If this repository is checked out locally, open the prepared .vscode/mcp.json.

Otherwise, put the following into your own .vscode/mcp.json:

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

Then click the start button shown above the c64bridge entry.

Your MCP server should now be running:

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

Enable the C64 Agent

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

This agent is preconfigured for Commodore 64 work. 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, override C64 Ultimate connection details, or force an initial backend:

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

• C64BRIDGE_CONFIG points to a specific config file
• C64U_HOST, C64U_PORT, and C64U_PASSWORD override the C64 Ultimate connection without editing config files
• C64_MODE forces the initial backend to c64u or vice
• LOG_LEVEL=debug enables verbose logging

Environment Variables in MCP Client Configs

Every runtime environment variable documented in the root mcp.json can be supplied by your MCP client configuration, including .vscode/mcp.json under servers.c64bridge.env.

When an environment variable maps to a JSON config field, the override order is always:

1. the explicit environment variable from your MCP client config or shell
2. the merged JSON config section loaded from C64BRIDGE_CONFIG, the repo .c64bridge.json, then ~/.c64bridge.json
3. the built-in default compiled into the server

When an environment variable has no JSON config equivalent, the order is:

1. the explicit environment variable from your MCP client config or shell
2. the built-in default

That rule applies uniformly across the documented runtime environment variables below.

Example: visible VICE with a specific ROM or resource directory, plus a hardware fallback that can still be selected instantly at runtime:

{
  "servers": {
    "c64bridge": {
      "command": "node",
      "args": ["${workspaceFolder}/scripts/start.mjs"],
      "type": "stdio",
      "env": {
        "C64_MODE": "vice",
        "C64U_HOST": "c64u",
        "C64U_PORT": "80",
        "VICE_BINARY": "/usr/local/bin/x64sc",
        "VICE_DIRECTORY": "/usr/local/share/vice",
        "VICE_VISIBLE": "true",
        "VICE_WARP": "false"
      }
    }
  }
}

Example: keep JSON config files for backend endpoints, but override diagnostics, polling, and RAG behavior from VS Code:

{
  "servers": {
    "c64bridge": {
      "command": "node",
      "args": ["${workspaceFolder}/scripts/start.mjs"],
      "type": "stdio",
      "env": {
        "C64BRIDGE_CONFIG": "/home/you/.c64bridge.json",
        "LOG_LEVEL": "debug",
        "C64BRIDGE_POLL_MAX_MS": "8000",
        "C64BRIDGE_POLL_INTERVAL_MS": "200",
        "RAG_BUILD_ON_START": "1",
        "RAG_EMBEDDINGS_DIR": "/home/you/c64bridge-data"
      }
    }
  }
}

Runtime Environment Variable Reference

Every runtime environment variable documented in mcp.json can be set in your MCP client configuration, including .vscode/mcp.json under servers.c64bridge.env.

Server Runtime

Variable	Default	JSON Config Key	Description
C64_MODE	c64u	—	Select active backend (c64u for Ultimate hardware, vice for emulator)
C64_TASK_STATE_FILE	auto	—	Override the path used to persist MCP background-task state
C64BRIDGE_CONFIG	~/.c64bridge.json	config path	Path to configuration JSON
C64BRIDGE_DIAGNOSTICS_DIR	~/.c64bridge/diagnostics	—	Override the directory where persistent MCP diagnostics files are written
C64BRIDGE_DISABLE_DIAGNOSTICS	0	—	Set to 1 to disable persistent diagnostics logging
C64BRIDGE_POLL_INTERVAL_MS	200	—	Interval between screen polls during program-output validation in normal runtime mode
C64BRIDGE_POLL_MAX_MS	2000	—	Maximum time to poll for program-output validation before timing out in normal runtime mode
C64BRIDGE_POLL_STABILIZE_MS	100	—	Extra settle time after a successful poll match before considering output stable
LOG_LEVEL	info	—	Logger verbosity (debug, info, warn, error)

C64 Ultimate

Variable	Default	JSON Config Key	Description
C64U_HOST	c64u	c64u.host	Override the C64 Ultimate host name or IP address
C64U_PASSWORD		c64u.networkPassword	Override the C64 Ultimate network password sent as X-Password
C64U_PORT	80	c64u.port	Override the C64 Ultimate REST port

VICE Runtime

Variable	Default	JSON Config Key	Description
DISABLE_XVFB	0	—	Set to 1 to disable Xvfb fallback and use the current display only
FORCE_XVFB	0	—	Set to 1 to force managed VICE launches to run under Xvfb
VICE_ARGS		vice.args	Extra command-line arguments forwarded to managed VICE launches
VICE_BINARY	x64sc	vice.exe	VICE binary to launch for managed emulator sessions and audio capture; automatic search is used only when this override is missing or invalid
VICE_DIRECTORY	auto-detect	vice.directory	Override the VICE resource directory used for ROM and UI asset discovery; automatic search is used only when this override is missing or invalid
VICE_HOST	127.0.0.1	vice.host	Override the VICE Binary Monitor host
VICE_PORT	6502	vice.port	Override the VICE Binary Monitor port
VICE_VISIBLE	true	vice.visible	Launch VICE visibly on the desktop instead of headless/Xvfb when possible
VICE_WARP	false when visible, true when headless	vice.warp	Enable warp mode for managed VICE sessions
VICE_XVFB_DISPLAY	:99	—	Display number to use when managed VICE launches under Xvfb

VICE Audio Capture

Variable	Default	JSON Config Key	Description
VICE_LIMIT_CYCLES	120000000	—	Maximum CPU cycles to render when VICE generates audio
VICE_MODE	ntsc	—	Default video standard for VICE audio capture (ntsc|pal)
VICE_RUN_TIMEOUT_MS	10000	—	Timeout for headless VICE runs in milliseconds

SID Playback

Variable	Default	JSON Config Key	Description
SIDPLAY_BINARY	sidplayfp	—	sidplayfp binary to launch when generating audio
SIDPLAY_LIMIT_CYCLES	120000000	—	Maximum CPU cycles to render when sidplayfp generates audio
SIDPLAY_MODE	ntsc	—	Default SID playback mode (ntsc|pal)
SIDPLAYFP_BINARY		—	Legacy alias for SIDPLAY_BINARY (sidplayfp executable name)

RAG

Variable	Default	JSON Config Key	Description
GITHUB_TOKEN		—	Personal access token used for optional RAG discovery against GitHub
RAG_BUILD_ON_START	0	—	Set to 1 to rebuild embeddings on server start
RAG_DISCOVER_FORCE_REFRESH	0	—	Set to 1 to ignore cached discovery results when fetching external docs
RAG_DOC_FILES		—	Comma-separated extra docs to include in RAG
RAG_EMBEDDINGS_DIR	data	—	Directory containing RAG embedding JSON files
RAG_REINDEX_INTERVAL_MS	0	—	Periodic reindex interval in ms (0 disables)

Testing

Variable	Default	JSON Config Key	Description
C64_TEST_TARGET		—	Overrides integration tests to hit mock or real hardware (mock|real)

Claude Code

Claude Code is supported as a first-class MCP client. It uses the same canonical start command and the same backend Configuration files and environment variables as every other client — only the discovery file differs.

Claude Code CLI — register the published server in one command:

claude mcp add c64bridge -- npx -y c64bridge@latest

Use --scope user to make it available across all your projects, or --scope project to write a .mcp.json next to the current repo. Backend selection (c64u vs vice), host, port, and password come from the same files documented in Configuration; per-shell overrides come from the variables in Runtime Environment Variable Reference.

Project-scoped discovery — this repository ships a checked-in .mcp.json that points Claude Code at the local source via node scripts/start.mjs. When you open the repo with claude (CLI or VS Code plugin), Claude Code prompts to enable the project-scoped server on first run. Approve it once and the c64_* tools become discoverable in that workspace.

Claude Code VS Code plugin — the plugin reads the same .mcp.json and the same user-scope claude mcp add registrations as the CLI. No extra setup is required beyond installing the plugin and approving the project server prompt. The existing .vscode/mcp.json is read by GitHub Copilot, not by Claude Code; the two files coexist without conflict because they target different clients with different config schemas.

Verify it works — after registration, run claude mcp list (CLI) or open the MCP panel (plugin) and look for c64bridge. Then ask Claude Code something like “use vice: write a small BASIC program that clears the screen and prints HELLO CLAUDE” — it should call c64_select_backend and c64_program directly. If tools do not appear, confirm Node 24+ is on PATH, that the server was approved at the requested scope, and that the backend is reachable per the Configuration section.

Example Workflow

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

Then render PETSCII art for it:

This is representative of the intended workflow:

1. Ask the MCP client to generate or refine C64-oriented content.
2. Use grouped tools such as c64_program, c64_graphics, and c64_sound to execute it.
3. Verify the result via screen reads, frame capture, memory inspection, or audio analysis.

HTTP Invocation

• Preferred transport is stdio.
• The HTTP bridge is disabled by default and is intended only for manual testing.
• The following curl commands are illustrative so you can see what grouped MCP calls look like over HTTP.

# 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 and Test

The ./build script at the project root wraps all development tasks behind a single, self-documented interface:

./build --help                                       # full command reference
./build                                              # install + build + test matrix (full CI run)
./build --skip-tests                                 # install + build only
./build build                                        # TypeScript compile + doc generation
./build test                                         # integration tests (mock backend)
./build test --real                                  # test against real hardware
./build test --platform vice --target mock           # single test leg
./build test:matrix                                  # full matrix (c64u/mock · vice/mock · vice/device)
./build coverage                                     # merged coverage report
./build coverage:single --platform c64u --target mock
./build check                                        # build + test matrix (no install)
./build rag:rebuild                                  # rebuild RAG embeddings
./build release --version 1.2.3                      # prepare a release

Starting the MCP server is not managed by ./build. Use npm start (from source) or npx -y c64bridge@latest (published package) as shown in the Quick Start section above.

Documentation

• DeepWiki - architecture and implementation overview
• 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

Static MCP Interface

The repository contains an auto-generated static mirror of the MCP server interface in the ./mcp folder.

This allows agents to inspect the available tools, resources, prompts, and schemas without connecting to the server.

MCP API Reference

This MCP server exposes 17 tools, 26 resources, and 10 prompts for controlling your Commodore 64.

Tools

Address range convention: address + length means start address plus byte count; startAddress + endAddress means inclusive bounds.

c64_batch

Execute multiple c64bridge tool calls in a single request. Reduces latency for multi-step workflows.

No operations defined.

c64_config

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

Operation	Description	Required Inputs	Optional Inputs	Notes	C64U	VICE
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	item	—	✅	✅
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	applyToFlash=false	—	✅	✅
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.	—	root="/", extensions=["prg","crt"], durationMs=5000, captureScreen=true, maxPrograms=10, outputPath, resetDelayMs=100	—	✅
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_debug

Grouped entry point for VICE debugger operations (breakpoints, registers, stepping).

Operation	Description	Required Inputs	Optional Inputs	Notes	C64U	VICE
continue_execution	Exit the Binary Monitor and resume CPU execution (BM 0xAA Exit).	—	—	—		✅
create_checkpoint	Create a new checkpoint (breakpoint) in VICE.	address	endAddress, stopOnHit=true, enabled=true, temporary=false, label, operations, memspace	—		✅
delete_checkpoint	Remove a checkpoint by id.	id	—	—		✅
get_checkpoint	Fetch a single checkpoint by id.	id	—	—		✅
get_monitor_state	Read CPU registers and return the current monitor state.	—	memspace	—		✅
get_registers	Read register values, optionally filtered by name or id.	—	memspace, registers	—		✅
list_checkpoints	List all active VICE checkpoints (breakpoints).	—	—	—		✅
list_registers	List available registers (metadata).	—	memspace	—		✅
nuclear_reset	Kill and restart the VICE process (managed instances only).	—	—	—		✅
set_condition	Attach a conditional expression to a checkpoint.	id, expression	—	—		✅
set_registers	Write register values.	writes	memspace	—		✅
step	Single-step CPU execution.	—	count=1, mode	—		✅
step_return	Continue execution until the current routine returns.	—	—	—		✅
toggle_checkpoint	Enable or disable a checkpoint by id.	id, enabled	—	—		✅
wait_for_state	Poll CPU registers until PC equals expectedPC or timeout elapses.	—	expectedPC, timeoutMs=5000, pollMs=100	—		✅

c64_disk

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

Operation	Description	Required Inputs	Optional Inputs	Notes	C64U	VICE
create_image	Create a blank disk image of the specified format.	format, path	diskname, tracks	—	✅
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	root="/", extensions, caseInsensitive=true, sort="discovered", waitMs=0, captureCandidates=10	—	✅
list_drives	List Ultimate drive slots and their mounted images.	—	—	—	✅	✅
mount	Mount a disk image with optional verification and retries.	drive, image	type, attachmentMode, driveMode, verify=false, powerOnIfNeeded=true, resetAfterMount=true, maxRetries=2, retryDelayMs=500	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	Optional Inputs	Notes	C64U	VICE
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	Optional Inputs	Notes	C64U	VICE
charset	Locate and extract 2KB character sets from RAM.	—	address, scanRange="common", outputPath, pauseDuringRead=true, minNonEmptyChars=32, minEntropy=0.3	—	✅
firmware_health	Run firmware readiness checks and report status metrics.	—	—	—	✅
fs_stats	Walk the filesystem and aggregate counts/bytes by extension.	—	root="/", extensions, includeContainers=true, maxSamplesPerExtension=3	—	✅
memory_dump	Dump a RAM range to hex or binary files with manifest metadata.	address, length, outputPath	format="hex", chunkSize=512, pauseDuringRead=true, retries=1	—	✅
sprites	Scan RAM for sprites and optionally export .spr files.	address, length	stride=64, maxSprites=16, minNonZeroRows=4, minSetBits=12, includeBase64=true, outputDir, pauseDuringRead=true	—	✅

c64_graphics

Grouped entry point for frame capture and graphics rendering workflows.

Operation	Description	Required Inputs	Optional Inputs	Notes	C64U	VICE
capture_frame	Capture one or more complete video frames from the active backend.	—	count=1, includePixels=true, encoding="base64"	—	✅	✅
get_display_state	Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. Works on C64U and VICE; both backends are read through shared memory primitives so the response shape is identical.	—	—	—	✅	✅
render_bitmap	Import an image file, convert it to VIC-II bitmap memory, write it into RAM, and display it.	imagePath, format	bitmapAddress=8192, screenAddress=1024, borderColor=0, backgroundColor=0, preserveAspect=true	—	✅	✅
render_petscii_art	Create PETSCII art from prompts, text, or explicit bitmap data, and optionally display it on the C64.	—	prompt, text, maxWidth, maxHeight, borderColor, backgroundColor, foregroundColor, dryRun=false, bitmap	—	✅	✅
render_petscii_text	Display PETSCII text with optional border and background colours.	text	borderColor, backgroundColor	—	✅	✅
render_sprite	Display supplied 63-byte sprite data at the requested position and colour by writing memory and patching VIC-II registers directly.	sprite	index=0, x=100, y=100, color=1, multicolour=false	—	✅	✅

c64_input

Keyboard buffer injection (cross-platform) and joystick simulation (VICE only).

Operation	Description	Required Inputs	Optional Inputs	Notes	C64U	VICE
joystick	Simulate joystick input by writing directly to CIA1 Port A/B registers.	port, controls, action	durationMs=80	—		✅
key	Tap a single key or hold it for a duration.	key	durationMs=0, count=1	—	✅	✅
write_text	Send a text string to the keyboard buffer, with PETSCII token expansion.	text	delayMs=0	—	✅	✅

c64_memory

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

Operation	Description	Required Inputs	Optional Inputs	Notes	C64U	VICE
compare_memory	Compare two memory regions byte-by-byte and report differences.	address1, address2, length	maxDiffs=10	—	✅	✅
copy_memory	Copy a RAM region to another address.	source, dest, length	—	—	✅	✅
disassemble	Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from .vs files are applied when available. Works on both C64U and VICE.	address	length=64, instructionCount	—	✅	✅
fill_memory	Fill a memory range with a repeating byte pattern.	address, length, pattern	—	—	✅	✅
read	Read a range of bytes and return a hex dump with address metadata.	address	length=256	—	✅	✅
read_screen	Return the current 40x25 text screen converted to ASCII.	—	—	—	✅	✅
save_memory	Dump a memory range to a local file, with an optional PRG load-address header.	startAddress, endAddress, filePath	asPrg=true	—	✅	✅
search_memory	Search for a byte pattern within a memory range and return matching addresses.	startAddress, endAddress, pattern	maxResults=10	—	✅	✅
wait_for_text	Poll the screen until a substring or regex appears, or timeout elapses.	pattern	isRegex=false, caseInsensitive=true, timeoutMs=3000, intervalMs=100	—	✅	✅
write	Write a hexadecimal byte sequence into RAM.	address, bytes	verify=false, expected, mask, abortOnMismatch=true	supports verify	✅	✅

c64_printer

Grouped entry point for Commodore and Epson printing helpers.

Operation	Description	Required Inputs	Optional Inputs	Notes	C64U	VICE
define_chars	Define custom printer characters (Commodore DLL mode).	firstChar, chars	secondaryAddress	—	✅
print_bitmap	Print a bitmap row via Commodore (BIM) or Epson ESC/P workflows.	printer="commodore", columns	repeats, useSubRepeat, secondaryAddress, ensureMsb=true, mode, density, timesPerLine	—	✅
print_text	Generate BASIC that prints text to device 4.	text	target="commodore", secondaryAddress, formFeed=false	—	✅

c64_program

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

Operation	Description	Required Inputs	Optional Inputs	Notes	C64U	VICE
batch_run	Run multiple PRG/CRT programs with post-run assertions.	programs	continueOnError=false, durationMs=2000, outputPath, resetDelayMs=100	—	✅	✅
bundle_run	Capture screen, memory, and debug registers into an artifact bundle.	runId, outputPath	captureScreen=true, memoryRanges, captureDebugReg=true	—	✅
cross_platform_greeting	Show a platform-customized greeting on one or more configured backends, capture screenshots, and verify the results.	—	platforms=["vice","c64u"], messageTemplate="HAVE A GREAT DAY, {PLATFORM}!", verify=true, captureScreenshot=true, outputPath, restoreActiveBackend=true, timeoutMs=1500, pollIntervalMs=100	supports verify	✅	✅
load_prg	Load a PRG from Ultimate storage without executing it.	path	symbolsFile	—	✅
run_crt	Mount and run a CRT cartridge image.	path	—	—	✅
run_prg	Load and execute a PRG from Ultimate-visible storage on c64u or a host-local path on VICE.	path	symbolsFile	—	✅	✅
upload_run_asm	Assemble 6502/6510 source, upload the PRG, and execute it.	program	verify=false	supports verify	✅	✅
upload_run_basic	Upload Commodore BASIC v2 source and execute it immediately.	program	verify=false	supports verify	✅	✅

c64_rag

Grouped entry point for BASIC and assembly RAG lookups.

Operation	Description	Required Inputs	Optional Inputs	Notes	C64U	VICE
asm	Retrieve 6502/6510 assembly references from the local knowledge base.	q	k=3	—	✅	✅
basic	Retrieve BASIC references and snippets from the local knowledge base.	q	k=3	—	✅	✅

c64_select_backend

Switch the active backend between C64U hardware and the VICE emulator at runtime.

Operation	Description	Required Inputs	Optional Inputs	Notes	C64U	VICE
select	Switch the active runtime backend without restarting the MCP server.	backend	—	—	✅	✅

c64_sound

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

Operation	Description	Required Inputs	Optional Inputs	Notes	C64U	VICE
analyze	Automatically analyze SID playback when verification is requested.	request	durationSeconds, expectedSidwave	—	✅
capture_samples	Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream.	—	count=256, encoding="base64"	—	✅
compile_play	Compile SIDWAVE or CPG source and optionally play it immediately.	—	sidwave, cpg, format, output="prg", dryRun=false	—	✅	✅
generate	Generate a lightweight SID arpeggio playback sequence.	—	root="C4", pattern="0,4,7", steps=16, tempoMs=120, waveform="tri", preset="classic"	—	✅	✅
note_off	Release a SID voice by clearing its gate bit.	voice	—	—	✅	✅
note_on	Trigger a SID voice with configurable waveform, ADSR, and pitch.	—	voice=1, note, frequencyHz, system="PAL", waveform="pulse", pulseWidth=2048, attack=1, decay=1, sustain=15, release=3	—	✅	✅
pipeline	Compile a SIDWAVE score, play it, and analyze the recording.	—	sidwave, cpg, output="prg", waitBeforeCaptureMs=500, analysisDurationSeconds=3, expectedSidwave, verifySilenceBefore=true, verifySilenceAfter=true, silenceDurationSeconds=1.5, silenceRmsThreshold=0.02, postSilenceWaitMs=200, silenceWaitMs=150	supports verify	✅
play_mod_file	Play a MOD tracker module via the Ultimate SID player.	path	—	—	✅
play_preset	Compile and play a built-in SID preset such as Für Elise by Beethoven.	—	preset="fuer_elise", platforms, verify=true, analysisDurationSeconds=4, waitBeforeCaptureMs=400, restoreActiveBackend=true	supports verify	✅	✅
play_sid_file	Play a SID file stored on the Ultimate filesystem.	path	songnr	—	✅
record_analyze	Record audio for a fixed duration and return SID analysis metrics.	durationSeconds	expectedSidwave	—	✅
reset	Soft or hard reset of SID registers to clear glitches.	—	hard=false	—	✅	✅
set_volume	Set the SID master volume register at $D418 (0-15).	volume	—	—	✅	✅
silence_all	Silence all SID voices with optional audio verification.	—	verify=false	supports verify	✅	✅

c64_stream

Grouped entry point for starting and stopping Ultimate streaming sessions.

Operation	Description	Required Inputs	Optional Inputs	Notes	C64U	VICE
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	Optional Inputs	Notes	C64U	VICE
list_tasks	List known background tasks with status metadata.	—	—	—	✅	✅
menu	Toggle the Ultimate menu button for navigation.	—	—	—	✅
pause	Pause the machine until resumed.	—	—	—	✅
performance_report	Summarize diagnostics spans and tool latencies from the current or latest MCP session.	—	scope="current", includeTimeline=true, maxEntries=25	—	✅	✅
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 pause.	—	—	—	✅
start_task	Start a named background task that runs on an interval.	name, operation	arguments={}, intervalMs=1000, maxIterations	—	✅	✅
stop_all_tasks	Stop every running background task and persist state.	—	—	—	✅	✅
stop_task	Stop a specific background task and clear its timer.	name	—	—	✅	✅

c64_vice

Grouped entry point for reading and updating selected VICE resources.

Operation	Description	Required Inputs	Optional Inputs	Notes	C64U	VICE
resource_get	Read a VICE configuration resource (safe prefixes only).	name	—	—		✅
resource_set	Write a VICE configuration resource (safe prefixes only).	name, value	—	—		✅

Resources

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

Prompts

Name	Description
assembly-program	Route 6502/6510 routine requests to the canonical assembly skill.
basic-program	Route bespoke Commodore BASIC v2 requests to the canonical BASIC skill.
cross-platform-demo	Route quick visible demo requests to the cross-platform demo skill.
drive-manager	Route disk-image and drive-state requests to the canonical drive skill.
graphics-demo	Route graphics requests to the canonical graphics skill.
hello-world	Route ultra-fast hello-world and smoke-test requests to the canonical greeting skill.
memory-debug	Route reversible memory inspection or patching work to the canonical memory skill.
preset-music-demo	Route quick recognizable tune requests to the SID music skill.
printer-job	Route printer work to the canonical printer skill.
sid-music	Route SID playback and composition work to the canonical SID skill.