gbdocs-mcp

An MCP server that turns the Game Boy Pan Docs into precise, low-token, citable lookups for decompilation work.

Instead of grepping 456 KB of markdown, an agent can ask directly:

• What is $FF41? → gb_lookup_register
• What does ld a,$91 / ldh [rLCDC],a configure? → gb_decode_register_value
• What does a write to $2000 do on MBC1? → gb_mbc_decode_write
• What is opcode $CB 7C? → gb_decode_opcode
• What register state does my ROM inherit from the boot ROM? → gb_boot_state

Two rules shape every response:

1. Nothing is fabricated. Each response carries a source block naming the page, section and https://gbdev.io/pandocs/... URL it came from. Where Pan Docs does not cover something (opcode cycle counts, for instance), the server says so.
2. pandocs/ is never modified. The docs are read live at startup, so a git pull inside the clone updates the server with no rebuild.

Install

The Pan Docs markdown ships inside the package, so there is nothing else to download.

pip install gbdocs-mcp                # or: uv tool install gbdocs-mcp
pip install "gbdocs-mcp[semantic]"    # adds embedding-backed search (pulls in torch)

Register with Claude Code:

claude mcp add gbdocs -- uvx gbdocs-mcp

{
  "mcpServers": {
    "gbdocs": {
      "command": "uvx",
      "args": ["gbdocs-mcp"]
    }
  }
}

From source

git clone https://github.com/Nighthawk42/gbdocs-mcp && cd gbdocs-mcp
uv sync --extra semantic --dev
uv run gbdocs-mcp

Optionally clone pandocs beside the checkout; a local clone takes precedence over the bundled copy, so git pull in it updates the server with no rebuild.

Configuration

Docs are resolved in that order: PANDOCS_ROOT, then a sibling pandocs/ clone, then the bundled copy. Whichever is in use is reported by pandocs_toc as docs_revision, including the upstream commit hash.

Semantic search loads lazily — the model is only downloaded the first time a search actually needs it, and vectors are cached thereafter. Without the semantic extra, search degrades to BM25 and says so in its response rather than failing.

Tools

Navigation & retrieval

Registers

Memory

Cartridge

MBCs

CPU

Hardware behaviour

Pages are also exposed as MCP resources (pandocs://page/LCDC).

Opcode data provenance

Pan Docs' CPU_Instruction_Set.md is an encoding reference — it has no cycle counts and no flag effects, and explicitly defers to gbz80(7) and the optables. This server therefore:

• derives mnemonics, operands and instruction length from Pan Docs' {{#bits}} groupings,
• merges cycles and flag effects from a vendored copy of gbdev.io/gb-opcodes/Opcodes.json,
• and labels every field with which of the two it came from.

The two are cross-checked against each other across all 512 opcodes in the test suite.

Development

uv run pytest                             # 599 tests, ~1s
uv run python scripts/smoke.py            # call all 21 tools, print a digest of each
uv run python scripts/client_probe.py     # drive the server as a real MCP stdio client
uv run mcp dev src/gbdocs_mcp/server.py   # MCP Inspector

The heaviest test decodes all 512 opcodes from Pan Docs' {{#bits}} groupings and asserts they agree with the vendored table. A disagreement there means the markdown parser has drifted, so it is worth keeping green.

Contributing

See AGENTS.md for the architecture, the corpus quirks the parsers have to keep handling, and the invariants that must not regress.

Licence

Server code is MIT (see LICENSE).

The bundled documentation is not mine: Pan Docs is released into the public domain (CC0-1.0) by the gbdev community, and the opcode timing table comes from gb-opcodes. This project only reformats their work for machine consumption. Full attribution is in NOTICE.md.