C64u MCP Server

🚀 Commodore 64 Ultimate MCP 服務器

使用人工智能控制你的 Commodore 64 Ultimate 設備。這個 MCP 服務器允許 Claude 和其他 AI 助手通過本地網絡與你的 C64 Ultimate 硬件進行交互。

🚀 快速開始

本服務器實現了 模型上下文協議 (MCP)，將 C64 Ultimate REST API 作為工具暴露給 AI 助手使用。當連接到 Claude Desktop 或其他 MCP 客戶端時，你可以就你的 C64 進行自然對話，Claude 將使用這些工具來執行你的請求。

✨ 主要特性

• 創建和調試程序：Claude 可以編寫 C64 BASIC 或機器代碼程序，運行它們，捕獲屏幕以查看結果，檢查內存，並迭代修復問題。描述你的需求，然後看著 Claude 在真實硬件上開發程序。
• 編寫和運行 BASIC 程序：要求 Claude 編寫一個 BASIC 程序，它將對代碼進行標記化處理，直接將其注入 C64 內存並運行，無需手動輸入。
• 玩經典遊戲和演示：從設備存儲中加載並運行 .PRG 程序或 .CRT 卡帶鏡像，也可以直接上傳這些文件。
• 聆聽 SID 音樂：播放經典的 C64 SID 曲調或 Amiga MOD 音軌文件，只需指定設備上的文件或上傳一個文件即可。
• 查看屏幕內容：從任何圖形模式（文本、多色、高分辨率位圖等）捕獲屏幕截圖，Claude 可以查看屏幕上的情況並做出相應響應。
• 輸入和控制：通過鍵盤緩衝區發送按鍵、導航菜單並與正在運行的程序進行交互。
• 管理軟盤驅動器：掛載和卸載 D64/D71/D81 磁盤鏡像，在 1541/1571/1581 仿真模式之間切換，以及創建新的磁盤鏡像。
• 讀寫內存：通過 DMA 直接檢查和修改 C64 內存，這對於調試、修改值或檢查程序狀態非常有用。
• 配置設備：調整設備設置，將配置保存到閃存，並管理你的 C64 Ultimate 配置。

📦 安裝指南

前提條件

從 C64 Ultimate 菜單中啟用 Web 遠程控制服務：

• 導航至：網絡設置 → Web 遠程控制服務 → 啟用

安裝步驟

cd c64u-mcp-server
uv sync

配置

將 C64U_URL 環境變量設置為你的設備 IP 地址：

export C64U_URL="http://192.168.200.157"

默認值：http://192.168.200.157

運行服務器

uv run python server.py

Claude Desktop 配置

將以下內容添加到你的 Claude Desktop claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "commodore64": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/c64u-mcp-server", "python", "server.py"],
      "env": {
        "C64U_URL": "http://192.168.200.157"
      }
    }
  }
}

💻 使用示例

可用工具

機器控制

• machine_reset - 重置 C64
• machine_reboot - 重啟 Ultimate 設備
• machine_pause - 通過 DMA 暫停 CPU
• machine_resume - 從暫停狀態恢復
• machine_poweroff - 關機（僅適用於 U64）
• capture_screen - 將 C64 屏幕捕獲為 PNG 圖像
• type_text - 將文本輸入到鍵盤緩衝區（支持特殊鍵）
• send_key - 向鍵盤緩衝區發送特殊鍵
• enter_basic_program - 直接將 BASIC 程序輸入到內存（已標記化）

內存訪問

• write_memory - 將十六進制數據寫入 C64 內存
• write_memory_binary - 將二進制數據寫入內存（Base64 編碼）
• read_memory - 讀取 C64 內存
• read_debug_register - 讀取調試寄存器（U64）
• write_debug_register - 寫入調試寄存器（U64）

運行器（SID/MOD/PRG/CRT）

• sidplay_file - 從設備文件系統播放 SID 文件
• sidplay_upload - 上傳並播放 SID 文件（Base64 編碼）
• modplay_file - 從設備文件系統播放 MOD 文件
• modplay_upload - 上傳並播放 MOD 文件（Base64 編碼）
• load_prg_file - 加載 PRG 文件但不執行
• load_prg_upload - 上傳並加載 PRG 文件（Base64 編碼）
• run_prg_file - 從文件系統加載並運行 PRG 文件
• run_prg_upload - 上傳並運行 PRG 文件（Base64 編碼）
• run_crt_file - 從文件系統啟動卡帶
• run_crt_upload - 上傳並啟動卡帶（Base64 編碼）

軟盤驅動器

• list_drives - 列出所有驅動器和已掛載的鏡像
• mount_disk_file - 從文件系統掛載磁盤
• mount_disk_upload - 上傳並掛載磁盤（Base64 編碼）
• drive_reset - 重置驅動器
• drive_remove - 卸載磁盤
• drive_on - 啟用驅動器
• drive_off - 禁用驅動器
• drive_load_rom_file - 加載自定義 ROM
• drive_load_rom_upload - 上傳自定義 ROM（Base64 編碼）
• drive_set_mode - 更改驅動器類型（1541/1571/1581）

配置

• list_config_categories - 列出所有配置類別
• get_config_category - 獲取某個類別中的項目
• get_config_item - 獲取特定的配置項
• set_config_item - 設置配置項的值
• batch_set_config - 設置多個配置項
• load_config_from_flash - 從閃存恢復配置
• save_config_to_flash - 將配置保存到閃存
• reset_config_to_default - 重置為出廠默認設置

流（僅適用於 U64）

• stream_start - 啟動視頻/音頻/調試流
• stream_stop - 停止活動流

文件操作

• get_file_info - 獲取文件元數據
• get_version - 獲取 REST API 版本
• create_d64 - 創建 D64 磁盤鏡像
• create_d71 - 創建 D71 磁盤鏡像
• create_d81 - 創建 D81 磁盤鏡像
• create_dnp - 創建 DNP 磁盤鏡像

📚 詳細文檔

API 參考基於：https://1541u-documentation.readthedocs.io/en/latest/api/api_calls.html