dosbox-x-mcp

デスクトップに一切触れずにDOSBox-Xゲストを操作するMCPサーバーです。フォーカスを奪うことも、ホストへの合成キー入力も、ポインター移動もありません。モデルはDOSプログラムを最初から最後まで実行でき、その間もあなたは目の前で作業を続けられます。

これは、あるリバースエンジニアリングプロジェクトのキャプチャワークフローとして始まり、現在は汎用の支援ツールとなっています。実行中のDOSゲストがあれば、事前知識ゼロでそのゲストを見つけ、どのプログラムがどこからロードされているかを伝え、任意のセグメントを読み書き・パッチし、時間経過に沿って値をサンプリングし、ビデオメモリから画面を読み出し、エミュレータ自身のレコーダーを操作し、デバッガなしで、ディスク上のバイトを一切変更せずにコードの実行を監視できます。

できること

Related MCP server: re-winedbg

仕組み

ここで行われることには、ホストの入力キューや画面は一切関与しません。

• ゲストの発見。 すべてのDOSゲストには、BIOSキーボードリングの範囲ワード0x001E/0x003Eが0040:0080にあり、その範囲内にヘッドとテール、そしてライブのINT 21hベクタがあります。エミュレータのメモリ内でこの三つ組を見つければ、ゲストの物理アドレス0が見つかり、そこからすべてのセグメントにアクセス可能になります。プロファイルは不要で、これが新規プロジェクトが陥る鶏と卵の問題を解決します。

• キーは、実際のキーボード割り込みと同様に、ゲストのBIOSキーボードリングに追加されます。

• クリックは、ゲーム自身のINT 33hハンドラが書き込むワードに書き込まれます。ゲームが実際に読み取る状態です。ゲームのハンドラが上書きし続けるため、単一の書き込みでは競合に負けるので、しばらく連続して書き換えます。

• フレームはビデオメモリから取得します。DOSBoxはチェーン4ページをハードウェアと同じ方法で格納します。CPUオフセットoはリニア4 * (o & ~3) + (o & 3)に対応します。したがって、16グループごとに4バイトを取ると、領域が画面に戻ります。どのバイトが画面かを特定するには参照フレームが必要です。エミュレータのメモリには、画像に似たデータが多数あり、それが実際の画像ではないため、ページは参照とバイト単位で確認されるか、未確認と報告されます。画面の読み取りを参照してください。

• トレースは、近距離CALLをゼロパディングの連続領域に向けるようにパッチします。ケイブは置き換えられたターゲットを呼び出し、フラグを保存し、要求されたデータを自身のコードの後のスロットにコピーして戻ります。エミュレータは実行とともに終了し、パッチも消えます。

インストール

pip install "dosbox-x-mcp[all] @ git+https://github.com/md0-code/dosbox-x-mcp"

追加機能はすべてオプションで、その効果に応じて名前が付けられています。

MCPクライアントに登録します。Claude Codeの場合、プロジェクトルートに.mcp.jsonを置きます。

{
  "mcpServers": {
    "dosbox": {
      "command": "python",
      "args": ["-m", "dosbox_mcp.server"],
      "env": {
        "DOSBOX_MCP_PROFILE_DIR": "dosbox-x/profiles",
        "DOSBOX_MCP_EXECUTABLE": "dosbox-x/dosbox-x.exe"
      }
    }
  }
}

ツールが読み書きするすべてのパスは、次の規則に従います。絶対パスはそのまま、相対パスはDOSBOX_MCP_OUTPUT_DIRの下に置かれます。ツールは解決済みのパスを返すため、ファイルがどこに保存されたか迷うことはありません。

ツール

オフセットを受け付ける場所では、プロファイルのシンボル名も使用できます。0x634Aの代わりにtreasuryのように。

プロファイル未作成のゲームで始める

プロファイルは前提条件ではありません。これが最初のセッション全体です。

dosbox_launch(config="game.conf", profile="none")     → pid
dosbox_find_guest()
   → 640 KiB, INT 21h live, and:
       JP2D     load segment 2456    1.1 MB   C:\JP\JP2D.EXE
       JP       load segment 08A1     64 KB   C:\JP\JP.EXE
       COMMAND  load segment 0801     16 KB   C:\COMMAND.COM
dosbox_search_memory(text="sprites.dbt")   → 2456:027A
dosbox_dump_segment(path="jp2d.bin", segment="0x2456")

そのダンプがプロファイルのマーカーになります。実行間で変わらない50〜100バイトを選び、2〜3の簡単なチェックを追加すれば、DS相対のすべてのツールが名前で動作し始めます。

画面の読み取り

dosbox_read_framebufferは、読み取り時点でゲストが書き込んだパレットインデックスを返します。正確で、描画途中のフレームを捉えることはなく、ゲストに負荷をかけません。そのため、測定対象にはこの方法が推奨されます。

参照フレームが必要で、推測ではなく明示します。 ページの位置特定は、数百メガバイトの中から64,000バイトを見つけることを意味し、一貫性だけでは不十分です。実際のゲームで測定したところ、盲目的なスキャンでは、デコードされたスプライトバンク（画面ではない）を0.999のスコアで返しました。そこで、reference=に現在画面に表示されている内容を含む64,000バイトのファイルを渡すと、ページはバイト単位で確認されます。

dosbox_read_framebuffer(reference="credits_logo.bin", stem="shots/logo")
   → page_offset 16, confirmed true, pages [16, 64016, 128016, 192016]

