Gearsystem MCP Server

Gearsystem

Gearsystem は、C++ で書かれた高精度かつクロスプラットフォーム対応の Sega Master System／Game Gear／SG-1000 エミュレーターです。Windows、macOS、Linux、BSD、RetroArch で動作し、AI によるデバッグと開発のための MCP サーバーを内蔵しています。

このオープンソースプロジェクトの継続的な開発は、素晴らしい支援者の皆様のご支援によって実現しています。役に立ったと感じた場合は、スポンサーになることをご検討ください。

Issue を作成して、バグを報告したり、新機能をリクエストしたりすることをぜひご検討ください。

## ダウンロード

プラットフォーム	アーキテクチャ	ダウンロードリンク
Windows	デスクトップ x64	Gearsystem-3.9.23-desktop-windows-x64.zip
	デスクトップ ARM64	Gearsystem-3.9.23-desktop-windows-arm64.zip
macOS	Homebrew	brew install --cask drhelius/geardome/gearsystem
	デスクトップ Apple Silicon	Gearsystem-3.9.23-desktop-macos-arm64.zip
	デスクトップ Intel	Gearsystem-3.9.23-desktop-macos-intel.zip
Linux	Ubuntu PPA	drhelius/ppa-geardome
	Fedora RPM	drhelius/rpm-geardome
	デスクトップ Ubuntu 26.04 x64	Gearsystem-3.9.23-desktop-ubuntu26.04-x64.zip
	デスクトップ Ubuntu 26.04 ARM64	Gearsystem-3.9.23-desktop-ubuntu26.04-arm64.zip
	デスクトップ Ubuntu 24.04 x64	Gearsystem-3.9.23-desktop-ubuntu24.04-x64.zip
	デスクトップ Ubuntu 24.04 ARM64	Gearsystem-3.9.23-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 が必要になる場合があります

対応機種

• Sega Mark III
• Sega Master System
• Sega Game Gear
• Sega Game 1000（SG-1000）
• Othello Multivision

特徴

• 非常に高精度な Z80、VDP、PSG、FM エミュレーション。
• 対応カートリッジ：ROM、ROM + RAM、SEGA、Codemasters、韓国版、MSX + Nemesis、Janggun、SG-1000、および多数の韓国製マルチカート。
• 地域の自動検出：NTSC-JAP、NTSC-USA、PAL-EUR。
• YM2413（OPLL）FM サウンドチップに対応。
• 2 つのローカルデスクトッププロセス間での Gear-to-Gear ケーブルに対応（シリアル通信とパラレル通信を含む）。
• 2 つのローカルデスクトッププロセス間での Mark III Joy-Joy ケーブルに対応。
• Light Phaser と Paddle Control に対応。
• ROM 検出用の内部データベース。
• バッテリー駆動 RAM のセーブに対応。
• プレビューと巻き戻しに対応したステートセーブ。
• 入力遅延を軽減するランアヘッドに対応。
• 圧縮 ROM に対応（ZIP）。
• Game Genie と Pro Action Replay のチートに対応し、RetroArch .cht のインポートも可能。
• VGM レコーダー。
• 対応プラットフォーム（スタンドアロン）：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。
• JIT ディスアセンブラー、CPU ブレークポイント、メモリアクセスブレークポイント、コードナビゲーション（アドレスへの移動、JP、JR、CALL のダブルクリック）、デバッグシンボル、自動ラベル、メモリエディター、トレースロガー、IO インスペクター、タイル、スプライト、背景、パレットを表示する VRAM ビューアーを備えた完全なデバッガー。
• Claude Code、Codex などを使った AI 支援デバッグ用の MCP サーバー。実行制御、メモリ検査、ハードウェア状態、巻き戻しなどのツールを公開します。
• Windows、Linux、macOS の ポータブルモード。
• プログラマブルシェーダーチェーン。
• ROM のパスを引数として指定することで、コマンドラインから ROM を読み込みます。
• ドラッグ＆ドロップで ROM を読み込みます。
• アプリケーションのバイナリと同じディレクトリにある gamecontrollerdb.txt ファイルを通じて、最新のゲームコントローラーに対応します。

ヒント

基本的な使い方

