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