mcp-openmsx-usage

MCP-OpenMSX 使用ガイド

スキルの使い方

• このファイルを最後まで読んでください。
• トピックや説明がタスクに関連する場合は、リンク先のファイルを読んでください。内容が必要になる可能性が少しでもある場合は、必ず参照ファイルを読み込んでください。パターンを見落としたり、間違いを犯したりするより、コンテキストを把握しておくほうが適切です。

概要

mcp-openmsx は、AI アシスタントと openMSX MSX エミュレーターをつなぐ MCP サーバーです。openMSX を起動し、STDIO または HTTP トランスポート経由で TCL コマンドを送信します。

一般的なワークフロー：エミュレーターを起動 → メディアを挿入 → 操作（キーボード／BASIC／デバッグ） → 画面をキャプチャ → 終了。

前提条件

• npx を含む Node.js >= 18：
  • Windows：nodejs.org または winget install OpenJS.NodeJS からインストールします
  • macOS：brew install node または公式インストーラーを使用します
  • Linux：ディストリビューションのパッケージマネージャーまたは nvm を使用します
• openMSX エミュレーターがインストールされ、アクセス可能であること（OS ごとのパスについては MCP の設定を参照してください）。 PATH にない場合は、環境変数 OPENMSX_EXECUTABLE を設定してください。
• MCP クライアントで mcp-openmsx を設定していること。
• 自動検出に失敗する場合、またはカスタムフォルダーが必要な場合は、環境変数 OPENMSX_SHARE_DIR を設定してください。

スキル索引

• MCP の設定：トランスポートの選択（stdio または HTTP）、エミュレーターの実行ファイルのパス、共有ディレクトリの設定など、MCP サーバーの設定方法。
• 環境変数
• MCP ツールのリファレンス：
  1. エミュレーターの制御：エミュレーターの状態（起動、電源、リセット）、メディア（テープ、ROM、ディスク）、マシン情報、キーボード入力、ステートセーブ、タイムトラベル再生を管理します。
  2. VDP（ビデオディスプレイプロセッサー）：レジスター、パレット、画面モード、テキスト内容など、VDP の状態を確認および変更します。
  3. 画面キャプチャ：エミュレーターのスクリーンショットと画面メモリダンプを取得します。
  4. デバッグ：実行を制御（ブレーク、一時停止解除、ステップ実行）し、CPU レジスター、RAM、VRAM を調べ、ブレークポイントを管理します。
  5. BASIC プログラミング：エミュレーター上で BASIC プログラムを作成、読み込み、実行、管理します。
  6. ドキュメントと検索：開発タスクを支援するために、埋め込みベクトルデータベースとリソースライブラリから MSX の技術ドキュメントを検索および取得する方法。
  7. ネイティブ Tcl の自動検出：オプションの openmsx_tcl_cmd ツールを使って、型付きツールではカバーされていない openMSX コンソール機能を検出して使用します。
• MCP リソース：MCP ベクトルデータベースに埋め込まれた MSX ドキュメントリソースと参考資料の豊富なコレクション。簡単に取得できるよう、カテゴリとトピック別に整理されています。
• MCP プロンプト：埋め込みドキュメントリソースに基づいて構造化された参考資料（MSX BASIC 命令マニュアルのページなど）を生成するカスタム MCP プロンプト。
• ヒントとベストプラクティス

ワークフローのリファレンスファイルとガイド

一般的なワークフローの詳細な手順ガイドです。内容が必要になる可能性が少しでもある場合は、必ずリファレンスファイルを読み込んでください。パターンを見落としたり、間違えたりするより、コンテキストを把握しておく方が適切です。必要に応じて関連ファイルを読んでください。

