GB Studio MCP Server

GameBoy ゲームを作成する GB Studio / GBA Studio 向けエージェント型 MCP サーバー

生徒や子ども、またはご自身が拡張できるテンプレートを作成するためのプロンプトです。

GBA STUDIO でも動作します。これは GBA に対応する、私がフォークした GB Studio です。

クイックスタート

1. インストール：npm install -g gbstudio-claude-mcp

2. サーバーを起動：gbstudio-claude-mcp

3. Claude Desktop を接続（TUTORIAL.md を参照）

4. Claude にプロンプトを入力：「アプリケーションのロジックをレビューしてテストしてください」

以上です。Claude がレビュー、拡張、さらにはプレイ可能なゲームテンプレートの生成まで行います。GB Studio で生徒と一緒に反復して改良できます。

バイブコーディング、LLM、そして現代の教育：生徒に答えだけでなく、建設的なツールを提供できるか

子どもたちにプログラミング、電子工作、3D プリント、ゲーム開発を14年間教えてきて、私はこう学びました。最高の教育ツールは、物事を簡単にするだけではありません。学習をやりがいのある活動にしてくれます。GB Studio はそのようなツールのひとつです。これはビジュアルなゲーム制作ツールで、Game Boy 開発を可能にし、実機向けの制作に必要な本物の創造力を、生徒、教育者、愛好家の手に届けます。GB Studio と、大規模言語モデル（LLM）でできることについての教育を組み合わせれば、LLM を松葉杖のように頼るのではなく、LLM とどう連携できるかについて、生徒に前向きな視点をもたらせます。

バイブコーディングとは？

「バイブコーディング」は、単なる流行語ではありません。これはパラダイムシフトです。構文による障壁を取り払い、セミコロンを暗記する代わりに、クリエイターが流れ、ロジック、アイデアに集中できるプログラミングです。Scratch、App Inventor、GB Studio のようなツールは、この考え方を体現しています。障壁を取り除き、創造性と問題解決という本当に重要なものを中心に、プログラミングを再構築します。

子どもたちにとって、バイブコーディングは成長する中で身近なものです。構文に圧倒されることなく、プログラミングの「なぜ」と「どのように」に集中できます。これは単に役立つというだけではありません。システム、設計、ロジックについて考える必要がある一方で、従来のコーディングの急な学習曲線によってその機会を奪われている生徒にとって、大切なことです。

教育における LLM の役割

ChatGPT のような大規模言語モデルは、教育現場で激しい議論を巻き起こしています。それにはもっともな理由があります。不注意に使えば、考えることをコピペするだけの姿勢に置き換える、不正のためのツールになってしまいます。しかし、目的を持って使えば、実際の学習を加速させる足場になり得ます。違いを生むのはツールではなく、使い方です。

だからこそ、私は Clawdbot MCP サーバーを作りました。LLM を GB Studio と直接連携させることで、ユーザーや教師は次のことができます。

• プロジェクトの足場を作る：簡単なプロンプトから、スターターテンプレート、アセット、イベントフローを生成します。
• テストを自動化する：スモークテストを実行し、バグを見つけてプロジェクトのロジックを検証します。
• 反復を促す：提案や例を提示して、生徒がプロジェクトを改良できるよう支援します。

ゲームをゼロから作ることもできますが、AAA クラスにはならないので、期待値は調整してください（笑）。

Pong（Game Boy）

Create a Pong clone for the original Game Boy. Two paddles, a ball, and a score counter. The player controls the left paddle, the right paddle is AI-controlled. Use simple monochrome graphics and authentic GB sound effects. Generate all scenes, actors, and assets for a playable Pong game.

Pac-Man（Game Boy Color）

Build a Pac-Man style maze game for Game Boy Color. The player navigates a maze, collects pellets, and avoids ghosts. Include at least one maze layout, four ghosts with basic AI, and colorful graphics. Generate all scenes, actors, and assets needed for a playable demo.

Mario Bros 風プラットフォーマー（Game Boy Color）

Design a Mario Bros inspired platformer for Game Boy Color. The player can run, jump, and stomp on enemies. Include three levels, power-ups, coins, and a flagpole at the end of each level. Use bright palettes and catchy background music. Generate all scenes, actors, and assets for a classic platformer experience.

スペースシューター（Game Boy）

Create a vertical scrolling space shooter for the original Game Boy. The player controls a spaceship, shoots enemies, and dodges obstacles. Include multiple enemy types, power-ups, and a boss fight. Use classic GB graphics and chiptune sound effects. Generate all scenes, actors, and assets for a playable shooter.

GB Studio 向け Claude MCP サーバー

