C64u MCP Server

🚀 Commodore 64 Ultimate MCP 服务器

使用人工智能控制你的 Commodore 64 Ultimate 设备。这个 MCP 服务器允许 Claude 和其他 AI 助手通过本地网络与你的 C64 Ultimate 硬件进行交互。

🚀 快速开始

本服务器实现了 模型上下文协议 (MCP)，将 C64 Ultimate REST API 作为工具暴露给 AI 助手使用。当连接到 Claude Desktop 或其他 MCP 客户端时，你可以就你的 C64 进行自然对话，Claude 将使用这些工具来执行你的请求。

✨ 主要特性

• 创建和调试程序：Claude 可以编写 C64 BASIC 或机器代码程序，运行它们，捕获屏幕以查看结果，检查内存，并迭代修复问题。描述你的需求，然后看着 Claude 在真实硬件上开发程序。
• 编写和运行 BASIC 程序：要求 Claude 编写一个 BASIC 程序，它将对代码进行标记化处理，直接将其注入 C64 内存并运行，无需手动输入。
• 玩经典游戏和演示：从设备存储中加载并运行 .PRG 程序或 .CRT 卡带镜像，也可以直接上传这些文件。
• 聆听 SID 音乐：播放经典的 C64 SID 曲调或 Amiga MOD 音轨文件，只需指定设备上的文件或上传一个文件即可。
• 查看屏幕内容：从任何图形模式（文本、多色、高分辨率位图等）捕获屏幕截图，Claude 可以查看屏幕上的情况并做出相应响应。
• 输入和控制：通过键盘缓冲区发送按键、导航菜单并与正在运行的程序进行交互。
• 管理软盘驱动器：挂载和卸载 D64/D71/D81 磁盘镜像，在 1541/1571/1581 仿真模式之间切换，以及创建新的磁盘镜像。
• 读写内存：通过 DMA 直接检查和修改 C64 内存，这对于调试、修改值或检查程序状态非常有用。
• 配置设备：调整设备设置，将配置保存到闪存，并管理你的 C64 Ultimate 配置。

📦 安装指南

前提条件

从 C64 Ultimate 菜单中启用 Web 远程控制服务：

• 导航至：网络设置 → Web 远程控制服务 → 启用

安装步骤

cd c64u-mcp-server
uv sync

配置

将 C64U_URL 环境变量设置为你的设备 IP 地址：

export C64U_URL="http://192.168.200.157"

默认值：http://192.168.200.157

运行服务器

uv run python server.py

Claude Desktop 配置

将以下内容添加到你的 Claude Desktop claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "commodore64": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/c64u-mcp-server", "python", "server.py"],
      "env": {
        "C64U_URL": "http://192.168.200.157"
      }
    }
  }
}

💻 使用示例

可用工具

机器控制

• machine_reset - 重置 C64
• machine_reboot - 重启 Ultimate 设备
• machine_pause - 通过 DMA 暂停 CPU
• machine_resume - 从暂停状态恢复
• machine_poweroff - 关机（仅适用于 U64）
• capture_screen - 将 C64 屏幕捕获为 PNG 图像
• type_text - 将文本输入到键盘缓冲区（支持特殊键）
• send_key - 向键盘缓冲区发送特殊键
• enter_basic_program - 直接将 BASIC 程序输入到内存（已标记化）

内存访问

• write_memory - 将十六进制数据写入 C64 内存
• write_memory_binary - 将二进制数据写入内存（Base64 编码）
• read_memory - 读取 C64 内存
• read_debug_register - 读取调试寄存器（U64）
• write_debug_register - 写入调试寄存器（U64）

运行器（SID/MOD/PRG/CRT）

• sidplay_file - 从设备文件系统播放 SID 文件
• sidplay_upload - 上传并播放 SID 文件（Base64 编码）
• modplay_file - 从设备文件系统播放 MOD 文件
• modplay_upload - 上传并播放 MOD 文件（Base64 编码）
• load_prg_file - 加载 PRG 文件但不执行
• load_prg_upload - 上传并加载 PRG 文件（Base64 编码）
• run_prg_file - 从文件系统加载并运行 PRG 文件
• run_prg_upload - 上传并运行 PRG 文件（Base64 编码）
• run_crt_file - 从文件系统启动卡带
• run_crt_upload - 上传并启动卡带（Base64 编码）

软盘驱动器

• list_drives - 列出所有驱动器和已挂载的镜像
• mount_disk_file - 从文件系统挂载磁盘
• mount_disk_upload - 上传并挂载磁盘（Base64 编码）
• drive_reset - 重置驱动器
• drive_remove - 卸载磁盘
• drive_on - 启用驱动器
• drive_off - 禁用驱动器
• drive_load_rom_file - 加载自定义 ROM
• drive_load_rom_upload - 上传自定义 ROM（Base64 编码）
• drive_set_mode - 更改驱动器类型（1541/1571/1581）

配置

• list_config_categories - 列出所有配置类别
• get_config_category - 获取某个类别中的项目
• get_config_item - 获取特定的配置项
• set_config_item - 设置配置项的值
• batch_set_config - 设置多个配置项
• load_config_from_flash - 从闪存恢复配置
• save_config_to_flash - 将配置保存到闪存
• reset_config_to_default - 重置为出厂默认设置

流（仅适用于 U64）

• stream_start - 启动视频/音频/调试流
• stream_stop - 停止活动流

文件操作

• get_file_info - 获取文件元数据
• get_version - 获取 REST API 版本
• create_d64 - 创建 D64 磁盘镜像
• create_d71 - 创建 D71 磁盘镜像
• create_d81 - 创建 D81 磁盘镜像
• create_dnp - 创建 DNP 磁盘镜像

📚 详细文档

API 参考基于：https://1541u-documentation.readthedocs.io/en/latest/api/api_calls.html