C64 MCP

C64桥

Commodore 64的人工智能指挥桥。

C64 Bridge是一个MCP服务器，用于从AI客户端控制Commodore 64并与之协同工作。

它允许您在真实的计算机上运行程序、读写内存、渲染图形和播放声音 Commodore 64终极版 或 终极64。您也可以切换到 副 仿真器会话随时可用，因此相同的MCP对话适用于硬件和仿真器。

它基于官方的TypeScript构建 @modelcontextprotocol/sdk 并支持两者 stdio 用于本地AI集成，以及用于手动检查的可选HTTP桥。

C64桥列在 MCP官方登记处.

目录

• C64桥

- 目录 - 概述 - 特性 - 快速开始 - - 2.启动服务器 - 3.添加后端配置 - 4.从MCP客户端连接 - 配置 - 配置文件顺序 - 配置合并规则 - 后端配置：C64终极版 - 后端配置：VICE - 运行时后端切换 - VS代码MCP设置 - 启用C64代理 - 可选替代 - MCP客户端配置中的环境变量 - 运行时环境变量引用 - 服务器运行时 - C64终极版 - VICE运行时 - VICE音频采集 - SID播放 - 检索增强生成 - 测试 - 示例工作流程 - HTTP调用 - 构建和测试 - 文档 - 静态MCP接口 - MCP API参考 - 工具 - c64_config - c64_debug - c64_disk - c64_drive - c64_提取 - c64_图形 - c64_内存 - c64_打印机 - c64_程序 - c64_rag - c64_选择_备份 - c64_声音 - c64_流 - c64_系统 - c64_冰 - 资源 - 提示

概述

C64 Bridge为AI代理提供了一个地方，可以在Commodore 64环境中驱动程序执行、内存访问、图形、声音、存储、打印机工作流程和知识检索。

核心工作流程很简单：

1. 启动MCP服务器。
2. 将其指向C64 Ultimate硬件、VICE或两者。
3. 让客户端调用分组的MCP工具，例如 c64_program, c64_memory, c64_graphics，以及 c64_sound.
4. 使用以下命令在运行时切换后端 c64_select_backend 当两者都被配置时。

特性

• 用于BASIC、6510汇编和PRG或CRT执行的程序运行器
• 完全内存访问，包括原始读写和屏幕轮询
• 驱动器、文件、打印机和任务编排的系统集成
• 用于播放、作曲、生成和验证的SID音乐工具
• 内置知识资源和提示，实现更安全的法学硕士工作流程
• 硬件的混合运行时支持 c64u 和模拟器 vice

快速开始

如果你想走最短的路，做以下四件事：

1. 安装Node.js 24+和npm。
2. 启动服务器。
3. 为C64 Ultimate、VICE或两者添加后端配置。
4. 从VS Code或其他MCP客户端连接。

1.安装Node.js 24+和npm

Linux（Ubuntu或Debian）：

推荐：

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

退路：

sudo apt install -y nodejs npm

macOS：

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

窗户：

# winget
winget install OpenJS.NodeJS.LTS
# or Chocolatey
choco install nodejs-lts -y

验证安装：

node --version

预期结果： v24.x

2.启动服务器

使用以下入口点之一。

逃离 npx 零设置：

npx -y c64bridge@latest

从本地npm安装运行：

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

从源代码运行以进行开发或测试：

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

启动时，服务器探测所选目标，执行连接检查，然后宣布它正在stdio上运行。

3.添加后端配置

服务器可以针对以下对象运行：

• 只有C64终极硬件
• 只有VICE
• 一个会话中的两个后端，具有运行时切换功能

详细的查找顺序、合并规则、后端示例和覆盖模型在 配置 下面的部分。

4.从MCP客户端连接

如果您使用VS Code，请按照 VS代码MCP设置 下面的部分。

如果您使用另一个MCP客户端，请将其指向 stdio 服务器入口点，并按照本README和 mcp.json.

配置

配置文件顺序

服务器按以下顺序读取配置：

1. C64BRIDGE_CONFIG，如果它指向配置文件
2. .c64bridge.json 在项目根中
3. ~/.c64bridge.json 在主目录中