Model Context Protocol（MCP）を使用して GB Studio プロジェクトを操作する TypeScript サーバーです。プロジェクトの検出、検証、ゲームアセットの作成を行うエンドポイントを提供します。

---

インストール

npm でグローバルにインストールします。

npm install -g gbstudio-claude-mcp

---

ローカル環境のセットアップ（.env）

ローカル開発では、API キーと設定をプロジェクトルートの .env ファイルに保存します。これにより、シークレットをソース管理から除外でき、GitHub Actions で使用されているパターンにも合わせられます。

1. プロジェクトルートに .env ファイルを作成します：

   CLAUDE_API_KEY=your-claude-api-key-here
   # Add other keys as needed
   

2. [dotenv] を使用すると、サーバーは .env の変数を自動的に読み込みます。
3. .env ファイルはデフォルトで gitignore に登録されています。

.env ファイルはソース管理に絶対にコミットしないでください。

---

使用方法

サーバーを起動します：

gbstudio-claude-mcp

サーバーはデフォルトで http://localhost:3000 で実行されます。

MCP クライアント（例：Claude Desktop）を設定して、このサーバーに接続します。詳しいセットアップ方法とトラブルシューティングについては、このドキュメントの末尾にリンクされているチュートリアルをご覧ください。

---

エンドツーエンドの使用方法：Windows と Linux/macOS

TUTORIAL.md では、スクリーンショットと Windows および Linux/macOS 向けのトラブルシューティングのヒントを含む、このサーバーを使って GB Studio ゲームを構築するための完全な手順を説明しています。

---

MCP プロトコルのサポート

このパッケージは Model Context Protocol (MCP) をサポートしています。Claude Desktop やその他の MCP クライアントで使用するために、サーバーを MCP stdio モードで実行できます：

npm run build:mcp
node build/mcp.js

MCP stdio サーバーはローカル REST API に http://localhost:3000 でプロキシするため、先に REST サーバーを起動してください。別のポートを使用するには、GBSTUDIO_API_URL（完全な URL）または GBSTUDIO_API_PORT（ポート番号）を設定します：

gbstudio-claude-mcp

または、これを MCP クライアントの設定に追加します：

{
   "mcpServers": {
      "gbstudio-mcp": {
         "command": "node",
         "args": ["/absolute/path/to/build/mcp.js"]
      }
   }
}

---

Clawdbot / Moltbot との互換性

Clawdbot と Moltbot は、AgentSkills 互換の SKILL.md ファイルを通じてツールを検出します。このリポジトリには、次のファイルが含まれています：

• skills/gbstudio-mcp/SKILL.md

互換性はトランスポート方式によって異なります：

• Clawdbot が stdio MCP サーバーを子プロセスとして実行できる場合は、node build/mcp.js が動作します。
• Clawdbot のセットアップで HTTP+SSE MCP サーバーが必要な場合は、この MCP サーバーが stdio のみのため、ブリッジが必要です。
• REST API のみを実行する場合、Clawdbot はツールを MCP として自動検出しません。

Moltbot でスキルを有効にするには、次のようなエントリーを追加します：

{
  "skills": {
    "load": {
      "extraDirs": [
        "~/.clawdbot/skills"
      ],
      "watch": true,
      "watchDebounceMs": 250
    },
    "entries": {
      "gbstudio-mcp": {
        "enabled": true,
        "env": {}
      }
    }
  }
}

---

プロジェクト構成

• src/index.ts — メインサーバーとエンドポイントのロジック
• tests/ — すべてのエンドポイント用の Jest テストスイート
• tests/poachermon/ — 統合テスト用の実際の GB Studio プロジェクト
• gbstudio_api_endpoints.csv — 計画されているすべてのエンドポイントのカタログ

ローカル開発

1. リポジトリをクローンします：

   git clone https://github.com/eoinjordan/gb-studio-agent.git
   cd gb-studio-agent
   

2. Node.js をインストールします（推奨：v21.7.1 または互換性のあるバージョン）
3. 依存関係をインストールします：

   npm install
   

4. 開発サーバーを起動します：

   npm run dev
   

5. テストスイートを実行します：

   npm test
   

---

ヘルスチェック

• GET /health — ヘルスチェック用に { status: "ok" } を返します。

Claude API キー

• GET /claude-key — 環境に CLAUDE_API_KEY が設定されている場合は { present: true } を返し、設定されていない場合は 404 とともに { present: false } を返します。

プロジェクトの検索

• POST /find_project — 指定されたディレクトリを起点に、最初に見つかった .gbsproj ファイルを検索します。
  • 本文： { startPath: string }
  • 戻り値： { projectPath: string }。見つからない場合は 404。

インベントリ

