RPG Maker MZ MCP Server - 使用说明书

⚠ 実験版/WIP / 作者环境专用 这是“RPG塞克尔”MZ的AI摆弄MCP服务器”的 开发中版本（0.x） 是。\ 仅在作者环境（Windows+Antigravity）中确认动作是。 重要说明： - 其他环境MCP在客户端不动的可能性很高是 - Antigravity实施CWD的情况下，看起来通用的设定方法可能无法动作 - 阅读代码并根据需要更改路径和设置 - 建议在测试项目中使用 - 在接触生产数据之前必须进行备份定位为“自己用工具+代码公开”。请自己负责使用。

TL;DR（超短缩版）

假设用户

RPG塞孔MZ的AI想欺负的人

能做的事

✅ AI地图
✅ 扩建活动
✅ 添加和配置插件
✅ 自动运行测试和截图

3行快速启动（Google Antigravity）

无需安装: npx自动检索包
MCP设定: mcp_config.json添加以下内容

   {
     "mcpServers": {
       "rpg-maker-mz": {
         "command": "npx",
         "args": ["-y", "@rein634/rpg-maker-mz-mcp"]
       }
     }
   }

使用: Antigravity重新启动-MCP Servers → Refresh →“分析此项目，将对话事件添加到第一个地图”AI搭讪

💡 其他MCP使用客户端（Cursor/Claude等）时：请参阅设置部分中的项目本地。

______________________________________________________________________

概要

这MCP服务器RPG塞孔MZ游戏开发完全自动化中所述修改相应参数的值。AI中描述的场景，使用下列步骤创建明细表，以便在概念设计中分析体量的周长。

主要特点：

✅ 抽象层: MZ即使不知道内部构造也可以开发
✅ 自动ID管理：交换机映射ID自动解析/分配
✅ 防止春电影: MCP Resources可参考规格
✅ 品质保证: Zod Validation和资产完整性检查
✅ 自动备份：写入文件前自动备份
✅ Undo机能：可以轻松撤消上一次更改
✅ 安全增强：白名单方式的代码执行、密码对策

______________________________________________________________________

安装，安装

谷歌反重力

⚠️ 环境相关警告: Antigravity实施CWD的情况下，看起来通用的设定方法（npx、rpg-maker-mz-mcp命令、相对路径等）它可能无法运作。\ 以下为在作者环境中实际运行的设置示例是。如果环境不同，请适当更改路径。

设定方法（实际动作的例子）

首先，全局安装：

npm install -g @rein634/rpg-maker-mz-mcp

mcp_config.json 中添加以下内容（使用绝对路径）：

{
  "mcpServers": {
    "rpg-maker-mz": {
      "command": "node",
      "args": [
        "C:/Users/YOUR_USERNAME/AppData/Roaming/npm/node_modules/@rein634/rpg-maker-mz-mcp/dist/index.js"
      ]
    }
  }
}

⚠️ 重要: - C:/Users/YOUR_USERNAME/AppData/Roaming/npm/node_modules/... 的部分您的环境中的实际路径中所述修改相应参数的值YOUR_USERNAME你管索引Windows更改为用户名） - Windows那么C:/像斜线一样/），然后单击\）请不要使用 - 路径是环境变量 %APPDATA%\npm\node_modules\@rein634\rpg-maker-mz-mcp\dist\index.js 中所述修改相应参数的值

其他设置方法（可能无法正常工作）

以下设定方法Antigravity环境依存它可能无法运作：

方法A: npx通过（不推荐）

{
  "mcpServers": {
    "rpg-maker-mz": {
      "command": "npx",
      "args": ["-y", "@rein634/rpg-maker-mz-mcp"]
    }
  }
}

方法B: 直接指定命令名（不推荐）

{
  "mcpServers": {
    "rpg-maker-mz": {
      "command": "rpg-maker-mz-mcp"
    }
  }
}

方法C: 相对路径（不工作）

{
  "mcpServers": {
    "rpg-maker-mz": {
      "command": "node",
      "args": ["./node_modules/@rein634/rpg-maker-mz-mcp/dist/index.js"]
    }
  }
}

❌ Antigravity啊 .gemini/antigravity 将条目添加到文档注册表

