RPG Maker MV Copilot MCP 是一个 Model Context Protocol 服务器，使 AI 智能体能够检查并编辑磁盘上真实的 RPG Maker MV 项目，通过 18 个整合工具完成地图生成、数据库与事件编辑、断链引用查找以及可重复的试玩。它主要解决通常缺失的三件事：离线项目智能分析、语义化地图生成，以及与实际引擎联动的实时桥接调试。
用途：面向 RPG Maker MV 开发者，帮助 AI 智能体定位事件为何不触发、验证修复效果、构建事件逻辑，并在真实引擎中试玩。适用于 Claude Desktop、Claude Code、opencode 及任何 MCP 兼容客户端。
主要能力：
- 地图生成：通过 generate_map 提供两条路径。知识驱动路径对 town、village、dungeon、interior、castle、world 等有匹配模板的主题克隆真实地图，无模板主题（beach、swamp、desert 等）回退到 Perlin 地形、BSP 地牢和细胞洞穴；战斗主题自动从既有敌群装配随机遭遇，城镇与村庄自动创建可进入房屋内部及双向传送。还支持 blank、themed、template、batch、duplicate 等模式。与图块集无关的语义路径先挖掘现有地图的语义布局与图块集配置，再以“入口→钥匙→锁门→宝藏→Boss→出口”的图结构生成，从构造上保证可解。
- 实时桥接：提供 Telemetry（异常堆栈、console.error/warn、场景切换、玩家位置、正在执行的事件指令、FPS 与堆内存）、Hot reload（reload_map 重读当前地图并重建场景且不丢失队伍状态；reload_database 重读单个数据文件，System.json 与 Tilesets.json 需重新试玩并被拒绝）、Screenshots（take_screenshot 保存带时间戳 PNG 到 .mcp-cache/screenshots/）、Video evidence（record_video 录制游戏画布的静默 WebM）。
- 项目智能：analyze_project 为只读且完全离线，可发现断链传送、缺失地图文件、悬空公共事件/物品/敌群引用、重复 ID、命名但未用的开关与变量、错误起始位置、不可达地图，以及对话中写入的 \N[id] 不解析。还提供可达性洪水填充、死空间、形状骨架图分析、多样性（5×5 图块窗口的香农熵）、张力分析，以及对技能、武器、防具、敌人的平衡性离一法比较（伤害公式只解析不执行）。
- 离线地图检查：query_map 支持 ascii 视图渲染字符网格与事件标记，validate 视图检查无效图块 ID、断链传送和缺失事件终止符。
使用方式：需安装 Node.js 20.19.0 或更新版本，编辑项目文件前关闭 MV 编辑器，先在项目副本上操作。无需克隆，包内附可执行文件，将其添加到 MCP 客户端；通过 RPGMAKER_PROJECT_PATH 指向包含 data/、js/ 和 index.html 的文件夹，也可运行时调用 set_project_path。添加或升级服务器后需重启客户端，因为 MCP 客户端只在启动时加载工具定义。Codex CLI 可使用 codex mcp add rpgmaker --env RPGMAKER_PROJECT_PATH=C:/path/to/project -- npx -y rpgmaker-mv-mcp；无法启动 npx 的 Windows 客户端可用 cmd 配合参数 ["/c", "npx", "-y", "rpgmaker-mv-mcp"]。
适用场景：调试事件不触发、验证地图可解性、批量生成带任务的关卡、项目引用完整性检查、数值平衡审查、语义搜索项目内容，以及需要可重复证据的 QA 试玩。
限制：桥接仅支持 Windows/NW.js 试玩，且需在项目中安装插件；语义模式当前生成地牢形状任务，城镇与开放世界任务语法仍在计划中；装饰语义在 RTP 模板路径下为尽力而为，罕见多图块对象可能落为单图块；城镇与地牢布局仍在改进；balance 在同类间比较，Boss 相对随机遭遇会表现为离群值，应读取标记而非结论；视觉 AI 需自备 OpenAI 兼容端点，不配置则不上传任何内容；服务器仅绑定 127.0.0.1，拒绝带浏览器 Origin 的升级请求，要求 5 秒内提供会话令牌；命令面为固定白名单，无任意脚本或 eval 命令；写入为原子操作、带时间戳备份于 .mcp-backups/（默认保留 10 个，由 RPGMV_BACKUP_KEEP 控制），支持 dryRun 预览；编辑器不遵守 MCP 锁，多文件操作不是事务。已部署的玩家双击构建不会触达 socket 代码。MIT 许可，专为 RPG Maker MV 构建。