• POST /inventory — GB Studio プロジェクトのルートからシーン、アクター、トリガー、アセットを一覧表示します。
  • 本文： { projectRoot: string }
  • 戻り値： { scenes, actors, triggers, assets }。エラーの場合は 404/400。

検証

• POST /validate — GB Studio プロジェクトの構造を検証します（有効な .gbsproj ファイルと必須フィールドを確認します）。
  • 本文： { projectRoot: string }
  • 戻り値： 有効な場合は { valid: true, message: string, scenes: number, projectPath: string, target: "gb" | "gba", engine: "gb-studio" | "gba-studio", version: string | null }。無効な場合、または必須フィールドがない場合は、エラーメッセージとともに 400/404 を返します。
  • エラーケース：
    • projectRoot が指定されていない場合、または .gbsproj が無効／必須フィールドを欠いている場合は 400
    • projectRoot が存在しない場合、または .gbsproj ファイルが見つからない場合は 404

GBA ROM のビルド

• POST /gba/build — ローカルの GBA Studio チェックアウトを使用して .gba ROM をビルドします。
  • 本文： { projectRoot: string, gbaStudioRoot?: string, output?: string, buildCli?: boolean, verbose?: boolean, extraArgs?: string[] }
  • 環境変数： gbaStudioRoot の代わりに GBA_STUDIO_ROOT を使用できます。
  • 戻り値： 成功時は { success: true, projectPath, gbaStudioRoot, output, stdout, stderr }、失敗時は { success: false, error, stdout, stderr } を返します。
  • MCP ツール： build_gba_rom は Claude／エージェントのクライアント向けに同じ引数を公開します。

シーンの作成

• POST /scene/create — 指定した GB Studio プロジェクトに新しいシーンを追加します。
  • 本文： { projectRoot: string, scene: object }
  • 戻り値： 成功時は { success: true, scene }、失敗時はエラーメッセージとともに 400／404／500 を返します。

アクターの作成

• POST /actor/create — 指定したシーンに新しいアクターを作成します。
  • 本文： { projectRoot: string, sceneId: string, actor: object }
  • 戻り値： 成功時は { success: true, actor }、失敗時はエラーメッセージとともに 400／404／500 を返します。

背景の作成

• POST /background/create — プロジェクトに新しい背景を作成します。
  • 本文： { projectRoot: string, background: object }
  • 戻り値： 成功時は { success: true, background }、失敗時はエラーメッセージとともに 400／404／500 を返します。

スプライトの作成

• POST /sprite/create — プロジェクトに新しいスプライトを作成します。
  • 本文： { projectRoot: string, sprite: object }
  • 戻り値： 成功時は { success: true, sprite }、失敗時はエラーメッセージとともに 400／404／500 を返します。

音楽の作成

• POST /music/create — プロジェクトに新しい音楽トラックを作成します。
  • 本文： { projectRoot: string, music: object }
  • 戻り値： 成功時は { success: true, music }、失敗時はエラーメッセージとともに 400／404／500 を返します。

効果音の作成

• POST /sound/create — プロジェクトに新しい効果音を作成します。
  • 本文： { projectRoot: string, sound: object }
  • 戻り値： 成功時は { success: true, sound }、失敗時はエラーメッセージとともに 400／404／500 を返します。

タイルセットの作成

• POST /tileset/create — プロジェクトに新しいタイルセットを作成します。
  • 本文： { projectRoot: string, tileset: object }
  • 戻り値： 成功時は { success: true, tileset }、失敗時はエラーメッセージとともに 400／404／500 を返します。

トリガーの作成

• POST /trigger/create — 指定したシーンに新しいトリガーを作成します。
  • 本文： { projectRoot: string, sceneId: string, trigger: object }
  • 戻り値： 成功時は { success: true, trigger }、失敗時はエラーメッセージとともに 400／404／500 を返します。

変数の作成

• POST /variable/create — プロジェクトに新しい変数を作成します。
  • 本文： { projectRoot: string, variable: object }
  • 戻り値： 成功時は { success: true, variable }、失敗時はエラーメッセージとともに 400／404／500 を返します。

スクリプトの作成

• POST /script/create — プロジェクトに新しいスクリプトを作成します。
  • 本文： { projectRoot: string, script: object }
  • 戻り値： 成功時は { success: true, script }、失敗時はエラーメッセージとともに 400／404／500 を返します。

パレットの作成

• POST /palette/create — プロジェクトに新しいパレットを作成します。
  • 本文： { projectRoot: string, palette: object }
  • 戻り値： 成功時は { success: true, palette }、失敗時はエラーメッセージとともに 400／404／500 を返します。

フォントの作成

