Skip to content

About

MCP server giving LLMs hardware-validated NGPC knowledge, API, examples and validation tools

Topics

Resources

Stars

4 stars

Watchers

1 watching

Forks

Repository files navigation

NgpCraft MCP

Inactivity policy (2026-10-01): disable the BIOS ten-minute idle request by clearing User_Answer / HW_USR_ANSWER (0x6F86) bit 6; keep reserved bit 5 clear (HW_USR_ANSWER &= (u8)0x9F;). Continue handling every nonzero HW_USR_SHUTDOWN (0x6F85), including battery and POWER requests. This is a precaution pending investigation, not a confirmed hardware-defect diagnosis.

Model Context Protocol server for NgpCraft — gives any MCP-compatible LLM the hardware-validated knowledge, API, examples, and validation tooling to write working NGPC homebrew.

Install once, and every Claude Code / Cursor / Claude Desktop session gains the ability to look up real NGPC hardware facts, retrieve canonical ASM patterns, search a proven game's source by feature, and scaffold a new project — instead of hallucinating half-correct code that crashes on silicon.

Using this from an AI agent? Read AGENT_GUIDE.md first. It maps symptom → tool, explains the save-state workflow for reproducing a user's bug, and covers the BIOS requirement — without a real bios.bin the emulator renders a plausible but wrong picture. It is also served as the MCP resource ngpc://doc/agent_guide.


Why this exists

Writing NGPC code with an LLM today without context = hallucinated C99 constructs the compiler rejects, toolchain mis-encodes (a D0 prefix wrongly emitted for a register op) and broken silicon opcodes (add A,C = CB 81 C-source ALU), wrong ABI, forgotten NGP_FAR on ROM data, etc. The user ends up debugging on real hardware what should have been caught before code was written.


Quick start

Install (local dev)

cd /path/to/NgpCraft_MCP
npm install

Configure Claude Code

Add to ~/.claude/mcp.json (or equivalent for your client):

{
  "mcpServers": {
    "ngpcraft": {
      "command": "node",
      "args": ["/absolute/path/to/NgpCraft_MCP/src/server.js"]
    }
  }
}

Restart your MCP client. Tools will appear prefixed with mcp__ngpcraft__*.

Quick test

Any of these prompts should now work:

  • "Use the NGPC bug checker to look up D0 prefix."
  • "Search NGPC docs for DMA VBlank restrictions."
  • "Show me StarGunner's state machine implementation."
  • "Give me the canonical ASM for enabling VBlank interrupts."

Tools (v0.2)

