内容
# NgpCraft MCP
**NgpCraft 的模型上下文协议服务器，为 NgpCraft 提供硬件验证的知识、API、示例和验证工具，以便编写可运行的 NGPC 自制软件。**
安装一次后，每个 Claude Code / Cursor / Claude Desktop 会话都能够查找真实的 NGPC 硬件事实，检索规范的 ASM 模式，搜索具有特定功能的已验证游戏源码，并搭建新项目 —— 而不是生成半正确的代码，这些代码在硅片上运行会崩溃。
---
## 为什么存在
目前使用 LLM 编写 NGPC 代码时，没有上下文意味着：
* 编译器拒绝的 C99 构造
* 破坏的硅片操作码（D0 前缀，CB 系列）
* 错误的 ABI
* 遗忘 `NGP_FAR` 在 ROM 数据上
* 等等
用户最终需要在真实硬件上调试本应在编写代码之前捕获的问题。
---
## 快速入门
### 安装（本地开发）
```bash
cd /path/to/NgpCraft_MCP
npm install
```
### 配置 Claude Code
将以下内容添加到 `~/.claude/mcp.json`（或适用于您的客户端的等效文件）：
```json
{
"mcpServers": {
"ngpcraft": {
"command": "node",
"args": ["/absolute/path/to/NgpCraft_MCP/src/server.js"]
}
}
}
```
重启您的 MCP 客户端。工具将以 `mcp__ngpcraft__*` 为前缀出现。
### 快速测试
任何以下提示都应该有效：
- *"使用 NGPC 错误检查器查找 D0 前缀。*"
- *"在 NGPC 文档中搜索 DMA VBlank 限制。*"
- *"给我展示 StarGunner 的状态机实现。*"
- *"给我启用 VBlank 中断的规范 ASM。*"
---
## 工具（v0.2）
| 工具 | 状态 | 目的 |
|---|---|---|
| `ngpc_bug_check` | 工作中 | 通过操作码/关键词查询硅片 + 工具链错误数据库 |
| `ngpc_asm_pattern` | 工作中 | 检索硬件安全的 ASM 模式（前奏，LDIRW，DMA 加载等） |
| `ngpc_doc_search` | 工作中 | 在 NGPC 开发维基语料库（wiki/ + DENSE_INDEX + StarGunner 文档）中进行全文搜索 |
| `ngpc_api_lookup` | 工作中 | 从供应商/模板/基准/src/**/*.h 中查找模板函数签名 |
| `ngpc_example` | 工作中 | 按功能关键词搜索 StarGunner + Windcup RE |
| `ngpc_new_project` | 工作中 | 从基准 / cavegen / platformer / racer 模板搭建 |
| `ngpc_lint` | 工作中 | 通过 NGPC_Interp.compile（HW-1/HW-2/HW-3b）进行硬件保真 lint |
| `ngpc_quickrun` | 工作中 | 转译 + 运行 main() 生成器 N 同步滴答，返回状态摘要 |
| `ngpc_screenshot` | 工作中 | 帧缓冲区在帧 N 处的 PNG（假画布 + pngjs） |
| `ngpc_png_to_sprite` | 工作中 | 通过 NGPC_AssetTools.exportSprite 将 PNG 转换为精灵 C/H |
| `ngpc_png_to_tilemap` | 工作中 | 通过 NGPC_AssetTools.exportTilemap 将 PNG 转换为图块地图 C/H |
| `ngpc_font_bake` | 存根（v0.3） | PNG → NGPC 2bpp 字体数据 - 烘焙管道存在于实时编辑器之外 |
| `ngpc_disasm` | 工作中 | 通过 ngpc_disasm.py 桥接反汇编 ROM/字节范围 |
| `ngpc_emu_rom_info` | 工作中 | 通过 NgpCraft 模拟器解析 ROM 头 + 启动重置状态 |
| `ngpc_emu_peek` | 工作中 | 从模拟内存总线读取字节 |
| `ngpc_emu_decode` | 工作中 | 在地址处解码一个 TLCS-900 指令 |
| `ngpc_emu_step_trace` | 工作中 | 从启动地址/地址运行 N 指令，返回跟踪 + CPU 状态 |
| `ngpc_emu_trace_exec` | 工作中 | 每条记录执行跟踪 - CPU 执行前/后，标志更改，指令内存写入（与 step_trace 的压缩结果相比） |
| `ngpc_psg_trace` | 工作中 | 运行代码 N 帧 + 返回 PSG 事件日志（每帧音调/注意力/噪声写入） |
| `ngpc_visual_diff` | 工作中 | 在帧 N 处渲染两个 C 代码片段 + 返回每像素差异 PNG（洋红色在灰色上） |
| `ngpc_validate_project` | 工作中 | 检查目录下的每个 .c 文件，聚合报告（每个文件，每个规则） |
| `ngpc_compile_official` | 工作中（本地工具链） | 通过本地 Toshiba 工具链（cc900 + asm900 + tulink + tuconv + s242ngp）构建项目。返回生成的 ROM。.exe 留在用户的 PC 上 - 永远不会被捆绑或重新分发。 |
依赖后端的转译工具（`ngpc_lint` / `ngpc_quickrun` / `ngpc_screenshot` / `ngpc_png_to_*`）通过 `src/tools/_transpiler_loader.js` 将实时编辑器 JS 模块加载到 Node `vm` 上下文中 - 没有浏览器，没有 DOM。音频（PSG）故意不初始化：语音寄存器状态保留但不创建 WebAudio 上下文。
对于 `ngpc_screenshot`，假的 CanvasRenderingContext2D 捕获帧缓冲区；PNG 编码通过 `pngjs` 进行。
对于 `ngpc_png_to_sprite` / `ngpc_png_to_tilemap`，PNG 解码通过 `pngjs` 进行（替换浏览器独有的 `URL.createObjectURL` + `Image` 路径，在 `asset_tools.decodePng` 中使用）。
`ngpc_emu_*` 工具启动 `python vendor/emulator/ngpc_emu.py <cmd> --json`（主机上需要 Python 3）。它们只公开模拟器的可靠部分（ROM 解析，内存总线读取，单指令解码/执行，有界运行步骤）。按照模拟器的 `FEATURE_MATRIX.md` 策略（“标记为支持的功能必须在 NGPC 上真正可利用”），不公开全游戏模拟工具 - VDP/PSG/IRQ/时序尚未实现。
---
## 资源
通过 `ngpc://` URI 公开 - 支持 MCP 资源的客户端可以直接读取它们，无需工具调用。
- `ngpc://doc/quickstart` - 面向 AI 代理的指南
- `ngpc://doc/hw_registers` - 硬件寄存器映射
- `ngpc://doc/palettes` - RGB444，16 个调色板，透明度
- `ngpc://doc/sprites` - 64 个精灵，OAM，元精灵
- `ngpc://doc/tilemaps` - SCR1/SCR2，滚动，地图流
- `ngpc://doc/dma` - DMA 通道和限制
- `ngpc://doc/audio` - T6W28 PSG，BGM 格式
- `ngpc://doc/input` - 方向键寄存器，边缘检测
- `ngpc://doc/bios` - BIOS 调用，SYSFONT，电源按钮
- `ngpc://doc/asm` - TLCS-900/H ASM 指南
- `ngpc://doc/t900_dense_ref` - 操作码参考
- `ngpc://doc/collision` - AABB，图块碰撞
- `ngpc://doc/math` - Q8.8，LUT，sin_table
- `ngpc://doc/game_loop` - VBlank 同步，帧预算
- `ngpc://doc/asset_pipeline` - PNG → NGPC 资产约定
- `ngpc://doc/storage` - 闪存保存，RTC
- `ngpc://doc/language` - cc900/t900cc C 子集 + 易错点
- `ngpc://doc/build_toolchain` - Makefile + 链接器
- `ngpc://doc/debug_tools` - 模拟器 + 硬件测试工作流
- `ngpc://roadmap/ngpc` - 当前优先级
- `ngpc://example/stargunner/shmup_doc` - 完整的 shmup 架构
- `ngpc://example/stargunner/retex` - 移植事后分析
---
## 仓库布局
```
NgpCraft_MCP/
├── package.json
├── README.md ← 你在这里
├── src/
│ ├── server.js ← MCP stdio 入口
│ ├── tools/ ← 每个工具一个文件
│ │ ├── index.js ← 注册表
│ │ ├── bug_check.js ← [工作中] 硅片错误数据库查询
│ │ ├── asm_pattern.js ← [工作中] 规范的 ASM 模式
│ │ ├── doc_search.js ← [工作中] 全文搜索
│ │ ├── api_lookup.js ← [工作中] 头文件原型查找
│ │ ├── example_lookup.js ← [工作中] StarGunner/Windcup grep
│ │ ├── new_project.js ← [工作中] 搭建模板
│ │ ├── lint.js ← [工作中] 通过 vm 进行 NGPC_Interp.compile
│ │ ├── quickrun.js ← [工作中] 生成器驱动的 N 帧运行
│ │ ├── screenshot.js ← [工作中] 假画布 + pngjs PNG
│ │ ├── png_to_sprite.js ← [工作中] NGPC_AssetTools.exportSprite + pngjs 解码
│ │ ├── png_to_tilemap.js ← [工作中] NGPC_AssetTools.exportTilemap
│ │ ├── font_bake.js ← [存根 v0.3]
│ │ ├── disasm.js ← [工作中] 启动 ngpc_disasm.py
│ │ ├── _transpiler_loader.js ← 实时编辑器 JS 的共享 vm 加载器
│ │ ├── _png_decode.js ← pngjs 包装器
│ │ ├── _emu_bridge.js ← 共享 Python 启动辅助程序
│ │ ├── _emu_bridge.js ← 共享 Python 启动辅助程序
│ │ ├── emu_rom_info.js ← [工作中] ROM 头 + 重置状态
│ │ ├── emu_peek.js ← [工作中] 内存总线读取
│ │ ├── emu_decode.js ← [工作中] 单指令解码
│ │ └── emu_step_trace.js ← [工作中] 有界 N 步执行跟踪
│ ├── resources/
│ │ └── index.js ← URI → 语料库文件映射
│ └── data/
│ ├── bugs_silicon.json ← 从硬件验证会话中精选
│ └── asm_patterns.json ← 规范的硬件安全 ASM
├── corpus/ ← 标记语料库（doc_search 源）
│ ├── DENSE_INDEX.md ← 高密度入口（地图 + 秘籍）
│ ├── wiki/ ← NGPC 开发维基（22 页：硬件，CPU/工具链，图形，音频，系统，模式）
│ └── stargunner/ ← SHMUP + TEMPLATE_RETEX（参考游戏架构）
├── vendor/ ← 捆绑的 NgpCraft 子项目（所有 MIT - 见 vendor/*/LICENSE）
│ ├── toolchain/ ← t900cc / t900as / t900ld / ngpc_romtool（Python）+ ngpc.lcf + runtime/crt0.asm
│ ├── emulator/ ← ngpc_emu.py + core/ + specs/（无头 CPU / 总线 / 解码 / 运行步骤 / K2GE 检查器）
│ ├── disasm/ ← ngpc_disasm.py + MANUAL
│ ├── transpiler/ ← 实时编辑器 JS 核心（解释器，运行时，vdp，psg，资产工具）
│ ├── templates/ ← 基准 + 3 种类型变体
│ └── examples/
│ ├── stargunner/ ← 完整的游戏源码 + 文档（NgpCraft 模板 + API）
│ └── windcup_re/ ← 旧 2000 模板上的游戏（旧 API 的参考）
└── test/
```
---
## 范围决策
### 已包含
- **NGPC 开发维基** (`corpus/wiki/`) + 高密度 `DENSE_INDEX.md` - 核心知识，已清理且与引擎无关。
- **结构化知识** - `bugs_silicon.json` + `asm_patterns.json`，从硬件验证会话中精选。
- **自制工具链** (`vendor/toolchain/`：t900cc / t900as / t900ld / ngpc_romtool) - 驱动 `ngpc_compile_homemade`，无 `.exe` 依赖。
- **无头模拟器** (`vendor/emulator/`) - 驱动 `ngpc_emu_*` 工具（ROM 解析，内存总线，解码/执行，有界运行步骤，K2GE 检查器）。
- **反汇编器** + **实时编辑器转译器**（lint / quickrun / screenshot / 资产转换器）。
- **模板**（基准 + 3 种类型变体）和**参考游戏**（StarGunner 使用 NgpCraft 模板；Windcup 使用旧 2000 模板）。
### 故意不包含
- **东芝专有二进制文件** (`cc900` / `asm900` / `tulink` / `tuconv` / `s242ngp`，`system.lib`)。`ngpc_compile_official` 调用用户的本地安装 - 不会捆绑或重新分发任何内容。
- **完整游戏（帧精度）模拟** - `ngpc_emu_*` 工具公开可靠的无头子集；VDP/PSG/IRQ/时序帧循环仍在开发中。
- **ROM 二进制文件** - 对代码生成没有价值。
---
## 硬件验证声明
`src/data/bugs_silicon.json` 中的每个条目都引用验证参考（jalon / bisect / date）。这些不是推测性的 - 它们是在 NgpCraft 工具链开发过程中在真正的 NGPC 闪存卡上重现的。精选集捕获了原本只存在于长篇开发日志中的发现。
---
## 许可证
MIT。供应商快照保留其原始许可证（参见 `vendor/*/LICENSE`）。
---
## NgpCraft SDK 的一部分
| 项目 | 角色 |
|---|---|
| **NgpCraft 实时编辑器** | 浏览器游乐场，转译器，lint |
| **NgpCraft 工具链** | TLCS-900/H 的纯 Python cc/as/ld（WIP - 尚未通过 MCP 暴露） |
| **NgpCraft 模拟器** | Python NGPC 模拟器（WIP - 通过 `ngpc_emu_*` 工具暴露可靠的部分） |
| **NgpCraft 基准模板** | 启动项目 + 4 种类型变体 |
| **NgpCraft 反汇编器** | TLCS-900/H 反汇编器 |
| **NgpCraft 学习** | 双语 FR/EN 课程网站 |
| **NgpCraft MCP** | ← 本项目 - LLM 知识 + 验证层 |