• MSX ドキュメント検索ワークフロー — 開発タスクを支援するため、埋め込みベクトルデータベースとリソースライブラリから MSX の技術ドキュメントを検索、取得します。
• MSX マシンの起動と設定 — マシン／拡張機能の検出、起動、ブート完了待ち、状態確認、速度制御、電源の再投入。
• MSX BASIC でのプログラミング — BASIC プログラムの作成、読み込み、実行、確認、管理を行います。行の管理、中断、大規模なプログラムの読み込みも含まれます。
• VDP のデバッグ — VDP レジスタ、パレット、VRAM、画面モードの調査／変更を行います。スプライトのデバッグや画面の破損分析のワークフローも含まれます。
• BASIC プログラムのデバッグ — 実行の中断、状態の調査、行の編集、インタープリターの低レベルデバッグ、タイムトラベル、無限ループの検出、変数の調査を行います。
• ASM プログラムのデバッグ — ブレークポイント、ステップ実行、レジスタ／メモリの調査、逆アセンブル、BIOS 呼び出しの検証、クラッシュ／ハングの分析、.sym ファイルなしでの関数の特定を行います。
• MSX-DOS プログラムのデバッグ — ディスクから読み込む MSX-DOS プログラムの正しいブレークポイント設定ワークフローです。アプリケーションの起動前に BIOS／DOS がブレークポイントに到達することで発生するブート時の汚染を回避します。ハングの検出とステートセーブによるチェックポイント作成も含まれます。
• メディア（ROM、ディスク、テープ）の操作 — ROM、ディスク、テープの挿入／取り出しを行います。各メディアタイプの開発ワークフローも含まれます。
• リプレイとステートセーブを使ったタイムトラベルデバッグ — タイムラインの移動、フレーム単位のステップ実行、チェックポイント作成、実行パスの比較を行います。
• 画面キャプチャと視覚的な検証 — スクリーンショット（インライン／ファイル）、画面ダンプ（MSX 形式）、テキストの読み取り、変更前後の比較を行います。
• ネイティブ Tcl の自動検出 — オプションの raw Tcl ツールを通じて、help、about、machine_info、openmsx_info を使った実行時検出を行います。

ヒントとベストプラクティス

• 特定の BASIC 命令については、read_mcp_resource（または列挙型名のリソースには msxdocs_resource_get）を使って msxdocs://basic_wiki/{INSTRUCTION} を直接読み取ってください。 さらに vector_db_query で補完してください。basic_wiki リソースでは、効果／構文／パラメーター／例／互換性のページ全体を 1 回の呼び出しで取得でき、ベクトルクエリでは複数分野にまたがるトピックを検索できます。たとえば、CALL 命令のページを取得するには、msxdocs://basic_wiki/call と vector_db_query("CALL") を使います。
• 情報の探索や複数分野にまたがる質問（例：「スプライトの衝突＋インターレースモード」、「PSG のエンベロープのタイミング」）には vector_db_query を使ってください。
• BASIC プログラムでは、行終端に必ず \r（CR）を使ってください。解析の問題を防ぐため、\n（LF）や \r\n（CRLF）は避けてください。
• アドレスと値はすべて 16 進数形式で指定してください（例：0x4000、0xA5）。
• マシンが完全に起動してから操作できるよう、launch の後は必ず数秒間 emu_control.wait を使ってください。
• エミュレーターの状態は、いつでも screen_shot.as_image を使って視覚的に確認できます。
• タイムラインを安定させるため、emu_replay.goBack または absoluteGoto の前に debug_run.break を使ってください。
• 一般知識に頼る前に、vector_db_query を使って MSX のドキュメントを検索してください。
• BASIC の開発には emu_keyboard.sendText ではなく basic_programming ツールを使ってください。速度の最適化と入力のエンコードを自動で処理します。
• 複雑なデバッグセッション中に進捗をチェックポイントとして保存するには、emu_savestates を使ってください。
• .sym／.map ファイルのアドレスは、debug_breakpoints.create と debug_run.runTo で直接使用できます。
• トリガーが場所ではなくマシンの状態である場合は、debug_conditions.create を使ってください。CPU の実行中に継続的に評価される Tcl 式（例：[reg SP] > 0xC000）を指定します。
• MSX-DOS プログラム：アプリが画面に表示されていることを確認する前に、ブレークポイントを設定しないでください。先に BIOS／DOS の起動処理でブレークポイントに到達します。MSX-DOS プログラムのデバッグを参照してください。
• MSX の国際文字マップに最も近いエンコードは CP437 です。テキストの入出力に使用してください。特殊文字に注意してください。