AI エージェントでゲームを操作する（MCP）

マーチウィンド64 にはデバッグ用のインターフェースが組み込まれています。オプションで有効にすると、ゲームがこのパソコン内でポートを開き、リポジトリにある MCP サーバーがそれを通じてゲームをツール群として提供します。Model Context Protocol に対応した AI クライアント（Claude Code、Codex、Cursor など）から利用できます。

接続すると、エージェントは次のことができます。

いま何の画面か把握する（タイトル、会話、インターミッション、戦闘前確認、設定ウィンドウなど）
スクリーンショットを撮る、MP4 で録画する
プレイヤーと同じようにキーを押す、ネイティブ画面のボタンや入力欄を直接操作する
言語、画像モード、ルール、UI サイズを切り替える
ゲームのメモリを読み書きする（調査用）

私たち自身も開発中は、こうして AI にシナリオを進めさせたり、不具合を再現させたり、翻訳のレイアウトを確認させたりしています。自動操作のスクリプト作り、動画の録画、困ったときの原因調査などに使えます。

必要なもの

ゲーム本体：Windows 版、macOS 版、Linux 版、Steam Deck 版のいずれか。
Python 3：システム標準のもので十分です。追加パッケージは不要です。 Windows では python.org からインストールし、コマンドは python です。
MCP サーバーのスクリプト：ソースリポジトリにあります。クローンするだけで、ビルドは不要です。
```
git clone https://github.com/dyzz/srw64-recomp.git
```
使うのは tools/recomp/debug/mcp_server.py と、同じ場所の session.py です。
MCP 対応の AI クライアント

1. ゲーム内でデバッグインターフェースを有効にする

「オプション → 情報」で「AI デバッグインターフェース（MCP）」を「オン」にします。すぐに有効になり、再起動は不要です。設定は保存され、以降は起動のたびに画面上部へ有効になっていることを知らせる通知が出ます。使い終わったら同じ場所でオフにしてください。接続中のものもその場で切断されます。

オンの間は、その行の下に待ち受け中のアドレスと今回の実行フォルダが表示され、「実行フォルダをコピー」ボタンでフルパスをクリップボードにコピーできます。

ゲームはこのパソコン内（127.0.0.1）だけでポートを開き、実行フォルダに debug.json を書き出します。ポート番号とランダムなトークンが記録され、接続時にはまずトークンを提示する必要があります。このファイルを読めるのは自分のアカウントだけで、ゲームの終了時やオフにしたときに削除されます。

起動オプション --debug でも有効にできます（その回の実行だけ）

macOS：/Applications/Marchwind64.app/Contents/MacOS/srw64-gfx-host --play --rom ~/Games/srw64.z64 --debug（.z64・.v64・.n64 のどれでも可）
Windows：展開したフォルダで Marchwind64.cmd --debug を実行
Linux：./marchwind64.sh --debug
Steam Deck：Steam でゲームの「プロパティ → 起動オプション」に %command% --debug

この方法で有効にした場合、オプションのスイッチは「オン」と表示され、その実行中はオフにできません。

OS ごとの実行フォルダ：

