# game-narrative-mcp

**v0.3.1** — 通用游戏叙事引擎 MCP：一致性校验、动态 Run、Meta 伏笔、工作区自发现、Playthrough 对比、角色弧光、Ludo-narrative 检查、Ink/Yarn 导出。

> MCP 是「叙事秘书」，不替代游戏运行时。程序与叙事数据分离，支持双工作区布局。

## 快速开始

```bash
git clone <your-repo-url> game-narrative-mcp
cd game-narrative-mcp
npm install
npm run build
npm run setup:cursor   # 生成本机 .cursor/mcp.json
```

1. 用 Cursor **打开本仓库**
2. **Settings → MCP** → 刷新，确认 `game-narrative` 已连接
3. 零基础图文见 **[配置向导](docs/setup-wizard.md)**（含游戏总仓口述模板）

**验收**：在对话中说「请调用 list_projects 和 validate_project 验收 _example」。

## CLI

```bash
npx game-narrative-mcp validate --project _example
npx game-narrative-mcp export --project _example --adapter game-json-v1
npx game-narrative-mcp export --project _example --adapter ink-v1
npx game-narrative-mcp simulate --project _example --runs 5
```

## 文档

| 文档 | 说明 |
|------|------|
| **[配置向导](docs/setup-wizard.md)** | **零基础：一键配 MCP + 游戏仓口述模板** |
| [快速开始](docs/getting-started.md) | 安装、验收 |
| [架构说明](docs/architecture.md) | 三层架构、环境变量 |
| [双工作区布局](docs/workspace-setup.md) | MCP 仓 vs 游戏仓 |
| [工作区引导](docs/workspace-bootstrap.md) | 自发现 + Cursor 模板 |
| [Cursor 配置](docs/cursor-config.md) | mcp.json 详解 |
| [数据模型](docs/data-schema.md) | YAML 字段单一事实来源 |
| [工具参考](docs/tools-reference.md) | 全部 tools + resources |
| [一致性检查](docs/consistency.md) | canon vs knowledge |
| [Run 引擎](docs/run-engine.md) | dynamic vs fixed_depth |
| [节奏板](docs/pacing.md) | Beat Sheet 与分析 |
| [内容控制](docs/content-control.md) | Project Bible |
| [场景清单](docs/scene-registry.md) | Scene Registry |
| [时间线](docs/timeline.md) | 因果检查 |
| [体量估算](docs/volume-estimation.md) | 字数/VO/key |
| [结局向量](docs/ending-vectors.md) | 多结局空间 |
| [Meta 叙事](docs/meta-narrative.md) | 跨局伏笔 |
| [伏笔生命周期](docs/foreshadowing.md) | thread phase 状态机 |
| [写作辅助](docs/writing-assist.md) | 治「写不出来」 |
| [Rog walkthrough](docs/workflow-rog-meta.md) | 动态 Rog 全流程 |
| [固定层 walkthrough](docs/workflow-fixed-depth.md) | 固定层 AVG |
| [与 AI 协作](docs/ai-collaboration.md) | 对话模板 |
| [导出适配器](docs/export-adapters.md) | game-json / Ink / Yarn |
| [Playthrough 差异](docs/playthrough-diff.md) | 多结局对比 |
| [角色弧光](docs/character-arcs.md) | 情感曲线 |
| [Ludo-narrative](docs/ludo-narrative.md) | 玩法-叙事冲突 |
| [能力预设](docs/capabilities.md) | capabilities 对照 |
| [分支图](docs/branching.md) | 强分支 AVG |
| [本地化](docs/localization.md) | 文本约束 |
| [发布指南](docs/publishing.md) | 发布检查清单 |
| [版本升级](docs/upgrading.md) | 兼容性 |

## 示例

- [`projects/_example/`](projects/_example/) — 迷你 Rog + Meta 线程 + 2 结局
- [`projects/_example_fixed_depth/`](projects/_example_fixed_depth/) — 固定层 AVG

## 开发

```bash
npm run build
npm test
```

详见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## License

[MIT](LICENSE)