配置合并规则

在按顺序扫描这些文件时，每个后端部分都会合并配置。

• 第一个包含 c64u 第节提供了C64终极配置。
• 第一个包含 vice 部分提供VICE配置。
• 这允许项目在本地 .c64bridge.json 定义 c64u 当 ~/.c64bridge.json 定义 vice，两个后端在运行时都可用。

后端配置：C64终极版

将此用于C64终极版或终极64：

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

• 如果找不到文件，则默认目标为 c64u:80 没有网络密码。
• networkPassword 仅当您在C64 Ultimate网络设置中启用密码时才需要。
• C64U_HOST, C64U_PORT，以及 C64U_PASSWORD 覆盖配置的主机、端口和网络密码。

后端配置：VICE

将此用于受管理的VICE启动：

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

• directory 是可选的。如果省略，C64 Bridge会通过查找仿真器二进制文件附近和公共系统位置中的标准C64 ROM集来自动检测VICE资源目录。
• VICE_BINARY, VICE_DIRECTORY, VICE_HOST, VICE_PORT, VICE_VISIBLE, VICE_WARP，以及 VICE_ARGS 在不编辑配置文件的情况下覆盖受管理的VICE启动。
• 如果没有配置显式二进制文件，运行时更喜欢 /usr/local/bin/x64sc 如果存在，则回退到 x64sc 或 x64 上 PATH 因此，相同的设置在操作系统之间仍然是可移植的。

\[！注意\] VICE仅支持在中标记有VICE复选标记的操作 MCP API参考.返回不支持的操作 unsupported_platform.

运行时后端切换

当两者都 c64u 和 vice C64 Bridge从一个活动后端开始，并保持另一个可用于运行时切换。

• C64_MODE 选择初始后端： c64u 或 vice
• c64_select_backend 在不重新启动MCP服务器的情况下切换后端
• c64://platform/status 报告活动后端和完整配置的后端集
• 在提示中，说出以下内容 use vice, vice: run this program, use c64u，或 run this on the real machine
• 在VS Code中，当您想强制执行模拟器而不是硬件时，请在同一提示中包含后端首选项

提示图（通过VS Code中的Copilot发布，使用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

下面的屏幕截图是在这些提示运行后，使用相同的方法从实际的后端位图响应中捕获的 c64_graphics capture_frame MCP工具位于两个后端。C64U实现捕获流式视频帧，而VICE实现捕获并规范仿真器显示帧。然后，使用C64字符生成器对这两幅图像与预期文本进行光学验证，两者完全匹配。

VS代码MCP设置

如果此存储库已在本地签出，请打开准备好的 .vcode/mcp.json.

否则，请将以下内容放入您自己的 .vscode/mcp.json:

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

然后单击上面显示的开始按钮 c64bridge 进入。

您的MCP服务器现在应该正在运行：

有关更多详细信息，请参阅官方 VS代码MCP服务器文档.

启用C64代理

服务器运行后，切换到 C64 VS Code中的代理。

此代理已针对Commodore 64工作进行了预配置。它将Copilot引导到 c64bridge BASIC、6502组装、SID音频、VIC-II图形、内存检查、磁盘操作、打印、流媒体和设备控制的工作流程。

可选替代

您可以添加 env 条目在 .vscode/mcp.json 要选择配置文件，请覆盖C64 Ultimate连接详细信息，或强制初始后端：

{
  "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 指向特定的配置文件
• C64U_HOST, C64U_PORT，以及 C64U_PASSWORD 在不编辑配置文件的情况下覆盖C64 Ultimate连接
• C64_MODE 强制初始后端 c64u 或 vice
• LOG_LEVEL=debug 启用详细日志记录

MCP客户端配置中的环境变量

根目录中记录的每个运行时环境变量 mcp.json 可以由您的MCP客户端配置提供，包括 .vscode/mcp.json 在...之下 servers.c64bridge.env.

当环境变量映射到JSON配置字段时，覆盖顺序始终为：

1. MCP客户端配置或shell中的显式环境变量
2. 从加载的合并JSON配置部分 C64BRIDGE_CONFIG，回购 .c64bridge.json那么 ~/.c64bridge.json
3. 编译到服务器中的内置默认值

当环境变量没有等效的JSON配置时，顺序为：

1. MCP客户端配置或shell中的显式环境变量
2. 内置默认值

该规则统一适用于下面记录的运行时环境变量。

示例：具有特定ROM或资源目录的可见VICE，以及在运行时仍可以立即选择的硬件回退：

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

示例：保留后端端点的JSON配置文件，但覆盖VS代码中的诊断、轮询和RAG行为：

{
  "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"
      }
    }
  }
}