起动确认

Antigravity重新启动MCP服务器 → 刷新中所述修改相应参数的值。\ 终端显示以下日志：

[2025-11-29T05:43:43.574Z] [INFO] RPG Maker MZ MCP Server running on stdio.

显示这条信息后等待输入的是正常运行是。MCP正在等待客户端的请求。

💡 关于日志：日志是 标准错误 将条目添加到文档注册表MCP协议JSON（stdout）中所述修改相应参数的值。即使控制台显示日志MCP没有问题。

______________________________________________________________________

项目本地（例如Cursor/Claude Code）

⚠️ 未検证：以下设置为在作者的环境中没有验证。\ 在项目根目录中放置配置文件MCP这是面向客户端的假设设置。如果不工作，请阅读代码并根据环境进行调整。

1.安装到项目中

RPG塞孔MZ在项目根目录中运行：

npm install -D @rein634/rpg-maker-mz-mcp

2. MCP配置文件设置

项目根目录中的配置文件（例如： .cursor/mcp.json 啊 mcp_config.json），并添加：

{
  "mcpServers": {
    "rpg-maker-mz": {
      "command": "node",
      "args": ["./node_modules/@rein634/rpg-maker-mz-mcp/dist/index.js"]
    }
  }
}

⚠️ 注意: - 此设置为在作者的环境中没有验证 - MCP客户机实施CWD的情况下有可能无法运行 - 如果无法正常工作，请使用绝对路径或根据环境进行调整

______________________________________________________________________

其他方法

全局安装（可选高级）

这是一种全局安装并以命令名直接运行的方法。

npm install -g @rein634/rpg-maker-mz-mcp

安装后MCP在配置文件中添加：

{
  "mcpServers": {
    "rpg-maker-mz": {
      "command": "rpg-maker-mz-mcp"
    }
  }
}

⚠️ 注意：某些客户端（特别是Windows 在环境中，全局包装脚本（.cmd/.ps1），模板名称将采用不同的格式Error: calling "initialize": EOF 时褪色为此颜色。\ 在这种情况下Antigravity用或项目本地中所述修改相应参数的值。

直接从源代码运行（面向开发人员）

npm不需要安装软件包。只需克隆存储库并安装依赖关系即可使用。

git clone https://github.com/rein1225/RPGMakerMZ_MCP.git
cd RPGMakerMZ_MCP
npm install

MCP在配置文件中添加：

{
  "mcpServers": {
    "rpg-maker-mz": {
      "command": "npx",
      "args": ["tsx", "C:/path/to/RPGMakerMZ_MCP/index.ts"],
      "cwd": "C:/path/to/RPGMakerMZ_MCP"
    }
  }
}

⚠️ 重要: - C:/path/to/RPGMakerMZ_MCP 替换为实际项目路径 - Windows那么C:/像斜线一样/），然后单击\）请不要使用 - npx tsx中描述的相应参数的值TypeScript可以直接运行文件（无需构建） - cwd不允许属性：故障排除Q1选项卡页面上创建或编辑条目

______________________________________________________________________

可用工具

Phase 1: 项目分析数据操作

1. `get_project_info` -获取项目基本信息

说明： System.json中描述的场景，使用下列步骤创建明细表，以便在概念设计中分析体量的周长。 参数：

projectPath （必需）：项目文件夹的绝对路径

2. `list_data_files` -数据文件列表

说明： data在动态输入提示中单击JSON获取文件列表。 参数：

projectPath （必需）：项目文件夹的绝对路径

3. `read_data_file` -数据文件读取

说明： 读取指定数据文件（如Actors.json）的内容。 参数：

projectPath （必需）：项目文件夹的绝对路径
filename （必需）：文件名（例如'Actors.json'）

4. `write_data_file` -数据文件写入

说明： 在指定的数据文件中JSON写入内容。写入前自动创建备份。 参数：

projectPath （必需）：项目文件夹的绝对路径
filename （必需）：文件名
content （必需）：写入JSON字符串

5. `search_events` -事件搜索

说明： 在地图事件和公共事件中查找文本和命令代码。 参数：

projectPath （必需）：项目文件夹的绝对路径
query （必需）：要搜索的文本或数字