OS	実行フォルダ
Windows	`%LOCALAPPDATA%\SRW64Recomp\sessions\<セッション>\run\`
macOS	`~/Library/Application Support/SRW64Recomp/sessions/<セッション>/run/`
Linux / Steam Deck	`~/.local/share/srw64-recomp/sessions/<セッション>/run/`

2. AI クライアントに MCP サーバーを登録する

MCP サーバーは標準入出力で通信する Python スクリプトです。

Claude Code：

claude mcp add srw64 -- python3 /パス/srw64-recomp/tools/recomp/debug/mcp_server.py

その他のクライアント：多くは次のような JSON で設定します（ファイルの場所や最上位のキー名は各クライアントの説明に従ってください）。

{
  "mcpServers": {
    "srw64": {
      "command": "python3",
      "args": ["/パス/srw64-recomp/tools/recomp/debug/mcp_server.py"]
    }
  }
}

Windows では python3 を python に変え、パスは C:\\パス\\srw64-recomp\\tools\\recomp\\debug\\mcp_server.py のように書きます（JSON ではバックスラッシュを 2 つ重ねます）。

登録できると、srw64_ で始まるツールがクライアントに表示されます。

3. 接続して使う

エージェントに「接続して」と頼むだけです。パスを教える必要はありません。

srw64_attach でゲームに接続して、スクリーンショットを撮って今どの画面か教えて。

srw64_attach を引数なしで呼ぶと、ユーザーフォルダからデバッグインターフェースが有効なゲームを探し、いちばん新しく起動して応答するものに接続します。複数のゲームを起動している場合や特定のものを選びたい場合は、「実行フォルダをコピー」で得たパスを run 引数に渡してください。

あとは普通の言葉で作業を頼めます。

「メインメニューが出るまで待って新しくゲームを始め、最初の選択肢まで早送りして。」
「言語を英語に切り替えて、同じ画面の中国語版とスクリーンショットを比べて、文字がはみ出していないか見て。」
「10 秒録画して。この戦闘アニメのどこで引っかかるか見たい。」
「会話が止まって進まない。状態と最近のイベントログを読んで、どのスクリプト命令で止まっているか調べて。」

エージェントはたいてい srw64_status とスクリーンショットで画面を判断し、srw64_wait で条件がそろうまで待ちます。当てずっぽうに待ち時間を入れる必要はありません。

ツール一覧

ツール	内容
`srw64_attach`	起動中のゲームに接続します。引数なしなら最新のものを自動で探し、`run` に実行フォルダを渡せば指定できます。
`srw64_launch`	ソースからビルドし、独立した開発セッションを起動します（開発環境一式が必要。後述）。
`srw64_status`	現在の状態：フレーム数、ウィンドウ、言語、画像モード、ルール、タイトルとオープニング、会話（ページ、文字サイズ、速度、早送り）、各ネイティブ画面、通知、押下中のキー。
`srw64_screenshot`	次のフレームをネイティブ画面の重ね描きも含めて撮影し、画像で返します。設定ウィンドウなど別のウィンドウも撮れます。
`srw64_record`	この先数秒を MP4 で録画し、ファイルのパスを返します。
`srw64_record_start` / `srw64_record_stop`	長さを決めずに録画を開始・終了します。
`srw64_wait`	条件がそろうまで待ちます：フレーム数、会話の表示、画面が開く、メインメニュー、会話中の特定の文字列、イベントログ上の特定のイベント。
`srw64_events`	イベントログを読みます（会話、オープニング、ルール、設定、各インターミッション画面、スクリプトなど）。
`srw64_keys`	ゲーム用キーボード。プレイヤーのキー設定にかかわらず常にクラシック配置：Z＝A、X＝B、Enter＝START、矢印キー、Q/E＝L/R、I/K＝C 上/下、WASD＝スティック。`e+z`（早送り）のような同時押しや長押しも指定できます。
`srw64_pad`	Steam Deck のボタン名で操作する仮想コントローラー。標準の割り当てどおりに働きます（View で設定を開くなど）。
`srw64_buttons`	キーボード層を通さず、N64 コントローラーのボタンを直接押します。
`srw64_ui_tree`	ネイティブ画面（名前入力、設定ウィンドウ、メニューバーなど）のコントロールを、位置と文字列付きで一覧します。
`srw64_click` / `srw64_type` / `srw64_ui_key`	文字列か座標でコントロールをクリック、入力欄に文字を入力（IME の変換中状態も可）、画面にキーを送ります。
`srw64_menu`	メニューバーの項目をパスで指定して押す、またはメニューを一覧します。
`srw64_window`	ウィンドウのサイズ変更、最前面化、終了。
`srw64_settings`	ルール、言語、画像モード、UI サイズ、画面比率、各画面のオリジナル/モダン表示を直接設定します。
`srw64_mini_stage_load`	コンパイル済みのミニステージを読み込んで入ります。ミニステージを参照。
`srw64_viewer_start`	バトルビューアーで指定した戦闘アニメを再生します。
`srw64_memory` / `srw64_memory_write`	ゲームのメモリを 16 進で読み書きします。書き込みは 1 回 4096 バイトまで。
`srw64_quit`	ゲームを正常終了し、今回の実行レポートを返します。

ツールが失敗した場合はエラーとして結果を返し、MCP サーバー自体は動き続けます。

注意点

普段のゲームとセーブデータそのものです。 エージェントが接続するのは普段遊んでいるゲームで、いつものセーブと設定を読み書きします。エージェントがセーブしたり設定を変えたりすれば、実際に反映されます。気兼ねなく試すなら、先にユーザーフォルダの saves/ をバックアップするか、--user-dir で別フォルダを指定し、必要なセーブをコピーしてください。
srw64_memory_write はゲームを壊すことがあります。 ゲームの処理を介さずメモリを書き換えます。内容を理解しているときだけ使ってください。
接続できるのはこのパソコンからだけです。 ゲームは 127.0.0.1 でしか待ち受けないので、同じネットワークの他の機器からは接続できません。このパソコン上の他のプログラムも、debug.json のトークンがなければ操作できません。このファイルは人に渡さないでください。リモートからは ssh の転送を使います（下記）。
srw64_quit でゲームは終了します。 接続だけ切って遊び続けたいときは、「オプション → 情報」でスイッチをオフにしてください。
使わないときはオフに。 スイッチは保存されたままになるので、起動時の通知で知らせています。

パソコンから Steam Deck に接続する

前提として、パソコンから ssh で Deck にログインできること（例：~/.ssh/config に Deck というホストを設定済み）、Deck 側のゲームで「オプション → 情報」のデバッグインターフェースをオンにしていること（または上記のとおり --debug 付きで起動していること）が必要です。パソコンのリポジトリで次を実行します。

python3 tools/release/linux/attach.py --host Deck

Deck 上で実行中のゲームを見つけ、ssh -L でポートをパソコンに転送し、「現在のセッション」に設定します。あとはエージェントが引数なしで srw64_attach を呼べば Deck に接続できます。スクリーンショット、録画、イベントログはゲームが Deck 上に書き出すファイルですが、同じ接続を通じて自動的に取り寄せます。

attach.py --start で ssh 経由で --debug 付きで起動できます。さらに --data-dir '~/srw64-debug' を付けると別のデータフォルダを使います（ROM と HD パックはリンク、セーブと設定はコピー）。自分のセーブデータには書き込みません。

Android

Android 版も「オプション → 情報」で有効にします。スマートフォンとパソコンの間は adb でつなぎます。開発者向けオプションで USB デバッグ（またはワイヤレスデバッグ）をオンにして adb で接続し、リポジトリで次を実行します。

python3 tools/release/android/attach.py --no-start

adb forward でゲームのインターフェースをパソコンに転送して「現在のセッション」に設定するので、あとは同じく srw64_attach を呼びます。スクリーンショット、録画、イベントログも同じ接続で取り寄せます。Android ではトークンを使わず、パソコンは adb の転送を通じて接続します。

開発者向け：ソースから起動する

手元にビルド環境一式がある場合（リポジトリのビルド手順を参照）、srw64_launch が必要に応じてビルドし、独立したデバッグセッションを起動します。実行フォルダはリポジトリの build/recomp/debug/ 以下で、普段のセーブデータには触れません。起動時に言語、画像モード、ルール、セーブ、ミニステージも指定できます。セッションは MCP サーバーの終了とともに終わります。

詳しくはリポジトリの docs/guide/debug-interface.md を参照してください。コマンドラインツール srw64ctl.py、Python からの操作方法、インターフェースが扱える範囲をまとめています。