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 nonzeroHW_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.binthe emulator renders a plausible but wrong picture. It is also served as the MCP resourcengpc://doc/agent_guide.
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.
cd /path/to/NgpCraft_MCP
npm installAdd 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__*.
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."
| 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'stimingfield.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: truemakes the first one stop the run. See AGENT_GUIDE.md for how to report them.
| 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 |
Exposed via ngpc:// URIs — clients that support MCP resources can read them directly without a tool call.
ngpc://doc/quickstart— orientation for AI agentsngpc://doc/hw_registers— hardware register mapngpc://doc/palettes— RGB444, 16 palettes, transparencyngpc://doc/sprites— 64 sprites, OAM, metaspritesngpc://doc/tilemaps— SCR1/SCR2, scroll, mapstreamngpc://doc/dma— DMA channels and restrictionsngpc://doc/audio— T6W28 PSG, BGM formatngpc://doc/input— joypad register, edge detectngpc://doc/bios— BIOS calls, SYSFONT, power buttonngpc://doc/asm— TLCS-900/H ASM guidengpc://doc/t900_dense_ref— opcode referencengpc://doc/collision— AABB, tilemap collisionngpc://doc/math— Q8.8, LUT, sin_tablengpc://doc/game_loop— VBlank sync, frame budgetngpc://doc/asset_pipeline— PNG → NGPC asset conventionsngpc://doc/storage— flash save, RTCngpc://doc/language— cc900/t900cc C subset + gotchasngpc://doc/build_toolchain— Makefile + linkerngpc://doc/debug_tools— emulator + hw test workflowngpc://roadmap/ngpc— current prioritiesngpc://example/stargunner/shmup_doc— full shmup architecturengpc://example/stargunner/retex— porting post-mortem
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/
- The NGPC dev wiki (
corpus/wiki/) + a high-densityDENSE_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) — drivesngpc_compile_homemade, no.exedependency.⚠️ 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, usengpc_compile_official. - The headless emulator (
vendor/emulator/) — drives thengpc_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).
- Proprietary Toshiba binaries (
cc900/asm900/tulink/tuconv/s242ngp,system.lib).ngpc_compile_officialinvokes the user's local install — nothing is bundled or redistributed. - Full-game emulation is available via
ngpc_emu_native_run(native C++ core). The otherngpc_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.
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.
MIT. Vendored snapshots retain their original licenses (see vendor/*/LICENSE).
| 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 |