C64 Bridge

io.github.chrisgleissner由 GitHub 帳號 chrisgleissner 發布v1.3.3更新於 Nov 22, 2026

MCP server for Commodore 64 Ultimate hardware and VICE emulator control.

已驗證STDIO僅桌面開發者工具媒體與設計

概覽

AI 產生的概覽

讓助理撰寫、檢視並控制 Commodore 64 硬體(Ultimate 64、U2 卡匣)或 VICE 模擬器的 MCP 伺服器。

可以做什麼
  • 在所選目標上執行 BASIC、6510 組合語言以及 PRG/CRT 程式
  • 讀寫記憶體、輪詢畫面,並在支援時擷取畫面
  • 管理磁碟機、檔案、印表機與背景任務
  • 播放、創作、產生並驗證 SID 音樂
  • 在 c64u、u2 與 vice 後端之間切換並檢視平台狀態
適用情境
適合想讓 AI 助理撰寫與測試 C64 程式、檢視記憶體或畫面,或為復古運算開發與類 CI 測試自動化模擬器工作階段的場合。
執行需求
以本機程序執行(npx 或 npm 安裝),需要 Node.js 24+ 與 npm。需要可連線的目標:網路可達的 Ultimate 64 或 U2 系列卡匣(主機、連接埠與網路密碼,透過 C64U_PASSWORD 或 U2_PASSWORD 提供),或具 ROM 資源的 VICE 執行檔(VICE_BINARY)。以 C64_MODE 選擇後端,可用 C64BRIDGE_CONFIG 指定設定檔。
安裝前請注意
預設存取模式為 full,助理可寫入記憶體、建立磁碟映像、儲存至快閃、重新開機或關機;可將 C64BRIDGE_ACCESS 設為 no-destructive 或 read-only 加以限制。主機檔案路徑預設限制在允許目錄內,除非透過 C64BRIDGE_ALLOWED_DIRS 擴充或設為 *。網路密碼以環境變數傳遞;選用的 HTTP 傳輸在未設定 C64BRIDGE_HTTP_TOKEN 時,本機任何程序皆可呼叫。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 C64 Bridge,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

C64 Bridge

[Logo]

Your AI Command Bridge for the Commodore 64.

[npm] [Build] [codecov] [License: GPL v2] [Platform]

[Install in VS Code] [Install in VS Code Insiders] [Install in Visual Studio] [Install in Cursor] [Use with Claude Code]

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:

  1. Start the MCP server.
  2. Point it at C64U/U64 hardware, a U2-family cartridge, VICE, or any configured combination.
  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 c64u (C64U/U64), u2 (U2/U2+/U2+L), and 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 C64U/U64, U2-family, VICE, or any combination.
  4. Connect from VS Code or another MCP client.

1. Install Node.js 24+ and npm

Linux (Ubuntu or Debian):

Recommended:

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

Fallback:

bash
sudo apt install -y nodejs npm

macOS:

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

Windows:

powershell
# wingetwinget install OpenJS.NodeJS.LTS# or Chocolateychoco install nodejs-lts -y

Verify the installation:

bash
node --version

Expected result: v24.x

2. Start the Server

Use one of the following entry points.

Run from npx with zero setup:

bash
npx -y c64bridge@latest

Run from a local npm install:

bash
mkdir -p ~/c64bridge && cd ~/c64bridgenpm init -ynpm install c64bridgenode ./node_modules/c64bridge/dist/index.js

Run from source for development or testing:

bash
git clone https://github.com/chrisgleissner/c64bridge.gitcd c64bridge./build installnpm 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:

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

