MCP Openmsx

🚀 MCP-openMSX

本項目藉助標準化的MCP協議，為MSX軟件開發、測試和自動化提供了全面的工具，是現代AI輔助開發與復古計算（MSX系統）之間的橋樑。

🎁🎁 如果您覺得這個項目有用，請考慮捐贈：PAYPAL鏈接

🚀 快速開始

您可以使用 預編譯的NPM包 以基本方式使用此MCP服務器。

使用VSCode快速安裝

在VSCode中安裝MCP服務器的步驟：

1. 安裝 Github Copilot擴展
2. 安裝nodejs（您的PATH中必須有npx命令）。
3. 安裝MCP服務器：
   • 使用上面的 Install MCP Server 按鈕將MCP服務器安裝到您的VSCode設置中。
   • 或者在您的 工作區文件夾 中添加一個名為 .vscode/mcp.json 的文件，並使用以下JSON配置。

STDIO模式（推薦）

{
  "servers": {
    "mcp-openmsx": {
      "command": "npx",
      "args": ["@nataliapc/mcp-openmsx"],
      "env": {
        "OPENMSX_SHARE_DIR": "C:\\the\\location\\of\\your\\openmsx\\share\\folder"
      }
    }
  }
}

⚠️ 重要提示

環境變量是可選的。您可以根據需要進行自定義。

流式HTTP模式（更高級）

{
  "servers": {
    "mcp-openmsx": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { }
    }
  }
}

⚠️ 重要提示

MCP HTTP服務器必須在同一臺計算機或另一臺計算機上獨立運行（make run_http）。

使用Claude Desktop進行基本安裝

按照 這些說明 訪問Claude的 claude_desktop_config.json 文件。

編輯該文件以包含以下JSON條目：

{
  "mcpServers": {
    "mcp-openmsx": {
      "command": "npx",
      "args": ["@nataliapc/mcp-openmsx"],
      "env": {
        "OPENMSX_SHARE_DIR": "C:\\the\\location\\of\\your\\openmsx\\share\\folder"
      }
    }
  }
}

⚠️ 重要提示

環境變量是可選的。您可以根據需要進行自定義。

環境變量

✨ 主要特性

本項目在現代AI輔助開發（如GitHub Copilot、Claude Desktop）和復古計算（MSX系統）之間搭建了一座橋樑，提供了以下功能：

• 模擬器控制：啟動、配置、管理openMSX實例，並回放時間線。
• 媒體管理：處理ROM卡帶、軟盤和磁帶。
• BASIC編程支持：提供有助於BASIC語言編程和開發的工具。
• 調試工具：通過斷點、內存檢查和單步執行進行全面的CPU調試。
• 視頻控制：VDP寄存器操作和屏幕捕獲。
• 內存操作：讀寫RAM、VRAM和I/O端口訪問。
• 自動化：模擬鍵盤輸入和管理保存狀態。
• 向量數據庫集成：查詢嵌入式向量數據庫中的MSX資源，以支持開發。
• 混合模式：此MCP服務器支持混合訪問模式（STDIO 和 HTTP 傳輸）。

🏗️ 架構

flowchart TB
  %%{init: {'flowchart': {'curve':'monotoneX' }}}%%

  subgraph yourComputerGroup[" "]
    HOST["您的AI開發夥伴<br>(支持MCP客戶端)"]
    EMU["openMSX模擬器<br>(本地實例)"]

    subgraph mcpGroup["**mcp-openmsx**"]
      MCP["MCP服務器<br>stdio / http"]
      TOOLS["MCP工具"]
      VECTORDB[("嵌入式RAG<br>(向量數據庫)")]
      RESOURCES["MCP資源"]
      LOCALDATA["本地數據<br>(內部文檔)"]
    end
    EXTDATA["外部數據<br>(網頁)"]

    HOST <--"_MCP<br>&nbsp;協議&nbsp;_"--> MCP
    MCP <--> TOOLS & RESOURCES
    TOOLS <--"_&nbsp;查詢&nbsp;_"--> VECTORDB
    TOOLS <--"_&nbsp;控制檯命令&nbsp;_"---> EMU
    RESOURCES <--_&nbsp;http&nbsp;_---> EXTDATA
    RESOURCES <--> LOCALDATA
  end

  HOST@{ shape: rounded }
  MCP@{ shape: rounded }
  EMU@{ shape: rounded }
  LOCALDATA@{ shape: docs }
  EXTDATA@{ shape: docs }
  style yourComputerGroup color:#fff,fill:#4444,text-align:left
  style mcpGroup color:#fff,fill:#4444
  style HOST color:#000000,fill:#BBDEFB,stroke-width:4px,stroke-dasharray:0
  style MCP color:#000000,fill:#FFF9C4
  style EMU color:#FFFFFF,fill:#0000FF,stroke-width:4px,stroke-dasharray:0

MCP服務器將來自Copilot AI的高級自然語言命令轉換為 TCL 命令，以控制 openMSX，從而實現MSX軟件的自動化測試和調試。

🛠️ 可用的MCP工具

模擬器控制工具

