Gearcoleco MCP Server

Gearcoleco

Gearcolecoは、C++で書かれた非常に高精度なクロスプラットフォーム対応のColecoVisionおよびColeco ADAMエミュレーターです。Windows、macOS、Linux、BSD、RetroArchで動作し、AIによるデバッグと開発のためのMCPサーバーを組み込んでいます。

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

バグの報告や新機能のリクエストは、遠慮なくissueを作成してください。

## ダウンロード

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

機能

• 高精度な Z80 コア、TMS9918A VDP、SN76489 PSG、AY-3-8910 SGM のエミュレーション。
• ColecoVision Super Game Module（SGM）と MegaCart ROM に対応。
• Coleco ADAM のコンピューターおよびカートリッジの起動モード、フルキーボード、ADAMnet、プリンター、Digital Data Pack、フロッピーディスクに対応。
• F18A v1.9 のエミュレーション（オプション）。
• Super Action Controller（SAC）、Wheel Controller、Roller Controller に対応。
• プレビューと巻き戻しに対応したステートセーブ。
• 入力遅延を軽減するランアヘッドに対応。
• 圧縮 ROM（ZIP）に対応。
• 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 のポータブルモード。
• プログラマブルシェーダーチェーン。
• カートリッジ、ADAM メディア、プレイリストのパスを引数として指定することで、コマンドラインからコンテンツを読み込みます。
• ドラッグ＆ドロップでコンテンツを読み込みます。
• アプリケーションのバイナリと同じディレクトリにある gamecontrollerdb.txt ファイルを通じて、最新のゲームコントローラーに対応します。

ヒント

基本的な使い方

• BIOS と ADAM ファームウェア：ファームウェアは付属していません。Emulator > BIOS で ColecoVision BIOS（OS-7）を選択してください。元の BIOS が推奨されます（CRC32 3aa93ef3、ファイル名は colecovision.rom、coleco.rom、または os7.u2）。ADAM ではさらに、ADAM > EOS ROM（eos.rom、8192 バイト、一般的な CRC32 05a37a34）と ADAM > SmartWriter ROM（writer.rom、wp.rom、または wp_r80.rom、32768 バイト、一般的な CRC32 58d86a2a）が必要です。
• ADAM の起動とメディア：ADAM メニューのディスクまたはデータパックのサブメニューからイメージを挿入し、Power On を選択してください。対応形式は、256 KiB の .ddp、160/320 KiB の .dsk、有効な ADAM イメージを 1 つ含む ZIP アーカイブ、および同じ種類のイメージを含む .m3u プレイリストです。各ドライブには、それぞれの最近使用したイメージ、プレイリスト、書き込み保護の設定があります。挿入／取り出しは対象のドライブにのみ作用します。ドロップしたイメージは、空いている対応ドライブに挿入されるか、挿入先を確認するメッセージが表示されます。ColecoVision カートリッジを起動するには、Gearcoleco > Open ROM... を選択してください。
• ADAM の電源とセーブ：Power Off を選択すると、変更したメディアが保存され、挿入されたままになります。ファームウェアの変更は次回の Power On 時に適用されます。Computer Reset では、現在のファームウェアとマウント済みメディアが維持されます。変更内容は Save Files の下に完全なイメージとして保存され、元のファイルは変更されません。ドライブメニューには Save Changes と Save As もあります。保存に失敗した場合も、変更したイメージはマウントされたままです。
• ADAM の入力：ADAM に直接入力します。デバッグモードでは、入力するには Output にフォーカスを移し、デバッガーツールのショートカットを使うにはそのツールにフォーカスを移してください。特殊キーは ADAM > Keyboard で設定します（以下のデフォルトを参照）。F12 で全画面表示を切り替えます。ポートごとに、ADAM > Controller 1 / Controller 2 からゲームパッド（デフォルト）、キーボード、またはハンドコントローラーなしを選択できます。割り当ては Input > Gamepads または Input > Keyboard Configuration で設定します。ハンドコントローラーに割り当てられたキーは、ADAM への入力には使用されません。ADAM のコントローラー設定は、ColecoVision の設定とは別に保存されます。
• スピナー：Input > Spinners > Capture Mouse、または設定済みの Capture Mouse ショートカットを使用します。スピナーを使用しないソフトウェアでは、スピナーを無効にしてください。
• 巻き戻し：設定した巻き戻しホットキー（デフォルトは Backspace）を押し続けるか、ゲームパッドに割り当てたショートカットを使うと、最近のゲームプレイをさかのぼれます。
• オーバースキャン：元の画像を正確に再現するには、Video メニューで Overscan を Top+Bottom、Aspect Ratio を Standard (4:3 DAR) に設定してください。
• マウスカーソル：メインの出力ウィンドウにカーソルを合わせると、自動的に非表示になります。Main Menu が無効の場合も非表示になります。
• ポータブルモード：--portable を指定して起動するか、アプリケーションのバイナリと同じディレクトリに portable.ini という名前の空ファイルを作成してください。macOS では、.app バンドルの隣にファイルを配置してください。

