@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

Tool inventory

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