参照の入手先:

• 開発中のポートには無料で付属 — 同じ画面の独自レンダリングです。これも比較する価値があります。2つがバイト単位で一致すれば、ポートのレンダラーは正しいことになります。

• 同じ画面の以前の確認済みキャプチャ があれば、再確認できます。

• ウィンドウの写真 — プロファイルにパレットが含まれている場合。これは自動で、引数は不要です。

一度確認されると位置はキャッシュされるため、以降の読み取りやdosbox_watch_framesの各フレームは無料です。allow_unconfirmed=trueは、自分で確認したい人のために盲目的スキャンの推測を返します。

ページは必ずしも予想した場所にあるとは限りません。CRTCの開始アドレスが示す場所、つまり4バイト境界（それより細かい粒度はありません）から始まります。実際に測定した1つはオフセット16にありました。

プロファイル

プロファイルは、ゲームを記述する1つのJSONファイルです。データセグメントの認識方法、マウス状態の保存場所、画面サイズとパレット、名前付きオフセット、ウォッチセット、既知のケイブなどです。 profiles/example.jsonは注釈付きテンプレートです。OpenJPリポジトリには、1993年にリリースされたゲームに対して書かれた実際のプロファイルがあります。

{
  "name": "example",
  "ds_segment": "0x1234",
  "marker": { "bytes": "6578616d706c652e64617400", "offset": "0x0100" },
  "checks": [ { "kind": "cstring_via_pointer", "pointer": "0x0200", "value": "game" } ],
  "mouse": { "buttons": "0x00B2", "position": "0x00B6" },
  "screen": { "width": 320, "height": 200 },
  "symbols": { "lives": { "offset": "0x1234", "size": 1, "description": "Lives left." } },
  "watch_sets": { "player": ["lives", "score", "level"] }
}

マーカーはbytesの16進数としてインライン化するか、参照ダンプからスライス（source_dump + offset + length）できます。利用可能なチェック: cstring_via_pointer、max、max_range、equals — 誤検出の可能性を極めて低くするのに十分です。なぜなら、代替手段はランダムな割り当てにパッチを当てることになるからです。

プラットフォーム

dosbox_capabilities は実行中のホストについてこれらすべてを報告するので、推測するのではなく問い合わせてください。

Linux では、kernel.yama.ptrace_scope が Windows の整合性レベルとまったく同じように、別プロセスのメモリへのアクセスを制限します:

一般的なデフォルトでは、アタッチではなく起動を使用します。サーバーは sysctl を読み取り、素の EPERM を出すのではなくその旨を報告します。

Linux には、コンポジットマネージャなしで遮蔽されたウィンドウを撮影する方法がなく、Wayland にはクロスクライアントキャプチャがまったくありません。答えは PrintWindow をエミュレートすることではなく、それが存在する目的である制約を取り除くことです: dosbox_launch(isolated=true) はエミュレータを専用の Xvfb ディスプレイ上に配置します。そこには保護すべきデスクトップがなく、エミュレータ自身のキーボードショートカットも誰からもキー入力を奪うことなく使用できます。

macOS では task_for_pid が必要であり、したがって root または署名付きで entitlement を持つバイナリが必要です。これに対応するバックエンドはありません。

注意事項

• エミュレータに到達可能でなければなりません: Windows では同じ整合性レベル、Linux では許容可能な ptrace_scope が必要です。

• プロファイルごとに同時に実行できるエミュレータは 1 つです。同じゲームを実行している 2 つのゲストはセグメントスキャンを曖昧にするため、サーバーは推測するのではなく拒否します。

• source="window" を指定した dosbox_capture_screen は、正確な整数スケールを得るためにエミュレータウィンドウのサイズを変更します。これがこのサーバーがデスクトップに与える唯一の目に見える影響であり、source="vram" を優先する理由でもあります。source="vram" はより高速で、描画途中のフレームを捉えることもありません。

• ウィンドウの撮影はゲストの実時間を消費します: 撮影ループはゲストから見えるフェーズを約 1.6 倍に引き伸ばします。定量的な用途にはフレームバッファを使用してください。

• 一部のゲームでは、1 回のクリックで「クリックして続行」のページを 2 ページ進めることができます。リストをページ送りするときはキーを送信してください。

• 実行中のゲームへの書き込みは元に戻せず、ゲームは設定直後にフィールドを再計算する可能性があります。再計算される前に読み取られるタイミングでパッチを適用してください。

• トレースメモリのキャプチャは、cave が実行された時点で DS が保持している値を通して読み取られます。データセグメントが 1 つのゲームではそれは完全に正しい動作です。DS を切り替えるルーチンの場合は、ds も一緒にキャプチャして確認してください。

• ビデオメモリから読み取られるのは chain-4 リニアモード 13h のみです。それ以外は source="window" が必要です。

• ブラインドフレームバッファスキャンは答えではなくヒントであり、未確認として報告されます。参照フレームを指定してください。

開発

pip install -e ".[dev,all]"
pytest

このスイートは完全にオフラインです: DOS ゲスト、メモリチェーン、chain-4 フレームバッファ、トレース可能なコードセグメントはすべて bytearray 内に構築されるため、エミュレータもゲームもなしに任意のプラットフォームで実行できます。カバーされていないのは、最下層の 2 つのシステムコール — 別プロセスの読み取りと書き込み — とウィンドウです。

ライセンス

MIT。