RPG Maker MZ · Codex 本地插件

通过 Codex 的 MCP 工具制作 RPG Maker MZ 游戏：地图绘制、NPC 和事件、角色/物品/技能数据库、素材查询、引擎截图及自动试玩。基于 Redseb/rpgmaker-mz-mcp 固定提交 5119a9a3，复用 128 项工具，补充 10 项本机工具，共 138 项。附中文开发 skill 和自定义图块目录 skill。

插件 logo 为 Aseprite 制作的 48×48 原创透明像素角色：黄毛朋克少年、皮夹克、金属链和香烟。assets/logo.png 是正式图标，assets/punk-logo.aseprite 是 7 层可编辑母版，assets/punk-logo-preview.png 是 8 倍最近邻预览。图标已配置到插件列表与输入框图标。

Codex 中使用 Claude / GPT 调用插件（2026-11-11 更新）

这次更新后，在 Codex 里切换到 Claude 模型（例如通过 Magpie 等中转站接入的 Claude API）也可以正常调用本插件的工具和 skill，与使用 GPT 模型时一致。

• 已在 Codex 桌面版（Windows）实测：修复后 Claude 与 GPT 会话都能加载这组本地插件的 MCP 工具，并实际调用了 Blender、Aseprite、Flux、Stable Audio 的状态工具。

• 原因：Codex 读取插件 mcp.json 时只接受 type、command、args、env、cwd，command 必须是裸可执行名，并会拒绝 startup_timeout_sec、tool_timeout_sec 等字段；旧格式导致部分模型会话里插件工具不出现。

• 现在构建脚本生成的 mcp.json 统一使用 cmd.exe 调用插件目录内的 launch-mcp.cmd，本机 Python/Node 的绝对路径和环境变量写在启动器里。

• 已安装旧版本的用户：重新运行安装/构建脚本后，新开一个 Codex 聊天或重启 Codex 即可生效。

• 长任务需要更长超时时，可在 ~/.codex/config.toml 对应的 [mcp_servers.<名称>] 中设置 tool_timeout_sec。

Related MCP server: RPG Maker MZ MCP Server

连接方式

MCP 直接编辑游戏工程文件。mz_open_editor 启动本机 RPGMZ.exe 并返回工程路径；本机 MZ 1.10 实测可能忽略命令行工程参数，此时需在“文件 → 打开工程”选择该路径。mz_launch_playtest 用 MZ 附带的 NW.js 启动试玩，run_playtest 用 Chromium 自动验证。插件不读取 Qt 编辑器当前选区或未保存状态，也不提供编辑器内按钮点击/热刷新。

编辑已有工程前保存并关闭编辑器中的该工程，修改后重新打开，防止旧内存覆盖磁盘。MZ 安装目录与游戏工程目录是两个不同路径。默认安装位置为 D:\steam\steamapps\common\RPG Maker MZ；可在安装命令里改。

安装发布包

解压 dist/rpgmaker-mz-local-plugin-1.0.0.zip，保留完整目录结构，在解压出的 rpgmaker-mz-codex 目录运行：

powershell -NoProfile -ExecutionPolicy Bypass -File .\install-plugin.ps1

依赖 Node.js 20+、带插件 CLI 的 Codex，以及合法安装的 RPG Maker MZ。安装器优先寻找 PATH 中的 Node，随后寻找 Codex bundled Node。发布包包含已构建 MCP 服务与 Playwright Core，无需 npm/pip 安装依赖，不下载浏览器。自动试玩可使用本机 Edge/Chrome。

其他机器可明确指定：

.\install-plugin.ps1 -MZPath 'D:\steam\steamapps\common\RPG Maker MZ' -NodePath 'C:\Program Files\nodejs\node.exe'

-ProjectPath 可设置默认游戏目录，-ChromiumPath 可指定浏览器，-PrepareOnly 仅准备配置。安装器注册本地 marketplace 并安装 rpgmaker-mz-local@rpgmaker-mz-local-market，随后在新 Codex 聊天加载工具与 skill。仅卸载插件可运行 uninstall-plugin.ps1，游戏与备份保留。

使用示例

• “检查本机 MZ，连接 E:/games/MyGame 工程。”

• “在 E:/games 下新建一个叫「林间小镇」的 MZ 工程，铺好地面，加入能说中文的 NPC，并验证走过去可以对话。”

• “把我现有游戏的物品价格调整一下，先给我变更预览，再修改并检查引用。”

• “查看地图通行性，给出口添加双向传送并自动试玩。”

mz_create_project 目标必须尚不存在，父目录必须存在。工程内自带商业素材不会进入插件 ZIP。

本机扩展工具

每个 MCP 会话首次实际写入前自动备份 data、js/plugins、js/plugins.js、工程标记和 package.json。媒体素材、存档、引擎不在此备份范围。并发 MCP 请求会串行执行，防止同一进程内读改写冲突；不能阻止另一个编辑器或外部进程同时写文件。

源码构建与验证

源码工作区保留 vendor/upstream 与锁文件。使用 pnpm 安装固定依赖，再运行：

pnpm install --frozen-lockfile
node scripts/build.mjs
node --test tests/local.test.mjs tests/editor-compat.test.mjs
node tests/integration.mjs
python scripts/package.py

构建器把 MCP SDK、Zod 和上游工具打入单个服务；Playwright Core 单独随包分发。发布包不包含测试游戏、本机路径配置、node_modules 开发依赖或 RTP 资源。outputs/verification.json 保存本次工作区集成检查证据；测试工程仅在本机用于验证。

插件故障排查：确认新聊天已经加载插件；调用 mz_installation；用 get_project 检查目标；浏览器启动失败时设置 -ChromiumPath；结构校验失败时修复输入而不是直接 force:true。

编辑器兼容：游戏能试玩不等于编辑器能读取 js/plugins.js。先调用 mz_check_editor_project。若是可解析的字面 JSON 清单但布局不规范，可先预览 mz_update_plugin({dryRun:true})，确认后 mz_update_plugin({}) 规范化；修改某插件例如 mz_update_plugin({name:"MyPlugin",enabled:true,parameters:{text:"你好"},dryRun:true})。实际更新前保存并关闭工程；启用前须放好对应 js/plugins/MyPlugin.js。工具不会执行清单中的任意 JavaScript，不可安全解析时拒绝写入。mz_open_editor 自动预检，但仍不声称确认编辑器加载成功。

GitHub 源码与许可

源码仓库：https://github.com/YZ2020CHINA/rpgmaker-mz-codex

自有代码使用 MIT License，第三方组件、软件、模型与素材保留各自许可。开发、分支和发布流程见 CONTRIBUTING.md。

首次从源码安装时，先复制 config.example.json 为 config.json 并按本机安装位置修改；本机配置不会提交到 Git。