C64 Ultimate MCP

C64终极MCP服务器

用于在Commodore 64 Ultimate设备上开发的模型上下文协议（MCP）服务器。此MCP服务器为AI助手提供工具，通过其REST API、FTP服务器和DMA功能，帮助您直接在C64 Ultimate上编程。

特性

🎮 机器控制

• 重置、重新启动、暂停和恢复C64
• 整机状态控制

💾 项目群管理

• 从Ultimate文件系统加载并运行PRG文件
• 通过FTP上传文件并直接运行
• 从二进制数据运行程序，无需文件系统存储
• 加载并运行盒式（CRT）文件
• 通过ca65组装6502/6510电源，并立即运行

🔧 内存访问（DMA）

• 通过DMA直接读/写存储器
• 从开发环境中窥视和戳戳
• 可用于调试和实时修补

📀 软盘驱动器管理

• 装载和弹出磁盘映像（D64、D71、D81、G64、G71）
• 创建新的磁盘映像
• 控制驱动器设置和模式
• 支持多个驱动器

⚙️ 配置

• 读取并修改C64终极配置
• 从闪存保存/加载设置
• 基于类别的配置管理

📁 文件操作

• FTP文件上传到Ultimate文件系统
• 创建D64、D71和D81磁盘映像
• 完全文件系统访问

🖼️ 图形工具

• 通过以下方式将PNG/JPG/BMP转换为C64位图资源（租用或多色） c64img
• 从图像中提取精灵资源
• 生成ASM包含或BASIC加载器（可选）
• 使用报告进行调色板和约束分析

安装

1. 克隆此存储库：

git clone https://github.com/azcoigreach/c64-ultimate-mcp.git
cd c64-ultimate-mcp

1. 创建虚拟环境并安装依赖项：

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

1. 配置您的C64 Ultimate连接：

# Create .env and set your device IP
cat > .env << 'EOF'
C64_ULTIMATE_HOST=10.45.42.23
C64_ULTIMATE_FTP_HOST=10.45.42.23
C64_ULTIMATE_FTP_USER=anonymous
C64_ULTIMATE_FTP_PASS=
EOF

配置

设置以下环境变量（或使用 .env 文件）：

• C64_ULTIMATE_HOST -C64 Ultimate的IP地址或主机名（例如10.45.42.23）
• C64_ULTIMATE_FTP_HOST -FTP服务器地址（通常与主机相同）
• C64_ULTIMATE_FTP_USER -FTP用户名（默认：匿名）
• C64_ULTIMATE_FTP_PASS -FTP密码（默认值：空）
• ASSEMBLER -装配器选择（默认值： ca65，未来： acme, dasm)
• ASSEMBLER_PATH -汇编二进制文件的路径（默认值： ca65)
• LD65_PATH -ld65链接器二进制文件的路径（默认值： ld65)
• ASSEMBLER_TIMEOUT -程序集超时（秒）（默认值：30）

当前支持：ca65（来自cc65）。ACME/DASM可以稍后添加。

用法

运行MCP服务器

服务器通过stdio进行通信，旨在与MCP兼容的客户端一起使用：

python src/c64_ultimate_mcp.py

与Claude Desktop一起使用

添加到您的Claude Desktop配置(claude_desktop_config.json):

{
  "mcpServers": {
    "c64-ultimate": {
      "command": "/home/azcoigreach/repos/c64-ultimate-mcp/.venv/bin/python",
      "args": [
        "/home/azcoigreach/repos/c64-ultimate-mcp/src/c64_ultimate_mcp.py"
      ],
      "env": {
        "C64_ULTIMATE_HOST": "10.45.42.23"
      }
    }
  }
}

可用工具

系统信息

• get_version -获取C64 Ultimate REST API版本

机器控制

• reset_machine -软重置C64
• reboot_machine -使用墨盒重新初始化完全重新启动
• pause_machine -通过DMA暂停CPU
• resume_machine -从暂停状态恢复

程序加载

• load_prg -将PRG文件加载到内存中（不运行）
• run_prg -加载并自动运行PRG文件（通过键盘缓冲区自动键入run）
• upload_and_run_prg -通过FTP上传，然后运行
• run_prg_from_data -从十六进制数据运行PRG
• run_cartridge -加载并运行CRT文件

汇编

• assemble_asm -组装6502/6510源代码（默认ca65）并返回十六进制编码的PRG
• assemble_and_run_asm -组装6502/6510源代码，并立即通过DMA运行（未存储）

内存访问

• write_memory -通过DMA（十六进制格式）写入C64内存
• read_memory -通过DMA从C64内存读取

驱动器管理

• get_drives -列出所有驱动器及其状态
• mount_disk -将磁盘映像装载到驱动器
• eject_disk -从驱动器中弹出/取出磁盘
• reset_drive -重置特定驱动器

配置

• get_config_categories -列出所有配置类别
• get_config -读取配置值
• set_config -设置配置值
• save_config -将配置保存到闪存（持久）
• load_config -从闪存加载配置

磁盘映像

