MCP-openMSX

MCP-openMSX

"AI が指揮し、MCP が解釈し、openMSX が 8 ビットの歌姫を演じる、バイナリーオペラを指揮します。"

Model Context Protocol（MCP）に対応し、openMSX エミュレーターのインスタンスを自動化する MCP サーバーです。

このサーバーは、標準化された MCP プロトコルを通じて、MSX ソフトウェアの開発、テスト、自動化に役立つ包括的なツールを提供します。

🎁🎁 このプロジェクトが役に立った場合は、PAYPAL のリンクまたはGitHub Sponsorsからの寄付をご検討ください

---

目次

• プロジェクト概要
• アーキテクチャ
• 利用可能な MCP ツール
• 利用可能な MCP リソース
• ⚡ クイックスタート
  • VSCode で簡単にインストール
  • Claude Desktop に基本インストール
  • 環境変数
• 高度な手動使用方法
• 開発
• ライセンス
• サポート
• コントリビューション
• 🌟 スターをもっと！ 🌟

プロジェクト概要

このプロジェクトは、以下を提供することで、AI 支援による現代の開発（例：GitHub Copilot、Claude Desktop）とレトロコンピューティング（MSX システム）の橋渡しをします。

• エミュレーター制御：openMSX インスタンスの起動、設定、管理、タイムラインの再生を行います。
• メディア管理：ROM カートリッジ、フロッピーディスク、カセットテープを扱います。
• BASIC プログラミングのサポート：BASIC 言語でのプログラミングと開発を支援するツールです。
• デバッグツール：ブレークポイント、メモリ検査、ステップ実行に対応した CPU の完全なデバッグ機能です。
• ビデオ制御：VDP レジスターの操作と画面キャプチャを行います。
• メモリ操作：RAM、VRAM の読み書きと I/O ポートへのアクセスを行います。
• 自動化：キーボード入力のシミュレーションとセーブステート管理を行います。
• ハイブリッドドキュメント検索：MSX リソースのローカルインデックスを組み込んで検索します。多言語エンベディングによるセマンティック検索と BM25 によるキーワード検索を組み合わせ、完全にオフラインで動作します。
• ハイブリッドモード：この 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, writeBlock, searchBytes。
• debug_vram：VRAM 操作：getBlock, readByte, writeByte, searchBytes。
• debug_breakpoints：ブレークポイント管理：create, remove, list。
• debug_log：デバッグログ：log, read。
• debug_conditions：条件管理（ブレークポイントのように動作しますが、アドレスには紐づかず、CPU の実行中に継続的に評価される Tcl 式です）：create, remove, list。

自動化ツール

• emu_keyboard：テキストまたはキーの組み合わせをエミュレーターに送信します：sendText, sendKeyCombo。
• 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 システム、カートリッジ、プログラミング、その他の開発リソースに関する情報を対象に、ローカルの MSX ドキュメントインデックスをハイブリッド検索（セマンティック埋め込み＋BM25）します。
• msxdocs_resource_get：MCP リソースに対応していない MCP クライアント向けに、MCP リソースを取得します。

オプションの高度なツール

• openmsx_tcl_cmd：接続された openMSX インスタンス内でネイティブ Tcl コマンドを実行します。既定では無効で、ユーザーが OPENMSX_ENABLE_RAW_TCL=true を設定した場合にのみ登録されます。既存の型付きツールも引き続き利用でき、対象とする操作にはそれらを優先して使用してください。

利用可能な 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 サーバーには、開発体験を向上させるため、これらのリソースの一部が含まれています。

重要

これらのリソースの権利は各作者に帰属し、作者が定めたライセンスに基づいて配布されています。

クイックスタート

プリコンパイル済みの NPM パッケージを使って、この MCP サーバーを簡単に利用できます。

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

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

1. Github Copilot 拡張機能をインストールします。
2. nodejs をインストールします（npx コマンドを PATH から実行できる必要があります）。
3. MCP サーバーをインストールします：
   • 上の MCP サーバーをインストール ボタンを使って、VSCode の設定に MCP サーバーをインストールします。
   • または、以下の JSON 設定を含む .vscode/mcp.json という名前のファイルを ワークスペースフォルダー に追加します。

STDIO モード（推奨）

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

メモ

Windows で権限の問題が発生する場合は、command フィールドを npx.cmd に変更できます。

メモ

環境変数は任意です。必要に応じてカスタマイズしてください。

ストリーミング 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"
      }
    }
  }
}

メモ

環境変数は任意です。必要に応じてカスタマイズしてください。

環境変数