6. `get_event_page` -获取事件页面

说明： 获取指定事件页面的命令列表。主要的命令（会话、选项、开关操作等）被赋予可读性高的说明。因此AI可以理解现有活动的内容，进行推敲和修正。 参数：

projectPath （必需）：项目文件夹的绝对路径
mapId （必需）：映射ID
eventId （必需）：事件ID
pageIndex （必需）：页码（0开始）

______________________________________________________________________

Phase 2: 资产管理

7. `list_assets` -资源列表

说明： img以及audio获取目录中的文件列表。 参数：

projectPath （必需）：项目文件夹的绝对路径
assetType （可选）：'img', 'audio', 'all' (默认值：'all')

8. `check_assets_integrity` -资产完整性检查

说明： 检查事件中引用的资源（如图像、声音）是否实际存在于项目中。 参数：

projectPath （必需）：项目文件夹的绝对路径

______________________________________________________________________

Phase 3: 插件管理

9. `write_plugin_code` -创建插件

说明： js/plugins在目录中创建新的插件文件（.js）。 参数：

projectPath （必需）：项目文件夹的绝对路径
filename （必需）：插件文件名（例如'MyPlugin.js'）
code （必需）：JavaScript代码

10. `get_plugins_config` -获取插件设置

说明： js/plugins.js查看项目中可用的所有族。 参数：

projectPath （必需）：项目文件夹的绝对路径

11. `update_plugins_config` -更新插件设置

说明： js/plugins.js中所述修改相应参数的值。 参数：

projectPath （必需）：项目文件夹的绝对路径
plugins （必需）：排列插件配置对象

______________________________________________________________________

Phase 4: 映射事件操作（抽象层）

12. `add_dialogue` -添加对话事件

说明： 将对话添加到消息窗口。 参数：

projectPath （必需）：项目文件夹的绝对路径
mapId （必需）：映射ID
eventId （必需）：事件ID
pageIndex （必需）：页码
insertPosition （必需）：插入位置（-1结尾）
text （必需）：显示文本
face, faceIndex, background, position (省略可)

请求示例：

{
  "tool": "add_dialogue",
  "arguments": {
    "projectPath": "C:/Games/MyProject",
    "mapId": 1,
    "eventId": 1,
    "pageIndex": 0,
    "insertPosition": -1,
    "text": "こんにちは！\n新しい仲間です。"
  }
}

响应示例：

{
  "content": [
    {
      "type": "text",
      "text": "会話イベントを追加しました。"
    }
  ]
}

13. `add_choice` -显示选项

说明： 向事件添加选项。最多可以设置6个选项。 参数：

projectPath （必需）：项目文件夹的绝对路径
mapId （必需）：映射ID
eventId （必需）：事件ID
pageIndex （必需）：页码
insertPosition （必需）：插入位置（-1结尾）
options （必须）：选択肢の文字列配列（最大6个）
cancelType （可选）：取消时的行为（-1=不可取消，0-5=分支到选项，默认值：-1）

请求示例：

{
  "tool": "add_choice",
  "arguments": {
    "projectPath": "C:/Games/MyProject",
    "mapId": 1,
    "eventId": 1,
    "pageIndex": 0,
    "insertPosition": -1,
    "options": ["はい", "いいえ"],
    "cancelType": -1
  }
}

响应示例：

{
  "content": [
    {
      "type": "text",
      "text": "選択肢を追加しました。"
    }
  ]
}

14. `add_loop` -添加循环

说明： 添加事件命令的循环结构。 参数：

projectPath, mapId, eventId, pageIndex, insertPosition （必须）

15. `add_break_loop` -循环中断

说明： 添加用于中断循环的命令。 参数：

projectPath, mapId, eventId, pageIndex, insertPosition （必须）

16. `add_conditional_branch` - 条件分岐追加

说明： 添加条件分支（If-Else-End）。 参数：

projectPath, mapId, eventId, pageIndex, insertPosition （必须）
condition （必需）：条件参数对象
includeElse （可选）：Else包括分支或（默认值：true）

17. `delete_event_command` -删除事件命令

说明： 删除指定索引的事件命令。 参数：

