RPG-Maker-MZ---MCP-Ultimate

# RPG Maker MZ - MCP Ultimate > 服务器模型上下文协议（MCP），可对 **RPG Maker MZ** 项目实现完全控制，并与 AI 代理交互。 **版本：** 1.0.0 **作者：** 牛顿·阿尔维斯 **产品：** RPG Maker MZ - MCP Ultimate **许可证：** MIT --- ## 目录 - [概述](#概述) - [先决条件](#先决条件) - [安装](#安装) - [配置](#配置) - [使用方式](#使用方式) - [项目内存](#项目内存) - [语义分析](#语义分析) - [了解工具目录](#了解工具目录) - [它能做什么](#它能做什么) - [命令示例](#命令示例) - [架构](#架构) - [安全性和原子性](#安全性和原子性) - [多个实例同时运行](#多个实例同时运行) - [测试](#测试) - [项目结构](#项目结构) - [问题解决](#问题解决) - [已知限制](#已知限制) - [路线图](#路线图) - [贡献](#贡献) - [致谢](#致谢) --- ## 概述 `rpg-maker-mz-mcp` 是一个用 TypeScript 编写的 MCP 服务器，提供 **193 个工具**，分为 28 个类别，允许 AI 代理通过自然语言命令创建、编辑和检查任何 RPG Maker MZ 项目的方面。 架构是 **混合型** 的： - **编辑模式（游戏关闭）：** 服务器直接读写项目 JSON 文件（`data/`）、JavaScript 插件（`js/plugins/`）和资源（`img/`、`audio/`），具有原子性保证、自动备份和与 MZ 编辑器打开的冲突检测。 - **运行时模式（游戏运行中）：** 一个伴侣插件（`MzMcpCompanion.js`）安装在项目中，打开一个本地 WebSocket 连接，允许代理在游戏运行时查询和修改游戏状态（HP、开关、变量、玩家位置、活动场景、可见窗口、战斗进行中等等）。 --- ## 先决条件 | 需求 | 最低版本 | 备注 | |---|---|---| | Node.js | 18.0.0+ | 推荐 20.x 或 22.x | | RPG Maker MZ | 任意 | 使用产品所需 | | MCP 客户端 | 任意 | 与任何实现 MCP 协议（stdio 服务器）的客户端兼容 | | 操作系统 | Windows、macOS、Linux | 通过 Steam 自动检测 MZ 安装 | ### 可选外部依赖 一些工具依赖于不包含在此 MCP 中的外部程序。您只需在需要使用相关工具时安装。 | 外部程序 | 依赖工具 | 没有它 | |---|---|---| | **rpgmpacker** ([github.com/erri120/rpgmpacker](https://github.com/erri120/rpgmpacker)) | `mz_build` | 仅禁用跨平台构建。其他 192 个工具正常工作。如果尝试使用，工具会返回清晰的消息并提供下载链接。 | **重要：** 如果您从 GitHub 克隆此 MCP 并将其安装在另一台计算机上，**不需要自动安装 `rpgmpacker`** - 仅当您想为分发（Windows、Mac、Web、Android）打包游戏时需要。创建地图、角色、插件、事件编辑等，无需外部依赖。 要随时检查其可用性，请询问代理：*“检查 rpgmpacker 是否可用”*（调用 `mz_build_check_rpgmpacker`）。 --- ## 安装 ### 克隆仓库 ```bash git clone <仓库 URL> cd rpg-maker-mz-mcp npm install npm run build ``` ### 构建后结构 运行 `npm run build` 后，`dist/` 文件夹包含编译后的服务器。入口点是 `dist/index.js`。 --- ## 配置 ### 1. 环境变量 | 变量 | 必需 | 描述 | |---|---|---| | `MZ_PROJECT_PATH` | 是 | RPG Maker MZ 项目文件夹的绝对路径 | | `MZ_INSTALL_PATH` | 否 | RPG Maker MZ 安装路径（如果省略，则自动检测） | | `MZ_MCP_CONFIG` | 否 | `mz-mcp.config.json` 文件路径（默认：`<project>/mz-mcp.config.json`） | | `MZ_MCP_LOG_LEVEL` | 否 | `debug`、`info`、`warn`、`error`（默认：`info`） | ### 2. 配置文件（可选） 在 MZ 项目根目录下创建 `mz-mcp.config.json`: ```json { "project": { "path": "auto", "autoBackup": true, "backupRetention": 20, "backupDir": ".mz-mcp/backups" }, "editor": { "onLock": "warn" }, "mz": { "installPath": "auto", "corescriptVersion": "v1.6.0" }, "runtime": { "enableEvalJs": false, "companionPort": 0, "tokenFile": ".mz-mcp/companion.token" }, "plugins": { "defaultNamingConvention": "snake", "knownBases": {} }, "logging": { "level": "info" } } ``` ### 3. MCP 客户端配置 编辑 MCP 客户端的 `mcp.json` 文件（以下是一个示例）： ```json { "mcpServers": { "rpg-maker-mz-mcp": { "command": "node", "args": ["C:\\完整路径\\dist\\index.js"], "env": { "MZ_PROJECT_PATH": "C:\\您的项目路径\\MZ" } } } } ``` 配置后重启 MCP 客户端。 --- ## 使用方式 ### 基本流程（编辑模式） 1. 在客户端配置 MCP 服务器（上一项）。 2. 重启客户端。 3. 向代理发出自然语言请求： - *“创建一个名为 Marina 的角色，职业为 Mage，等级为 5。”* - *“在地图 5 的 NPC 中添加一个对话框。”* - *“生成一个 40x30 的程序化迷宫，带有 A2 自动贴图。”* 4. 打开 RPG Maker MZ - 更改将显示在那里。 ### 运行时流程（游戏运行中） 1. 请求代理：*“在我的项目中安装伴侣。”* 2. 打开 RPG Maker MZ 并启动 **Playtest**。 3. 在游戏过程中发出请求： - *“Marina 现在的 HP 多少？”* - *“激活开关 5。”* - *“将玩家转移到地图 10，位置（5，5）。”* - *“当前场景是什么？有任何活动窗口吗？”*（结构化查询，无 `eval_js`） - *“截取屏幕截图。”*（图像作为原生内容，不为 base64 文本） --- ## 项目内存 每个代理会话通常从零开始 - 不会记住设计决策、约定、故事、平衡规则或昨天由另一个 Claude 完成的操作。**持久内存系统** 解决了这个问题：代理可以 **记录事实**，这些事实存储在 `.mz-mcp/memory/` 中，并在任何未来的会话中读回。 ### 类别 | 类别 | 用途 | |---|---| | `design_decisions` | 有意的设计决策（例如：“Reid 故意开始时很弱”） | | `conventions` | 项目模式（命名、组织、样式） | | `lore` | 游戏世界事实 | | `balance_rules` | 平衡规则（例如：“BOSS 提供 5 倍于普通小怪的 XP”） | | `wip_notes` | 进行中的工作笔记 | | `agent_handoff` | 留给下一个代理继续的消息 | | `custom` | 不适合其他类别的所有内容 | ### 工具 - `project_memory_remember(category, key, content, tags?)` - 记录或更新 - `project_memory_recall(category?, search?, tags?)` - 按筛选器检索 - `project_memory_list(category?)` - 列出元数据（无内容） - `project_memory_forget(key)` - 删除条目 - `project_memory_categories()` - 按类别概览计数 ### 存储 ``` .mz-mcp/memory/ ├── index.json # 所有条目的元数据 └── entries/ └── <sha1-of-key>.md # 免费内容（Markdown） ``` 原子写入（tmp + 重命名），多代理安全（在每次修改前重新读取索引），如果您愿意，可以通过 git 版本控制。 --- ## 语义分析 工具 `analysis_*` 运行项目扫描并返回 **结构化报告**。每个分析都基于 `data/` 的 mtime 缓存 - 如果没有更改，则重新运行是瞬间的。 | 工具 | 回答 | |---|---| | `analysis_npc_dialogue_map` | 显示文本（Show Text 101/401）的所有 NPC，按地图分组，并预览。识别空地图。 | | `analysis_switch_variable_graph` | 使用图：谁设置和谁读取每个开关/变量。识别 **死亡**（已注册但从未使用）和 **孤儿**（已读取但从未设置 - 可能有 bug）。 | | `analysis_item_economy` | 对于每个物品/武器/盔甲：敌人掉落、商店、事件宝藏。识别 **无法获得** 的物品（无来源）。 | | `analysis_skill_distribution` | 对于每个技能：谁学习（通过学习 + 状态添加技能），等级，成本，公式中使用的主状态。识别 **无法访问** 的技能。 | | `analysis_enemy_appearances` | 对于每个敌人：在哪些小队中，哪些小队被调用在地图事件或随机遭遇中。识别 **无法访问** 的敌人。 | | `analysis_tileset_usage` | 对于每个 tileset：哪些地图使用，尺寸如何。识别 **未使用** 的 tileset。 | | `analysis_map_flow` | 基于传输玩家命令（代码 201）的地图流程有向图。识别 **孤儿**（无入口）**死胡同**（无出口）和 **无法到达**（通过 BFS 从起始地图无法到达）的地图。 | 每个调用都接受 `force: true` 以忽略缓存。 ### 现实示例 > *"我的游戏中玩家无法获得哪些物品？”* ``` analysis_item_economy → 返回 unreachableCount + 列表 ``` > *"我创建了哪些开关但从未使用？”* ``` analysis_switch_variable_graph → switches.dead[] ``` > *"谁在游戏中谈论火山？”* ``` analysis_npc_dialogue_map → 在每个地图的预览中搜索“火”或“火山” ``` > *"这个新地图是否与游戏其他部分相连？废弃的旧地图呢？”* ``` analysis_map_flow → nodes.unreachable + nodes.orphan + 边缘图 ``` --- ## 了解工具目录 MCP 将其工具组织成两个互相补充的 **类别**： ### 通用工具（CRUD） **CRUD** 是一个编程术语：**C**reate（创建），**R**ead（读取），**U**pdate（更新），**D**elete（删除）- 任何数据库的基本操作。 与其为每个组合创建单独的工具（创建演员，读取演员，更新演员，创建物品，读取物品，更新物品...），MCP 有 **6 个通用工具**，它们接受一个 `category` 参数来指示数据类型。 | 工具 | 功能 | 示例 | |---|---|---| | `db_list` | 列出某一类别的所有记录 | `db_list(category: "actor")` 列出角色 | | `db_get` | 按 ID 读取特定记录 | `db_get(category: "skill", id: 5)` | | `db_create` | 创建新记录 | `db_create(category: "item", data: {...})` | | `db_update` | 更新现有记录的字段 | `db_update(category: "item", id: 1, patch: { price: 100 })` | | `db_delete` | 删除记录（带有自动快照） | `db_delete(category: "enemy", id: 7)` | | `db_search` | 在 name/note/description 中搜索子字符串 | `db_search(category: "skill", query: "火")` | 支持的类别：`actor`、`class`、`skill`、`item`、`weapon`、`armor`、`enemy`、`troop`、`state`、`animation`、`tileset`、`common_event`。 **优势：** 6 个工具涵盖 12 个不同类别 - 极其灵活。 **缺点：** 要从头开始，您需要提供带有所有必需字段的完整 JSON 对象。 ### 专用工具（帮助器） 它们是具有 **合理默认值** 的快捷方式，适用于常见用例。通常，代理更喜欢这些，因为它们需要的参数要少得多： | 帮助器 | 功能 | |---|---| | `actor_create(name, classId, level)` | 创建具有默认精灵和面部、空装备的角色 | | `skill_create_damage(name, formula, mpCost, elementId)` | 创建具有 `type=1`、`scope=1`（1 个敌人）、`hitType=1`（物理）的伤害技能 | | `skill_create_damage(name, formulaPreset)` | 相同，但使用预设（例如 `"physical_basic"`、`"magical_high"`、`"drain_hp"`） | | `skill_create_healing(name, formula)` | 创建具有 `type=3`、`scope=7`（1 个盟友）的治疗技能 | | `enemy_create_balanced(level, role)` | 创建具有根据等级和角色自动计算的统计数据的敌人（`tank`、`mage`、`glass_cannon`、`boss`等） | **优势：** 更简单 - 您只需提供必要的内容。 **缺点：** 仅限于预期的情况。对于自定义，请使用通用 CRUD。 ### 实际比较 创建名为“火球”的技能: **使用通用 CRUD：** ``` db_create(category: "skill", data: { name: "火球", description: "造成火伤害", iconIndex: 64, stypeId: 1, mpCost: 8, scope: 1, occasion: 1, hitType: 1, damage: { type: 1, elementId: 2, formula: "a.mat * 3", variance: 20, critical: false }, effects: [], traits: [], message1: "", message2: "", messageType: 1, successRate: 100, repeats: 1, speed: 0, tpGain: 0, tpCost: 0, requiredWtypeId1: 0, requiredWtypeId2: 0, animationId: 0, note: "" }) ``` **使用专用帮助器：** ``` skill_create_damage( name: "火球", formula: "a.mat * 3", mpCost: 8, elementId: 2 ) ``` 结果相同。代理根据具体请求选择最合适的路径。 --- ## 它能做什么 ### 完整数据库 适用于 MZ 所有数据类型的通用 CRUD 和专用帮助器: - **角色**（角色）：创建具有职业、等级、精灵、面部、装备 - **职业**：定义、EXP 曲线、学习技能、特征 - **技能**：伤害公式、成本、效果、特征 - **物品、武器、盔甲**：统计数据、价格、效果、特征 - **敌人**：根据等级和角色（坦克、法师、炮塔、BOSS 等）平衡统计数据 - **敌人小组（Troops）**：成员、布局、战斗事件 - **状态、动画、图块集、公共事件、系统** ### 地图和事件 - 创建地图，按坐标或矩形编辑图块 - 程序化生成（BSP 迷宫、细胞自动机洞穴、户外） - 具有 8 个命令模板的事件：对话、选择、条件、传输、战斗、声音、成员更改、商店 - MZ 的 ~117 个事件命令的完全支持，通过通用工具 - **视觉地图渲染** (`map_render`) - 将图块 + 图块图像组成 PNG；作为本机图像内容返回给代理商，无需打开编辑器 - **文本搜索/替换** (`text_replace_all`) - 一次重命名/更正项目中的所有对话（干运行 + 快照） ### 完整性检查（4 个支柱） - `db_check_consistency` - **交叉 ID**：检查数据库中的错误（例如，角色 ID 不存在，技能指向已删除的状态，武器 ID/ETypd 超出范围，敌人动作的技能 ID 无效，部队成员的敌人 ID 不存在，职业的学习技能已删除）。几秒钟内进行 500 多项检查，按严重程度排序。 - `asset_check_missing_references` - **资源文件**：检测引用的图像/音频是否不存在（`missing`）或存在但大小/大小写不匹配（`case_mismatch` - 在 Web/ Linux 导出时中断）。通过 `effects/*.efkefc` 动画。 - `event_validate_structure` - **事件结构**：命令列表格式错误，阻止解释器运行（无终止符、无效缩进、未关闭的块）。仅使用已证明的 MZ 不变量 - 零误报。 - `event_check_references` - **事件内容**：传输到不存在的地图，调用不存在的公共事件/小队，开关/变量超出范围，`\V[n]`/`\N[n]` 转义代码指向无效数据。 ### JavaScript 插件 - 安装现成插件（本地文件或捆绑的 DLC） - 从零开始编写插件，带有规范元数据（验证的 JSDoc） - 使用 AST 解析器（acorn）验证语法 - 检查兼容性（VisuStella、Galv、SRDude 套件与 MZ 的冲突等） ### 资源 - 导入图像，严格验证格式（按类别的官方尺寸） - 导入音频（BGM、BGS、ME、SE） - 使用 MZ 角色生成器的零件合成角色精灵（使用 jimp 进行渲染） - 启发式清理未引用的资源 ### 构建、翻译、保存 - 通过 `rpgmpacker` 封装器进行跨平台打包（Windows、Mac、Web、移动） - 可翻译字符串的提取和导入（与 Translator++ 兼容的格式） - 编辑 `.rmmzsave` 文件（LZ-string + JSON），带有语义帮助器（金币、物品、等级、技能、位置） ### 知识蒸馏 MZ 中隐藏的 JSON 目录： - 事件命令（所有 ~117 个代码，名称、类别、参数） - 效果代码（回复 HP、添加状态、学习技能等） - 特性代码（参数率、元素率、X 参数率等） - 图块集标志（通行、立式标签、梯子、灌木、柜台） - 已知 Notetag（VisuStella、Galv、SRDude 等） - 伤害公式预设（物理基础、魔法高、吸血等） 运行时（配合 当游戏在运行 `MzMcpCompanion.js： - **：** 玩家状态、地图、开关、系统 - **结构（替代 `eval_js` 安全的替代方案）：** runtime_get_scene_state 当前 Scene_* 名称属性（mapId、playerXY、troopId 等） - `runtime_get_window_state` — 可见窗口列表，包含类型、位置、选中索引 - `runtime_get_battle_state` — 阶段、回合、活动主体、队伍/怪物存活状态，HP/MP - `runtime_get_message_state`本、面、选择项（如果有活动消息） runtime_inspect的读取任意属性 `$gameParty._goldgameActors._data[1]._level`） `runtime_simulate_b — 模拟完整的离（克隆队伍 +，自动攻击，调用的 `Game_Action.makeDamageValue`）。遵循自定义插件Stella、Yanfly、自定义系统）。返回日志 + 胜利者 + 总伤害。不影响实际游戏玩法。 - **操作：** 设置开关/变量，角色 HP/MP，转移，强制战斗，共同事件，热重载 - **截图：** 通过 PIXI extract 捕获，固定大小（816×624），避免因插件添加精灵导致内存溢出。返回原生图片内容（Claude 可视化）。 - **推送事件（11 种）：** 伴侣通知更改 — mapChanged、battleStarted、battleEnded、levelUp、switchChanged、variableChanged、goldChanged、itemChanged、partyMemberAdded、partyMemberRemoved、commonEventStarted - **任意 JavaScript 执行**（需配置开启，用于高级调试） --- ## 命令示例 ### 内容创建 > 创建 3 个 12-15 级的冰属性敌人，掉落回复药水。 结果：3 次 `enemy_create_balanced` + `db_update` 更新掉落 + `troop_create` 分组。 ### 地图编辑 > 在地图 5 的 NPC 上添加 "你好，旅行者！" 的对话，如果开关 7 已激活，则显示 "你回来了！"。 结果：`map_event_search` + `event_template_dialogue` + `event_page_add` 带条件 + 第二个 `event_template_dialogue` 在新页面。 ### 可视化 > 展示地图 39 当前的样子（城市 1）。 结果：`map_render(id: — 代理接收图像并描述布局，识别空区域，建议改进。 ### 审计 > 在构建前检查数据库中是否有交叉引用问题。 结果：`db_check_consistency 报告所有损坏的引用（技能指向已删除的状态，特性具有无效 ID 等），按严重性排序。 ### 插件创作 > 创建一个名为 StaminaBar 的插件，添加一个带有 maxStamina 参数（默认为 100）的耐力条和 setStamina 命令。 结果：`plugin_create_new` 带有生成的元数据，结构化 JS 代码，语法验证和 `plugins.js` 中的注册。 ### 构建和部署 > 为 Windows 和 Web 构建，加密音频。 结果：`mz_validate_project` + `mz_build(platforms=["windows","web"], encryptAudio=true)`。 ### 运行时模式 > 当前游戏场景是什么？有任何选定的窗口吗？ 结果：`runtime_get_scene_state` + `runtime_get_window_state`（无需 `eval_js`）。 > Marina 当前的 HP 是多少？将其设置为 1，我想测试低 HP 动画。 结果：`runtime_get_actor_state` + `runtime_set_actor_hp(actorId=marinaId, value=1)`。 > 截取一个截图给我看结果：`runtime_s — Claude 接收图像并描述所见内容。 --- ## 架构 ``` MCP 客户端 | | MCP 协议（stdio） v rpg-maker-mz-mcp（TypeScript） | | 工具（193，别） | Zod 模式 | SafeWriter + 自动备份 + 版本 ID 增量 | +-- 读取/写入文件 --> RPG Maker MZ 项目 | （data/，js/，img/，audio/） | +-- WebSocket --> McpCompanion.js （在游戏 playtest 中） ``` 所有写入操作都是原子的（`.tmp` + 重命名），并创建旋转备份。`data/System.json` 中的 `versionId` 每次保存时都会增加，确保如果打开编辑器，MZ 编辑器会自动重新加载。 --- ## 安全性和原子性 - **原子写入：** 写入临时文件后重命名。 - **自动备份：** 在破坏性操作前完整快照（`data/`、`js/plugins/`、`js/plugins.js`、`mz-mcp.config.json`）。 - **锁定检测：** 检测 MZ 编辑器是否打开（通过 `RPGMZ.exe` 进程），可以发出警告（`warn`）、阻止（`block`）或忽略（`ignore`）— 可配置。 - **事务撤销：** `project_undo_last_change` 恢复最后一个快照。 - **不透明的备注字段：** 插件的 `note` 字段（用于第三方插件）按字节保留。 - **Zod 验证：** 所有写入操作在写入磁盘前都会根据模式验证有效载荷。 - **仅本地伴侣：** WebSocket 桥仅接受来自 `127.0.0.1` 的连接，并需要共享身份验证令牌（一次性生成并保存在 `.mz-mcp/companion.token` 中）。 - **无 `eval` 检查 `runtime_inspect` 对 `$gameParty._gold型的路径执行安全的点遍历，不执行任意代码（拒绝括号、运算符等）。 --- ## 多实例并发 您可以并行运行多个 MCP 客户端会话（例如，两个 Claude 窗口，或 Claude Desktop + Claude Code）。每个会话都启动自己的 MCP 服务器实例。 | 组件 | 默认端口 |备用端口范围 | |---|---|---| | 伴侣桥（WebSocket） | 39872 | 39872-39881（尝试下一个可用端口） | 实际选择的端口写入 `<project>/.mz-mcp/companion.port`。`MzMcpCompanion.js` 在 Playtest 启动时读取此文件，因此始终连接到写入的 MCP 实例的正确桥（通常是聚焦的实例）。 --- ## 测试 该项目包含两种类型的测试： ### 单元测试（vitest） ```bash npm test ``` 111 个测试覆盖 SafeWriter、自动图块编码、插件元数据解析器、Zod 模式、生成器助手、错误类型、mz-codes 加载器、帮助链接和项目内存。 ### 端到端烟雾测试 端到端测试在 RPG Maker MZ 默认模板的临时副本上运行真正的 MCP 服务器： ```bash node scripts/smoke-test-phase2.mjs # 数据库 CRUD node scripts/smoke-test-phase3.mjs # 地图和事件 node scripts/smoke-test-phase4.mjs # 插件和资产 node scripts/smoke-test-phase5.mjs # 额外 node scripts/smoke-test-phase6.mjs # 运行时（带有假伴侣） node scripts/smoke-test-phase7.mjs # 精细化 node scripts/smoke-test-wave-a.mjs # 精灵/自动图块/清理/保存助手 node scripts/smoke-test-wave-b.mjs # CSV 嵌套，插件解析器，推送事件 -test-wave-c.mjs # 本地初始化变量 node scripts-test-wave-e.mjs # 知识蒸馏 node scripts/smoke-test-wave-f.mjs # 多端口，地图渲染，运行时结构，完整性检查 node scripts/smoke-test-wave-g.mjs # 持久项目内存 + 6 项语义分析 node scripts/smoke-test-wave-j.mjs # asset_check_missing_references + event_validate_structure（注入缺陷） node scripts/smoke-test-wave-k.mjs # event_check_references + text_replace_all + event_template_shop（注入缺陷） ``` 还有 `scripts/smoke-test.mjs`（第 1 阶段 — 核心）— 总共 15 个烟雾测试。其中一些**故意注入缺陷**（幽灵资产、损坏的命令列表、损坏的引用），并确认诊断工具检测到它们 — 证明不会产生误报。 --- ## 项目结构 ``` rpg-maker-mz-mcp/ ├──│ ├── index.ts # MCP 服务器│ ├── config.ts # 配置加载 │ ├── core/ # SafeWriter、锁定检测、版本递增、备份等 │ │ # 地图渲染、完整性检查等 │ ├── schemas/ 所有类型的 Zod 模式 │ ├── data/ # 7 个 JSON 目录（代码、备注标签、公式） │ ├── tools/ # 28 类别 MCP 工具 │ ├── runtime/ # WebSocket 桥用于伴侣 │ └── utils/ # 日志、错误、 ├── companion-src/ │ └── MzMcpCompanion.js # 游戏内插件（处理 11 个推送事件钩├── tests/unit/ # 111 个单元测试（vitest） ├── scripts/ # 15 个端到端烟雾测试 + 构建助手 ├── dist/ # 编译后的输出（运行 npm run build 后） ├── package.json ├── tsconfig.json── README.md ## 故障排除 问题 | 可能原因解决方案 | |---|---| 服务器未启动 | `MZ_PROJECT_PATH 设置环境变量指向 MZ 项目 | | `MZ 安装未检测到` | MZ非规范路径中 | 设置 `MZ_INSTALL_PATH` 或 `mz.installPath` 在配置中 | |pgmpacker 未找到 CLI 未安装 | 从 github.com/erri120/rpgmpacker 下载并添加到 PATH | | 伴侣未连接 | 插件未在 `plugins.js` 中启用或 Playtest 未启动 | 通过 `runtime_status` 检查；使用 `companion_install` 重新安装 | | 编辑器打开时编辑导致冲突 | MZ在内存中缓存数据 | 在大操作前关闭编辑器 `editor.on "block"` 平铺数据似乎 特定平铺 ID 的平铺集配置 | 咨询 `tileset_get_flags_decoded` 和_command_describe` | | 两个 MCP 实例冲突 | 伴侣无法确定要连接哪个 MCP | 关闭一个实例；另一个实例写入正确的 `companion.port` | | 截图错误 `Invalid typed array length`方插件添加了巨大的精灵边界 | 已侣使用固定屏幕大小的 RenderTexture。 如果来自旧版本，请更新 `MzMcpCompanion | --- ## 已知限制 为了透明地当前不具备**的功能： - **`map_render` 中的自动图块渲染：** A1 类别的图块以形状 0（基本渲染，没有完整的边界/角编码（形状 1-47）。具有许多自动图块的地图可能在预览中视觉上不完整。不会影响游戏本身 — 仅视觉渲染。`procgen` 在生成时使用正确的自动图块编码。 - **战斗模拟：** 游戏中没有战斗模拟器。要测试平衡性，必须通过 Playtest 进入实际战斗（代理可以通过 `runtime_force_battle` 强制进入）。 - **插件沙盒：** 插件验证涵盖 AST 语法隔离环境中执行恶意插件仍打开 Playtest 时被检测到。 - **MV（RPG Maker MV）：** 该项目仅支持MV 有较小的差异，可能会被覆盖，但。 --- 线图 ###（v1.0.0） - 28 类别中的 193 个工具 - 111 个单元测试 + 15 个端到端烟雾测试 - **asset_check_missing_references** — 检测磁盘上缺失的引用资产（缺失 + 案例不匹配） - **event_validate_structure** — 验证命令列表的结构（终止符、缩进、关闭块） - **event_check_references** — 验证命令指向的内容（转移→地图，调用→公共事件，开关/变量范围，战斗→怪物，退出代码 \V[n]/\N[n]） - **text_replace_all** — 在项目的所有对话中搜索/替换文本（干运行 + 快照） - **event_template_shop** — 商店模板（Shop Processing 302/605） - **runtime_get_console_log** — 在 Playtest 期间捕获游戏错误/警告（插件崩溃） - **地图流程分析** (`analysis_map_flow`) — 具有 unreachable/orphan/dead-end 检测的地图流程图 - **战斗模拟** (`runtime_simulate_battle`) — 在真实引擎上模拟离线战斗，尊重自定义插件 - 通过 jimp 进行精灵合成 - 发生器中的自动图块编码 - 事件命令、效果、特性、图块集标志目录 - 社区目录（备注标签、插件兼容性、伤害公式） - 具有结构化查询的运行时（替代 `eval_js`） - 具有 11 种推送事件类型的运行时 - 通过 PIXI RenderTexture 截图（无内存溢出） - 视觉 `map_render` 具有原生图像内容 数据库完整性检查db_check_cons- 多实例并发） - 套字段的 CSV - 具有语义帮助的保存编辑 - **项目内存** (`project_memory_*`) — 7 类别，多代理安全 - **语义分析** (`analysis_*`) — 7 种分析，基于 mtime 的缓存 ### 未来版本考虑 - `map_render` 中的自动图块形状编码 1-47（更忠实的视觉预览） - 交互式地图可视化检查器（单击图块显示 ID + 标志） - RPG Maker MV 支持（目录有较小差异） - 通过 CLI 与 Translator++ 直接集成 --- ## 贡献 欢迎贡献。在提交拉取请求之前： 1. `npm run typecheck` 必须通过 2. `npm test` 必须 100% 通过（目前 100%） 3. 为新功能添加测试 4. 为影响完整更改添加端到端烟雾测试 --- ## 致谢 **作者：** 牛顿·阿尔维斯 **产品：** RPG Maker MZ - MCP Ultimate **版本：** 1.0.0 **适用于：** RPG Maker MZADOKAWA 株式会社） 与 KAWA 无官方 从 RPG Maker MZ 安装目录读取的文件cript/`、`/`、`samplemapsgenerator/`、`dlc/`、`help-en/`拥有有效产品许可证的用户。 --- ## 许可证 MIT 许可证 — 查看 [LICENSE](LICENSE) 了解完整详情。