Geargrafx MCP Server

Geargrafx

Geargrafxは、C++で書かれた非常に高精度なクロスプラットフォームのTurboGrafx-16／PC Engine／SuperGrafx／CD-ROM²／LD-ROM²エミュレーターです。Windows、macOS、Linux、BSD、RetroArchで動作し、AIによるデバッグと開発のためのMCPサーバーを組み込んでいます。

このオープンソースプロジェクトは、素晴らしい支援者の皆さまのサポートによって開発が継続されています。役に立ったと感じたら、ぜひスポンサーになってください。

Issueを作成してバグを報告したり、新機能をリクエストしたりすることを、どうぞお気軽にご検討ください。

## ダウンロード

プラットフォーム	アーキテクチャ	ダウンロードリンク
Windows	デスクトップ x64	Geargrafx-1.8.5-desktop-windows-x64.zip
	デスクトップ ARM64	Geargrafx-1.8.5-desktop-windows-arm64.zip
macOS	Homebrew	brew install --cask drhelius/geardome/geargrafx
	デスクトップ Apple Silicon	Geargrafx-1.8.5-desktop-macos-arm64.zip
	デスクトップ Intel	Geargrafx-1.8.5-desktop-macos-intel.zip
Linux	Ubuntu PPA	drhelius/ppa-geardome
	Fedora RPM	drhelius/rpm-geardome
	デスクトップ Ubuntu 26.04 x64	Geargrafx-1.8.5-desktop-ubuntu26.04-x64.zip
	デスクトップ Ubuntu 26.04 ARM64	Geargrafx-1.8.5-desktop-ubuntu26.04-arm64.zip
	デスクトップ Ubuntu 24.04 x64	Geargrafx-1.8.5-desktop-ubuntu24.04-x64.zip
	デスクトップ Ubuntu 24.04 ARM64	Geargrafx-1.8.5-desktop-ubuntu24.04-arm64.zip
MCPB	全プラットフォーム	MCP の README
RetroArch	全プラットフォーム	Libretro コアのドキュメント
開発ビルド	全プラットフォーム	GitHub Actions

注意事項：

• Windows： Visual C++ Redistributable と OpenGL Compatibility Pack が必要になる場合があります
• Homebrew：Homebrew からサードパーティの tap を信頼するよう求められた場合は、brew trust --tap drhelius/geardome を実行してください
• Linux：libsdl3 が必要になる場合があります

機能

• HuCard PCE／SGX の全カタログを正確にエミュレートします。
• CD-ROM²、Super CD-ROM²、Arcade CD-ROM² システムに対応しています。
• MMI イメージを使用した NEC LaserActive LD-ROM² に対応しています。
• プレビューと巻き戻しに対応したステートセーブ機能。
• 入力遅延を軽減するランアヘッド機能。
• バックアップ RAM と Memory Base 128 に対応しています。
• AAAAAA:VV コードのチートに対応し、RetroArch .cht のインポートも可能です。
• 同じマシン上で 2 つのエミュレーターインスタンスを使った TurboLink マルチプレイヤー。
• マルチタップ（最大 5 人プレイ）。
• 標準ゲームパッド（2 ボタン）、Avenue Pad 3（3 ボタン、ゲームに応じて自動設定）、Avenue Pad 6（6 ボタン）、マウスに対応しています。
• スキャンライン数を調整できます（224p、240p、または手動）。
• オプションの LPF フィルターを使用した RGB またはコンポジットのカラー出力。
• 圧縮 ROM と CD イメージに対応しています（pce、sgx、cue、zip、chd、mmi）。
• 物理 CD-ROM ディスクの再生に対応しています。
• 音楽 ROM に対応しています：HES。
• VGM レコーダー。
• Auto オプション選択時に、ROM を自動検出してハードウェアを選択する内部データベース。
• 対応プラットフォーム（スタンドアロン）：Windows、Linux、BSD、macOS。
• 対応プラットフォーム（libretro）：Windows、Linux、macOS、Raspberry Pi、Android、iOS、tvOS、webOS、PlayStation Vita、PlayStation 3、Nintendo 3DS、Nintendo GameCube、Nintendo Wii、Nintendo WiiU、Nintendo Switch、Emscripten、Classic Mini システム（NES、SNES、C64 など）、OpenDingux、RetroFW、QNX。
• ジャストインタイム・ディスアセンブラー、CPU ブレークポイント、メモリアクセス・ブレークポイント、コードナビゲーション（アドレスへのジャンプ、JP、JR、JSR のダブルクリック）、デバッグシンボル、自動ラベル、メモリエディター、PSG インスペクター、レジスター、タイル、スプライト、背景、CD-ROM サブシステム、SuperGrafx モードの両方の VDC を含むビデオビューアーを備えた、完全なデバッガー。
• Claude Code、Codex などを使った AI 支援デバッグ用の MCP サーバー。実行制御、メモリ検査、ハードウェア状態、巻き戻しなどのツールを提供します。
• Windows、Linux、macOS の ポータブルモード。
• プログラマブルシェーダーチェーン。
• ROM のパスを引数として追加することで、コマンドラインから ROM を読み込めます。
• ドラッグ＆ドロップで ROM を読み込めます。
• アプリケーションのバイナリと同じディレクトリにある gamecontrollerdb.txt ファイルを通じて、最新のゲームコントローラーに対応しています。