projectPath, mapId, eventId, pageIndex, commandIndex （必须）

18. `update_event_command` -更新事件命令

说明： 用新内容覆盖指定索引的事件命令。 参数：

projectPath, mapId, eventId, pageIndex, commandIndex, newCommand （必须）

19. `add_actor` -添加操作者

说明： 向数据库添加新的操作者。 参数：

projectPath, name （必须）
classId, initialLevel, maxLevel (省略可)

20. `add_item` -添加项目

说明： 向数据库添加新项目。 参数：

projectPath, name （必须）
price, consumable, scope, occasion (省略可)

21. `add_skill` -添加技能

说明： 向数据库添加新技能。 参数：

projectPath, name （必须）
mpCost, tpCost, scope, occasion (省略可)

22. `draw_map_tile` -映射平铺绘制

说明： 在地图的指定坐标上放置平铺。 参数：

projectPath, mapId, x, y, layer, tileId （必须）

23. `create_map` -新建映射

说明： 创建新映射。 参数：

projectPath （必需）：项目文件夹的绝对路径
mapName （必需）：映射名称
width （可选）：贴图宽度（平铺数，默认值：17）
height （可选）：贴图高度（平铺数，默认值：13）
parentMapId （可选）：父映射ID（默认值：0）

24. `show_picture` -显示图片

说明： 向事件添加图片显示命令。 参数：

projectPath （必需）：项目文件夹的绝对路径
mapId （必需）：映射ID
eventId （必需）：事件ID
pageIndex （必需）：页码
insertPosition （必需）：插入位置（-1结尾）
pictureId （必需）：图片编号
pictureName （必需）：图像文件名
x, y （必须）：表示坐标
origin （可选）：原点位置（0=左上，1=中心，默认值：0）
scaleX, scaleY （可选）：放大率（%，默认值：100）
opacity （可选）：不透明度（0-255，默认值：255）
blendMode （可选）：合成模式（0-3，默认值：0）

25. `inspect_game_state` -游戏状态检查

说明： 从运行中的游戏（Puppeteer连接）中获取变量和开关的值。 安全性： 采用白名单方式，只执行允许的模式。输入长度限制（100个字符）和ID还实施了范围检查（1-9999）。 允许的模式示例：

$gameVariables.value(1) -获取变量值
$gameSwitches.value(1) -获取交换机值
$gameParty.gold() -拿着钱
$gameMap.mapId() -当前映射ID获得
SceneManager._scene -获取当前场景

参数：

script （必需）：评估JavaScript代码（仅在白名单中注册的模式）
port （可选）：调试端口（默认值：9222）

请求示例：

{
  "tool": "inspect_game_state",
  "arguments": {
    "script": "$gameVariables.value(1)",
    "port": 9222
  }
}

响应示例：

{
  "content": [
    {
      "type": "text",
      "text": "100"
    }
  ]
}

⚠️ 危险工具：此工具JavaScript执行代码。有关详细信息，请参见危险工具的封印指南中所述修改相应参数的值。

______________________________________________________________________

Phase 5: 测试自动化

26. `run_playtest` -测试运行

说明： Game.exe中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。Game.exe如果找不到，则自动执行基于浏览器的测试播放（后退模式）。Puppeteer也可以指定连接的调试端口。 参数：

projectPath （必需）：项目文件夹的绝对路径
duration （可选）：拍摄前的等待时间（ms）（默认值：5000）
autoClose （可选）：true的情况下，拍摄后自动结束游戏。（默认值：false）
debugPort （可选）：远程调试端口（例如，9222）。Puppeteer中所述修改相应参数的值。
startNewGame （可选）：true的情况下，跳过标题画面开始新游戏。（默认值：false）
postLaunchScript （可省略）：游戏启动后执行JavaScript代码。调试UI查看项目中可用的所有族。

postLaunchScript使用示例：

{
  "projectPath": "C:/Games/MyProject",
  "postLaunchScript": "Input._currentState['debug'] = true; setTimeout(() => { Input._currentState['debug'] = false; }, 100);"
}

Phase 6: 备份Undo功能

27. `undo_last_change` -撤消上一次更改

