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

环境变量

💻 使用示例

基础用法

远程运行程序

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

三种输入方式

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

示例：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的其他产品：

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

此MCP服务器的功能

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

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

可用工具

连接管理

程序执行

音频播放

内存操作

驱动器和磁盘管理

机器控制

配置

文件操作

流式传输（仅适用于Ultimate 64）

传输模式

SSE模式（默认） — 用于托管/远程访问

默认模式使用服务器发送事件（SSE） 进行持久HTTP连接。此模式适用于：

• 托管部署（云、VPS）
• 基于Web的AI助手
• 多客户端场景

端点：

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