运行时环境变量引用

中记录的每个运行时环境变量 mcp.json 可以在MCP客户端配置中设置，包括 .vscode/mcp.json 在...之下 servers.c64bridge.env.

服务器运行时

C64终极版

VICE运行时

VICE音频采集

SID播放

检索增强生成

测试

示例工作流程

使用ChatGPT和VS Code创作一首儿歌：

然后为它渲染PETSCII艺术：

这代表了预期的工作流程：

1. 要求MCP客户端生成或改进面向C64的内容。
2. 使用分组工具，如 c64_program, c64_graphics，以及 c64_sound 执行它。
3. 通过屏幕读取、帧捕获、内存检查或音频分析验证结果。

HTTP调用

• 首选交通工具是 stdio.
• 默认情况下，HTTP桥被禁用，仅用于手动测试。
• 以下curl命令是说明性的，因此您可以看到HTTP上分组的MCP调用是什么样子的。

# Upload and run BASIC
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"op":"upload_run_basic","program":"10 PRINT \"HELLO\"\n20 GOTO 10"}' \
  http://localhost:8000/tools/c64_program | jq

# Read current screen (PETSCII→ASCII)
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"op":"read_screen"}' \
  http://localhost:8000/tools/c64_memory | jq

# Reset the machine
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"op":"reset"}' \
  http://localhost:8000/tools/c64_system

构建和测试

这 ./build 项目根目录下的脚本将所有开发任务封装在一个单独的、自文档化的界面后面：

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

启动MCP服务器 不由管理 ./build.使用 npm start （来源）或 npx -y c64bridge@latest （已发布的包）如所示 快速开始 上面的部分。

文档

• doc/developer.md --开发工作流程和RAG详细信息
• data/context/bootstrap.md --在提示之前注入底漆
• doc/c64u/c64-openapi.yaml --REST界面（OpenAPI 3.1）
• 代理商.md --LLM面临快速设置、使用和角色

静态MCP接口

存储库包含MCP服务器接口的自动生成的静态镜像 ./mcp 文件夹。

这允许代理在不连接到服务器的情况下检查可用的工具、资源、提示和模式。

MCP API参考

此MCP服务器公开 15工具, 26资源，以及 10个提示 用于控制Commodore 64。

工具

c64_config

配置读/写、诊断和快照的分组入口点。

c64_debug

VICE调试器操作的分组入口点（断点、寄存器、步进）。

c64_disk

磁盘装载、列表、映像创建和程序发现的分组入口点。

c64_drive

驱动器电源、模式、重置和ROM操作的分组入口点。

c64_提取

用于精灵/字符集提取、内存转储、文件系统统计和固件健康检查的分组入口点。

c64_图形

帧捕获和图形渲染工作流的分组入口点。

c64_内存

内存I/O、屏幕读取和屏幕轮询的分组入口点。

c64_打印机

Commodore和Epson打印助手的分组入口点。

c64_程序

程序上传、执行和批处理工作流的分组入口点。

c64_rag

BASIC和汇编RAG查找的分组入口点。

c64_选择_备份

在运行时在C64U硬件和VICE仿真器之间切换活动后端。

c64_声音

SID控制、播放、合成和分析工作流的分组入口点。

c64_流

用于启动和停止Ultimate流媒体会话的分组入口点。

c64_系统

电源、重置、菜单和后台任务控制的分组入口点。

c64_冰

用于读取和更新选定VICE资源的分组入口点。

资源

提示