JinDaGe - c64u-mcp-server MCP Details

article

README

🚀 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

c64u-mcp-server