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