• create_d64 -创建新的D64图像（35或40个轨迹）
• create_d71 -创建新的D71映像
• create_d81 -创建新的D81图像

文件操作

• upload_file_ftp -通过FTP上传文件

图形工具

• graphics.convert_bitmap -将图像转换为位图资源+清单/报告
• graphics.convert_sprites -将图像转换为精灵资源
• graphics.analyze -报告每个单元格的颜色冲突

示例工作流

快速测试-更改屏幕颜色

Use write_memory tool:
  address: "D020"  (border color)
  data: "0E"       (light blue)

组装和运行（ca65）

Use assemble_and_run_asm:
  source: """
  .segment "CODE"
  lda #$00
  sta $d020 ; border black
  sta $d021 ; background black
  rts
  """
  load_address: 2049  # $0801 default

返回程序集诊断和运行结果。对于没有自动运行BASIC存根的PRG，添加自己的存根或注入 SYS 通过键盘缓冲区。

示例在 examples/*.asm 现在兼容ca65。

图形工具

将图像转换为多色位图资源

python -m graphics convert-bitmap \
  ./examples/title.png ./build/title_bitmap \
  --mode bitmap_multicolor \
  --emit-asm

注意：位图转换使用 c64img 用于调色板处理；这 --dither 标志当前被忽略。

发射的文件：

• bitmap.bin （8000字节）
• screen.bin （1000字节）
• color.bin （1000字节，低半字节=彩色RAM）
• manifest.json + report.json/report.txt
• 可选的 bitmap.inc 用于ASM集成

将排放资产纳入装配项目（ca65）

    .include "build/title_bitmap/bitmap.inc"

BASIC加载器示例

python -m graphics convert-bitmap \
  ./examples/title.png ./build/title_bitmap \
  --mode bitmap_multicolor \
  --emit-basic

雪碧提取

python -m graphics convert-sprites \
  ./examples/sprites.png ./build/sprites \
  --sprite-mode multicolor

MCP JSON使用

{
  "tool": "graphics.convert_bitmap",
  "arguments": {
    "input_path": "/path/to/image.png",
    "mode": "bitmap_multicolor",
    "output_dir": "/path/to/output",
    "dither": false,
    "emit_asm": true
  }
}

默认值和内存布局

• 位图： $2000
• 屏幕RAM： $0400
• 彩色RAM： $D800
• 短跑： $3000

开发和运行程序

1. 在本地编写BASIC或汇编程序
2. 使用附带的标记器将BASIC转换为PRG，或将程序集编译为PRG
3. 上传并运行：

Use upload_and_run_prg:
  local_path: "./examples/test_hello.prg"
  remote_path: "/USB0/repos/examples/test_hello.prg"

BASIC标记器

• 脚本： src/tokenizer.py
• 用途：

/home/azcoigreach/repos/c64-ultimate-mcp/.venv/bin/python src/tokenizer.py examples/test_hello.bas examples/test_hello.prg

• 笔记：

- 与官方BASIC V2令牌（运算符、函数、REM、字符串）对齐 - 通过适当的线路链接生产标准PRG - 示例见 示例 被预标记（PRG重新生成）

创建和装载工作磁盘

1. Use create_d64:
     path: "/usb0/workdisk.d64"
     diskname: "WORK DISK"

2. Use mount_disk:
     drive: "a"
     image: "/usb0/workdisk.d64"
     mode: "readwrite"

调试内存内容

Use read_memory:
  address: "0400"  (screen memory start)
  length: 40       (one line of screen)

开发技巧

• 文件系统路径：终极文件系统使用Unix风格的路径。USB驱动器通常安装在 /USB0/, /USB1/ （设备不区分大小写）。
• 内存地址：始终使用十六进制 $ 前缀（例如，“D020”不是“$D020”）
• PRG文件：标准C64 PRG格式，带2字节加载地址头
• DMA访问：每次调用的写入操作限制为128字节
• 磁盘格式:

- D64:35或40个轨道（170KB/197KB） - D71:70首曲目（340KB） - D81:每边80条轨道（800KB）

API 参考

完整的REST API文档：https://1541u-documentation.readthedocs.io/en/latest/api/api_calls.html

故障排除

连接问题：

• 验证C64 Ultimate是否在网络上且可访问
• 检查配置中的IP地址
• 测试： curl http://YOUR_IP/v1/version

FTP上传失败：

• 确保在C64 Ultimate设置中启用FTP服务器
• 检查防火墙设置
• 验证文件系统是否可写（USB驱动器已连接）

程序无法运行：

• 验证PRG文件格式是否正确
• 检查Ultimate文件系统上是否存在文件路径
• 尝试使用 load_prg 首先在不运行的情况下测试负载

贡献

欢迎投稿！请随时提交问题或拉取请求。

许可证

有关详细信息，请参阅LICENSE文件。

资源

• C64最终文档
• 模型上下文协议
• 终极64/II+产品页面

致谢

• Gideon Zweijtzer为令人难以置信的C64 Ultimate硬件和固件
• MCP社区提供卓越的协议规范

C64最终开发MCP