/ ディレクトリ / プレイグラウンド / Gearboy
● コミュニティ drhelius ⚡ 即起動

Gearboy

作者 drhelius · drhelius/Gearboy

AI 支援デバッグおよび ROM 解析用の MCP サーバーが組み込まれたゲームボーイ / ゲームボーイ カラー エミュレータ。

Gearboy は、MCP サーバーが組み込まれた、C++ で書かれたクロスプラットフォームのゲームボーイ、ゲームボーイカラー、およびスーパーゲームボーイのエミュレータです。 AI エージェントは、実行の制御 (一時停止、ステップ実行、再開)、メモリの検査、ブレークポイントの設定、コードの逆アセンブル、およびハードウェア状態のリアルタイム監視を行うことができます。 標準入出力および HTTP トランスポート (ポート 7777) をサポートします。 macOS、Windows、Linux、BSD、および RetroArch 上で実行します。

なぜ使うのか

主な機能

ライブデモ

実際の動作

gearboy-2.replay ▶ 準備完了
0/0

インストール

クライアントを選択

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config を開く。保存後、アプリを再起動。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

Cursor は Claude Desktop と同じ mcpServers スキーマを使用。プロジェクト設定はグローバルより優先。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

Cline サイドバーの MCP Servers アイコンをクリックし、"Edit Configuration" を選択。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

Claude Desktop と同じ形式。Windsurf を再起動して反映。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "gearboy-2",
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  ]
}

Continue はマップではなくサーバーオブジェクトの配列を使用。

~/.config/zed/settings.json
{
  "context_servers": {
    "gearboy-2": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/drhelius/Gearboy"
        ]
      }
    }
  }
}

context_servers に追加。保存時に Zed がホットリロード。

claude mcp add gearboy-2 -- TODO 'See README: https://github.com/drhelius/Gearboy'

ワンライナー。claude mcp list で確認、claude mcp remove で削除。

ユースケース

実用的な使い方: Gearboy

Gearboy を使用して AI 支援でゲームボーイ ROM をデバッグする方法

👤 自作ゲームボーイ開発者とROMハッカー ⏱ ~30 min intermediate

使うタイミング: あなたはゲームボーイの自作 ROM を開発していて、ランタイムの問題をデバッグする必要があります。

前提条件
  • MCP サポートを使用して構築された Gearboy — GitHub README に従ってソースからビルドする
  • ゲームボーイ ROM ファイル (.gb または .gbc) — 自分の自作 ROM または合法的に所有する ROM
フロー
  1. ROMをロードして接続します
    Gearboy MCP サーバーに接続し、ROM をロードします。 プログラムカウンターで現在のCPUの状態と逆アセンブリを表示します。✓ コピーしました
    → PC の CPU レジスタ、フラグ、および逆アセンブルされた命令
  2. ブレークポイントを設定して調査する
    アドレス 0x0150 (ヘッダーの後) にブレークポイントを設定します。 実行を段階的に説明し、各命令が何を行うかを説明します。✓ コピーしました
    → 手順の説明付きのステップバイステップの実行
  3. メモリを検査する
    WRAM の内容を 0xC000 から 0xC0FF まで表示します。 認識可能なデータ構造はありますか?✓ コピーしました
    → データパターンの分析によるメモリダンプ

結果: ROM がどのように実行されるかを明確に理解し、バグを特定して説明します。

注意点
  • 頻繁にヒットするアドレスにブレークポイントがあると、実行が大幅に遅くなる — 条件付きブレークポイントを使用するか、バグに近づいた場合にのみ設定します。
組み合わせ: filesystem

AI と Gearboy を使用してゲームボーイのアーキテクチャをインタラクティブに学習

👤 レトロなコンソールのハードウェアと組み立てを学ぶ学生 ⏱ ~45 min intermediate

使うタイミング: ゲームボーイの CPU、メモリ、グラフィックスがどのように動作するかを実際に理解したいと考えています。

前提条件
  • MCP サーバーを備えた Gearboy — ソースからビルドする
  • 簡易テストROM — 自作のテスト ROM または Blargg のテスト ROM を使用する
フロー
  1. メモリマップを探索する
    ゲームボーイのメモリマップを見せてください。 0x0100 ~ 0x014F の ROM ヘッダーを読み取り、各フィールドについて説明します。✓ コピーしました
    → タイトル、カートリッジ タイプ、ROM/RAM サイズを含む注釈付きヘッダー
  2. VRAM の動作を観察する
    VBlank 割り込みハンドラーをステップ実行し、タイルがどのように VRAM にロードされるかを説明します。✓ コピーしました
    → VRAM 状態によるタイルのロードのステップバイステップの説明

結果: インタラクティブな探索を通じてゲームボーイ ハードウェアを実践的に理解します。

注意点
  • 組み立ては初心者にとっては大変かもしれません — 一度に 1 つのハードウェア機能を実行する単純なテスト ROM から開始します。

組み合わせ

他のMCPと組み合わせて10倍の力を

gearboy-2 + filesystem

オフライン分析のためにメモリ ダンプとデバッグ ログをエクスポートする

VRAM の内容全体をファイルにダンプし、タイル データ レイアウトに注釈を付けます。✓ コピーしました

ツール

このMCPが提供する機能

ツール入力呼び出すタイミングコスト
pause/resume/step none / step_count? エミュレータの実行を制御する 0
read_memory address: int, size: int 任意のアドレスでエミュレータ メモリを読み取る 0
write_memory address: int, data: bytes エミュレータメモリへの書き込み 0
set_breakpoint address: int, type?: str CPUまたはメモリのブレークポイントを設定する 0
disassemble address: int, count: int アドレスで命令を逆アセンブルする 0
get_cpu_state none 現在の CPU レジスタとフラグを取得する 0

コストと制限

運用コスト

APIクォータ
該当なし — 完全にローカル
呼び出しあたりのトークン
デバッグ コマンドあたり 100 ~ 500 トークン
金額
無料およびオープンソース (MIT ライセンス)
ヒント
トークンの使用量を低く抑えるには、フル ダンプの代わりにターゲットを絞ったメモリ読み取りを使用します。

セキュリティ

権限、シークレット、影響範囲

認証情報の保管: 該当なし
データ送信先: 完全にローカル — ネットワーク呼び出しなし

トラブルシューティング

よくあるエラーと対処法

MCP server not responding

Gearboy が MCP サポートを有効にして構築されていることを確認してください。 サーバーポート (デフォルトは 7777) が使用されていないことを確認してください。

確認: curl http://localhost:7777/health
ROM fails to load

ROM ファイルが有効な .gb または .gbc ファイルであることを確認してください。 ファイルが破損していないか確認してください。

確認: Check the ROM header with a hex editor
Breakpoint never hits

アドレスが実行パス内にあることを確認してください。 逆アセンブラを使用して、コードがそのアドレスで実際に実行されるかどうかを確認します。

確認: Disassemble around the target address

代替案

Gearboy 他との比較

代替案代わりに使う場面トレードオフ
Geargrafxゲームボーイの代わりに PC エンジン / TurboGrafx-16 ROM をデバッグしたい異なるコンソール、同じ開発者による同じ MCP 対応エミュレータのアプローチ

その他

リソース

📖 GitHub の公式 README を読む

🐙 オープンな issue を見る

🔍 400以上のMCPサーバーとSkillsを見る