json
{  "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.

Firmware Requirements for Native Input and Menu Screens

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:

json
{  "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:

json
{  "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:

ModeConfigurationWhat happensUse when
VisibleVICE_VISIBLE=trueVICE opens a normal desktop window. Warp defaults to off.You are developing locally and want to watch or interact with the emulator.
MinimizedVICE_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/XvfbVICE_VISIBLE=falseC64 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:

json
{  "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:

json
{  "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.

ProfileTargetsKey limits
c64uC64 Ultimate, Ultimate 64Full Ultimate REST surface, including machine input and streaming.
u2U2, U2+, U2+LShared REST subset; no machine input, debug registers, power-off, or streaming.
viceVICE emulatorBinary 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):

text
c64u: write a small BASIC program that clears the screen and prints HELLO C64U
text
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.

BackendScreenshot
C64 Ultimate[C64 Ultimate backend switch example]
U2-familyFrame capture unavailable (no firmware streaming).
VICE[VICE backend switch example]

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.

json
"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.

json
"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.

VariableDefaultDescription
C64BRIDGE_ALLOWED_DIRSunsetAdditional directories for host file paths in tool arguments. Separate entries with the platform path delimiter; * disables the confinement.
C64BRIDGE_ACCESSfullfull, no-destructive or read-only. Limits which operations a client may call.
C64BRIDGE_HTTP_TOKENunsetWhen 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_KEEP200Number 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_SCHEMAunsetSet 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:

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

Then click the start button shown above the c64bridge entry.

Your MCP server should now be running:

[VS Code Started MCP server]

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.

[VS Code C64 agent]

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:

json
{  "servers": {    "c64bridge": {      "type": "stdio",      "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:

  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: start on minimized VICE with a specific ROM or resource directory, plus a hardware fallback that can still be selected instantly at runtime:

json
{  "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:

json
{  "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
VariableDefaultJSON Config KeyDescription
C64_MODEc64u—Select active backend (c64u/U64 hardware, u2/U2-family cartridge, or vice emulator)
C64_TASK_STATE_FILEauto—Override the path used to persist MCP background-task state
C64BRIDGE_ACCESSfull—Access mode limiting which operations may be called (full, no-destructive, read-only)
C64BRIDGE_ALLOW_HIDDEN_PATHS—Set to 1 to allow hidden host path components; protected configuration and task-state files remain inaccessible
C64BRIDGE_ALLOWED_DIRS—Additional directories allowed for host file paths in tool arguments, separated by the path delimiter; * disables the check
C64BRIDGE_CONFIG~/.c64bridge.jsonconfig pathPath to configuration JSON
C64BRIDGE_DIAGNOSTICS_DIR~/.c64bridge/diagnostics—Override the directory where persistent MCP diagnostics files are written
C64BRIDGE_DIAGNOSTICS_KEEP200—Number of diagnostics files kept at startup; files older than 30 days are always removed
C64BRIDGE_DISABLE_DIAGNOSTICS0—Set to 1 to disable persistent diagnostics logging
C64BRIDGE_HTTP_TOKEN—Bearer token required by the optional HTTP transport (--http)
C64BRIDGE_POLL_INTERVAL_MS200—Interval between screen polls during program-output validation in normal runtime mode
C64BRIDGE_POLL_MAX_MS2000—Maximum time to poll for program-output validation before timing out in normal runtime mode
C64BRIDGE_POLL_STABILIZE_MS100—Extra settle time after a successful poll match before considering output stable
C64BRIDGE_STATE_DIR~/.c64bridge—Root directory for task state, run artifacts and diagnostics
C64BRIDGE_VERBOSE_SCHEMA—Set to 1 to include full per-operation schemas in tools/list
LOG_LEVELinfo—Logger verbosity (debug, info, warn, error)
C64 Ultimate
VariableDefaultJSON Config KeyDescription
C64U_HOSTc64uc64u.hostOverride the C64 Ultimate host name or IP address
C64U_PASSWORDc64u.networkPasswordOverride the C64 Ultimate network password sent as X-Password
C64U_PORT80c64u.portOverride the C64 Ultimate REST port
U2-family
VariableDefaultJSON Config KeyDescription
U2_HOSTu2.hostOverride the U2/U2+/U2+L host name or IP address when C64_MODE=u2
U2_PASSWORDu2.networkPasswordOverride the U2-family network password sent as X-Password when C64_MODE=u2
U2_PORTu2.portOverride the U2-family REST port when C64_MODE=u2
VICE Runtime
VariableDefaultJSON Config KeyDescription
DISABLE_XVFB0—Set to 1 to disable Xvfb fallback and use the current display only
FORCE_XVFB0—Set to 1 to force managed VICE launches to use Xvfb even when a graphical session is detected
VICE_ARGSvice.argsExtra command-line arguments forwarded to managed VICE launches, such as -minimized for a visible window that starts iconified
VICE_BINARYx64scvice.exeVICE binary to launch for managed emulator sessions and audio capture; automatic search is used only when this override is missing or invalid
VICE_DIRECTORYauto-detectvice.directoryOverride the VICE resource directory used for ROM and UI asset discovery; automatic search is used only when this override is missing or invalid
VICE_HOST127.0.0.1vice.hostOverride the VICE Binary Monitor host
VICE_PORT6502vice.portOverride the VICE Binary Monitor port
VICE_PREWARM0vice.prewarmSet to 1 to start/connect VICE in the background during MCP startup; disabled by default so VICE starts lazily on first use
VICE_VISIBLEtruevice.visibleLaunch VICE as a desktop window when true; use headless/Xvfb managed launch when false
VICE_WARPfalse when visible, true when headlessvice.warpEnable warp mode for managed VICE sessions
VICE_XVFB_DISPLAY:99—Display number to use when managed VICE launches under Xvfb
VICE Audio Capture
VariableDefaultJSON Config KeyDescription
VICE_LIMIT_CYCLES120000000—Maximum CPU cycles to render when VICE generates audio
VICE_MODEntsc—Default video standard for VICE audio capture (ntsc|pal)
VICE_RUN_TIMEOUT_MS10000—Timeout for headless VICE runs in milliseconds
SID Playback
VariableDefaultJSON Config KeyDescription
SIDPLAY_BINARYsidplayfp—sidplayfp binary to launch when generating audio
SIDPLAY_LIMIT_CYCLES120000000—Maximum CPU cycles to render when sidplayfp generates audio
SIDPLAY_MODEntsc—Default SID playback mode (ntsc|pal)
SIDPLAYFP_BINARY—Legacy alias for SIDPLAY_BINARY (sidplayfp executable name)
RAG
VariableDefaultJSON Config KeyDescription
GITHUB_TOKEN—Personal access token used for optional RAG discovery against GitHub
RAG_BUILD_ON_START0—Set to 1 to rebuild embeddings on server start
RAG_DISCOVER_FORCE_REFRESH0—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_DIRdata—Directory containing RAG embedding JSON files
RAG_REINDEX_INTERVAL_MS0—Periodic reindex interval in ms (0 disables)
Testing
VariableDefaultJSON Config KeyDescription
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:

bash
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.

Claude Desktop and Cursor

Both clients use the same mcpServers shape (checked against the official MCP quickstart for Claude Desktop and the Cursor MCP documentation):

json
{  "mcpServers": {    "c64bridge": {      "command": "npx",      "args": ["-y", "c64bridge@latest"],      "env": {        "C64U_HOST": "192.168.1.99"      }    }  }}
  • Claude Desktop: Settings, Developer, Edit Config opens claude_desktop_config.json (macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json). Restart Claude Desktop completely after saving. Claude Desktop starts the server with its own PATH; if npx is not found or is too old, use the absolute path of a Node 24 npx as command.
  • Cursor: .cursor/mcp.json in a project, or ~/.cursor/mcp.json for all projects.
  • Replace 192.168.1.99 with the IP address of your Ultimate (the default host name c64u only works when it resolves on your network). For VICE use "C64_MODE": "vice" instead.
  • The server writes its log to stderr and then waits for the client on stdin. Started by hand in a terminal it appears to hang; that is expected, stop it with Ctrl-C.
  • Claude Code sets the same variable with -e (--env), placed before the -- that starts the server command: claude mcp add c64bridge -e C64U_HOST=192.168.1.99 -- npx -y c64bridge@latest.

Example Workflow

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

[duck song]

Then render PETSCII art for it:

[duck petscii]

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. Start it with npx -y c64bridge@latest --http 3000 (from a checkout: npm start -- --http 3000). The port defaults to 3000; the server binds to 127.0.0.1 only. Set C64BRIDGE_HTTP_TOKEN and send Authorization: Bearer <token> to require a token.
  • The single endpoint is http://127.0.0.1:<port>/mcp and speaks MCP JSON-RPC. Every request needs Content-Type: application/json and Accept: application/json, text/event-stream; the answer arrives as one server-sent event (data: {...}).
  • There are no per-tool REST routes. A grouped tool is called with tools/call, and op goes inside arguments.
bash
# Read the current screen (PETSCII to ASCII)curl -s -X POST http://127.0.0.1:3000/mcp \  -H 'Content-Type: application/json' \  -H 'Accept: application/json, text/event-stream' \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"c64_memory","arguments":{"op":"read_screen"}}}'
# List the toolscurl -s -X POST http://127.0.0.1:3000/mcp \  -H 'Content-Type: application/json' \  -H 'Accept: application/json, text/event-stream' \  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Build and Test

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

bash
./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

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, 53 resources, and 11 prompts for controlling your Commodore 64.

See the hardening behavior guide for host path restrictions, argument limits, task retention, cancellation and verification semantics.

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.

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
batch_updateApply several configuration updates at once. Pass updates as {category: {item: value}}.—updates✅✅✅
diffCompare configuration with a snapshot.path—✅✅✅
getRead a configuration category or specific item.categoryitem, includeSecretValues=false✅✅✅
infoRetrieve Ultimate hardware information and status.——✅✅✅
listList configuration categories reported by the firmware.——✅✅✅
load_flashLoad configuration from flash.—category✅✅
read_debugregRead the Ultimate debug register ($D7FF).——✅
reset_defaultsReset configuration to factory defaults.—category✅✅
restoreRestore configuration from a snapshot file. Writes only items that differ from the device; if the device refuses a category (e.g. 403 for a wrong network password), the others are still restored and the error names the failed categories.pathapplyToFlash=false✅✅✅
save_flashPersist the configuration to flash.—category✅✅
setWrite a configuration value in the selected category.category, item, value—✅✅✅
shuffleDiscover PRG/CRT files and run each, optionally capturing the screen.—root="/", extensions=["prg","crt"], durationMs=5000, captureScreen=true, maxPrograms=10, outputPath, resetDelayMs=100✅✅
snapshotSnapshot configuration to disk.path—✅✅✅
versionFetch firmware version details.——✅✅✅
write_debugregWrite a hex value to the Ultimate debug register ($D7FF).value—✅
c64_debug

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

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
continue_executionExit the Binary Monitor and resume CPU execution (BM 0xAA Exit).——✅
create_checkpointCreate a new checkpoint (breakpoint) in VICE.addressendAddress, stopOnHit=true, enabled=true, temporary=false, label, operations, memspace✅
delete_checkpointRemove a checkpoint by id.id—✅
get_checkpointFetch a single checkpoint by id.id—✅
get_monitor_stateRead CPU registers and return the current monitor state.—memspace✅
get_registersRead register values, optionally filtered by name or id.—memspace, registers✅
list_checkpointsList all active VICE checkpoints (breakpoints).——✅
list_registersList available registers (metadata).—memspace✅
nuclear_resetKill and restart the VICE process (managed instances only).——✅
set_conditionAttach a conditional expression to a checkpoint.id, expression—✅
set_registersWrite register values.writesmemspace✅
stepSingle-step CPU execution.—count=1, mode✅
step_returnContinue execution until the current routine returns.——✅
toggle_checkpointEnable or disable a checkpoint by id.id, enabled—✅
wait_for_stateWait until the CPU is stopped (checkpoint hit or step) and, with expectedPC, PC equals it, or 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.

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
create_imageCreate 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, pathdiskname, tracks✅✅
file_infoInspect a file on the Ultimate filesystem.path—✅✅
find_and_runSearch for a PRG/CRT by name substring and run the first match.nameContainsroot="/", extensions, caseInsensitive=true, sort="discovered", waitMs=0, captureCandidates=10✅✅
find_pathsSearch Ultimate storage for paths containing a name substring, without running anything.nameContainsroot="/", extensions, maxResults=100, caseInsensitive=true✅✅
list_drivesList drive slots and mounted images.——✅✅✅
mountMount a disk image with optional verification/retries. Supports verification.drive, imagetype, attachmentMode, location, driveMode, verify=false, powerOnIfNeeded=true, resetAfterMount=true, maxRetries=2, retryDelayMs=500✅✅✅
unmountUnmount the image from a drive slot.drive—✅✅
c64_drive

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

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
load_romTemporarily load a custom ROM into an Ultimate drive slot.drive, path—✅✅
power_offPower off a specific Ultimate drive slot.drive—✅✅✅
power_onPower on a specific Ultimate drive slot.drive—✅✅✅
resetIssue an IEC reset for the selected drive slot.drive—✅✅✅
set_modeSet 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.

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
charsetLocate and extract 2KB character sets from RAM.—address, scanRange="common", outputPath, pauseDuringRead=true, minNonEmptyChars=32, minEntropy=0.3✅✅✅
firmware_healthRun firmware readiness checks and report status metrics.——✅✅✅
fs_statsPer-extension size statistics for one directory (no recursion); the firmware returns at most one file per extension.—root="/", extensions, includeContainers=true, maxSamplesPerExtension=3✅✅
memory_dumpDump a RAM range to hex or binary files with manifest metadata.address, length, outputPathformat="hex", chunkSize, pauseDuringRead=true, retries=1✅✅✅
spritesScan RAM for sprites and optionally export .spr files.address, lengthstride=64, maxSprites=16, minNonZeroRows=4, minSetBits=12, includeBase64=false, includeRows=false, outputDir, pauseDuringRead=true✅✅✅
c64_graphics

Grouped entry point for frame capture and graphics rendering workflows.

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
capture_frameCapture one or more complete video frames from the active backend.—count=1, includePixels=false, format, encoding="base64"✅✅
get_display_stateRead VIC-II and CIA2 registers to determine the current graphics mode and memory layout.——✅✅✅
render_bitmapConvert an image file to VIC-II bitmap memory, write it to RAM and display it.imagePath, formatbitmapAddress=8192, screenAddress=1024, borderColor=0, backgroundColor=0, preserveAspect=true✅✅✅
render_petscii_artCreate PETSCII art from a prompt, text or bitmap data, optionally displaying it.—prompt, text, maxWidth, maxHeight, borderColor, backgroundColor, foregroundColor, dryRun=false, bitmap✅✅✅
render_petscii_textDisplay PETSCII text with optional border and background colours.textborderColor, backgroundColor✅✅✅
render_spriteDisplay 63-byte sprite data at a position and colour by writing memory and VIC-II registers.spriteindex=0, x=100, y=100, color=1, multicolour=false, dataAddress✅✅✅
c64_input

Cross-platform PETSCII typing plus native Ultimate keyboard and joystick events.

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
joystickSimulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches the joyport simulation device, which also pulls CIA lines 5-7 low: port 1 produces phantom keys and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4.port, controls, actiondurationMs=80✅✅
keyPress one key one or more times, optionally with a delay.keydurationMs=0, count=1✅✅✅
keyboardSend physical C64 keyboard matrix events through machine:input (needs firmware support; U64 3.15+).inputs, transition—✅
release_allRelease every key and joystick control injected through machine:input.——✅
stateRead the keys and joystick controls held through machine:input.——✅
write_textSend a text string to the keyboard buffer, with PETSCII token expansion.textdelayMs=0✅✅✅
c64_memory

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

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
compare_memoryCompare two memory regions byte-by-byte and report differences.address1, address2, lengthmaxDiffs=10, includeIo=false✅✅✅
copy_memoryCopy a RAM region to another address.source, dest, lengthincludeIo=false✅✅✅
disassembleDisassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes. Labels from loaded .vs files annotate the listing.addresslength=64, instructionCount✅✅✅
fill_memoryFill a memory range with a repeating byte pattern.address, length, pattern—✅✅✅
list_basicList the BASIC program in memory as text: reads the $2B-$2E pointers, walks the line links and detokenises.——✅✅✅
readRead a range of bytes and return a hex dump with address metadata.addresslength=256, format="hex", bank✅✅✅
read_screenReturn the current 40x25 text screen converted to ASCII.——✅✅✅
save_memoryDump a memory range to a local file, with an optional PRG load-address header.startAddress, endAddress, filePathasPrg=true, includeIo=false✅✅✅
search_memorySearch for a byte pattern within a memory range and return matching addresses.startAddress, endAddress, patternmaxResults=10, includeIo=false✅✅✅
wait_for_textPoll the screen until a substring or regex appears, or timeout elapses.patternisRegex=false, caseInsensitive=true, timeoutMs=3000, intervalMs=100✅✅✅
writeWrite a hexadecimal byte sequence into RAM. Supports verification.address, bytesverify=false, expected, mask, abortOnMismatch=true✅✅✅
c64_printer

Grouped entry point for Commodore and Epson printing helpers.

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
define_charsDefine custom printer characters (Commodore DLL mode).firstChar, charssecondaryAddress✅✅
print_bitmapPrint a bitmap row via Commodore (BIM) or Epson ESC/P workflows.printer="commodore", columnsrepeats, useSubRepeat, secondaryAddress, ensureMsb=true, mode, density, timesPerLine✅✅
print_textGenerate BASIC that prints text to device 4.texttarget="commodore", secondaryAddress, formFeed=false✅✅
c64_program

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

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
batch_runRun multiple PRG/CRT programs with post-run assertions.programscontinueOnError=false, durationMs=2000, outputPath, resetDelayMs=100✅✅✅
bundle_runCapture screen, memory and debug registers into a bundle.runId, outputPathcaptureScreen=true, memoryRanges, captureDebugReg✅✅✅
cross_platform_greetingShow a platform-specific greeting on configured backends, capture screenshots and verify. Supports verification.—platforms, messageTemplate="HAVE A GREAT DAY, {PLATFORM}!", verify=true, captureScreenshot=true, outputPath, restoreActiveBackend=true, timeoutMs=1500, pollIntervalMs=100✅✅✅
load_prgLoad a PRG into memory without running it (Ultimate path, host path on VICE, or location host).pathlocation, symbolsFile✅✅✅
run_crtRun a CRT cartridge image from an Ultimate path, or upload a host file with location host (c64u/u2).pathlocation✅✅
run_prgLoad and run a PRG: Ultimate path on c64u/u2 (location host uploads a host file), host path on VICE.pathlocation, symbolsFile✅✅✅
upload_run_asmAssemble 6502/6510 source (ACME, ca65 and 64tass directive spellings; .include/.incbin read host files), upload and run it. Supports verification.programverify=false✅✅✅
upload_run_basicTokenize BASIC v2 source, upload and run it; verify:true reports BASIC errors with their line. Supports verification.programverify=false, autoFix=true✅✅✅
c64_rag

Grouped entry point for BASIC, assembly and curated-docs RAG lookups.

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
asmRetrieve 6502/6510 assembly references from the local knowledge base.qk=3✅✅✅
basicRetrieve BASIC references and snippets from the local knowledge base.qk=3✅✅✅
docsSearch all curated docs (hardware, Ultimate features, game development, specs) with no BASIC/assembly filter.qk=3✅✅✅
c64_select_backend

Switch the active backend between C64U/U64 hardware, U2-family cartridges, and the VICE emulator at runtime.

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
selectSwitch the active runtime backend without restarting the MCP server.backend—✅✅✅
c64_sound

SID control, playback, composition and audio analysis.

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
analyzeAnalyze SID playback or a host WAV.—wavPath, request="analyze the SID output", durationSeconds, expectedSidwave✅✅✅
capture_samplesCapture Ultimate stereo PCM.—count=256, encoding="base64"✅
compile_playCompile and optionally play SIDWAVE.—configure, sidwave, cpg, format, output="prg", dryRun=false, outputPath✅✅✅
generateCompose and play a seeded SIDWAVE PRG. Replaces the program in memory.—includeScore, configure, root="C4", pattern, steps, tempoMs, waveform, preset="classic", system, style="chiptune", seed=65✅✅✅
note_offRelease a SID voice.voice—✅✅✅
note_onStart a SID voice.—voice=1, note, frequencyHz, system, waveform="pulse", pulseWidth=2048, attack=1, decay=1, sustain=15, release=3✅✅✅
pipelineCompile, play and analyze SIDWAVE. Supports verification.—configure, sidwave, cpg, output="prg", waitBeforeCaptureMs=500, analysisDurationSeconds=3, expectedSidwave, verifySilenceBefore=false, verifySilenceAfter=false, silenceDurationSeconds=1.5, silenceRmsThreshold=0.02, postSilenceWaitMs=200, silenceWaitMs=150✅✅✅
play_mod_filePlay an Ultimate MOD file.path—✅✅
play_presetCompile and play a built-in SID preset. Supports verification.—includeScore, configure, preset="chiptune_drive", platforms, verify=false, analysisDurationSeconds=4, waitBeforeCaptureMs=400, restoreActiveBackend=true✅✅✅
play_sid_filePlay an Ultimate SID file.pathsongnr✅✅
record_analyzeAnalyze a recording from the Ultimate stream or host microphone on other backends.durationSecondsexpectedSidwave✅✅✅
resetReset SID registers.—hard=false✅✅✅
sample_renderRender a SIDWAVE sample to WAV.—definition, rate=4000, outputDir✅✅✅
set_volumeSet SID volume ($D418).volumefilterMode✅✅✅
silence_allSilence all SID voices. Supports verification.—verify=false✅✅✅
c64_stream

Grouped entry point for starting and stopping Ultimate streaming sessions.

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
startStart an Ultimate streaming session. The device sends an unencrypted UDP stream to the target (IPv4 address or hostname, optional :port).stream, target—✅
stopStop an active Ultimate streaming session.stream—✅
c64_system

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

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
delete_taskDelete a finished task and its artifacts; stop running tasks first.name—✅✅✅
list_tasksList background tasks with status.——✅✅✅
menuToggle the Ultimate menu button.——✅✅
pausePause the machine until resumed.——✅✅✅
performance_reportSummarize diagnostics spans and tool latencies of the current or latest session.—scope="current", includeTimeline=true, maxEntries=25✅✅✅
power_cycleReturn the backend to a fresh state. C64U/U64 Tool Menu verification needs machine:menu_screen (U64 3.15+ or supporting C64U firmware); U2-family reboots through REST.—waitForReady=false, readyTimeoutMs=15000✅✅✅
poweroffShut down C64U/U64 or quit VICE. U2-family hardware cannot power off. On C64U/U64 software cannot restart it: power must be restored at the outlet, and it starts by itself only if automatic startup on power restoration is enabled.——✅✅
read_menu_screenRead the active Ultimate menu's raw character and colour matrix through machine:menu_screen (needs firmware support; U64/U2 3.15+).——✅✅
rebootTrigger a firmware reboot to recover from faults.—waitForReady=false, readyTimeoutMs=15000✅✅✅
resetIssue a soft reset without cutting power.—waitForReady=false, readyTimeoutMs=15000✅✅✅
resumeResume CPU execution after a pause.——✅✅✅
start_taskStart a named interval task.name, operationarguments={}, intervalMs=1000, maxIterations✅✅✅
stop_all_tasksStop all running tasks and persist state.——✅✅✅
stop_taskStop a background task.name—✅✅✅
c64_vice

VICE resources, snapshots.

OperationDescriptionRequired InputsOptional InputsC64UU2VICE
resource_getRead a VICE configuration resource (safe prefixes only).name—✅
resource_setWrite a VICE configuration resource (safe prefixes only).name, value—✅
snapshot_restoreRestore snapshot.path—✅
snapshot_saveSave snapshot.path—✅
versionVICE version.——✅

Resources

NameSummary
c64://guide/indexExplains how to approach each knowledge bundle and when to consult it.
c64://guide/bootstrapStep-by-step rules for safe automation, verification, and rollback on the C64.
c64://guide/fast-pathsCondensed routing guide for one-call demos, backend switching, and when to prefer orchestration over manual tool composition.
c64://gamedev/indexTarget decision, reading plan by game type, resource table with sizes, and the c64bridge dev loop for games.
c64://gamedev/architectureFrame-synchronous loop, state machine, frame and cycle budgets, memory-map templates for stock and REU-streaming games.
c64://gamedev/techniquesCompact 6502 recipes for the techniques most C64 games need, each with reference projects to study.
c64://gamedev/toolchainAssembler and compiler choice, Makefile build, Exomizer packing, VICE and hardware test loop, .cfg and REU image for modern releases.
c64://gamedev/referencesModern Ultimate projects and classic C64 games mapped to techniques, with licence cautions for reuse.
c64://ultimate/hardwareTurbo, SID layout, video and palette, REU/UCI presence, model detection and config settings, with fallbacks for stock machines.
c64://ultimate/uciUCI register protocol, command targets, file and REU loading, network, palette, safe use and detection.
c64://ultimate/reuREU registers, tested level-load and detection routines, DMA behaviour, enabling and preloading an image, streaming levels, graphics and samples.
c64://ultimate/upicCycle-exact border-colour technique for 384x256 16-colour graphics, framebuffer, palette use and limits.
c64://ultimate/multisidVerified 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/benchBenchmark programs, result block layout, decoding formulas and a step-by-step rerun recipe using only c64bridge tools.
c64://vice/binary-monitor-specTransport framing, single-client constraints, command semantics, and monitor side effects that shape all VICE-backed operations.
c64://basic/specToken definitions, syntax rules, and device I/O guidance for BASIC v2.
c64://basic/pitfallsQuickref covering quotation handling, line length, tokenization, variable names, and other BASIC traps.
c64://assembly/6510-specOfficial opcode matrix, addressing modes, and zero-page strategy for the 6510 CPU.
c64://sound/sid/specRegister map, waveform behaviour, and ADSR envelopes for expressive SID playback.
c64://sound/sidwave/specDefines the SIDWAVE interchange format used by the SID composer workflow.
c64://sound/examplesMusic presets with annotated SIDWAVE scores.
c64://sound/examples/chiptune_driveChip arpeggios, gliding pulse lead and drum break
c64://sound/examples/ambient_filterSlow pads, filtered bass and ring modulated bells
c64://sound/examples/funk_bassSyncopated filter bass, chord chops and sync accents
c64://sound/examples/acid_lineAcid bass, resonance accents and slides over a four-on-the-floor kick
c64://sound/examples/arp_balladMinor ballad with chord arpeggios and a connected PWM lead
c64://sound/examples/drum_and_bassBreakbeats and a pair of detuned Reese bass oscillators
c64://sound/examples/digi_grooveCIA2 volume digis with syncopated synth bass and arpeggios
c64://sound/examples/metal_syncHard sync, ring modulation, double kick and power chords
c64://sound/examples/stereo_echoTwo SIDs with stereo echo, ping-pong arpeggios and unison pads
c64://sound/examples/chamber_waltzThree independent voices in 3/4 with no percussion
c64://sound/examples/title_fanfareShort filtered brass fanfare with timpani and a held cadence
c64://sound/examples/ultisid_orchestraEight SIDs with divided strings, twin echo leads, arps and a drum kit
c64://sound/examples/wall_of_sidNine SIDs and a gradual build to a 27-voice finale
c64://sound/examples/fuer_eliseLegacy three-voice arrangement of Beethoven’s Bagatelle
c64://sound/sid/file-formatExplains PSID/RSID headers, metadata blocks, and compatibility notes for imported music.
c64://sound/sid/best-practicesCaptures proven waveforms, ADSR presets, phrasing, and verification workflow for pleasant SID music.
c64://graphics/vic/specCovers raster timing, sprite control, colour RAM, and bitmap modes on the VIC-II.
c64://graphics/character-setCharacter code table mapping PETSCII codes to screen codes, glyphs, and keyboard input.
c64://graphics/petscii/style-guideDocuments colour palette, readability presets, dithering patterns, and best practices for creating artistic and readable PETSCII displays.
c64://graphics/sprite-charset/best-practicesDocuments sprite and charset workflows, memory layout, VIC-II configuration, common pitfalls, and proven techniques for hardware-accelerated graphics.
c64://memory/mapPage-by-page breakdown of the 64 KB address space with hardware, ROM, and RAM regions.
c64://memory/zero-page-and-workspaceDocuments zero-page variables, BASIC pointers, and KERNAL workspace addresses.
c64://basic/rom-routinesMaps BASIC ROM landmarks, reusable interpreter routines, numeric helpers, string helpers, and C64-specific BASIC continuation entries.
c64://kernal/rom-routinesMaps KERNAL ROM vectors, jump table entries, internal routines, serial/tape/screen services, and reset handlers.
c64://io/specCovers VIC-II, SID, CIA, and system control registers with address ranges and usage notes.
c64://io/cia/specDetails CIA 1/2 registers, timers, interrupts, and keyboard matrix layout.
c64://printer/specCovers device setup, control codes, and Ultimate 64 integration for printers.
c64://printer/commodore/textCharacter sets, control codes, and formatting for Commodore MPS text output.
c64://printer/commodore/bitmapDetails bitmap modes, graphics commands, and data layout for MPS bitmap printing.
c64://printer/epson/textLists ESC/P control codes and formatting advice for Epson FX text output.
c64://printer/epson/bitmapExplains bit-image modes, density options, and data packing for Epson bitmap jobs.
c64://printer/prompt-guideReusable prompt templates that drive complex printer jobs through the MCP server.

Prompts

NameDescription
assembly-programRoute 6502/6510 routine requests to the canonical assembly skill.
basic-programRoute bespoke Commodore BASIC v2 requests to the canonical BASIC skill.
cross-platform-demoRoute quick visible demo requests to the cross-platform demo skill.
drive-managerRoute disk-image and drive-state requests to the canonical drive skill.
game-developmentRoute requests to write, port or extend a C64 game to the game development skill and the c64://gamedev/index reading plan.
graphics-demoRoute graphics requests to the canonical graphics skill.
hello-worldRoute ultra-fast hello-world and smoke-test requests to the canonical greeting skill.
memory-debugRoute reversible memory inspection or patching work to the canonical memory skill.
preset-music-demoRoute quick recognizable tune requests to the SID music skill.
printer-jobRoute printer work to the canonical printer skill.
sid-musicRoute SID playback and composition work to the canonical SID skill.

來源:README.md,提交 cc818ff

工具

17

c64_program

Runs PRG/CRT files, uploads BASIC or ASM, and coordinates batch test flows.

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

輸入參數op必填pathrunIdverifyautoFixprogramlocationprogramsplatformstimeoutMsdurationMsoutputPath另有 10 個

c64_memory

Reads or writes RAM, captures the screen, or waits for text matches in one tool.

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

輸入參數op必填bankdestmaskasPrgbytesformatlengthsourceverifyaddressisRegex另有 15 個

c64_sound

Adjusts SID registers, plays files, composes music, and runs verification captures.

SID control, playback, composition and audio analysis.

輸入參數op必填cpghardnotepathraterootseedcountdecaystepsstyle另有 39 個

c64_system

Manages machine state (pause, reset, power) and schedules recurring background tasks.

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

輸入參數op必填namescopeargumentsoperationintervalMsmaxEntrieswaitForReadymaxIterationsreadyTimeoutMsincludeTimeline

c64_select_backend

Changes the active backend without restarting the MCP server and reports resulting tool availability.

Switch the active backend between C64U/U64 hardware, U2-family cartridges, and the VICE emulator at runtime.

輸入參數op必填backend

c64_graphics

Captures frames, renders PETSCII text or art, previews sprites, and displays bitmap images from one tool.

Grouped entry point for frame capture and graphics rendering workflows.

輸入參數xyop必填textcolorcountindexbitmapdryRunformatpromptsprite另有 13 個

c64_rag

Returns knowledge references for BASIC (basic), 6502/6510 assembly (asm) or all curated docs including game development and Ultimate features (docs).

Grouped entry point for BASIC, assembly and curated-docs RAG lookups.

輸入參數kqop必填

c64_disk

Mount or unmount images, create new disks, list drives, and find programs from one tool.

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

輸入參數op必填pathrootsorttypedriveimageformattracksverifywaitMsdiskname另有 12 個

c64_drive

Power cycle drive slots, reset IEC state, switch emulation modes, or load custom ROMs.

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

輸入參數op必填modepathdrive

c64_printer

Print text or bitmaps and define custom characters for Commodore or Epson printers.

Grouped entry point for Commodore and Epson printing helpers.

輸入參數op必填modetextcharstargetcolumnsdensityprinterrepeatsformFeedensureMsbfirstChar另有 3 個

c64_config

List or update settings, access firmware info, take snapshots, and run program shuffle workflows.

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

輸入參數op必填itempathrootvalueupdatescategorydurationMsextensionsoutputPathmaxProgramsapplyToFlash另有 3 個

c64_extract

Export sprites or charsets, dump RAM, compute filesystem stats, or run firmware health checks.

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

輸入參數op必填rootformatlengthstrideaddressretrieschunkSizeoutputDirscanRangeextensionsmaxSprites另有 10 個

c64_stream

Start or stop audio/video/debug streaming in a single tool.

Grouped entry point for starting and stopping Ultimate streaming sessions.

輸入參數op必填streamtarget

c64_debug

Manage breakpoints, inspect registers, and step through code on the VICE backend.

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

輸入參數idop必填modecountlabelpollMswritesaddressenabledmemspaceregistersstopOnHit另有 6 個

c64_vice

Reads or updates selected VICE resources that are safe to expose through MCP.

VICE resources, snapshots.

輸入參數op必填namepathvalue

c64_input

Types text, sends physical key combinations, and controls joysticks.

Cross-platform PETSCII typing plus native Ultimate keyboard and joystick events.

輸入參數op必填keyporttextcountactioninputsdelayMscontrolsdurationMstransition

c64_batch

Runs an ordered list of tool commands and returns all results with per-command timing.

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

輸入參數commands必填stopOnError

版本歷史

11
  1. v1.3.3最新Nov 22, 2026
  2. v1.3.2Nov 21, 2026
  3. v1.3.1Nov 21, 2026
  4. v1.3.0Nov 20, 2026
  5. v1.2.0Nov 14, 2026
  6. v1.1.0Nov 13, 2026
  7. v1.0.7Nov 5, 2026
  8. v1.0.6Oct 15, 2026
  9. v1.0.5Oct 15, 2026
  10. v1.0.4Oct 7, 2026
  11. v1.0.2Sep 16, 2026

評分

已滿足適用檢查項的 90%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分
  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分