说明： 从最新备份恢复文件。filename中描述的场景，使用下列步骤创建明细表，以便在概念设计中分析体量的周长。 参数：

projectPath （必需）：项目文件夹的绝对路径
filename （可选）：要恢复的文件名（例如'Actors.json'）。省略时自动检测最新变更文件

28. `list_backups` -备份浏览

说明： 显示指定文件或所有文件的备份列表。 参数：

projectPath （必需）：项目文件夹的绝对路径
filename （可选）显示备份的文件名。省略时显示所有文件的备份

关于备份功能：

所有文件写入操作（write_data_file、add_actor、add_item、add_skill、write_plugin_code、update_plugins_config、映射操作等）自动创建备份
备份文件 .{timestamp}.bak 格式保存
旧备份将自动清理（保留最新5个）
发生错误时自动回滚

Puppeteer高级自动测试

run_playtest的debugPort选项卡页面上创建或编辑条目Puppeteer使用游戏UI可以自动化操作和方案测试。详细信息API规格是 docs/API_REFERENCE.md 来修改标记元素的显示属性。

E2E如何运行测试

自动化方案（automation/test_*.js）是以生产游戏环境为前提的手动执行专用测试。CI 中所述修改相应参数的值。

# 代表的なシナリオをまとめて走らせる
npm run test:e2e

# もしくは個別に実行
node automation/test_full_suite.js
node automation/test_add_dialogue.js

⚠️ 浏览器操作Game.exe因为伴随着启动仅受信任的本地环境中所述修改相应参数的值。

______________________________________________________________________

MCP资源

`mz://docs/event_commands` -事件命令参考

AI的MZ中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

______________________________________________________________________

実用例

示例1:创建新操作者并添加对话事件

// 1. アクター作成
add_actor({ projectPath, name: "新キャラ" });
// 2. 会話追加
add_dialogue({ projectPath, mapId: 1, eventId: 1, pageIndex: 0, insertPosition: -1, text: "こんにちは！\n新しい仲間です。" });

示例2:事件搜索

search_events({ projectPath: "c:/path/to/project", query: "ポーション" });

______________________________________________________________________

故障排除

Q1: MCP配置错误“invalid character'-'after array element”或“属性”cwd 不允许“

✅ v0.1.2修改: stdout的日志输出stderr中所述修改相应参数的值MCP服务器端导致的invalid character '-' after array element错误已解决。\ 在动态输入提示中单击v0.1.2使用后续版本请：npm install -g @rein634/rpg-maker-mz-mcp@latest

原因:

MCP服务器端问题（大于或等于v0.1.1）：日志stdout而需要与环境混合的每条反射光线，进行环境采样JSON-RPC协议已损坏
JSON语法错误（注释、结尾逗号等）
正在使用MCP客户机cwd不支持属性

解决策：

第1步：JSON检查语法

删除注释: JSON是注释（//啊#），模板名称将采用不同的格式
删除尾部逗号：数组或对象的最后一个元素之后不能有逗号
通过联机验证器确认: Jsonlint 中的语法验证

步骤2:确认正确的设置示例

Google Antigravity の场合（推奨）：

{
  "mcpServers": {
    "rpg-maker-mz": {
      "command": "npx",
      "args": ["-y", "@rein634/rpg-maker-mz-mcp"]
    }
  }
}

✅ 这个方法的优点: - npm install 不需要（npx自动获取软件包） - CWD而需要与环境混合的每条反射光线，进行环境采样.gemini/antigravity 空转 - 在任何用户环境中都以相同的设置工作

对于项目本地（例如Cursor/Claude Code）：

在项目根目录中：

npm install -D @rein634/rpg-maker-mz-mcp

配置文件（位于项目根目录中）：

{
  "mcpServers": {
    "rpg-maker-mz": {
      "command": "node",
      "args": ["./node_modules/@rein634/rpg-maker-mz-mcp/dist/index.js"]
    }
  }
}

✅ 这个方法的优点: - 全球PATH不依赖于包装脚本 - Windows / Mac / Linux 通用行为 - 由于使用了工作区的相对路径，所以在项目根目录中放置配置文件的客户机中很容易处理

可选：全局安装（某些环境可能出现问题）

