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 C64 Ultimate, Ultimate 64, or U2-family cartridge. You can also switch to a VICE emulator session, so one MCP conversation can span hardware and emulation.
Built-in resources, skills, and RAG give your AI coding agent a head start with classic C64 programming and modern Ultimate features, including REU, CPU turbo, 10 SIDs, LED control, UCI networking, and UPIC full-colour border graphics.
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
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:
- Start the MCP server.
- Point it at C64U/U64 hardware, a U2-family cartridge, VICE, or any configured combination.
- Let the client call grouped MCP tools such as
c64_program, c64_memory, c64_graphics, and c64_sound.
- 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
c64u (C64U/U64), u2 (U2/U2+/U2+L), and vice
Quick Start
If you want the shortest path, do these four things:
- Install Node.js 24+ and npm.
- Start the server.
- Add backend configuration for C64U/U64, U2-family, VICE, or any combination.
- 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:
Expected result: v24.x
2. Start the Server
Use one of the following entry points.
Run from npx with zero setup:
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 one or more of:
- C64U/U64 hardware (
c64u)
- U2, U2+, or U2+L (
u2)
- VICE (
vice)
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. Select c64u, u2, or vice in the shared Configuration; clients only need the command.
Configuration
Configuration File Order
The server reads configuration in this order:
C64BRIDGE_CONFIG, if it points to a config file
.c64bridge.json in the project root
~/.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 each backend section (
c64u, u2, or vice) supplies that backend's configuration.
- This allows a project-local
.c64bridge.json to define c64u while ~/.c64bridge.json defines u2 or vice.
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.
The following operations require recently added Ultimate REST endpoints. C64 Bridge detects or explains unavailable endpoints without exposing a raw firmware error.
Before choosing an endpoint-dependent operation, read c64://platform/status. It probes machine:input safely and reports whether it is available. When native input is unavailable, use key or write_text for ordinary C64 input instead of physical matrix events. machine:menu_screen can only be confirmed after an Ultimate menu is visible; its tool returns fallback guidance rather than a transport error when no matrix can be read.
c64_input keyboard, release_all, and state, plus hardware joystick, use machine:input. They require a C64U firmware version that provides this endpoint, or U64 firmware 3.15 or later. machine:input is not available on U2-family cartridges.
c64_system read_menu_screen uses machine:menu_screen; it requires a C64U firmware version that provides this endpoint, or U64/U2 firmware 3.15 or later.
- On C64U/U64,
c64_system power_cycle verifies Tool Menu navigation with machine:menu_screen, so it has the same firmware requirement. U2-family power_cycle uses REST reboot instead.
Backend Configuration: U2-family
Use this profile for U2, U2+, and U2+L cartridges:
{
"u2": {
"host": "u2",
"port": 80,
"networkPassword": "secret"
}
}
Set C64_MODE=u2 to make this the initial backend. U2_HOST, U2_PORT, and U2_PASSWORD override this profile. U2-family firmware exposes the shared REST subset; it does not provide machine input, debug-register access, power-off, or streaming. read_menu_screen requires U2 firmware 3.15 or later.
Backend Configuration: VICE
C64 Bridge can either connect to an already running VICE Binary Monitor or manage a local VICE process for you. The usual managed setup only needs the emulator binary and, when auto-detection cannot find it, the VICE resource directory:
{
"vice": {
"exe": "/usr/bin/x64sc",
"directory": "/usr/local/share/vice"
}
}
exe is optional when x64sc or x64 is on PATH. If no explicit binary is configured, the runtime prefers /usr/local/bin/x64sc when present, then falls back to x64sc or x64 on PATH.
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.
host and port are optional and default to 127.0.0.1:6502, the Binary Monitor endpoint C64 Bridge starts for managed local sessions. On local endpoints, C64 Bridge first tries to reuse an already running monitor before starting its own process.
visible, warp, and args are optional runtime controls. They can live in JSON config, but most users set their environment-variable equivalents from the MCP client because they are per-session preferences.
- By default, VICE is started lazily on first access. When setting the environment variable
VICE_PREWARM=1, C64 Bridge starts or connects VICE in the background during MCP startup.
VICE_BINARY, VICE_DIRECTORY, VICE_HOST, VICE_PORT, VICE_VISIBLE, VICE_WARP, VICE_ARGS, and VICE_PREWARM override the JSON values without editing config files.
VICE Window Modes
Choose the window mode based on where the MCP server runs:
| Mode | Configuration | What happens | Use when |
|---|
| Visible | VICE_VISIBLE=true | VICE opens a normal desktop window. Warp defaults to off. | You are developing locally and want to watch or interact with the emulator. |
| Minimized | VICE_VISIBLE=true, VICE_ARGS="-minimized" | VICE still runs as a normal desktop app, but its window starts iconified. Binary Monitor operations, screen reads, frame capture, and keyboard input continue to work. | You are using an agent locally and do not want the emulator stealing focus, but still want the option to restore the window. |
| Headless/Xvfb | VICE_VISIBLE=false | C64 Bridge launches VICE without a user-facing desktop window, using Xvfb unless disabled. Warp defaults to on. | CI, unattended tests, servers, or any session where no one needs to inspect the emulator window. |
Minimized and headless are not the same thing. Minimized is still a visible desktop session with a real VICE window; it is simply hidden by the window manager at startup. Headless/Xvfb has no user-facing window, so it is better for automation but less convenient when you need to debug by looking at the emulator.
For normal local MCP use, prefer minimized VICE. It avoids focus stealing while preserving the ability to restore the window for visual inspection. Prefer headless/Xvfb for CI and remote or display-less environments.
FORCE_XVFB=1 forces the Xvfb path even if a graphical session is available. DISABLE_XVFB=1 disables that fallback and uses the current display, which is mainly useful for troubleshooting display detection.
Recommended VICE Configurations
Local agent session, VICE starts minimized:
{
"servers": {
"c64bridge": {
"command": "npx",
"args": ["-y", "c64bridge@latest"],
"env": {
"C64_MODE": "vice",
"VICE_VISIBLE": "true",
"VICE_ARGS": "-minimized",
"VICE_WARP": "false"
}
}
}
}
Headless automation, VICE runs without a visible desktop window:
{
"servers": {
"c64bridge": {
"command": "npx",
"args": ["-y", "c64bridge@latest"],
"env": {
"C64_MODE": "vice",
"VICE_VISIBLE": "false",
"VICE_WARP": "true"
}
}
}
}
If VICE is installed outside the usual search paths, add VICE_BINARY and, if ROM/resource auto-detection fails, VICE_DIRECTORY to either example.
NOTE
VICE supports only the operations marked with a VICE checkmark in the MCP API Reference. Unsupported operations return unsupported_platform.
Runtime Backend Switching
Configure any combination of c64u, u2, and vice. C64 Bridge starts on C64_MODE (default c64u) and keeps every configured backend ready for c64_select_backend.
| Profile | Targets | Key limits |
|---|
c64u | C64 Ultimate, Ultimate 64 | Full Ultimate REST surface, including machine input and streaming. |
u2 | U2, U2+, U2+L | Shared REST subset; no machine input, debug registers, power-off, or streaming. |
vice | VICE emulator | Binary Monitor-backed emulator controls; no Ultimate REST API. |
Use c64://platform/status to inspect the active backend and available tools. State the target in the same prompt, for example u2: list drives, c64u: run this PRG, or vice: write HELLO. On U2-family cartridges, c64_system power_cycle uses REST reboot; C64U/U64 uses verified Tool Menu navigation, and VICE starts fresh.
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 are available for the two backends that provide frame capture. C64U uses streamed video frames; VICE captures and normalizes its display. U2-family cartridges do not provide firmware streaming, so they intentionally have no screenshot row.
| Backend | Screenshot |
|---|
| C64 Ultimate |  |
| U2-family | Frame capture unavailable (no firmware streaming). |
| VICE |  |
Host File Access
Tool arguments that name a file or directory on the machine running C64 Bridge (memory dumps, configuration snapshots, sprite and charset exports, run artifacts, symbol files, and VICE PRG or disk image paths) are confined to a set of allowed directories:
- the working directory of the server, unless it is the user's home directory or
/
~/.c64bridge
- the system temporary directory (
os.tmpdir())
Paths are resolved to their real location before the check, so .. segments and symbolic links cannot leave these directories. A rejected path produces a validation error that lists the allowed directories, and nothing is written. Files read through these arguments are limited to 16 MiB (64 MiB for disk images).
Set C64BRIDGE_ALLOWED_DIRS to add directories. Separate entries with the platform path delimiter (: on Linux and macOS, ; on Windows). The single value * disables the confinement.
"env": { "C64BRIDGE_ALLOWED_DIRS": "/home/you/c64:/home/you/disks" }
Earlier versions accepted any path. Clients that pass paths outside these directories must now add them through C64BRIDGE_ALLOWED_DIRS.
Access Mode
Every operation has an effect: read (no change), write (changes machine or emulator state that a reset undoes, or writes a host file) or destructive (survives a reset or interrupts availability, for example power off, power cycle, reboot, flash save, load or reset to defaults, drive ROM load, disk image creation, debug register write, and config restore with applyToFlash). tools/list publishes MCP annotations derived from these effects, and each operation line in a tool description names its effect when it is not read.
Set C64BRIDGE_ACCESS to restrict what a client may call:
full (default): all operations are allowed.
no-destructive: destructive operations are rejected.
read-only: only read operations are allowed.
The variable is read on every call. An unknown value is treated as read-only and logged to stderr once. A rejected call returns a validation error that names the operation, its effect and the active mode. c64_batch checks each command separately, and c64_system start_task checks the effect of its task operation when the task starts. c64://platform/status shows the active mode.
After c64_system poweroff on C64U/U64, power must be restored at the outlet. The machine starts by itself only if automatic startup on power restoration is enabled in its configuration.
"env": { "C64BRIDGE_ACCESS": "no-destructive" }
Operator Environment Variables
These variables are read by the server itself and are set in the env block of the MCP client configuration. C64BRIDGE_ALLOWED_DIRS and C64BRIDGE_ACCESS are described above.
| Variable | Default | Description |
|---|
C64BRIDGE_ALLOWED_DIRS | unset | Additional directories for host file paths in tool arguments. Separate entries with the platform path delimiter; * disables the confinement. |
C64BRIDGE_ACCESS | full | full, no-destructive or read-only. Limits which operations a client may call. |
C64BRIDGE_HTTP_TOKEN | unset | When set, the optional HTTP transport (--http) requires Authorization: Bearer <token>. The transport binds to 127.0.0.1 and accepts only loopback Host and Origin headers regardless of this setting. Without a token, any process that can reach 127.0.0.1 on that port can call every tool. An invalid --http port is a startup error. |
C64BRIDGE_DIAGNOSTICS_KEEP | 200 | Number of diagnostics files kept in the diagnostics directory. At startup the server deletes older files beyond this count and files older than 30 days. An invalid value is ignored with a warning on stderr. Diagnostics files are created with mode 0600 in a directory created with mode 0700. |
C64BRIDGE_VERBOSE_SCHEMA | unset | Set to 1 to include the full per-operation schemas in tools/list. By default they are omitted to keep the listing small. |
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, u2, or vice; U2_HOST, U2_PORT, and U2_PASSWORD override the selected U2 profile. C64U_* variables apply to the U2 profile only when the configuration has no u2 section.
LOG_LEVEL=debug enables verbose logging
For VICE-specific overrides such as VICE_ARGS=-minimized, VICE_VISIBLE=false, or custom VICE paths, use the patterns in Backend Configuration: VICE.
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:
- the explicit environment variable from your MCP client config or shell
- the merged JSON config section loaded from
C64BRIDGE_CONFIG, the repo .c64bridge.json, then ~/.c64bridge.json
- the built-in default compiled into the server
When an environment variable has no JSON config equivalent, the order is:
- the explicit environment variable from your MCP client config or shell
- the built-in default
That rule applies uniformly across the documented runtime environment variables below.
Example: start on minimized 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_ARGS": "-minimized",
"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/U64 hardware, u2/U2-family cartridge, or vice emulator) |
C64_TASK_STATE_FILE | auto | — | Override the path used to persist MCP background-task state |
C64BRIDGE_ACCESS | full | — | Access mode limiting which operations may be called (full, no-destructive, read-only) |
C64BRIDGE_ALLOWED_DIRS | | — | Additional directories allowed for host file paths in tool arguments, separated by the path delimiter; * disables the check |
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_DIAGNOSTICS_KEEP | 200 | — | Number of diagnostics files kept at startup; files older than 30 days are always removed |
C64BRIDGE_DISABLE_DIAGNOSTICS | 0 | — | Set to 1 to disable persistent diagnostics logging |
C64BRIDGE_HTTP_TOKEN | | — | Bearer token required by the optional HTTP transport (--http) |
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 |
C64BRIDGE_VERBOSE_SCHEMA | | — | Set to 1 to include full per-operation schemas in tools/list |
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 |
U2-family
| Variable | Default | JSON Config Key | Description |
|---|
U2_HOST | | u2.host | Override the U2/U2+/U2+L host name or IP address when C64_MODE=u2 |
U2_PASSWORD | | u2.networkPassword | Override the U2-family network password sent as X-Password when C64_MODE=u2 |
U2_PORT | | u2.port | Override the U2-family REST port when C64_MODE=u2 |
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 use Xvfb even when a graphical session is detected |
VICE_ARGS | | vice.args | Extra command-line arguments forwarded to managed VICE launches, such as -minimized for a visible window that starts iconified |
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_PREWARM | 0 | vice.prewarm | Set to 1 to start/connect VICE in the background during MCP startup; disabled by default so VICE starts lazily on first use |
VICE_VISIBLE | true | vice.visible | Launch VICE as a desktop window when true; use headless/Xvfb managed launch when false |
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, u2, or 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:
- Ask the MCP client to generate or refine C64-oriented content.
- Use grouped tools such as
c64_program, c64_graphics, and c64_sound to execute it.
- 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.
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
curl -s -X POST -H 'Content-Type: application/json' \
-d '{"op":"read_screen"}' \
http://localhost:8000/tools/c64_memory | jq
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
./build
./build --skip-tests
./build build
./build test
./build test --real
./build test --platform vice --target mock
./build test:matrix
./build coverage
./build coverage:single --platform c64u --target mock
./build check
./build rag:rebuild
./build release --version 1.2.3
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
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, 38 resources, and 11 prompts for controlling your Commodore 64.
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 | C64U | U2 | VICE |
|---|
batch_update | Apply multiple configuration updates in a single request. Pass updates as {category: {item: value}}; categories as top-level keys are still accepted at runtime. | — | updates | ✅ | ✅ | ✅ |
diff | Compare the current configuration with a snapshot. | path | — | ✅ | ✅ | ✅ |
get | Read a configuration category or specific item. | category | item, includeSecretValues=false | ✅ | ✅ | ✅ |
info | Retrieve Ultimate hardware information and status. | — | — | ✅ | ✅ | ✅ |
list | List configuration categories reported by the firmware. | — | — | ✅ | ✅ | ✅ |
load_flash | Load configuration from flash storage. | — | category | ✅ | ✅ | |
read_debugreg | Read the Ultimate debug register ($D7FF). | — | — | ✅ | | |
reset_defaults | Reset firmware configuration to factory defaults. | — | category | ✅ | ✅ | |
restore | Restore configuration from a snapshot file. Writes only the items that differ from the device; if the device refuses a category (for example 403 when the network password is missing or wrong), the other categories are still restored and the result is an error naming the failed categories. | path | applyToFlash=false | ✅ | ✅ | ✅ |
save_flash | Persist the current configuration to flash storage. | — | category | ✅ | ✅ | |
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 | C64U | U2 | 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 | Wait until the CPU is stopped (checkpoint hit or step) and, when expectedPC is given, until PC equals it, or until the timeout elapses. Without a debug session the registers are polled. | — | 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 | C64U | U2 | VICE |
|---|
create_image | Create a blank disk image of the specified format. An existing file at the path is not overwritten; the call fails and a different path (or deleting the file first) is needed. | 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 | ✅ | ✅ | |
find_paths | Search Ultimate storage for paths whose names contain a substring, without running anything. | nameContains | root="/", extensions, maxResults=100, caseInsensitive=true | ✅ | ✅ | |
list_drives | List Ultimate drive slots and their mounted images. | — | — | ✅ | ✅ | ✅ |
mount | Mount a disk image with optional verification and retries. Supports verification. | drive, image | type, attachmentMode, driveMode, verify=false, powerOnIfNeeded=true, resetAfterMount=true, maxRetries=2, retryDelayMs=500 | ✅ | ✅ | ✅ |
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 | C64U | U2 | 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 | — | ✅ | ✅ | ✅ |
Grouped entry point for sprite/charset extraction, memory dumps, filesystem stats, and firmware health checks.
| Operation | Description | Required Inputs | Optional Inputs | C64U | U2 | 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 | C64U | U2 | VICE |
|---|
capture_frame | Capture one or more complete video frames from the active backend. | — | count=1, includePixels=false, format, encoding="base64" | ✅ | | ✅ |
get_display_state | Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. The same shared-memory path is used on C64U/U64, U2-family hardware, and VICE, 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 | ✅ | ✅ | ✅ |
Cross-platform PETSCII typing plus native Ultimate keyboard and joystick events.
| Operation | Description | Required Inputs | Optional Inputs | C64U | U2 | VICE |
|---|
joystick | Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4. | port, controls, action | durationMs=80 | ✅ | | ✅ |
key | Press a single key one or more times, optionally with a delay between presses. | key | durationMs=0, count=1 | ✅ | ✅ | ✅ |
keyboard | Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). | inputs, transition | — | ✅ | | |
release_all | Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). | — | — | ✅ | | |
state | Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). | — | — | ✅ | | |
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 | C64U | U2 | 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 C64U/U64, U2-family hardware, and VICE. | address | length=64, instructionCount | ✅ | ✅ | ✅ |
fill_memory | Fill a memory range with a repeating byte pattern. | address, length, pattern | — | ✅ | ✅ | ✅ |
list_basic | List the BASIC program in memory as text: reads the $2B-$2E pointers, walks the line links and detokenises. Works on C64U/U64, U2-family hardware, and VICE. | — | — | ✅ | ✅ | ✅ |
read | Read a range of bytes and return a hex dump with address metadata. | address | length=256, format="hex" | ✅ | ✅ | ✅ |
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. Supports verification. | address, bytes | verify=false, expected, mask, abortOnMismatch=true | ✅ | ✅ | ✅ |
c64_printer
Grouped entry point for Commodore and Epson printing helpers.
| Operation | Description | Required Inputs | Optional Inputs | C64U | U2 | 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 | C64U | U2 | 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 | ✅ | ✅ | ✅ |
cross_platform_greeting | Show a platform-customized greeting on one or more configured backends, capture screenshots, and verify the results. Supports verification. | — | platforms, messageTemplate="HAVE A GREAT DAY, {PLATFORM}!", verify=true, captureScreenshot=true, outputPath, restoreActiveBackend=true, timeoutMs=1500, pollIntervalMs=100 | ✅ | ✅ | ✅ |
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/U64 or U2-family hardware, or from a host-local path on VICE. | path | symbolsFile | ✅ | ✅ | ✅ |
upload_run_asm | Assemble 6502/6510 source, upload the PRG, and execute it. Supports verification. | program | verify=false | ✅ | ✅ | ✅ |
upload_run_basic | Upload Commodore BASIC v2 source and execute it immediately. Supports verification. | program | verify=false, autoFix=true | ✅ | ✅ | ✅ |
c64_rag
Grouped entry point for BASIC, assembly and curated-docs RAG lookups.
| Operation | Description | Required Inputs | Optional Inputs | C64U | U2 | 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 | ✅ | ✅ | ✅ |
docs | Search all curated docs (hardware, Ultimate features, game development, specs) with no BASIC/assembly filter. | q | k=3 | ✅ | ✅ | ✅ |
c64_select_backend
Switch the active backend between C64U/U64 hardware, U2-family cartridges, and the VICE emulator at runtime.
| Operation | Description | Required Inputs | Optional Inputs | C64U | U2 | 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 | C64U | U2 | 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. Supports verification. | — | sidwave, cpg, output="prg", waitBeforeCaptureMs=500, analysisDurationSeconds=3, expectedSidwave, verifySilenceBefore=true, verifySilenceAfter=true, silenceDurationSeconds=1.5, silenceRmsThreshold=0.02, postSilenceWaitMs=200, silenceWaitMs=150 | ✅ | ✅ | ✅ |
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. Supports verification. | — | preset="fuer_elise", platforms, verify=true, analysisDurationSeconds=4, waitBeforeCaptureMs=400, restoreActiveBackend=true | ✅ | ✅ | ✅ |
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. Uses the Ultimate audio stream on c64u and the host microphone on other backends. | 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. Supports verification. | — | verify=false | ✅ | ✅ | ✅ |
c64_stream
Grouped entry point for starting and stopping Ultimate streaming sessions.
| Operation | Description | Required Inputs | Optional Inputs | C64U | U2 | VICE |
|---|
start | Start an Ultimate streaming session. The device sends an unencrypted UDP stream to the target (IPv4 address or hostname, optional :port). | 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 | C64U | U2 | 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 | ✅ | ✅ | ✅ |
power_cycle | Return the active backend to a fresh state. C64U/U64 Tool Menu verification requires machine:menu_screen (a C64U firmware version that provides it, or U64 3.15+); U2-family reboots through REST. | — | waitForReady=false, readyTimeoutMs=15000 | ✅ | ✅ | ✅ |
poweroff | Shut down C64U/U64 or quit VICE. U2-family hardware cannot power off. On C64U/U64 the machine cannot be restarted by software afterwards: power must be restored at the outlet, and it starts by itself only if automatic startup on power restoration is enabled. | — | — | ✅ | | ✅ |
read_menu_screen | Read the active Ultimate menu's raw character and colour matrix through machine:menu_screen (a C64U firmware version that provides it, or U64/U2 3.15+). | — | — | ✅ | ✅ | |
reboot | Trigger a firmware reboot to recover from faults. | — | waitForReady=false, readyTimeoutMs=15000 | ✅ | ✅ | ✅ |
reset | Issue a soft reset without cutting power. | — | waitForReady=false, readyTimeoutMs=15000 | ✅ | ✅ | ✅ |
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 | C64U | U2 | 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://gamedev/index | Target decision, reading plan by game type, resource table with sizes, and the c64bridge dev loop for games. |
c64://gamedev/architecture | Frame-synchronous loop, state machine, frame and cycle budgets, memory-map templates for stock and REU-streaming games. |
c64://gamedev/techniques | Compact 6502 recipes for the techniques most C64 games need, each with reference projects to study. |
c64://gamedev/toolchain | Assembler and compiler choice, Makefile build, Exomizer packing, VICE and hardware test loop, .cfg and REU image for modern releases. |
c64://gamedev/references | Modern Ultimate projects and classic C64 games mapped to techniques, with licence cautions for reuse. |
c64://ultimate/hardware | Turbo, SID layout, video and palette, REU/UCI presence, model detection and config settings, with fallbacks for stock machines. |
c64://ultimate/uci | UCI register protocol, command targets, file and REU loading, network, palette, safe use and detection. |
c64://ultimate/reu | REU registers, tested level-load and detection routines, DMA behaviour, enabling and preloading an image, streaming levels, graphics and samples. |
c64://ultimate/upic | Cycle-exact border-colour technique for 384x256 16-colour graphics, framebuffer, palette use and limits. |
c64://ultimate/multisid | Verified control recipe per owner configuration (8 SIDs, or 10 with a chip in each socket), address map, range split and mirroring, mixer and pan, UCI LOAD_CONFIG setup and restore, ENV3 detection, sound differences. |
c64://ultimate/bench | Benchmark programs, result block layout, decoding formulas and a step-by-step rerun recipe using only c64bridge tools. |
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://basic/rom-routines | Maps BASIC ROM landmarks, reusable interpreter routines, numeric helpers, string helpers, and C64-specific BASIC continuation entries. |
c64://kernal/rom-routines | Maps KERNAL ROM vectors, jump table entries, internal routines, serial/tape/screen services, and reset handlers. |
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. |
game-development | Route requests to write, port or extend a C64 game to the game development skill and the c64://gamedev/index reading plan. |
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. |