shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

ultimate64mcp

这是一个为Commodore 64 Ultimate（官方现代C64电脑）设计的MCP服务器，通过REST API让AI助手（如Claude、ChatGPT）能够远程控制C64硬件，支持程序加载、内存操作、磁盘管理等功能。

article

README

🚀 康懋达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年以来一直让该平台保持活力

🔗 链接

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

Martijn Bosschaart
📧 martijn@runstoprestore.nl

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client