Tool Status Purpose
ngpc_bug_check working Query silicon + toolchain bug DB by opcode/keyword
ngpc_asm_pattern working Retrieve hardware-safe ASM patterns (prologue, LDIRW, DMA load, etc.)
ngpc_doc_search working Full-text search across the NGPC dev wiki corpus (wiki/ + DENSE_INDEX + StarGunner docs)
ngpc_api_lookup working Look up template function signatures from vendor/templates/base/src/**/*.h
ngpc_example working Grep StarGunner + Windcup RE by feature keyword
ngpc_new_project working Scaffold from base / cavegen / platformer / racer template
ngpc_lint working Hardware-fidelity lint via NGPC_Interp.compile (HW-1/HW-2/HW-3b)
ngpc_quickrun working Transpile + run main() generator N vsync ticks, return state digest
ngpc_screenshot working PNG of framebuffer at frame N (fake canvas + pngjs)
ngpc_png_to_sprite working PNG → sprite C/H via NGPC_AssetTools.exportSprite
ngpc_png_to_tilemap working PNG → tilemap C/H via NGPC_AssetTools.exportTilemap
ngpc_font_bake stub (v0.3) PNG → NGPC 2bpp font data — bake pipeline lives outside the live editor
ngpc_disasm working Disassemble ROM/byte range via ngpc_disasm.py bridge
ngpc_emu_rom_info working Parse ROM header + bootstrap reset state via NgpCraft emulator
ngpc_emu_native_run working Runs the game on the native C++ core: load a player save state (.s0), hold buttons, advance frames, return registers + a beam-accurate screenshot. Needs a real bios.bin.
ngpc_emu_peek working Read bytes from emulated memory bus
ngpc_emu_decode working Decode one TLCS-900 instruction at address
ngpc_emu_step_trace working Run N instructions from boot/address, return trace + CPU state
ngpc_emu_trace_exec working Per-record execution trace — CPU before/after, flag changes, memory writes per instruction (vs step_trace's condensed result)
ngpc_psg_trace working Run code N frames + return PSG event log (tone/attn/noise writes by frame)
ngpc_visual_diff working Render two C snippets at frame N + return per-pixel diff PNG (magenta on dimmed grey)
ngpc_validate_project working Lint every .c file under a directory, aggregated report (per file, per rule)
ngpc_compile_official working (local toolchain) Build a project via the LOCAL Toshiba toolchain (cc900 + asm900 + tulink + tuconv + s242ngp). Returns produced ROM. The .exe stay on the user's PC — never bundled or redistributed.
ngpc_studio_event working NgpCraft Studio (GB Studio projects for the NGPC): the exact JSON of any of the 156 GB Studio events — fields, defaults, a valid example, NGPC status (identical / adapted / refused). Use before writing an event by hand
ngpc_studio_check working NgpCraft Studio: one call = lint (GB Studio habits that misbehave on the NGPC, with fix), per-scene budget (tiles of 512, palettes), V3 compile with grouped warnings, ROM build, save slots that fit
ngpc_studio_run working NgpCraft Studio: play the game from any scene on the native core, scripted buttons / teleport / variable writes / power cycle, returns variables BY NAME and screenshots as images. Clean-room HLE BIOS included
ngpc_studio_save working NgpCraft Studio: read the cartridge's save journal (slots, signature of this build or not, variables by name)

The ngpc_studio_* tools serve NgpCraft Studio: GB Studio 4.3.2 projects compiled for the NGPC by the NgpCraft V3 compiler. They run src/tools/studio/ngpc_studio.py with the V3 found like the editor finds it (v3_root argument, NGPCRAFT_V3_HOME, or the copy bundled with an installed NgpCraft Studio, whose Python is used too), the Toshiba toolchain to link a ROM (toolchain_path, NGPC_TOSHIBA_HOME, default C:\t900), and this repository's emulator core with its clean-room HLE BIOS (vendor/emulator/hle_bios/), the BIOS the editor's own player uses for these games. The event catalogue src/data/studio_events.json is built from the editor's event definitions by scripts/build_studio_events.mjs; the rules an agent needs are in corpus/studio/NGPCRAFT_STUDIO_RULES.md (found by ngpc_doc_search). Smoke test: node scripts/smoke_studio_tools.mjs <project> <work dir> [<v3 root>].

The transpiler-backed tools (ngpc_lint / ngpc_quickrun / ngpc_screenshot / ngpc_png_to_*) load the Live Editor JS modules into a Node vm context via src/tools/_transpiler_loader.js — no browser, no DOM. Audio (PSG) is intentionally not initialised: voice register state is preserved but no WebAudio context is created.

For ngpc_screenshot, a fake CanvasRenderingContext2D captures the framebuffer; PNG encoding goes through pngjs.

For ngpc_png_to_sprite / ngpc_png_to_tilemap, PNG decoding goes through pngjs (replaces the browser-only URL.createObjectURL + Image path used inside asset_tools.decodePng).

The ngpc_emu_* tools spawn python vendor/emulator/ngpc_emu.py <cmd> --json (Python 3 required on the host). They cover ROM parsing, memory bus reads, decode/execute and the K2GE inspectors, and they read static state — a ROM at reset or a save state.

ngpc_emu_native_run is the exception: it spawns python vendor/emulator/ngpc_native.py run --json and executes the machine on the native C++ core (VDP, PSG, IRQ and the timing model), drawing the frame line by line as the beam passes. It needs the compiled core in vendor/emulator/cpp/build/ and, for most commercial games, a real bios.bin.

⏱️ It is timed like hardware. The raw core defaults to free instruction fetch for backward compatibility, which runs ~2.9× too fast; this bridge applies the silicon-calibrated set (cart_wait=3, cart_data_wait=0, ldir_cost=14) and reports which model ran in the answer's timing field. timing: "free" opts back out, for reproducing a pre-wait-state measurement and nothing else.

🩺 Every run returns hw_safety — a starved watchdog (a real console resets itself) or a stack that crossed into the BIOS page. Counted, not fatal, exactly as on hardware; hw_guard: true makes the first one stop the run. See AGENT_GUIDE.md for how to report them.


Requirements

For You need
the server Node 18+
every ngpc_emu_* tool Python 3 on PATH
ngpc_compile_homemade working
ngpc_emu_breakpoint working
ngpc_emu_eventlog_profile working
ngpc_emu_map_lookup working
ngpc_emu_memory_dump working
ngpc_emu_oam_info working
ngpc_emu_opcode_coverage working
ngpc_emu_palette_info working
ngpc_emu_registers working
ngpc_emu_run_until working
ngpc_emu_screenshot working
ngpc_emu_tick_frame working
ngpc_emu_tile_view working
ngpc_emu_tilemap_info working
ngpc_emu_tiles_view working
ngpc_emu_watchpoint working
running or rendering a game a real bios.bin, supplied by you — never shipped here

⚠️ The BIOS is not optional for correct output. The interrupt vector table lives in it; with no BIOS that table is all zeroes, so the first interrupt sends the CPU to address 0 and the game dies while the screen still shows a plausible frame. Some games check for it directly: Metal Slug — 2nd Mission silently disables fire and jump if the console did not boot through its BIOS.

Resources

Exposed via ngpc:// URIs — clients that support MCP resources can read them directly without a tool call.

  • ngpc://doc/quickstart — orientation for AI agents
  • ngpc://doc/hw_registers — hardware register map
  • ngpc://doc/palettes — RGB444, 16 palettes, transparency
  • ngpc://doc/sprites — 64 sprites, OAM, metasprites
  • ngpc://doc/tilemaps — SCR1/SCR2, scroll, mapstream
  • ngpc://doc/dma — DMA channels and restrictions
  • ngpc://doc/audio — T6W28 PSG, BGM format
  • ngpc://doc/input — joypad register, edge detect
  • ngpc://doc/bios — BIOS calls, SYSFONT, power button
  • ngpc://doc/asm — TLCS-900/H ASM guide
  • ngpc://doc/t900_dense_ref — opcode reference
  • ngpc://doc/collision — AABB, tilemap collision
  • ngpc://doc/math — Q8.8, LUT, sin_table
  • ngpc://doc/game_loop — VBlank sync, frame budget
  • ngpc://doc/asset_pipeline — PNG → NGPC asset conventions
  • ngpc://doc/storage — flash save, RTC
  • ngpc://doc/language — cc900/t900cc C subset + gotchas
  • ngpc://doc/build_toolchain — Makefile + linker
  • ngpc://doc/debug_tools — emulator + hw test workflow
  • ngpc://roadmap/ngpc — current priorities
  • ngpc://example/stargunner/shmup_doc — full shmup architecture
  • ngpc://example/stargunner/retex — porting post-mortem

Repository layout

NgpCraft_MCP/
├── package.json
├── README.md                      ← you are here
├── src/
│   ├── server.js                  ← MCP stdio entrypoint
│   ├── tools/                     ← one file per tool
│   │   ├── index.js               ← registry
│   │   ├── bug_check.js           ← [working] silicon bug DB query
│   │   ├── asm_pattern.js         ← [working] canonical ASM patterns
│   │   ├── doc_search.js          ← [working] full-text search
│   │   ├── api_lookup.js          ← [working] header prototype lookup
│   │   ├── example_lookup.js      ← [working] StarGunner/Windcup grep
│   │   ├── new_project.js         ← [working] scaffold genre template
│   │   ├── lint.js                ← [working] NGPC_Interp.compile via vm
│   │   ├── quickrun.js            ← [working] generator-driven N-frame run
│   │   ├── screenshot.js          ← [working] fake canvas + pngjs PNG
│   │   ├── png_to_sprite.js       ← [working] NGPC_AssetTools.exportSprite + pngjs decode
│   │   ├── png_to_tilemap.js      ← [working] NGPC_AssetTools.exportTilemap
│   │   ├── font_bake.js           ← [stub v0.3]
│   │   ├── disasm.js              ← [working] spawn ngpc_disasm.py
│   │   ├── _transpiler_loader.js  ← shared vm loader for live-editor JS
│   │   ├── _png_decode.js         ← pngjs wrapper
│   │   ├── _emu_bridge.js         ← shared Python-spawn helper
│   │   ├── _emu_bridge.js         ← shared Python-spawn helper
│   │   ├── emu_rom_info.js        ← [working] ROM header + reset state
│   │   ├── emu_peek.js            ← [working] memory bus read
│   │   ├── emu_decode.js          ← [working] single-instruction decode
│   │   └── emu_step_trace.js      ← [working] bounded N-step execution trace
│   ├── resources/
│   │   └── index.js               ← URI → corpus file mapping
│   └── data/
│       ├── bugs_silicon.json      ← curated from hw-validation sessions
│       └── asm_patterns.json      ← canonical hw-safe ASM
├── corpus/                        ← markdown corpus (doc_search source)
│   ├── DENSE_INDEX.md             ← high-density entry point (map + cheat-sheet)
│   ├── wiki/                      ← the NGPC dev wiki (22 pages: hardware, CPU/toolchain, graphics, audio, systems, patterns)
│   └── stargunner/                ← SHMUP + TEMPLATE_RETEX (reference game architecture)
├── vendor/                        ← bundled NgpCraft sub-projects (all MIT — see vendor/*/LICENSE)
│   ├── toolchain/                 ← t900cc / t900as / t900ld / ngpc_romtool (Python) + ngpc.lcf + runtime/crt0.asm
│   ├── emulator/                  ← ngpc_emu.py + core/ + specs/ (headless CPU / bus / decode / run-steps / K2GE inspectors)
│   ├── disasm/                    ← ngpc_disasm.py + MANUAL
│   ├── transpiler/                ← live-editor JS core (interpreter, runtime, vdp, psg, asset tools)
│   ├── templates/                 ← base + cavegen + platformer + racer
│   └── examples/
│       ├── stargunner/            ← full game src + docs (NgpCraft template + APIs)
│       └── windcup_re/            ← a game on the legacy 2000s template (reference for that older API)
└── test/

Scope decisions

What's included

  • The NGPC dev wiki (corpus/wiki/) + a high-density DENSE_INDEX.md — the core knowledge, cleaned and engine-agnostic.
  • Structured knowledge — bugs_silicon.json + asm_patterns.json, hand-curated from hardware-validation sessions.
  • The homemade toolchain (vendor/toolchain/: t900cc / t900as / t900ld / ngpc_romtool) — drives ngpc_compile_homemade, no .exe dependency. ⚠️ Experimental and unstable — a teaching pipeline, not a compiler to build with. It is there so the stages of a TLCS-900 build can be read and understood; expect mis-compiles and unimplemented constructs. For a ROM that must actually run, use ngpc_compile_official.
  • The headless emulator (vendor/emulator/) — drives the ngpc_emu_* tools (ROM parsing, memory bus, decode/execute, bounded run-steps, K2GE inspectors).
  • The disassembler + the live-editor transpiler (lint / quickrun / screenshot / asset converters).
  • Templates (base + 3 genre variants) and reference games (StarGunner on the NgpCraft template; Windcup on the legacy 2000s template).

Intentionally not included

  • Proprietary Toshiba binaries (cc900 / asm900 / tulink / tuconv / s242ngp, system.lib). ngpc_compile_official invokes the user's local install — nothing is bundled or redistributed.
  • Full-game emulation is available via ngpc_emu_native_run (native C++ core). The other ngpc_emu_* tools remain static inspectors by design — they describe a frozen moment, they do not run the machine.
  • ROM binaries — no value for code generation.

Hardware validation claim

Every entry in src/data/bugs_silicon.json cites the validation reference (jalon / bisect / date). These are not speculative — they were reproduced on a real NGPC flash cart during the NgpCraft toolchain development (WIP). The curated set captures findings that would otherwise only live in long-form dev logs.

Timing is calibrated too. Cartridge-flash wait-states were measured on silicon by hw_calibration/cpu_calib_v1.ngc (instruction fetch = 3 cycles/byte, cart data reads = 0) and ngpc_emu_native_run applies them, so a cycle figure from it is comparable to hardware. The one unsettled value, LDIR at 14 cycles/byte, is strongly evidenced but not yet pinned by a calibration ROM — the emulator's hw_calibration/README.md tracks what is proven and what is not.


License

MIT. Vendored snapshots retain their original licenses (see vendor/*/LICENSE).


Part of the NgpCraft SDK

Project Role
NgpCraft Live Editor Browser playground, transpiler, lint
NgpCraft Toolchain Pure-Python cc/as/ld for TLCS-900/H (WIP — not exposed via MCP yet)
NgpCraft Emulator NGPC emulator — Python inspectors (ngpc_emu_*) plus the native C++ core that runs games (ngpc_emu_native_run)
NgpCraft Base Template Starter project + 4 genre variants
NgpCraft Disasm TLCS-900/H disassembler
NgpCraft Learn Bilingual FR/EN course site
NgpCraft MCP ← this project — LLM knowledge + validation layer

About

MCP server giving LLMs hardware-validated NGPC knowledge, API, examples and validation tools

Topics

Resources

Stars

4 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages