@gbs-toolkit/mcp-server

MCP server for structured GB Studio 4.x project editing — read/patch scripts, scenes, actors, triggers, variables; build ROMs; sprite generation pipeline.

Designed to be driven by an LLM coding assistant (Claude Code, Cursor, etc.) so the model can mutate .gbsres resources safely instead of dropping bytes into JSON by hand.

Install

npm install -g @gbs-toolkit/mcp-server

Or invoke on demand via npx:

npx -y @gbs-toolkit/mcp-server

Run as an MCP server

The server speaks stdio MCP. Most users wire it up in their LLM client's .mcp.json:

{
  "mcpServers": {
    "gbs": {
      "command": "npx",
      "args": ["-y", "@gbs-toolkit/mcp-server"],
      "env": {
        "GBS_PROJECT_ROOT": "./gbsproj/demo"
      }
    }
  }
}

Environment variables

| Variable | Required | Default | Notes | |---|---|---|---| | GBS_PROJECT_ROOT | yes | — | Directory containing <name>.gbsproj | | GBS_CLI_PATH | no | probes common install locations | Absolute path to gb-studio-cli.js | | GBS_MGBA_RUNNER | no | none | Path to a libmgba-linked runner binary used by run_emulator (build it from native/build.sh) | | GBS_ROM_OUT | no | <root>/build | Output directory for build_rom | | GBS_LOG_PATH | no | <root>/build/compile.log | Captured compile log | | GBS_SCREENSHOT_DIR | no | <root>/build/screenshots | Where run_emulator drops PNGs | | SPRITE_PROVIDER | no | openai | openai / gemini / replicate / fal | | OPENAI_API_KEY | conditional | — | Required if SPRITE_PROVIDER=openai and generate_sprite is used | | GEMINI_API_KEY | conditional | — | Required for gemini provider | | REPLICATE_API_TOKEN | conditional | — | Required for replicate provider | | FAL_KEY | conditional | — | Required for fal provider |

Tool inventory

| Tool | Kind | |---|---| | list_scenes / read_scene / list_actors / read_script / read_compile_log | read | | patch_script | write (insert / replace / delete, applied in order) | | set_variable | write (upserts a VARIABLE_SET_TO_VALUE event in the start scene's onInit) | | create_scene / create_actor / create_trigger / create_variable / create_custom_event / set_start_scene | write | | delete_scene / delete_actor / delete_trigger / delete_custom_event / delete_variable | write (cross-script reference scan; refuses unless force: true) | | generate_sprite | write (text-to-image → 4-colour DMG quantise → emits (asset.png, asset.png.gbsres)) | | convert_image_to_sprite | write (no AI; same pipeline applied to a user-supplied PNG/JPG) | | build_rom | subprocess (spawns GB Studio CLI's make:rom) | | run_emulator | subprocess (drives a libmgba-linked C runner) | | screenshot | read image (returns base64 PNG as multimodal MCP content) |

What is NOT exposed

Creation/import of binary assets stays GUI-side: backgrounds, tilesets, emotes, avatars, fonts, music, sounds, plus actorPrefabs / triggerPrefabs / palettes / notes. The MCP layer can read and patch scripts that reference these resources by id, but cannot create their .png / .uge / .wav payloads. Sprites are the one exception (see generate_sprite / convert_image_to_sprite).

Built-in guardrails

The server enforces two checks that previously had to live in prompts:

1. Dialogue width audit — patch_script validates every EVENT_TEXT / EVENT_MENU / EVENT_CHOICE / EVENT_DIALOGUE / EVENT_MARQUEE string against the GB Studio default-font line budget (18 columns; $var$ placeholders reserve 5 chars to cover signed-16-bit values). Multi-box text: string[] form, CJK width (2 columns / char), and recursive children branches are all walked. A violation rejects the patch with DIALOGUE_WIDTH_EXCEEDED and a per-line breakdown. Pass widthBudget to override (e.g. for a custom narrow font) or force: true to bypass.

2. Sprite quality check — generate_sprite and convert_image_to_sprite analyse the post-quantisation RGBA buffer (opaque ratio, effective DMG colour count, edge density, single-shade dominance). Clearly degenerate outputs (near-empty frame, ≤1 effective shade) refuse to write the asset; borderline cases (2 shades, low edge density, >85% one shade) save with a quality.level: "warn" field in the response. Pass force: true to skip the check.

Both checks return structured metadata so the LLM can self-correct rather than ploughing through.

Building the emulator runner

run_emulator requires a libmgba-linked C binary. Stock mGBA CLIs do not accept a startup --script flag, so we ship a small dedicated runner. From the cloned repo:

cd native
MGBA_SRC=/path/to/mgba MGBA_BUILD=/path/to/mgba/build ./build.sh

Then point the env var at the result: GBS_MGBA_RUNNER=/path/to/gbs-mgba-runner.

If you don't need run_emulator, ignore this — every other tool works without it.

License

MIT