Ultimate64mcp

🚀 康懋达64终极版 — MCP服务器

这是一款用于康懋达64终极版（官方推出的现代康懋达64计算机）的模型上下文协议（MCP）服务器。该服务器能让Claude、ChatGPT和Cursor等AI助手通过终极版的REST API控制你的康懋达64计算机。

⚠️ 重要提示

这是一个Alpha版本。该版本已在我自己的终极版主板和家庭网络设置中进行了测试，但我尚未对所有配置组合和API端点进行全面测试。请将此版本视为一个有趣的起点！欢迎大家贡献代码、报告漏洞和提供反馈。

---

🚀 快速开始

前提条件

• Python 3.11及以上版本
• 网络中存在一台康懋达64终极版（或Ultimate 64/II+/II+L）设备
• 终极版的REST API必须可访问（默认已启用）

安装

# 克隆仓库
git clone https://github.com/yourusername/ultimate64-mcp.git
cd ultimate64-mcp/mcp_hosted

# 安装依赖
pip install -r requirements.txt

启动服务器

选项1：使用环境变量（推荐）

# 设置你的终极版设备的IP地址
export C64_HOST="192.168.1.64"

# 启动服务器
python mcp_ultimate_server.py

选项2：使用命令行参数

python mcp_ultimate_server.py http://192.168.1.64

选项3：动态连接

先不配置主机，稍后通过ultimate_set_connection工具进行设置：

python mcp_ultimate_server.py
# 服务器启动后，使用ultimate_set_connection工具进行连接

服务器默认运行在http://0.0.0.0:8000。

---

✨ 主要特性

• 37种工具：涵盖了终极版设备的所有主要功能
• 双传输模式：STDIO（本地）和SSE（远程/托管）
• 支持Docker：便于容器化部署
• 动态连接：可在运行时设置康懋达64的连接
• 通过Base64/URL上传PRG文件：可从任何位置运行程序
• 默认安全：使用非root用户的Docker容器

---

📦 安装指南

构建镜像

cd mcp_hosted
docker build -t ultimate64-mcp .

运行容器

# 使用环境变量
docker run -p 8000:8000 -e C64_HOST=192.168.1.64 ultimate64-mcp

# 使用自定义端口连接到终极版设备（如果康懋达64位于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	终极版设备的IP地址或URL，例如192.168.1.64或http://myC64.domain.com:6464

---

💻 使用示例

基础用法

远程运行程序

ultimate_run_prg_binary工具用于运行未存储在终极版设备上的PRG文件。这对于托管部署非常重要，因为AI助手需要从外部源上传和运行程序。

三种输入方式

参数	使用场景
prg_data_base64	AI将PRG文件以Base64编码嵌入请求中，适用于小型程序或AI生成的代码
url	服务器从任何HTTP/HTTPS URL下载PRG文件，适用于托管程序存档
file_path	从服务器的本地文件系统读取，适用于服务器端程序存储

每次调用只能提供一个参数。

示例：Base64编码的PRG文件

AI可以将编译后的PRG程序编码为Base64并直接发送：

{
  "name": "ultimate_run_prg_binary",
  "arguments": {
    "prg_data_base64": "AQgLCJ4ACJ4ACQoAHgoAoCAKgBQKgP8f..."
  }
}

这对于AI生成的演示程序特别有用，AI可以：

1. 编写6502汇编代码
2. 编译代码（如果有可用工具）或直接生成机器代码
3. 将生成的PRG文件编码为Base64
4. 发送到实际的康懋达64硬件上运行

示例：通过URL下载

指向互联网上任何位置的PRG文件：

{
  "name": "ultimate_run_prg_binary",
  "arguments": {
    "url": "https://csdb.dk/getinternalfile.php/12345/game.prg"
  }
}

MCP服务器将下载文件并上传到终极版设备。

示例：服务器本地文件

如果PRG文件位于MCP服务器的文件系统中：

{
  "name": "ultimate_run_prg_binary",
  "arguments": {
    "file_path": "/workspace/demos/mydemo.prg"
  }
}

注意：对于已经存储在终极版设备存储（USB、SD卡）中的文件，请使用ultimate_run_program工具。

高级用法

直接上传PRG文件的端点

除了MCP的ultimate_run_prg_binary工具外，服务器还提供了一个直接的REST端点用于上传PRG文件。这对于以下场景非常有用：

• 大文件（>100KB）：避免MCP协议的开销
• 非MCP客户端：直接上传程序
• 自动化脚本和CI/CD管道
• Web应用程序：集成终极版设备

端点

POST /upload-prg

支持的内容类型

1. 多部分表单上传 (multipart/form-data)

curl -X POST http://localhost:8000/upload-prg \
  -F "file=@myprogram.prg"

2. 原始二进制上传 (application/octet-stream)

curl -X POST http://localhost:8000/upload-prg \
  -H "Content-Type: application/octet-stream" \
  --data-binary @myprogram.prg

3. Base64 JSON上传 (application/json)

curl -X POST http://localhost:8000/upload-prg \
  -H "Content-Type: application/json" \
  -d '{"prg_data_base64": "AQgLCJ4A..."}'

响应

{
  "success": true,
  "message": "Running PRG (1234 bytes)",
  "size_bytes": 1234,
  "response": {"message": "Program started"}
}

---

📚 详细文档

康懋达64终极版

康懋达64终极版是康懋达官方推出的产品，是一款面向现代的全新康懋达64计算机。其内部使用了由Gideon Zweijtzer（来自Gideon's Logic）设计的Ultimate 64 FPGA主板的改进版本。它不是模拟器，而是一台真正的康懋达64计算机，具有精确的周期性能，并采用了现代技术构建。