ヒント

基本的な使い方

• BIOS：Geargrafx で CD-ROM ゲームを実行するには BIOS が必要です。任意の BIOS を読み込めますが、md5 が 38179df8f4ac870017db21ebcbf53114 の System Card 3.0 を推奨します。
• CD-ROM イメージ：Geargrafx は chd、圧縮および非圧縮の cue/bin、cue/img、cue/iso イメージに対応しています。CUE のオーディオトラックには、未加工の BIN、対応する WAV（44100 Hz、16 ビット、ステレオ）、または Ogg Vorbis（44100 Hz、ステレオ）ファイルを使用できます。MP3 オーディオトラックには対応していません。
• LaserActive イメージ：Geargrafx は NEC LD-ROM² .mmi イメージに対応しています。日本版 PAC-N1／PCE-LP1 または米国版 PAC-N10 の BIOS が必要です。ディスクの面は Geargrafx → MMI Media または libretro のディスクコントロールから切り替えてください。LaserActive では、デスクトップ版の巻き戻しとランアヘッドは無効になります。
• マウスカーソル：メイン出力ウィンドウにカーソルを合わせるか、メインメニューを無効にすると、自動的に非表示になります。
• ポータブルモード：--portable を指定して実行するか、アプリケーションのバイナリと同じディレクトリに portable.ini という名前の空ファイルを作成してください。macOS では、.app バンドルの隣にファイルを配置してください。
• チート：Emulator → Cheats... を開いてコードを入力するか、RetroArch .cht ファイルをインポートしてください。コードは物理アドレスを使った AAAAAA:VV 形式です。たとえば、1F0DB1:09 はワーク RAM の $0DB1 に $09 を書き込みます。複数のコードは + で連結してください。

デバッグ機能

• ウィンドウのドッキング：デバッグモードでは、SHIFT キーを押しながらウィンドウを別のウィンドウにドラッグすると、ウィンドウ同士をドッキングできます。
• マルチビューポート：Windows または macOS では、デバッグメニューで「マルチビューポート」を有効にできます。変更を適用するには、エミュレーターを再起動する必要があります。有効にすると、デバッガーのウィンドウをメインウィンドウの外にドラッグできます。
• 単一インスタンス：Emulator メニューで「Single Instance」を有効にできます。有効にすると、別のインスタンスの実行中に ROM を開いた場合、新しいインスタンスを起動する代わりに、実行中のインスタンスへ ROM が送られます。
• デバッグシンボル：エミュレーターは ROM の読み込み時にシンボルファイル（.sym、.lbl、.noi）の読み込みを自動的に試みます。たとえば、path_to_rom_file.rom の場合、path_to_rom_file.sym の読み込みを試みます。シンボルファイルは GUI または CLI から読み込むこともできます。PCEAS（旧形式と新形式）、wla-dx、vasm のファイル形式に対応しています。

コマンドラインの使用方法

geargrafx [options] [game_file] [symbol_file]

Arguments:
  [game_file]                 Accepts ROMs (.pce, .sgx, .hes), CUE (.cue), CHD (.chd), MMI (.mmi) or ZIP (.zip)
  [symbol_file]               Optional symbol file for debugging

Options:
    -f, --fullscreen          Start in fullscreen mode
    -w, --windowed            Start in windowed mode with menu visible
      --load-state SLOT       Load save state slot 1-5, or a state file, once the media is loaded
      --mcp-stdio             Auto-start MCP server with stdio transport
      --mcp-http              Auto-start MCP server with HTTP transport
      --mcp-router            Enable compact MCP tool routing
      --mcp-http-address A    HTTP bind address (default: 127.0.0.1)
      --mcp-http-port N       HTTP port for MCP server (default: 7777)
      --turbolink-join N      Join local TurboLink shared session 1-255
      --headless              Run without GUI (requires MCP or TurboLink)
      --portable              Store configuration and user data beside the application
    -v, --version             Display version information
    -h, --help                Display this help message

MCP サーバー

Geargrafx には、Claude Code、Codex などの AI エージェントを通じて AI によるデバッグを可能にする Model Context Protocol（MCP）サーバーが含まれています。このサーバーは、実行制御、メモリの調査、ブレークポイント、逆アセンブル、ハードウェアの状態、巻き戻しなどのツールを提供します。STDIO と HTTP のトランスポートに対応しており、STDIO が推奨されています。

