MCP Openmsx

🚀 MCP-openMSX

このプロジェクトは、標準化されたMCPプロトコルを通じて、MSXソフトウェアの開発、テスト、自動化のための包括的なツールを提供するMCPサーバーです。これにより、現代のAI支援開発とレトロコンピューティング（MSXシステム）をつなぐ架け橋となります。

🎁🎁 このプロジェクトが役に立った場合は、寄付をご検討ください: PAYPAL Link

🚀 クイックスタート

このMCPサーバーは、事前コンパイルされたNPMパッケージを使用して、基本的な方法で利用できます。

VSCodeでのクイックインストール

VSCodeにMCPサーバーをインストールする手順:

1. Github Copilot拡張機能をインストールします。
2. nodejsをインストールします（npxコマンドがPATHに含まれている必要があります）。
3. MCPサーバーをインストールします:
   • 上記のInstall MCP Serverボタンを使用して、VSCode設定にMCPサーバーをインストールします。
   • または、_ワークスペースフォルダ_に.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ポートの読み書きアクセス。
• 自動化：キーボード入力のシミュレーションとセーブステートの管理。
• ベクターDB統合：MSXリソースを含む埋，め込みベクターデータベースをクエリして、開発支援を行います。
• ハイブリッドモード：このMCPサーバーは、ハイブリッドアクセスモード（_STDIO_および_HTTP_トランスポート）をサポートしています。

🔧 技術詳細

アーキテクチャ

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

  subgraph yourComputerGroup[" "]
    HOST["Your AI dev companion<br>(MCP Client support)"]
    EMU["openMSX emulator<br>(local instance)"]

    subgraph mcpGroup["**mcp-openmsx**"]
      MCP["MCP Server<br>stdio / http"]
      TOOLS["MCP Tools"]
      VECTORDB[("Embeddings RAG<br>(Vector Database)")]
      RESOURCES["MCP Resources"]
      LOCALDATA["Local data<br>(inner documentation)"]
    end
    EXTDATA["External data<br>(webpages)"]

    HOST <--"_MCP<br>&nbsp;protocol&nbsp;_"--> MCP
    MCP <--> TOOLS & RESOURCES
    TOOLS <--"_&nbsp;Query&nbsp;_"--> VECTORDB
    TOOLS <--"_&nbsp;Console commands&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：Vector DBリソースをクエリして、MSXシステム、カートリッジ、およびその他の開発リソースに関する情報を取得します。
• msxdocs_resource_get：MCPリソースをサポートしていないMCPクライアント用にMCPリソースを取得します。

利用可能なMCPリソース

MCPリソースとは何ですか？

MCPリソースは、MCPサーバーの機能を拡張する構造化データセット、ドキュメント、およびヘルパーファイルです。これらは、マシン定義、拡張機能リスト、メディアテンプレート、およびプログラミング例などの重要な情報を提供し、MCP-openMSX環境内でのMSXソフトウェアのより強力な自動化、テスト、および開発ワークフローを可能にします。

利用可能なリソース

60以上のリソースが利用可能で、一部はMCPに直接含まれ、他のものはクエリ時にダウンロード可能です。これらは以下のカテゴリに分類されています。

• Processors (Z80, R800)
• Bios (Bios ROM, DOS ROM, SUBROM, ...)
• System
• Audio
• Video
• Programming (ASM, BASIC, ...)
• MSX-DOS
• MSX-UNAPI
• MSX BASIC

また、書籍やマニュアルもあります。

• MSX2 Technical Handbook
• The MSX Red Book
• SDCC Compiler

リソースの提供元

• Grauw MSX Assembly Page
• Z80 Heaven Wiki
• The MSX Red Book
• MSX2 Technical Handbook
• Konamiman MSX-UNAPI-specification
• BiFi MSX Net
• MRC Wiki
• MSX Banzai!
• SDCC

これらのリソースの作成者に感謝します。彼らは、さまざまなライセンスの下でこれらのリソースを公開しています。このMCPサーバーは、開発体験を向上させるために、これらのリソースの一部を含んでいます。

⚠️ 重要提示

これらのリソースの権利はそれぞれの作成者に帰属し、彼らが定義したライセンスの下で配布されています。

高度な手動使用方法

⚠️ 重要提示

これはMCPサーバーを使用するために必要なものではありませんが、手動でインストールしたい場合は、以下の手順に従ってください。

現在、MCPサーバーはコンパイルするためにLinuxが必要です。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
# or
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ページで問題を開くか、プロジェクトのディスカッションを確認してください。

コントリビューション

コントリビューションは大歓迎です！プルリクエストを送信してください。