変数	説明	デフォルト値	例
OPENMSX_EXECUTABLE	openMSX 実行ファイルのパスまたはコマンド	自動検出：openmsx（Linux）、/Applications/openMSX.app/Contents/MacOS/openmsx（macOS）、openmsx.exe（Windows）	/usr/local/bin/openmsx または C:\Program Files\openMSX\openmsx.exe
OPENMSX_SHARE_DIR	openMSX のデータファイル（マシン、拡張機能など）が含まれるディレクトリ	システムに依存	/home/myuser/.openmsx/share
OPENMSX_SCREENSHOT_DIR	スクリーンショットの保存先ディレクトリ	openmsx のデフォルト	/myproject/screenshots
OPENMSX_SCREENDUMP_DIR	画面ダンプの保存先ディレクトリ	openmsx のデフォルト	/myproject/screendumps
OPENMSX_REPLAYS_DIR	リプレイファイルの保存先ディレクトリ	openmsx のデフォルト	/myproject/replays
OPENMSX_ENABLE_RAW_TCL	オプションの openmsx_tcl_cmd ネイティブ Tcl ツールを登録します。MCP クライアントに openMSX やホストのファイルシステムへの強力なアクセス権を与える可能性があるため、明示的に必要な場合にのみ有効にしてください。	false	true
OPENMSX_LAUNCH_HEADLESS	レンダラーウィンドウを表示せずに openMSX を起動します（ヘッドレスモード）。起動時に renderer をデフォルトの SDLGL-PP ではなく none に設定します。CI、テスト、サーバー側の環境で便利です。	false	true
MCP_TRANSPORT	トランスポートモード（stdio または http）	stdio	http
MCP_HTTP_PORT	HTTP トランスポートモードのポート番号	3000	8080
MCP_ALLOWED_ORIGINS	HTTP トランスポートで許可するオリジンのカンマ区切りリスト	すべて許可する場合は空	http://localhost,http://mydomain.com
OPENMSX_WINDOWS_CONTROL	Windows のみ。 サーバーが openMSX の制御ソケットと通信する方法（下記参照）	stdio-proxy	direct-sspi
OPENMSX_WINDOWS_PROXY_EXECUTABLE	Windows のみ。 SSPI プロキシヘルパーのパスを上書きします（開発用）	同梱の bin/win-x64/mcp-openmsx-sspi-proxy.exe	C:\path\to\mcp-openmsx-sspi-proxy.exe
OPENMSX_MODELS_CACHE	埋め込みモデルのキャッシュ先ディレクトリ（HF_HOME / TRANSFORMERS_CACHE も使用されます）	~/.cache/mcp-openmsx	/opt/models
OPENMSX_EMBED_PROVIDER	インデックス生成ツールのみ。 cuda は GPU（fp32 モデル）を使ってインデックスを再生成します。CUDA を利用できない場合は CPU にフォールバックします。MCP サーバー自体は常に CPU/int8 を使用し、この変数を無視します。	（生成ツール：cpu）	cuda

ネイティブ Tcl コマンドツール（OPENMSX_ENABLE_RAW_TCL）

オプションの openmsx_tcl_cmd ツールを使用すると、型付きツールでは対応していない高度な機能やバージョン固有の機能のために、openMSX のネイティブ Tcl コンソールへ直接アクセスできます。使い慣れていないコマンドを実行する前に、ランタイムの自己文書化コマンド help、about、openmsx_info、machine_info を使用できます。

このツールはデフォルトでは登録されません。MCP サーバーの設定で有効にできるのはユーザーのみです。

{
  "env": {
    "OPENMSX_ENABLE_RAW_TCL": "true"
  }
}

直接の Tcl アクセスには意図的に制限がなく、エミュレーターの状態の変更、ファイルへのアクセス、スクリプトの読み込み、openMSX の終了が可能です。MCP クライアントにローカルでのコマンド実行権限を与えるのと同等のものとして扱ってください。設定を変更した後は、MCP サーバーを再起動してください。

ドキュメント検索モデル

vector_db_query ツールは、ローカルのハイブリッド検索（セマンティック埋め込み＋BM25）を実行します。埋め込みモデル （multilingual-e5-small、ONNX 量子化、約 118 MB、512 トークンのコンテキスト、多言語対応）は、初回のクエリ時に HuggingFace Hub から一度だけダウンロードされ、ディスクにキャッシュされます（上記の OPENMSX_MODELS_CACHE を参照）。その後は完全にオフラインで動作します。API キーは不要です。ネットワークから隔離された環境でキャッシュを事前に作成するには、ネットワークに接続されたマシンでクエリを 1 回実行し、キャッシュディレクトリをコピーしてください。

インデックスの再生成（まれに必要）は、コーパス全体を埋め込みます。CPU では時間がかかります。NVIDIA GPU でジェネレーターを実行するには、OPENMSX_EMBED_PROVIDER=cuda を設定してください（CUDA 13 ランタイムライブラリ＋cuDNN 9 が必要です）。約 50 倍高速になります。GPU パスでは、より大きな fp32 モデルを使用します。サーバーでは引き続き int8 モデルが使用され、検索では両者を互換的に使用できます（ランキングは同じです）。エンドユーザーが fp32 モデルをダウンロードすることはありません。

Windows の制御モード（OPENMSX_WINDOWS_CONTROL）

Windows では、openMSX は GUI アプリであり、その TCP 制御ソケットには SSPI（Negotiate/NTLM）認証が必要です。サーバーでは、いくつかのトランスポートをサポートしています。

値	説明
stdio-proxy	デフォルト。 SSPI を実行し、シンプルな XML stdio チャネルを提供する、自己完結型の .NET ヘルパーを起動します。最も堅牢な方法です。
direct-sspi	オプションの node-expose-sspi パッケージを使って Node から認証します。フォールバック／デバッグ用です。
socket	direct-sspi のレガシーな別名です。

Linux および macOS には影響しません（openmsx -control stdio）。

同梱のプロキシは helpers/openmsx-sspi-proxy からビルドされており、Docker を使って Linux から再現可能な形で再ビルドできます（ローカルの .NET は不要です）。

cd mcp-server
pnpm build:proxy:win-x64:docker   # → bin/win-x64/mcp-openmsx-sspi-proxy.exe

高度な手動利用

重要

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

MCP サーバーは Linux、macOS、Windows で動作します。ソースからビルドするには、Node.js >= 18 と TypeScript が必要です。

手動インストール

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 OPENMSX_ENABLE_RAW_TCL="true"
export OPENMSX_LAUNCH_HEADLESS="true"
export MCP_HTTP_PORT=3000
export MCP_ALLOWED_ORIGINS="http://localhost,http://mydomain.com"

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 ページで issue を作成するか、プロジェクトのディスカッションをご確認ください。

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

スターをお願いします！

このプロジェクトを気に入っていただけたら、GitHub でスターをお願いします。

スター履歴

---