npm install -g @rein634/rpg-maker-mz-mcp

{
  "mcpServers": {
    "rpg-maker-mz": {
      "command": "rpg-maker-mz-mcp"
    }
  }
}

⚠️ 注意: Windows环境等无法正确启动全局包装器脚本Error: calling "initialize": EOF 时褪色为此颜色。在这种情况下Antigravity用或项目本地中所述修改相应参数的值。

常见错误：

❌ 使用注释: // これはコメント → JSON不支持评论
❌ 尾部逗号: "args": ["tsx", "index.ts",] →不允许最后的逗号
❌ 单引号: 'path' → JSON仅限双引号
❌ 反作用: C:\path\to\file →斜线（/），模板名称将采用不同的格式

步骤3:确认设置文件的位置

反重力: %APPDATA%\Antigravity\mcp_config.json （Windows）
克劳德桌面版: %APPDATA%\Claude\claude_desktop_config.json （Windows）
使用配置文件路径MCP取决于客户机

步骤4:调试方法

在文本编辑器中打开配置文件
Jsonlint 复制并粘贴到验证
确认错误消息的行号并修改相应的位置
修改后MCP重新启动客户端

Q2: 找不到交换机错误

解决策： 自动注册功能工作。System.json查看项目中可用的所有族。

Q3: 与编辑器冲突

解决策： MCP编辑期间请关闭编辑器，或者编辑后重新打开项目。

Q4: Game.exe缺少

解决策： 使用部署功能创建测试播放包，或者Game.exe中所述修改相应参数的值。另外v1.2.0在以后Game.exe即使没有，也可以通过浏览器执行测试游戏。

Q5: npm找不到包

解决策：

全局安装： npm install -g @rein634/rpg-maker-mz-mcp
确认路径是否通过： which rpg-maker-mz-mcp（Linux/Mac）或 where rpg-maker-mz-mcp（Windows）
单击功能区上npx tsx请使用

______________________________________________________________________

技术仕样

体系结构

[AI] ← → [MCP Server] ← → [RPG Maker MZ Project]
           ├─ Tools (28個)
           ├─ Resources (1個)
           ├─ Schemas (Zod Validation)
           └─ Backup System (自動バックアップ・ロールバック)

测试覆盖

单元测试: Vitest使用
覆盖报告: npm run test:coverage 生成
CI/CD: GitHub Actions自动测试Codecov中覆盖跟踪

npm公开

本包装是npm中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积

npm install -g @rein634/rpg-maker-mz-mcp

包信息：https://www.npmjs.com/package/@rein634/rpg-maker-mz-mcp

文件配置

RPGツクールMZ＿MCP/
├── index.ts                    # MCPサーバー本体（TypeScript）
├── handlers/                   # ハンドラ層（TypeScript化済み）
│   ├── project.ts
│   ├── database.ts
│   ├── plugins.ts
│   ├── map.ts
│   ├── events.ts
│   └── playtest.ts
├── utils/                      # ユーティリティ層（TypeScript化済み）
│   ├── validation.ts
│   ├── mapHelpers.ts
│   └── ...
├── types/                      # 型定義ファイル
├── resources/
│   └── event_commands.json     # イベントコマンドリファレンス
├── schemas/
│   └── mz_structures.js        # Zod検証スキーマ
├── automation/                 # 自動化スクリプト
└── package.json

______________________________________________________________________

安全注意事项

本MCP服务器将在本地开发环境中使用。

实施的安全措施

inspect_game_state：采用白名单方式，只能执行许可的模式。输入长度限制（100个字符）和ID还实施了范围检查（1-9999）。
帕斯特橡胶对策: path.normalize()和fs.realpath()使用防止符号链接攻击。
文件名验证：写入插件时仅允许字母数字下划线连字符。
自动备份：在所有文件写入操作中创建自动备份，并在错误时自动回滚。

推奨事项

不要在对外公开的环境中使用。
仅在可靠的本地环境中使用。
建议在进行重要更改之前手动进行备份。

______________________________________________________________________

许可证

MIT许可证

典型用例

方案1:将子任务添加到现有项目

目标：在现有的村地图中添加3个子任务事件

手顺:

项目分析: get_project_info获取项目信息
事件搜索: search_events查看现有事件
事件页面检索: get_event_page了解现有事件的结构
会話追加: add_dialogue的NPC添加对话
选択肢追加: add_choice添加任务选项
条件分岐: add_conditional_branch设定任务完成条件
试运行: run_playtest确认动作

AI示例说明:

このプロジェクトを解析して、マップ1の村に3つのサブクエストを追加してください。
各クエストには会話、選択肢、完了条件を含めてください。

方案2:从创建新地图到事件展开

目标：创建新的迷宫地图并放置宝箱事件

手顺:

映射: create_map在中创建新映射
平铺: draw_map_tile在中绘制地图
创建事件: add_dialogue添加宝箱信息
添加项目: add_item在中创建报酬项
活动协作：在条件分支中设置项目授予
测试: run_playtest确认动作

AI示例说明:

新しいダンジョンマップを作成して、宝箱イベントを3つ配置してください。
各宝箱には異なるアイテムが入るようにしてください。

方案3:添加和配置插件

目标：添加自定义插件并更新设置

手顺:

插件创建: write_plugin_code在中添加插件代码
设定取得: get_plugins_config确认当前设置
设定更新: update_plugins_config在中启用插件
测试: run_playtest在中确认插件的动作

AI示例说明:

カスタムバトルプラグインを作成して、有効化してください。

______________________________________________________________________

危险工具的封印指南

危险工具一览

以下工具出于安全原因谨慎使用必须：

inspect_game_state: JavaScript运行代码（受白名单保护，但可能会出现运行时错误）

推奨设定

建议在初始状态下禁用。MCP客户端设置允许您禁用特定工具：

{
  "mcpServers": {
    "rpg-maker-mz": {
      "command": "rpg-maker-mz-mcp",
      "disabledTools": ["inspect_game_state"]
    }
  }
}

⚠️ 注意：当前MCP根据客户机的不同disabledTools属性可能不受支持。在这种情况下，请避免使用工具，或者只在可靠的环境中使用。

安全措施

inspect_game_state该工具实施了以下安全措施：

✅ 白名单制：仅允许执行允许的模式
✅ 入力长制限：最多100个字符
✅ ID范围检查：仅允许1-9999范围
✅ 帕斯特橡胶对策：防止未经授权的路径访问

尽管如此避免执行不可靠的代码。

______________________________________________________________________

更新履歴

v0.1.2（2025-11-29）

重要修正: stdout的日志输出stderr更改为（符合MCP协议）
invalid character '-' after array element解决错误
Logger.info()的console.error()重新启动交互渲染
更新测试console.error），模板名称将采用不同的格式

v0.1.1（2025-11-29）

logger.js将条目添加到文档注册表tsconfig.build.json修改
npm公开准备完了（@rein634/rpg-maker-mz-mcp）

v0.1.0（2025-11-29）

npm首次发布
TypeScript迁移完成：全部handlers层和入口点TypeScript添加
CI/CD集成：GitHub Actions添加类型检查
undo_last_change工具list_backups实现工具
测试覆盖改善（undo.ts、backup.ts的测试追加）
playtest.ts的重构（527行→311行，减少约41%）
README改进（TL；DR添加、请求示例添加、用例添加）
安全增强：密码保护措施，添加执行任意代码的警告
添加新工具： add_choice, create_map, show_picture, check_assets_integrity
单元测试部署
添加日志程序实用程序
run_playtest 添加基于浏览器的回退功能（无需Game.exe）
MCP Resources実装
Zod Validation実装

______________________________________________________________________

附加功能路线图

以下功能另行制定规格，预定依次安装。了解更多信息 docs/feature-roadmap.md 来修改标记元素的显示属性。

｜优先级｜功能｜状态｜ | --- | --- | --- | | ~~高~~ | ~~undo 功能（JSON备份/回滚）~~✅ 已实施 | 中 | validate_project 工具（统一执行完整性检查）📋 正在计划｜中｜批处理（通过单一请求执行多个命令）｜📋 正在计划｜低｜WebSocket通知（实时日志/状态通知）📋 正在计划

开発・贡献

运行测试

# ユニットテスト
npm test