• BIOS：Gearsystem は BIOS の有無にかかわらず実行できます。任意で BIOS を読み込み、有効にできます。Emulator メニューで Media Slot を None に設定すると、BIOS に含まれるタイトルを実行できます。これは、メディアが何も接続されていない本体をエミュレートします。
• オーバースキャン：元の画像を正確に再現するには、Video メニューで Overscan を Top+Bottom、Aspect Ratio を Standard (4:3 DAR) に設定してください。Game Gear ではオーバースキャン設定は無視されます。
• マウスカーソル：メイン出力ウィンドウ上にカーソルを置いたとき、またはメインメニューが無効になっているときに、自動的に非表示になります。
• ポータブルモード：--portable を指定して実行するか、アプリケーションのバイナリと同じディレクトリに portable.ini という名前の空のファイルを作成します。macOS では、.app バンドルの隣にファイルを置いてください。
• Gear-to-Gear および Mark III リンクケーブル： 2 つのデスクトップインスタンスで Link Cable を開き、同じセッションを選択して両方を接続するか、各プロセスを --link-session N を指定して起動します。Protocol で Auto、Gear-to-Gear、Mark III のいずれかを選択してください。セッションはこの選択から独立しています。Auto は、Game Gear のネイティブソフトウェアには Gear-to-Gear を、F-16 Fighting Falcon（日本版）には Mark III Joy-Joy を使用します。Mark III では、Return、1、2、Space が SK-1100 キーボードに割り当てられます。起動後に Mark III ハードウェアを接続した場合は、本体をリセットしてください。独立したインスタンスでは、設定、セーブデータ、単一起動制御が競合しないよう、アプリケーションを別々にコピーするか、--portable データディレクトリを使用してください。

デバッグ機能

• ウィンドウのドッキング：デバッグモードでは、SHIFT キーを押しながらウィンドウを別のウィンドウにドラッグすると、ウィンドウをドッキングできます。
• マルチビューポート：Windows または macOS では、デバッグメニューで「マルチビューポート」を有効にできます。変更を反映するには、エミュレーターを再起動する必要があります。有効にすると、デバッガーのウィンドウをメインウィンドウの外にドラッグできます。
• 単一インスタンス：Emulator メニューで「単一インスタンス」を有効にできます。有効にすると、別のインスタンスの実行中に ROM を開いた場合、新しいインスタンスを起動せず、実行中のインスタンスに ROM を送信します。
• デバッグシンボル：ROM の読み込み時に、エミュレーターはシンボルファイル（.sym、.noi）の読み込みを自動的に試みます。たとえば、path_to_rom_file.sms に対して path_to_rom_file.sym の読み込みを試みます。GUI または CLI を使ってシンボルファイルを読み込むこともできます。sjasmplus/Pasmo（EQU）、SDCC/NoICE（.noi）、wla-dx、vasm/汎用ファイル形式に対応しています。

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

gearsystem [options] [rom_file] [symbol_file]

Arguments:
  [rom_file]                  ROM file: accepts ROMs (.sms, .gg, .sg, .mv) 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)
      --headless              Run without GUI (requires MCP or Link Cable)
      --link-session N        Connect to link cable session 1-255
      --link-stall-us N       Override barrier stall threshold (0=default)
      --portable              Store configuration and user data beside the application
  -v, --version               Display version information
  -h, --help                  Display this help message

MCP サーバー

Gearsystem にはモデルコンテキストプロトコル（MCP）サーバーが含まれており、Claude Code、Codex などの AI エージェントを通じて、AI を活用したデバッグを行えます。このサーバーは、実行制御、メモリの調査、ブレークポイント、逆アセンブル、ハードウェアの状態などのツールを提供します。STDIO と HTTP のトランスポートに対応しており、STDIO が推奨されます。

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

エージェントスキル

Gearsystem は、特定のタスクでエミュレーターを効果的に使う方法を AI アシスタントに教えるエージェントスキルを提供しています。

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

npx skills add drhelius/gearsystem でインストールできます。詳細については、スキルの 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/ になるようにします。
• Gearsystem の Visual Studio ソリューション platforms/windows/Gearsystem.sln を開いてビルドします。

macOS

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

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 と Gearsystem の両方をビルドします。

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

精度テスト

Zexall Z80 命令テストプログラム（SMS Power! より）

SMS VDP テスト（SMS Power! より）

スクリーンショット

貢献者

Gearsystem にすでに貢献してくださった皆さんに感謝します！

ライセンス

Gearsystem は GNU General Public License v3.0 License のもとでライセンスされています。詳細についてはLICENSEをご覧ください。