gbdocs-mcp: Instructions file for Claude Code

CLAUDE.md

Project instructions for Claude Code. The full contributor guide is in AGENTS.md — read it before changing anything under src/.

Quick reference

uv sync --extra semantic --dev         # install (drop --extra semantic for BM25-only)
uv run pytest                          # ~600 tests, about a second
uv run python scripts/smoke.py         # every tool through real MCP dispatch
uv run python scripts/client_probe.py  # drive the server as a real stdio client
uv run gbdocs-mcp                      # run the server over stdio

Non-negotiables

1. Never invent hardware facts. This server reformats Pan Docs; it does not author documentation. If the docs are silent, the response says so. Do not add hardcoded tables of Game Boy knowledge — parse it from the docs or report the gap.
2. Every tool response carries a source naming the page, section and gbdev.io URL.
3. pandocs/ is read-only. Never write into the docs checkout.
4. tests/test_opcodes.py must stay green. It cross-checks all 512 opcodes derived from the docs against the vendored Opcodes.json. A failure means the markdown parser drifted — fix the parser, not the test.

Where things live

Logic goes in src/gbdocs_mcp/api.py (the Docs facade). server.py stays a thin MCP wrapper. mdparse.py holds ports of Pan Docs' own Rust preprocessor — when the port and the Rust disagree, the Rust wins, because mismatched slugs break every URL the server emits.

Traps that have already bitten

• Register bullets are not in bit order (IE lists VBlank first while its table is MSB-first) — match by name, never by position.
• Older MBC pages use a plain - separator where newer pages use an em-dash.
• Heading depth is inconsistent; match on heading text, not ## vs ###.
• Some value tables are raw HTML rather than pipe tables.

Style

Match the surrounding code. Comments explain why a quirk exists — usually "because the docs do this" — not what the line does.