c64bridge

# C64 Bridge

![Logo](./doc/img/logo.png)

Your AI Command Bridge for the Commodore 64.

[![npm](https://img.shields.io/npm/v/c64bridge.svg)](https://www.npmjs.com/package/c64bridge)
[![Build](https://img.shields.io/github/actions/workflow/status/chrisgleissner/c64bridge/ci.yaml)](https://github.com/chrisgleissner/c64bridge/actions/workflows/ci.yaml)
[![codecov](https://codecov.io/github/chrisgleissner/c64bridge/graph/badge.svg?token=AS9D41Y5EG)](https://codecov.io/github/chrisgleissner/c64bridge)
[![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-forestgreen)](doc/developer.md)

[![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=io.github.chrisgleissner%2Fc64bridge&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22c64bridge%22%5D%2C%22env%22%3A%7B%22C64_MODE%22%3A%22c64u%22%2C%22C64U_HOST%22%3A%22c64u%22%2C%22VICE_BINARY%22%3A%22%2Fusr%2Flocal%2Fbin%2Fx64sc%22%2C%22VICE_DIRECTORY%22%3A%22%2Fusr%2Flocal%2Fshare%2Fvice%22%2C%22VICE_VISIBLE%22%3A%22true%22%2C%22VICE_WARP%22%3A%22false%22%7D%7D)
[![Install in VS Code Insiders](https://img.shields.io/badge/Install_in-VS_Code_Insiders-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=io.github.chrisgleissner%2Fc64bridge&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22c64bridge%22%5D%2C%22env%22%3A%7B%22C64_MODE%22%3A%22c64u%22%2C%22C64U_HOST%22%3A%22c64u%22%2C%22VICE_BINARY%22%3A%22%2Fusr%2Flocal%2Fbin%2Fx64sc%22%2C%22VICE_DIRECTORY%22%3A%22%2Fusr%2Flocal%2Fshare%2Fvice%22%2C%22VICE_VISIBLE%22%3A%22true%22%2C%22VICE_WARP%22%3A%22false%22%7D%7D&quality=insiders)
[![Install in Visual Studio](https://img.shields.io/badge/Install_in-Visual_Studio-C16FDE?style=flat-square&logo=visualstudio&logoColor=white)](https://vs-open.link/mcp-install?%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22c64bridge%22%5D%2C%22env%22%3A%7B%22C64_MODE%22%3A%22c64u%22%2C%22C64U_HOST%22%3A%22c64u%22%2C%22VICE_BINARY%22%3A%22%2Fusr%2Flocal%2Fbin%2Fx64sc%22%2C%22VICE_DIRECTORY%22%3A%22%2Fusr%2Flocal%2Fshare%2Fvice%22%2C%22VICE_VISIBLE%22%3A%22true%22%2C%22VICE_WARP%22%3A%22false%22%7D%7D)
[![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?style=flat-square&logoColor=white)](https://cursor.com/en/install-mcp?name=io.github.chrisgleissner%2Fc64bridge&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImM2NGJyaWRnZSJdLCJlbnYiOnsiQzY0X01PREUiOiJjNjR1IiwiQzY0VV9IT1NUIjoiYzY0dSIsIlZJQ0VfQklOQVJZIjoiL3Vzci9sb2NhbC9iaW4veDY0c2MiLCJWSUNFX0RJUkVDVE9SWSI6Ii91c3IvbG9jYWwvc2hhcmUvdmljZSIsIlZJQ0VfVklTSUJMRSI6InRydWUiLCJWSUNFX1dBUlAiOiJmYWxzZSJ9fQ==)
[![Use with Claude Code](https://img.shields.io/badge/Use_with-Claude_Code-D97757?style=flat-square&logo=anthropic&logoColor=white)](#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](https://www.commodore.net/), [Ultimate 64](https://ultimate64.com/), or [U2](https://1541u-documentation.readthedocs.io/en/latest/quick_guide.html)-family cartridge. You can also switch to a [VICE](https://vice-emu.sourceforge.io/) emulator session, so one MCP conversation can span hardware and emulation.

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](https://registry.modelcontextprotocol.io/?q=c64bridge).

## Contents

- [C64 Bridge](#c64-bridge)
  - [Contents](#contents)
  - [Overview](#overview)
  - [Features](#features)
  - [Quick Start](#quick-start)
    - [1. Install Node.js 24+ and npm](#1-install-nodejs-24-and-npm)
    - [2. Start the Server](#2-start-the-server)
    - [3. Add Backend Configuration](#3-add-backend-configuration)
    - [4. Connect from an MCP Client](#4-connect-from-an-mcp-client)
  - [Configuration](#configuration)
    - [Configuration File Order](#configuration-file-order)
    - [Configuration Merge Rules](#configuration-merge-rules)
    - [Backend Configuration: C64 Ultimate](#backend-configuration-c64-ultimate)
    - [Backend Configuration: U2-family](#backend-configuration-u2-family)
    - [Backend Configuration: VICE](#backend-configuration-vice)
      - [VICE Window Modes](#vice-window-modes)
      - [Recommended VICE Configurations](#recommended-vice-configurations)
    - [Runtime Backend Switching](#runtime-backend-switching)
  - [VS Code MCP Setup](#vs-code-mcp-setup)
    - [Enable the C64 Agent](#enable-the-c64-agent)
    - [Optional Overrides](#optional-overrides)
    - [Environment Variables in MCP Client Configs](#environment-variables-in-mcp-client-configs)
    - [Runtime Environment Variable Reference](#runtime-environment-variable-reference)
      - [Server Runtime](#server-runtime)
      - [C64 Ultimate](#c64-ultimate)
      - [VICE Runtime](#vice-runtime)
      - [VICE Audio Capture](#vice-audio-capture)
      - [SID Playback](#sid-playback)
      - [RAG](#rag)
      - [Testing](#testing)
  - [Claude Code](#claude-code)
  - [Example Workflow](#example-workflow)
  - [HTTP Invocation](#http-invocation)
  - [Build and Test](#build-and-test)
  - [Documentation](#documentation)
  - [Static MCP Interface](#static-mcp-interface)
  - [MCP API Reference](#mcp-api-reference)
    - [Tools](#tools)
      - [c64\_batch](#c64_batch)
      - [c64\_config](#c64_config)
      - [c64\_debug](#c64_debug)
      - [c64\_disk](#c64_disk)
      - [c64\_drive](#c64_drive)
      - [c64\_extract](#c64_extract)
      - [c64\_graphics](#c64_graphics)
      - [c64\_input](#c64_input)
      - [c64\_memory](#c64_memory)
      - [c64\_printer](#c64_printer)
      - [c64\_program](#c64_program)
      - [c64\_rag](#c64_rag)
      - [c64\_select\_backend](#c64_select_backend)
      - [c64\_sound](#c64_sound)
      - [c64\_stream](#c64_stream)
      - [c64\_system](#c64_system)
      - [c64\_vice](#c64_vice)
    - [Resources](#resources)
    - [Prompts](#prompts)

## Overview

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

The core workflow is simple:

1. Start the MCP server.
2. Point it at 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 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:

```bash
sudo apt install -y nodejs npm
```

macOS:

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

Windows:

```powershell
# winget
winget install OpenJS.NodeJS.LTS
# or Chocolatey
choco 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 ~/c64bridge
npm init -y
npm install c64bridge
node ./node_modules/c64bridge/dist/index.js
```

Run from source for development or testing:

```bash
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](#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](#vs-code-mcp-setup).
- **Claude Code (CLI and VS Code plugin)** — see [Claude Code](#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](#runtime-environment-variable-reference) and the registry manifest in [mcp.json](./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](#configuration); clients only need the command.

## Configuration

### Configuration File Order

The server reads