• POST /font/create — プロジェクトに新しいフォントを作成します。
  • 本文： { projectRoot: string, font: object }
  • 戻り値： 成功時は { success: true, font }、失敗時はエラーメッセージとともに 400／404／500 を返します。

エモートの作成

• POST /emote/create — プロジェクトに新しいエモートを作成します。
  • 本文： { projectRoot: string, emote: object }
  • 戻り値： 成功時は { success: true, emote }、失敗時はエラーメッセージとともに 400／404／500 を返します。

アバターの作成

• POST /avatar/create — プロジェクトに新しいアバターを作成します。
  • 本文： { projectRoot: string, avatar: object }
  • 戻り値： 成功時は { success: true, avatar }、失敗時はエラーメッセージとともに 400／404／500 を返します。

定数の作成

• POST /constant/create — プロジェクトに新しい定数を作成します。
  • Body: { projectRoot: string, constant: object }
  • Returns: 成功時は { success: true, constant }、エラーメッセージとともに 400/404/500 を返します。

プレハブアクターの作成

• POST /prefab/actor/create — プロジェクトに新しいアクターのプレハブを作成します。
  • Body: { projectRoot: string, actorPrefab: object }
  • Returns: 成功時は { success: true, actorPrefab }、エラーメッセージとともに 400/404/500 を返します。

プレハブトリガーの作成

• POST /prefab/trigger/create — プロジェクトに新しいトリガーのプレハブを作成します。
  • Body: { projectRoot: string, triggerPrefab: object }
  • Returns: 成功時は { success: true, triggerPrefab }、エラーメッセージとともに 400/404/500 を返します。

設定の更新

• POST /settings/update — プロジェクトの設定を更新します。
  • Body: { projectRoot: string, settings: object }
  • Returns: 成功時は { success: true, settings }、エラーメッセージとともに 400/404/500 を返します。

メタデータの更新

• POST /metadata/update — プロジェクトのメタデータを更新します。
  • Body: { projectRoot: string, metadata: object }
  • Returns: 成功時は { success: true, metadata }、エラーメッセージとともに 400/404/500 を返します。

エンジンフィールド値の作成

• POST /engine-field-value/create — プロジェクトに新しいエンジンフィールド値を作成します。
  • Body: { projectRoot: string, engineFieldValue: object }
  • Returns: 成功時は { success: true, engineFieldValue }、エラーメッセージとともに 400/404/500 を返します。

Claude のキー

• POST /claude/key — 環境に Claude API キーを設定します。
  • Body: { key: string }
  • Returns: 成功時は { success: true }、エラーメッセージとともに 400 を返します。

ゲームを最初から最後まで構築する

Claude とこの MCP サーバーを使って GB Studio ゲームを構築するには、次の手順に従います。

1. プロジェクトの検出： /find_project を使って既存の .gbsproj ファイルを検索するか、ディレクトリを指定して開始します。
2. プロジェクトの検証： /validate を使って、プロジェクトが有効であることを確認します。
3. インベントリの取得： /inventory を使って、現在のシーン、アクター、トリガー、アセットを一覧表示します。
4. シーンの作成： /scene/create を使って、新しいシーンを追加します。
5. アクターの作成： /actor/create を使って、シーンにアクターを追加します。
6. アセットの作成： 作成用エンドポイント（現在はスタブ）を使って、スプライト、背景などを追加します。
7. 設定／メタデータの更新： 更新用エンドポイントを使って、プロジェクトを設定します。
8. ビルド／エクスポート： /gba/build または MCP の build_gba_rom を使って、GBA Studio プロジェクトを .gba にコンパイルします。

注：すべてのエンドポイントは現在、完全に動作します。

GBA Studio のビルド例

{
  "projectRoot": "C:/Users/Eoin/git/gba-studio/examples/gba-starter-project",
  "gbaStudioRoot": "C:/Users/Eoin/git/gba-studio",
  "output": "C:/tmp/gba-starter.gba",
  "buildCli": true
}

プロンプトの例

さまざまなゲームジャンル向けの詳細なプロンプト例と、最初から最後までのワークフローについては、TUTORIAL.md を参照してください。

テストカバレッジ

すべてのエンドポイントは、tests/ ディレクトリ内の Jest テストでカバーされています。npm test を実行して、すべての機能を検証してください。テストでは実際のサンプルプロジェクトを使用します。

公開

新しいバージョンを公開するには：

1. package.json のバージョンを更新します
2. プロジェクトをビルドします：

   npm run build
   

3. npm にログインします：

   npm login --auth-type=legacy
   

4. npm に公開します：

   npm publish --access public
   

詳しくは npm の公開ドキュメントを参照してください。

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えてテストを追加します
4. https://github.com/eoinjordan/gb-studio-agent にプルリクエストを送信します

ライセンス

MIT