# カバレッジレポート生成
npm run test:coverage

# 型チェック
npm run typecheck

# E2Eテスト（手動実行）
npm run test:e2e

构建

# 全ファイルをビルド（dist/に出力）
npm run build

# 公開前の確認
npm pack --dry-run

分发

欢迎拉式点播！请注意：

代码样式：TypeScript的，之strict符合模式
测试：请将测试添加到新功能
安全性：对文件操作和代码执行实施适当的验证

RPGMakerMZ MCP

快速接入

详细介绍

RPG Maker MZ MCP Server - 使用说明书

TL;DR（超短缩版）

假设用户

能做的事

3行快速启动（Google Antigravity）

概要

安装，安装

谷歌反重力

设定方法（实际动作的例子）

其他设置方法（可能无法正常工作）

起动确认

项目本地（例如Cursor/Claude Code）

1.安装到项目中

2. MCP配置文件设置

其他方法

全局安装（可选高级）

直接从源代码运行（面向开发人员）

可用工具

Phase 1: 项目分析数据操作

1. get_project_info -获取项目基本信息

2. list_data_files -数据文件列表

3. read_data_file -数据文件读取

4. write_data_file -数据文件写入

5. search_events -事件搜索

6. get_event_page -获取事件页面

Phase 2: 资产管理

7. list_assets -资源列表

8. check_assets_integrity -资产完整性检查

Phase 3: 插件管理

9. write_plugin_code -创建插件

10. get_plugins_config -获取插件设置

11. update_plugins_config -更新插件设置

Phase 4: 映射事件操作（抽象层）

12. add_dialogue -添加对话事件

13. add_choice -显示选项

14. add_loop -添加循环

15. add_break_loop -循环中断

16. add_conditional_branch - 条件分岐追加

17. delete_event_command -删除事件命令

18. update_event_command -更新事件命令

19. add_actor -添加操作者

20. add_item -添加项目

21. add_skill -添加技能

22. draw_map_tile -映射平铺绘制

23. create_map -新建映射

24. show_picture -显示图片

25. inspect_game_state -游戏状态检查

Phase 5: 测试自动化

26. run_playtest -测试运行

Phase 6: 备份Undo功能

27. undo_last_change -撤消上一次更改

28. list_backups -备份浏览

Puppeteer高级自动测试

E2E如何运行测试

MCP资源

mz://docs/event_commands -事件命令参考

実用例

示例1:创建新操作者并添加对话事件

示例2:事件搜索

故障排除

Q1: MCP配置错误“invalid character'-'after array element”或“属性”cwd 不允许“

第1步：JSON检查语法

步骤2:确认正确的设置示例

步骤3:确认设置文件的位置

步骤4:调试方法

Q2: 找不到交换机错误

Q3: 与编辑器冲突

Q4: Game.exe缺少

Q5: npm找不到包

技术仕样

体系结构

测试覆盖

npm公开

文件配置

安全注意事项

实施的安全措施

推奨事项

1. `get_project_info` -获取项目基本信息

2. `list_data_files` -数据文件列表

3. `read_data_file` -数据文件读取

4. `write_data_file` -数据文件写入

5. `search_events` -事件搜索

6. `get_event_page` -获取事件页面

7. `list_assets` -资源列表

8. `check_assets_integrity` -资产完整性检查

9. `write_plugin_code` -创建插件

10. `get_plugins_config` -获取插件设置

11. `update_plugins_config` -更新插件设置

12. `add_dialogue` -添加对话事件

13. `add_choice` -显示选项

14. `add_loop` -添加循环

15. `add_break_loop` -循环中断

16. `add_conditional_branch` - 条件分岐追加

17. `delete_event_command` -删除事件命令

18. `update_event_command` -更新事件命令

19. `add_actor` -添加操作者

20. `add_item` -添加项目

21. `add_skill` -添加技能

22. `draw_map_tile` -映射平铺绘制

23. `create_map` -新建映射

24. `show_picture` -显示图片

25. `inspect_game_state` -游戏状态检查

26. `run_playtest` -测试运行

27. `undo_last_change` -撤消上一次更改

28. `list_backups` -备份浏览

`mz://docs/event_commands` -事件命令参考