gbdocs-mcp: Instructions file for Codex

AGENTS.md

Guidance for coding agents (and humans) working on gbdocs-mcp.

What this project is

An MCP server that turns the Game Boy Pan Docs into structured, citable lookups for decompilation work. It is a reformatter, not an author: every fact it returns comes out of the documentation, and every response carries a source block pointing back at the page and section it came from.

Two rules that override convenience

1. Never fabricate hardware facts

If Pan Docs does not document something, say so. The codebase already does this in several places and new code must follow suit:

• decode_value() returns "note": "Pan Docs documents no bitfield layout..." rather than inventing bit meanings, and lists undocumented_bits separately.
• gb_decode_opcode labels cycle counts and flags source: "gb-opcodes" because Pan Docs deliberately omits them.
• lookup_cart_code returns meaning: null with "Not a documented value" instead of guessing.

Do not add a lookup table of hardware knowledge you happen to know. Parse it out of the docs, or report the gap.

2. pandocs/ is read-only input

Nothing in src/ writes to the docs. A local clone, if present, wins over the bundled copy so git pull inside it takes effect with no rebuild.

Architecture

mdparse.py   Pan Docs' custom markdown syntax. Ports of the upstream preprocessor.
corpus.py    Loads the docs into Page/Section objects; SUMMARY.md -> chapter tree.
render.py    Section -> compact text for an LLM to read.
registers.py Register index, bitfield semantics, value decode/encode.
memory.py    Address-space regions, I/O ranges, jump vectors.
cartridge.py Header fields and code tables; header byte decoder.
mbc.py       Mapper banking ranges and write identification.
opcodes.py   SM83 decoder built from the docs, merged with vendored cycles/flags.
search.py    BM25 + optional embeddings, fused with RRF.
api.py       The Docs facade -- all tool logic lives here.
server.py    Thin MCP wrapper: 21 tool definitions and one resource template.