Ultimate64 MCP

Commodore 64旗舰版——MCP服务器

⚠️ Alpha发布 这是一个alpha版本。它已经用我自己的Ultimate板和家庭网络设置进行了测试，但我还没有广泛测试所有配置组合和API端点。将此视为玩耍和娱乐的起点！欢迎投稿、错误报告和反馈。

A. 模型上下文协议（MCP） 服务器 Commodore 64终极版 --官方现代Commodore 64电脑。该服务器使Claude、ChatGPT和Cursor等人工智能助手能够通过Ultimate的REST API控制您的C64。

______________________________________________________________________

🎯 这是什么？

Commodore 64终极版

Commodore 64 Ultimate具有USB存储、以太网、HDMI输出和用于远程控制的强大REST API。这个MCP服务器利用REST API让人工智能助手直接和C64交互。

也兼容

此服务器还可以与来自的其他产品配合使用 吉迪恩的逻辑:

所有Ultimate设备都公开了此MCP服务器使用的相同REST API。

这个MCP服务器做什么？

此MCP服务器充当 桥 在人工智能助手和Commodore 64 Ultimate（或其他Ultimate设备）之间，将自然语言命令转换为API调用。有了它，您可以：

• 加载并运行C64程序（PRG、SID、MOD文件）
• 直接读写C64内存
• 安装并创建磁盘映像（D64、D71、D81）
• 控制驱动器仿真
• 管理设备配置
• 流式音频/视频（仅限Ultimate 64）

______________________________________________________________________

✨ 特性

• 37工具 涵盖所有主要的Ultimate设备功能
• 双重运输模式：STDIO（本地）和SSE（远程/托管）
• Docker支持：易于集装箱化部署
• 动态连接：在运行时设置C64连接
• 通过base 64/url上传PRG：从任何地方运行程序
• 缺省巩固安全：非根Docker容器

______________________________________________________________________

📋 可用工具

连接管理

程序执行

音频播放

存储器操作

驱动器和磁盘管理

机器控制

配置

文件操作

流媒体（仅限终极64）

______________________________________________________________________

📦 远程运行程序

这 ultimate_run_prg_binary 该工具旨在运行以下PRG文件 未存储在Ultimate设备上这对于托管部署至关重要，在托管部署中，AI助手需要从外部源上传和运行程序。

三种输入法

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

示例：Base64编码的PRG

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

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

这对于人工智能生成的演示来说尤其强大——人工智能可以：

1. 编写6502汇编代码
2. 编译它（如果工具可用）或直接生成机器代码
3. 将生成的PRG编码为base64
4. 将其发送到实际的C64硬件上运行

示例：URL下载

指向互联网上任何地方托管的PRG：

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

MCP服务器下载文件并将其上传到Ultimate设备。

示例：服务器本地文件

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

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

注： 对于Ultimate设备存储（USB、SD卡）上已有的文件，请使用 ultimate_run_program 相反。

______________________________________________________________________

🚀 快速开始

先决条件

• Python 3.11+
• A. Commodore 64终极版 （或终极64/II+/II+L）在您的网络上
• Ultimate的REST API必须是可访问的（默认情况下启用）

安装

# Clone the repository
git clone https://github.com/yourusername/ultimate64-mcp.git
cd ultimate64-mcp/mcp_hosted

# Install dependencies
pip install -r requirements.txt

运行服务器

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

# Set your Ultimate device's IP address
export C64_HOST="192.168.1.64"

# Start the server
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
# Server starts, then use ultimate_set_connection tool to connect

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

______________________________________________________________________

🔌 运输方式

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

默认模式使用 服务器发送事件（SSE） 用于持久HTTP连接。这非常适合：

• 托管部署（云、VPS）
• 基于网络的人工智能助手
• 多客户端场景

终点：

SSE连接流程：

1. 客户端连接到 GET /sse
2. 服务器发送初始事件 session_id 和端点URL
3. 客户端向发送JSON-RPC请求 POST /messages?session_id={id}
4. 响应通过SSE返回

STDIO模式——供本地使用

对于本地MCP客户端（如Cursor或Claude Desktop），请使用STDIO模式：

python mcp_ultimate_server.py --stdio
# Or with explicit host:
python mcp_ultimate_server.py http://192.168.1.64 --stdio

______________________________________________________________________

🐳 Docker部署

塑造形象

cd mcp_hosted
docker build -t ultimate64-mcp .

运行容器

# With environment variable
docker run -p 8000:8000 -e C64_HOST=192.168.1.64 ultimate64-mcp

# With custom port to Ultimate device (in case C64 is behind NAT/port fowards)
docker run -p 8000:8000 -e C64_HOST=http://192.168.1.64:6464 ultimate64-mcp 

# Start without connection (configure later via tool)
docker run -p 8000:8000 ultimate64-mcp

环境变量

______________________________________________________________________

⚙️ 客户端配置

光标IDE

添加到光标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配置中：

{
  "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)

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"}
}

______________________________________________________________________

🔧 配置文件

这 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用户身份运行
• Ultimate设备API需要网络访问
• 考虑在反向代理后面运行公共部署
• 使用环境变量进行敏感配置

______________________________________________________________________

🐛 故障排除

连接问题

1. 验证Commodore 64 Ultimate是否已通电并连接到网络
2. 在终极菜单（F2）中检查IP地址→ 网络设置）
3. 确保REST API已启用（默认情况下为启用）
4. 测试连接性： curl http:///v1/version

“未配置C64主机”错误

这意味着没有设置连接。要么：

• 设置 C64_HOST 环境变量
• 将URL作为命令行参数传递
• 使用 ultimate_set_connection 启动后的工具

大文件上传

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

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

______________________________________________________________________

📜 许可证

MIT许可证——见 许可证 了解详情。

______________________________________________________________________

🙏 致谢

• 准将 --感谢您将Commodore 64带回官方Commodore 64Ultimate，特别是Christian Simpson，又名PeriFractic
• Anthropic --对于模型上下文协议规范
• Commodore 64社区 --自1982年以来一直保持平台的活力

______________________________________________________________________

🔗 链接

• 吉迪恩的逻辑/最后通牒64.com --终极硬件之家
• 终极REST API文档
• 模型上下文协议规范
• Commodore国际公司

______________________________________________________________________

Have fun with your C64!

马丁 Bosschaart\ 📧 martijn@runstoprestore.nl