康懋达64终极版具备USB存储、以太网、HDMI输出以及强大的远程控制REST API。此MCP服务器利用该REST API让AI助手直接与康懋达64进行交互。

兼容设备

该服务器还支持Gideon's Logic的其他产品：

设备	描述
Ultimate 64	Gideon's Logic推出的基于FPGA的原始康懋达64主板
Ultimate II+	适用于原始康懋达64或C128的扩展卡，可添加USB存储、以太网、驱动器仿真等功能

所有终极版设备都提供了此MCP服务器使用的相同REST API。

此MCP服务器的功能

此MCP服务器充当AI助手与康懋达64终极版（或其他终极版设备）之间的桥梁，将自然语言命令转换为API调用。借助它，你可以：

• 加载和运行康懋达64程序（PRG、SID、MOD文件）
• 直接读写康懋达64的内存
• 挂载和创建磁盘镜像（D64、D71、D81）
• 控制驱动器仿真
• 管理设备配置
• 流式传输音频/视频（仅适用于Ultimate 64）

可用工具

连接管理

工具	描述
ultimate_set_connection	设置终极版康懋达64设备的主机名和端口
ultimate_get_connection	获取当前连接详情
ultimate_version	获取REST API版本

程序执行

工具	描述
ultimate_run_program	运行已存储在终极版文件系统（USB/SD）中的程序
ultimate_load_program	将程序加载到内存中但不运行
ultimate_run_prg_binary	从外部源上传并运行PRG文件 — 接受本地文件路径、Base64数据或URL（详情）
ultimate_run_cartridge	加载并运行卡带文件（.crt）

音频播放

工具	描述
ultimate_play_sid	播放SID音乐文件（可选歌曲编号）
ultimate_play_mod	播放Amiga MOD音乐文件

内存操作

工具	描述
ultimate_read_memory	从康懋达64的内存地址读取最多256字节的数据
ultimate_write_memory	将十六进制数据写入康懋达64的内存地址
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	对康懋达64进行复位操作
ultimate_soft_reset	软复位（加载空程序）
ultimate_reboot_device	重启终极版设备
ultimate_power_off	关闭终极版设备的电源
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 64）

工具	描述
ultimate_start_stream	开始视频、音频或调试流传输
ultimate_stop_stream	停止正在进行的流传输

传输模式

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模式：

python mcp_ultimate_server.py --stdio
# 或指定主机
python mcp_ultimate_server.py http://192.168.1.64 --stdio

客户端配置

Cursor IDE

在Cursor MCP设置（.cursor/mcp.json）中添加以下内容： SSE（远程）模式：

{
  "mcpServers": {
    "ultimate64-mcp": {
      "transport": {
        "type": "sse",
        "url": "http://your-server-address:8000/sse"
      }
    }
  }
}

STDIO（本地）模式：

{
  "mcpServers": {
    "ultimate64-mcp": {
      "command": "python",
      "args": ["/path/to/mcp_ultimate_server.py", "--stdio"],
      "env": {
        "C64_HOST": "192.168.1.64"
      }
    }
  }
}

Claude Desktop

在Claude Desktop配置中添加以下内容：

{
  "mcpServers": {
    "ultimate64-mcp": {
      "command": "python",
      "args": ["/path/to/mcp_ultimate_server.py", "--stdio"],
      "env": {
        "C64_HOST": "192.168.1.64"
      }
    }
  }
}

配置文件

config.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协议

服务器实现了模型上下文协议（MCP）规范。所有通信均使用JSON-RPC 2.0。

示例：列出工具

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

示例：调用工具

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "ultimate_play_sid",
    "arguments": {
      "file": "/Usb0/Music/Commando.sid",
      "song_number": 1
    }
  }
}

---

🔧 技术细节

安全考虑

• Docker容器以非root用户身份运行
• 终极版设备的API需要网络访问权限
• 对于公共部署，建议在反向代理后面运行
• 使用环境变量存储敏感配置信息

故障排除

连接问题

1. 确保你的康懋达64终极版设备已开机并连接到网络
2. 检查终极版菜单中的IP地址（F2 → 网络设置）
3. 确保REST API已启用（默认已启用）
4. 测试连接：curl http://<C64_HOST>/v1/version

“未配置康懋达64主机”错误

这意味着尚未设置连接。你可以：

• 设置C64_HOST环境变量
• 通过命令行参数传递URL
• 在启动后使用ultimate_set_connection工具进行连接

大文件上传

对于大于~100KB的PRG文件，可考虑：

• 直接使用/upload-prg REST端点
• 在ultimate_run_prg_binary中使用url参数让服务器获取文件

---

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

---

🙏 致谢

• 康懋达 — 推出了官方的康懋达64终极版，特别感谢Christian Simpson（又名PeriFractic）
• Gideon Zweijtzer / Gideon's Logic — Ultimate 64主板、Ultimate II+以及整个1541 Ultimate项目的创造者。他卓越的FPGA工程技术为康懋达64终极版提供了强大支持，为康懋达64社区带来了连接复古计算与现代便利的硬件设备
• Anthropic — 提供了模型上下文协议规范
• 康懋达64社区 — 自1982年以来一直让该平台保持活力

---

🔗 链接

• Gideon's Logic / Ultimate64.com — 终极版硬件的官方网站
• GitHub上的1541 Ultimate项目
• 终极版REST API文档
• 模型上下文协议规范
• 康懋达国际公司

---

愿你在康懋达64上玩得开心！

Martijn Bosschaart
📧 martijn@runstoprestore.nl