Ultimate64MCP

# Commodore 64 Ultimate — MCP 服务器 <p align="center"> <img src="https://img.shields.io/badge/Status-Alpha-orange.svg" alt="Alpha"> <img src="https://img.shields.io/badge/Python-3.11+-blue.svg" alt="Python"> <img src="https://img.shields.io/badge/MCP-1.0-green.svg" alt="MCP"> <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"> </p> > ⚠️ **Alpha 版本** > > 这是一个 Alpha 版本。我已经在自己的 Ultimate 主板和家庭网络设置中进行了测试，但我尚未广泛测试所有配置组合和 API 端点。您可以将其视为一个起点，以便使用和享受！欢迎贡献、错误报告和反馈。 一个适用于 **Commodore 64 Ultimate** 的 **Model Context Protocol (MCP)** 服务器，这是官方的现代 Commodore 64 计算机。该服务器使 Claude、ChatGPT 和 Cursor 等 AI 助手能够通过 Ultimate 的 REST API 控制您的 C64。 --- ## 🎯 这是什么？ ### Commodore 64 Ultimate **Commodore 64 Ultimate** 是 Commodore 的一款官方产品 — 一款适用于现代时代的全新 Commodore 64。内部，它使用由 [Gideon Zweijtzer](https://github.com/GideonZ) 的 [Gideon's Logic](https://ultimate64.com/) 设计的 **Ultimate 64** FPGA 主板。它不是模拟器 — 它 *是* 一个真正的 Commodore 64，周期准确，并使用现代技术构建。 Commodore 64 Ultimate 具有 USB 存储、以太网、HDMI 输出和用于远程控制的强大 REST API。MCP 服务器利用该 REST API，让 AI 助手可以直接与 C64 交互。 ### 也适用于 该服务器也适用于 [Gideon's Logic](https://ultimate64.com/) 的其他产品： | 设备 | 描述 | |--------|-------------| | **[Ultimate 64](https://ultimate64.com/Ultimate-64)** | Gideon Logic 的原始 FPGA-based Commodore 64 主板。 | | **[Ultimate II+](https://ultimate64.com/Ultimate-II)** | 适用于您原始 Commodore 64 或 C128 的卡式机，添加 USB 存储、以太网、驱动器仿真等。 | 所有 Ultimate 设备都暴露相同的 REST API，MCP 服务器使用该 API。 ### MCP 服务器的作用 MCP 服务器充当 AI 助手和您的 Commodore 64 Ultimate（或其他 Ultimate 设备）之间的 **桥梁**，将自然语言命令转换为 API 调用。有了它，您可以： - 加载和运行 C64 程序（PRG、SID、MOD 文件） - 直接读取/写入 C64 内存 - 挂载和创建磁盘镜像（D64、D71、D81） - 控制驱动器仿真 - 管理设备配置 - 流式传输音频/视频（仅限 Ultimate 64） --- ## ✨ 功能 - **37 种工具**，涵盖所有主要的 Ultimate 设备功能 - **双传输模式**：STDIO（本地）和 SSE（远程/托管） - **Docker 支持**：轻松的容器化部署 - **动态连接**：在运行时设置 C64 连接 - **通过 Base64/URL 上传 PRG**：从任何地方运行程序 - **默认安全**：非 root Docker 容器 --- ## 📋 可用工具 ### 连接管理 | 工具 | 描述 | |------|-------------| | `ultimate_set_connection` | 设置 Commodore 64 Ultimate 设备的 hostname 和 port | | `ultimate_get_connection` | 获取当前连接详情 | | `ultimate_version` | 获取 REST API 版本 | ### 程序执行 | 工具 | 描述 | |------|-------------| | `ultimate_run_program` | 运行 Ultimate 文件系统（USB/SD）上已存储的程序 | | `ultimate_load_program` | 加载程序到内存中但不运行 | | `ultimate_run_prg_binary` | **从外部源上传和运行 PRG** — 接受本地文件路径、base64 数据或 URL（[详情](#-running-programs-remotely)） | | `ultimate_run_cartridge` | 加载和运行卡式机文件 (.crt) | ### 音频播放 | 工具 | 描述 | |------|-------------| | `ultimate_play_sid` | 播放 SID 音乐文件（可选歌曲编号） | | `ultimate_play_mod` | 播放 Amiga MOD 音乐文件 | ### 内存操作 | 工具 | 描述 | |------|-------------| | `ultimate_read_memory` | 从 C64 内存地址读取最多 256 个字节 | | `ultimate_write_memory` | 将十六进制数据写入 C64 内存地址 | | `ultimate_write_memory_binary` | 将二进制文件内容写入内存 | ### 驱动器和磁盘管理 | 工具 | 描述 | |------|-------------| | `ultimate_mount_disk` | 在驱动器 A-D 上挂载磁盘镜像（D64/D71/D81） | | `ultimate_unmount_disk` | 从驱动器卸载磁盘 | | `ultimate_turn_drive_on` | 打开虚拟驱动器 | | `ultimate_turn_drive_off` | 关闭虚拟驱动器 | | `ultimate_set_drive_mode` | 设置驱动器类型：1541、1571 或 1581 | | `ultimate_load_drive_rom` | 加载自定义 ROM 到驱动器 | | `ultimate_create_d64` | 创建新的 D64 磁盘镜像（35 或 40 磁轨） | | `ultimate_create_d71` | 创建新的 D71 磁盘镜像 | | `ultimate_create_d81` | 创建新的 D81 磁盘镜像 | | `ultimate_create_dnp` | 创建新的 DNP 磁盘镜像 | ### 机器控制 | 工具 | 描述 | |------|-------------| | `ultimate_reset_machine` | 执行 C64 重置 | | `ultimate_soft_reset` | 软重置（加载空程序） | | `ultimate_reboot_device` | 重启 Ultimate 设备 | | `ultimate_power_off` | 关闭 Ultimate 设备 | | `ultimate_get_machine_info` | 获取机器信息和状态 | | `ultimate_get_machine_state` | 获取当前机器状态 | ### 配置 | 工具 | 描述 | |------|-------------| | `ultimate_get_config_categories` | 列出所有配置类别 | | `ultimate_get_config_category` | 获取类别中的设置 | | `ultimate_get_config_item` | 获取特定设置值 | | `ultimate_set_config_item` | 设置配置值 | | `ultimate_bulk_config_update` | 一次更新多个设置 | | `ultimate_save_config` | 将配置保存到闪存 | | `ultimate_load_config` | 从闪存加载配置 | | `ultimate_reset_config` | 重置为出厂默认值 | ### 文件操作 | 工具 | 描述 | |------|-------------| | `ultimate_get_file_info` | 获取 Ultimate 上的文件信息 | ### 流媒体（仅限 Ultimate 64） | 工具 | 描述 | |------|-------------| | `ultimate_start_stream` | 启动视频、音频或调试流媒体 | | `ultimate_stop_stream` | 停止活动流媒体 | --- ## 📦 远程运行程序 `ultimate_run_prg_binary` 工具旨在运行 **未存储在 Ultimate 设备上的** PRG 文件。这对于托管部署至关重要，其中 AI 助手需要从外部源上传和运行程序。 ### 三种输入方法 | 参数 | 用例 | |-----------|----------| | `prg_data_base64` | AI 将 PRG 嵌入为 base64 请求 — 适用于小型程序或 AI 生成的代码 | | `url` | 服务器从任何 HTTP/HTTPS URL 下载 PRG — 适用于托管程序存档 | | `file_path` | 从服务器的本地文件系统读取 — 用于服务器端程序存储 | **每次调用时应仅提供一个参数。** ### 示例：Base64 编码的 PRG AI 可以将编译的 PRG 程序编码为 base64 并直接发送： ```json { "name": "ultimate_run_prg_binary", "arguments": { "prg_data_base64": "AQgLCJ4ACJ4ACQoAHgoAoCAKgBQKgP8f..." } } ``` 这对于 AI 生成的演示特别有用 — AI 可以： 1. 编写 6502 汇编代码 2. 编译它（如果有工具可用）或直接生成机器代码 3. 将生成的 PRG 编码为 base64 4. 发送它以在实际 C64 硬件上运行 ### 示例：URL 下载 指向互联网上托管的 PRG： ```json { "name": "ultimate_run_prg_binary", "arguments": { "url": "https://csdb.dk/getinternalfile.php/12345/game.prg" } } ``` MCP 服务器下载文件并将其上传到 Ultimate 设备。 ### 示例：服务器本地文件 如果 PRG 在 MCP 服务器的文件系统上： ```json { "name": "ultimate_run_prg_binary", "arguments": { "file_path": "/workspace/demos/mydemo.prg" } } ``` > **注意：** 对于已经在 Ultimate 设备存储（USB、SD 卡）上的文件，请改用 `ultimate_run_program`。 --- ## 🚀 快速入门 ### 先决条件 - Python 3.11+ - 网络上的 **Commodore 64 Ultimate**（或 Ultimate 64/II+/II+L） - Ultimate 的 REST API 必须可访问（默认启用） ### 安装 ```bash # 克隆存储库 git clone https://github.com/yourusername/ultimate64-mcp.git cd ultimate64-mcp/mcp_hosted # 安装依赖项 pip install -r requirements.txt ``` ### 运行服务器 #### 选项 1：环境变量（推荐） ```bash # 设置 Ultimate 设备的 IP 地址 export C64_HOST="192.168.1.64" # 启动服务器 python mcp_ultimate_server.py ``` #### 选项 2：命令行参数 ```bash python mcp_ultimate_server.py http://192.168.1.64 ``` #### 选项 3：动态连接 启动时不配置主机，并在稍后使用 `ultimate_set_connection` 工具设置： ```bash python mcp_ultimate_server.py # 服务器启动，然后使用 ultimate_set_connection 工具连接 ``` 服务器默认在 `http://0.0.0.0:8000` 上运行。 --- ## 🔌 传输模式 ### SSE 模式（默认）— 适用于托管/远程访问 默认模式使用 **服务器发送事件（SSE）** 进行持久的 HTTP 连接。这适用于： - 托管部署（云、VPS） - 基于 Web 的 AI 助手 - 多客户端场景 **端点：** | 端点 | 方法 | 描述 | |----------|--------|-------------| | `/sse` | GET | 建立 SSE 连接，返回会话 ID | | `/messages?session_id={id}` | POST | 发送 JSON-RPC 消息 | | `/upload-prg` | POST | 直接 PRG 上传端点（绕过 MCP 进行大文件上传） | **SSE 连接流程：** 1. 客户端连接到 `GET /sse` 2. 服务器发送具有 `session_id` 和端点 URL 的初始事件 3. 客户端向 `POST /messages?session_id={id}` 发送 JSON-RPC 请求 4. 通过 SSE 向客户端返回响应 ### STDIO 模式 — 适用于本地使用 对于本地 MCP 客户端（例如 Cursor 或 Claude Desktop），使用 STDIO 模式： ```bash python mcp_ultimate_server.py --stdio # 或使用显式主机： python mcp_ultimate_server.py http://192.168.1.64 --stdio ``` --- ## 🐳 Docker 部署 ### 构建镜像 ```bash cd mcp_hosted docker build -t ultimate64-mcp . ``` ### 运行容器 ```bash # 使用环境变量 docker run -p 8000:8000 -e C64_HOST=192.168.1.64 ultimate64-mcp # 使用自定义端口到 Ultimate 设备（如果 C64 在 NAT/端口转发后面） docker run -p 8000:8000 -e C64_HOST=http://192.168.1.64:6464 ultimate64-mcp # 启动时不连接（稍后配置） docker run -p 8000:8000 ultimate64-mcp ``` ### 环境变量 | 变量 | 描述 | 示例 | |----------|-------------|---------| | `C64_HOST` | Ultimate 设备的 IP 地址或 URL | `192.168.1.64` 或 `http://myC64.domain.com:6464` | --- ## ⚙️ 客户端配置 ### Cursor IDE 将以下内容添加到您的 Cursor MCP 设置（`.cursor/mcp.json`）： **适用于 SSE（远程）模式：** ```json { "mcpServers": { "ultimate64-mcp": { "transport": { "type": "sse", "url": "http://your-server-address:8000/sse" } } } } ``` **适用于 STDIO（本地）模式：** ```json { "mcpServers": { "ultimate64-mcp": { "command": "python", "args": ["/path/to/mcp_ultimate_server.py", "--stdio"], "env": { "C64_HOST": "192.168.1.64" } } } } ``` ### Claude Desktop 将以下内容添加到您的 Claude Desktop 配置： ```json { "mcpServers": { "ultimate64-mcp": { "command": "python", "args": ["/path/to/mcp_ultimate_server.py", "--stdio"], "env": { "C64_HOST": "192.168.1.64" } } } } ``` --- ## 📡 直接 PRG 上传端点 除了 MCP `ultimate_run_prg_binary` 工具外，服务器还公开了一个用于上传 PRG 文件的直接 REST 端点。这对于： - **大文件**（>100KB）其中 MCP 协议开销不理想 - **非 MCP 客户端**直接上传程序 - **自动化脚本** 和 CI/CD 管道 - **Web 应用程序** 与 Ultimate 设备集成 ### 端点 ``` POST /upload-prg ``` ### 支持的内容类型 **1. 多部分表单上传** (`multipart/form-data`) ```bash curl -X POST http://localhost:8000/upload-prg \ -F "file=@myprogram.prg" ``` **2. 原始二进制上传** (`application/octet-stream`) ```bash curl -X POST http://localhost:8000/upload-prg \ -H "Content-Type: application/octet-stream" \ --data-binary @myprogram.prg ``` **3. Base64 JSON 上传** (`application/json`) ```bash curl -X POST http://localhost:8000/upload-prg \ -H "Content-Type: application/json" \ -d '{"prg_data_base64": "AQgLCJ4A..."}' ``` ### 响应 ```json { "success": true, "message": "Running PRG (1234 bytes)", "size_bytes": 1234, "response": {"message": "Program started"} } ``` --- ## 🔧 配置文件 `config.json` 文件提供默认设置： ```json { "ultimate": { "base_url": "http://192.168.1.64:6464", "timeout": 30, "retry_attempts": 3 }, "logging": { "level": "INFO", "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s" } } ``` > 注意：环境变量和命令行参数优先于 `config.json`。 --- ## 🛠️ API 参考 ### JSON-RPC 协议 服务器实现了 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 规范。所有通信都使用 JSON-RPC 2.0。 **示例：列出工具** ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } **示例：调用工具 ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "ultimate_play_sid", "arguments": { "file": "/Usb0/Music/Commando.sid", "song_number": 1 } } } ``` --- ## 🔐 安全考虑 - Docker 容器以非 root 用户运行 - Ultimate 设备 API 需要网络访问 - 考虑为公共部署使用反向代理 - 使用环境变量进行敏感配置 --- ## 🐛 故障排除 ### 连接问题 1. 验证您的 Commodore 64 Ultimate 是否已开启并连接到网络 2. 检查 Ultimate 菜单中的 IP 地址（F2 → 网络设置） 3. 确保 REST API 已启用（默认启用） 4. 测试连接：`curl http://<C64_HOST>/v1/version` ### "未配置 C64 主机" 错误 这意味着未配置连接。 Either： - 设置 `C64_HOST` 环境变量 - 将 URL 作为命令行参数传递 - 使用 `ultimate_set_connection` 工具启动后 ### 大文件上传 对于 >100KB 的 PRG 文件，请考虑： - 使用 `/upload-prg` REST 端点直接上传 - 使用 `url` 参数在 `ultimate_run_prg_binary` 中让服务器获取文件 --- ## 📜 许可证 MIT 许可证 - 参见 [LICENSE](LICENSE) 了解详情。 --- ## 🙏 致谢 - **[Commodore](https://www.commodore.net) - 感谢 Commodore 64 Ultimate 的发布，特别是 Christian Simpson aka PeriFractic - **[Gideon Zweijtzer](https://github.com/GideonZ) / [Gideon's Logic](https://ultimate64.com/)** - Gideon's Logic 的 Ultimate 64 主板、Ultimate II+ 和整个 1541 Ultimate 项目的创作者。他的不可思议的 FPGA 工程技术为 Commodore 64 Ultimate 提供了硬件，使 C64 社区能够拥有将复古计算与现代便利相结合的硬件。 - **[Anthropic](https://anthropic.com/)** - 适用于 Model Context Protocol 规范 - **Commodore 64 社区** - 自 1982 年以来让该平台保持活力 --- ## 🔗 链接 - [Gideon's Logic / Ultimate64.com](https://ultimate64.com/) - 硬件的家园 - [1541 Ultimate 项目在 GitHub](https://github.com/GideonZ/1541ultimate) - [Ultimate REST API 文档](https://github.com/GideonZ/1541ultimate/wiki/Ultimate-REST-API) - [Model Context Protocol 规范](https://modelcontextprotocol.io/) - [Commodore 国际公司](https://www.commodore.net) <p align="center"> <i>尽情享受您的 C64！</i> </p> **Martijn Bosschaart** 📧 [martijn@runstoprestore.nl](mailto:martijn@runstoprestore.nl)