• emu_control：控制openMSX模擬器：launch、close、powerOn、powerOff、reset、getEmulatorSpeed、setEmulatorSpeed、machineList、extensionList、wait。
• emu_replay：控制模擬時間線：start、stop、status、goBack、absoluteGoto、advanceFrame、reverseFrame、truncate、saveReplay、loadReplay。
• emu_info：獲取當前模擬機器的信息：getStatus、getSlotsMap、getIOPortsMap。
• emu_media：管理ROM、磁盤和磁帶媒體：tapeInsert、tapeRewind、tapeEject、romInsert、romEject、diskInsert、diskInsertFolder、diskEject。
• emu_vdp：管理VDP（視頻顯示處理器）：getPalette、getRegisters、getRegisterValue、setRegisterValue、screenGetMode、screenGetFullText。

編程工具

• basic_programming：BASIC工具：isBasicAvailable、newProgram、runProgram、setProgram、getFullProgram、getFullProgramAdvanced、listProgramLines、deleteProgramLines。

調試工具

• debug_run：控制執行：break、isBreaked、continue、stepIn、stepOut、stepOver、stepBack、runTo。
• debug_cpu：讀寫CPU寄存器、CPU信息、堆棧和反彙編代碼：getCpuRegisters、getRegister、setRegister、getStackPile、disassemble、getActiveCpu。
• debug_memory：RAM內存操作：selectedSlots、getBlock、readByte、readWord、writeByte、writeWord、advanced_basic_listing。
• debug_vram：VRAM操作：getBlock、readByte、writeByte。
• debug_breakpoints：斷點管理：create、remove、list。

自動化工具

• emu_keyboard：向模擬器發送文本輸入：sendText。
• emu_savestates：保存和恢復機器狀態：load、save、list。
• screen_shot：捕獲模擬器屏幕：as_image、to_file。
• screen_dump：將屏幕數據導出為BASIC BSAVE指令。
• msxdocs_resource_get：為不支持MCP資源的MCP客戶端檢索MCP資源。

文檔工具

• vector_db_query：查詢向量數據庫資源，以獲取有關MSX系統、卡帶和其他開發資源的信息。
• msxdocs_resource_get：為不支持MCP資源的MCP客戶端檢索MCP資源。

📦 可用的MCP資源

什麼是MCP資源？

MCP資源是結構化數據集、文檔和輔助文件，可擴展MCP服務器的功能。它們提供了諸如機器定義、擴展列表、媒體模板和編程示例等重要信息，從而在MCP-openMSX環境中為MSX軟件實現更強大的自動化、測試和開發工作流程。

可用資源

有60多種可用資源，其中一些直接包含在MCP中，另一些在查詢時可通過下載訪問。它們分為以下幾類：

• 處理器（Z80、R800）
• BIOS（BIOS ROM、DOS ROM、SUBROM等）
• 系統
• 音頻
• 視頻
• 編程（ASM、BASIC等）
• MSX-DOS
• MSX-UNAPI
• MSX BASIC

還有書籍和手冊：

• MSX2技術手冊
• MSX紅寶書
• SDCC編譯器

資源來源：

• Grauw MSX彙編頁面
• Z80 Heaven維基
• MSX紅寶書
• MSX2技術手冊
• Konamiman MSX-UNAPI規範
• BiFi MSX網絡
• MRC維基
• MSX Banzai!
• SDCC

感謝這些資源的作者，他們在各種許可證下提供了這些資源。此MCP服務器包含了其中一些資源，以增強開發體驗。

⚠️ 重要提示

這些資源的版權歸各自的作者所有，並根據他們定義的許可證進行分發。

💻 高級手動使用

⚠️ 重要提示

使用MCP服務器不需要此步驟，但如果您想手動安裝，請按照以下步驟操作。

目前，MCP服務器需要在Linux上編譯。雖然它可能也適用於macOS，但尚未在Windows或macOS上進行測試。

手動安裝

npm install -g @nataliapc/mcp-openmsx

手動設置環境變量

設置可選的環境變量以自定義服務器：

export OPENMSX_EXECUTABLE="openmsx"
export OPENMSX_SHARE_DIR="/usr/share/openmsx"
export OPENMSX_SCREENSHOT_DIR="/my_project/screenshots"
export OPENMSX_SCREENDUMP_DIR="/my_project/screendumps"
export OPENMSX_REPLAYS_DIR="/my_project/replays"
export MCP_HTTP_PORT=3000

作為MCP服務器（stdio）

mcp-openmsx

作為HTTP服務器

MCP_TRANSPORT=http mcp-openmsx
# 或者
mcp-openmsx http

🛠️ 開發

⚠️ 重要提示

使用MCP服務器不需要此步驟，但如果您想貢獻代碼或修改代碼，請按照以下步驟操作。

構建前提條件

• Node.js >= 18.0.0
• TypeScript
• 安裝openMSX模擬器

構建

git clone https://github.com/nataliapc/mcp-openmsx.git
cd mcp-openmsx/mcp-server
npm install
npm run build

在開發環境中運行

npm run dev

📄 許可證

GPL2許可證 - 詳情請參閱 LICENSE 文件。

🛠️ 支持

如果您需要幫助，或有問題或建議，請在 GitHub Issues 頁面上打開一個問題，或查看項目討論。

🤝 貢獻

歡迎貢獻代碼！請隨時提交拉取請求。