デスクトップ版 ADAM キーボード

通常の英字、数字、句読点、Return、Escape、Backspace、Tab、Shift、Control、Caps Lock、矢印キーは、そのまま対応するキーに割り当てられます。専用の ADAM キーには、次のデフォルト割り当てが使用されます。

ホストキー	ADAM キー
F1-F6	SmartKey I-VI
F7 / F8	Undo / Wild Card
Home / Insert / Delete	ADAM Home / Insert / Delete
Page Up / Page Down	Move-Copy / Store-Fetch
End	Clear
Print Screen	Print

保存済みのキーボード割り当ては維持されます。既存の設定でこのレイアウトを使用するには、ADAM > Keyboard > Restore Defaults を選択してください。

ADAM がキーボードフォーカスを持っている間は、SmartKeys や編集キーをエミュレートされたキーボードに送れるよう、重複するエミュレーターのホットキーをメニューから使用できます。ウィンドウから離れると、押したままの ADAM キーはすべて解放されます。

ADAM のキーボード入力はフォーカスに自動的に従います。通常は直接入力してください。デバッグモードでは、ADAM に入力するには Output にフォーカスを移し、デバッガーツールのショートカットを使うにはそのツールにフォーカスを移してください。F12 は引き続きデフォルトの全画面表示ショートカットです。

Libretro での ADAM

• 起動：OS-7、EOS、SmartWriter を、上記のファームウェア名を使用してフロントエンドのシステムディレクトリまたはその gearcoleco サブディレクトリに配置します。.ddp、.dsk、ADAM の .zip、.m3u、またはコンテンツなしで起動すると ADAM が自動的に起動します。起動可能なメディアがない場合は SmartWriter が開きます。カートリッジは、Cartridge Hardware を ADAM に設定しない限り ColecoVision として使用されます。
• メディアとセーブ：メディアはデフォルトで書き込み禁止です。Save-directory working copy を有効にすると、変更したイメージ全体がフロントエンドのセーブディレクトリに保存され、ソースファイルは変更されません。ADAM Disk Control Drive では Disk 1/2 または Data Pack 1/2 を選択します。Loaded media（デフォルト）はプライマリコンテンツドライブを対象にします。各ドライブにはそれぞれ独自のイメージリストがあります。フロントエンドの取り出し、選択、閉じる操作の順に切り替えます。他のドライブはマウントされたままです。
• 複数イメージ：オプションの ADAM サブシステム（adam）では、起動前に最大5つのスロットを読み込めます。順序は Cartridge、Disk 1、Disk 2、Data Pack 1、Data Pack 2 です。すべてのスロットは省略可能で、各ドライブはプレイリストに対応しています。古い3スロット構成はこのレイアウトに更新してください。単一のイメージまたはプレイリストには通常のコンテンツ読み込みを使用します。
• キーボード：キー割り当ては デスクトップのデフォルトに固定されており、Escape は Escape/WP、Shift/Control は修飾キーとして使用されます。RetroArch では Settings > Input > Auto Enable 'Game Focus' Mode を Detect に設定するか、入力前に Scroll Lock で Game Focus を切り替えます。RetroArch のショートカットを使うには、Game Focus をオフにしてください。Scroll Lock がない場合は、Game Focus Toggle を F10 に割り当てます。F9～F12 と Scroll Lock は ADAM では割り当てられていません。
• リセット：フロントエンドの Reset では現在の起動モードが維持されます。ADAM Computer Reset は、マウント済みのメディアを取り出さずにそこから起動します。このオプションが自動的に Idle に戻らない場合は、次のリセットを要求する前に Idle を選択してください。

デバッグ機能

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

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

gearcoleco [options] [content_file] [symbol_file]

Arguments:
  [content_file]              Cartridge or ADAM media (.col, .cv, .rom, .bin, .ddp, .dsk, .zip, .m3u)
  [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-stdio or --mcp-http)
      --portable              Store configuration and user data beside the application
  -v, --version               Display version information
  -h, --help                  Display this help message

MCP サーバー

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

セットアップ手順とツールのドキュメントについては、MCP_README.md をご覧ください。

エージェントスキル

Gearcoleco は、特定のタスクでエミュレーターを効果的に使用する方法を AI アシスタントに教える Agent Skills を提供しています。

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

npx skills add drhelius/gearcoleco でインストールします。詳細は 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/になるようにします。
• Gearcoleco の Visual Studio ソリューションplatforms/windows/Gearcoleco.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 と Gearcoleco の両方をビルドします。

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

スクリーンショット

コントリビューター

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

ライセンス

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