セットアップ手順とツールの詳細については、MCP_README.md を参照してください。

TurboLink マルチプレイヤー

両方のインスタンスで TurboLink メニューから同じセッション番号を選択して Connect を選ぶか、各プロセスを --turbolink-join N で起動します。セッションではローカル共有メモリを使用し、1 台のコンピューター上で正確に 2 つのピアに対応します。独立したインスタンスでは、設定、セーブデータ、単一インスタンスの処理が競合しないよう、別々のアプリケーションコピーまたは --portable データディレクトリを使用してください。

エージェントスキル

Geargrafx には、AI アシスタントが特定のタスクでエミュレーターを効果的に使えるようにする Agent Skills が用意されています。

• geargrafx-debugging — ゲームのデバッグ、コードのトレース、ブレークポイントの管理、ハードウェアの調査、リバースエンジニアリング。
• geargrafx-romhacking — チートの作成、メモリの検索、ROM データの変更、テキストの翻訳、ゲームのパッチ適用。

npx skills add drhelius/geargrafx でインストールしてください。詳細については、skills README を参照してください。

ビルド手順

Windows

• Microsoft Visual Studio Community 2026 以降をインストールします。
• SDL3 Releases から最新の SDL3 VC 開発ライブラリ（SDL3-devel-x.y.z-VC.zip という名前のファイル）をダウンロードします。
• アーカイブを展開し、展開後のフォルダー（例：SDL3-x.y.z）の名前を SDL3 に変更します。
• SDL3 フォルダーを platforms/windows/dependencies/ 内に配置し、インクルードパスが platforms/windows/dependencies/SDL3/include/SDL3/ になるようにします。
• Geargrafx の Visual Studio ソリューション platforms/windows/Geargrafx.sln を開いてビルドします。

macOS

• Xcode をインストールし、コマンドラインでコンパイラーを使用できるように、ターミナルで xcode-select --install を実行します。
• Mac の app バンドルを生成するには、次のコマンドを実行します。

brew install sdl3
cd platforms/macos
make dist

Linux

• Ubuntu / Debian / Raspberry Pi（Raspbian）：

Ubuntu 26.04 を使用している場合は、SDL3 を直接インストールできます。次のコマンドを使ってビルドします。

sudo apt install build-essential pkg-config libsdl3-dev libgl-dev
cd platforms/linux
make

Ubuntu 24.04 では、先に SDL3 をソースからビルドする必要があります。SDL3 と Geargrafx の両方をビルドするには、次のコマンドを使います。

sudo apt install build-essential cmake git curl jq pkg-config \
  libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxfixes-dev \
  libxi-dev libxss-dev libxkbcommon-dev libwayland-dev libdecor-0-dev \
  libdrm-dev libgbm-dev libgl1-mesa-dev libegl1-mesa-dev libdbus-1-dev libudev-dev libxtst-dev
SDL3_TAG=$(curl -s https://api.github.com/repos/libsdl-org/SDL/releases/latest | jq -r '.tag_name')
git clone --depth 1 --branch "$SDL3_TAG" https://github.com/libsdl-org/SDL.git /tmp/SDL3
cmake -S /tmp/SDL3 -B /tmp/SDL3/build -DCMAKE_INSTALL_PREFIX=/usr -DSDL_TESTS=OFF -DSDL_EXAMPLES=OFF
cmake --build /tmp/SDL3/build -j$(nproc)
sudo cmake --install /tmp/SDL3/build
cd platforms/linux
make

• Fedora：

sudo dnf install @development-tools gcc-c++ SDL3-devel
cd platforms/linux
make

• Arch Linux：

sudo pacman -S base-devel sdl3
cd platforms/linux
make

BSD

• FreeBSD：

su root -c "pkg install -y git gmake pkgconf sdl3"
cd platforms/bsd
USE_CLANG=1 gmake

• NetBSD：

su root -c "pkgin install gmake pkgconf SDL3"
cd platforms/bsd
gmake

• OpenBSD

doas pkg_add gmake sdl3
cd platforms/bsd
LDFLAGS=-L/usr/X11R6/lib/ USE_CLANG=1 gmake

Libretro

• Ubuntu / Debian / Raspberry Pi（Raspbian）：

sudo apt install build-essential
cd platforms/libretro
make

• Fedora：

sudo dnf install @development-tools gcc-c++
cd platforms/libretro
make

コントリビューター

Geargrafx に貢献してくださった皆さん、ありがとうございます！

ライセンス

Geargrafx は GNU General Public License v3.0 License の下でライセンスされています。詳しくは LICENSE をご覧ください。