rpgmaker-mz-mcp

快速开始

Claude Code（推荐）——将 MCP 服务和创作技能作为一个插件一起安装：

claude plugin marketplace add Redseb/rpgmaker-mz-mcp
claude plugin install rpgmaker-mz@rpgmaker-mz-mcp

系统会提示你选择 RPG Maker MZ 项目目录（可选——你也可以稍后直接让 Claude 执行 set_project）。

其他 MCP 客户端——此服务已发布到 npm；无需克隆或构建：

{
  "mcpServers": {
    "rpgmaker-mz": {
      "command": "npx",
      "args": ["-y", "rpgmaker-mz-mcp@latest"],
      "env": { "RPGMAKER_PROJECT_PATH": "/path/to/your/rpgmaker/project" }
    }
  }
}

Claude Desktop——可以使用上面的 JSON 配置，也可以从 Releases 下载一键安装包 rpgmaker-mz-mcp.mcpb，并用 Claude Desktop 打开。

初次使用？请阅读 SETUP.md 查看完整操作指南，并阅读 EXAMPLES.md 查看端到端示例。

目录

• 快速开始
• 功能
• 工作原理
• 安装
• 配置
• 使用方法
• 可用工具
• 输入验证
• 事件验证（默认抛出错误）
• 引用检查
• 试运行预览
• 自定义图块集目录技能
• 示例提示词
• 开发
• 项目结构
• 安全与最佳实践
• 限制

功能

• 数据库 CRUD — 操作角色、职业（含特性与参数曲线）、技能（完整控制 + 简化版伤害／治疗／增益／状态辅助工具）、物品、武器、防具、状态、敌人与队伍。创建时只需提供 name；其他所有内容都会回退到编辑器实际使用的“新建 X”模板。
• 地图与地图树 — 创建／删除地图，批量调整父级／排序／重命名并防止循环，还可编辑地图属性。新地图会按编辑器预期的方式注册到 MapInfos.json。
• 图块绘制（自动自动拼接） — paint_tiles／fill_area 可在六个地图图层中的任意图层设置图块，并根据相同种类的相邻关系重新计算自动拼接形状（及其邻居），使填充区域的边缘正确衔接。paint_blueprint 可通过 ASCII 行 + 图例一次绘制整个区域（多图层单元格、目录名称、自动生成的 A4 墙面），并返回通行性概览。place_object 可放置多图块 B/C 类物体（房屋、树木），并报告其通行性覆盖范围。
• 语义图块目录 — find_tile "grass" → 可绘制的图块 ID。内置所有默认图块集（Overworld、Outside、Inside、Dungeon、SF）的目录，数据来源为 RPG Maker 自带的英文名称 sidecar 文件。附带的视觉引导技能可为自定义图块集建立目录。
• 通行性与地形 — 读取图块标记或地图单元格的分层通行性（get_tile_flags／check_passability），并编辑通行性／地形标签／行为标记（set_tile_flags）。
• 事件命令构建器 — 高级只读构建器，可生成与编辑器写入内容完全一致的 EventCommand 序列（包括复杂的递归分支块与续行），并通过 insert_event_commands 添加到页面。涵盖对话与流程、游戏状态变更、表现效果／转场，以及场景处理。
• 事件与 NPC 易用性 — create_npc 可通过一次调用放置完整的对话 NPC；set_event_page 可原地合并页面的图像与行为。
• 资源识别 — list_assets 可列出有效的角色／脸部／图块集／音频名称，避免事件引用不存在的文件。
• 查看并体验构建结果 — render_map 可按引擎绘制方式截取地图画面（整张地图或游戏画面视图）；run_playtest 可驱动脚本化的无头会话（载入状态、触发事件、读取对话、选择选项、行走、自动战斗、截图）。两者都会报告控制台错误与缺失资源。验证器能证明结构正确；这些工具则能展示玩家实际看到的内容。
• 正确性保障 — 使用 Zod 验证输入，事件验证默认采用抛错策略（结构无效的写入会被拒绝，不会保存后再发出警告），提供跨文件引用检查器（validate_references），并对每次写入提供试运行／差异预览。

工作原理

安装

任选一种方式：

• Claude Code 插件（推荐）— 运行 claude plugin marketplace add Redseb/rpgmaker-mz-mcp，然后运行 claude plugin install rpgmaker-mz@rpgmaker-mz-mcp。此插件将 MCP 服务（通过 npm 包中的 npx 运行）与两个创作技能（rpgmaker-authoring、tileset-catalog）打包在一起——这些技能可补充工具未强制执行的判断，因此这是完整体验。
• npm 包 — 配置 MCP 客户端运行 npx -y rpgmaker-mz-mcp@latest（参见快速入门）。仅含工具，不含技能。
• MCPB 包（Claude Desktop） — 从 Releases 下载 rpgmaker-mz-mcp.mcpb，用 Claude Desktop 打开，并在安装对话框中选择项目文件夹。
• 从源码安装（开发）：

npm install
npm run build

配置

将 RPG Maker MZ 项目路径设置为环境变量：

# macOS/Linux
export RPGMAKER_PROJECT_PATH=/path/to/your/rpgmaker/project

# Windows
set RPGMAKER_PROJECT_PATH=C:\path\to\your\rpgmaker\project

路径必须指向包含 game.rmmzproject 和含有 System.json 的 data/ 目录的文件夹。

环境变量仅用于设置启动默认值：set_project 工具可以将运行中的服务重新指向其他项目（get_project 会报告当前项目），因此切换游戏无需修改配置或重启。

使用方法

运行服务

npm start          # or: node dist/index.js

在 Claude Desktop 中配置

最简单的方法是使用 Releases 中的 .mcpb 包——用 Claude Desktop 打开它，然后选择项目文件夹。若要手动配置，请将以下内容添加到 Claude Desktop 配置文件中（Windows 上为 %APPDATA%\Claude\claude_desktop_config.json，macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "rpgmaker-mz": {
      "command": "npx",
      "args": ["-y", "rpgmaker-mz-mcp@latest"],
      "env": {
        "RPGMAKER_PROJECT_PATH": "/path/to/your/rpgmaker/project"
      }
    }
  }
}

（如果是从源码检出，请改用 "command": "node" 和 "args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]。）

可用工具

全部 128 个工具，按类别分组。写入项目的工具接受可选的 dryRun 参数（请参阅试运行预览）；可能拒绝结构无效的写入操作的工具也接受 force（请参阅事件验证：默认抛出错误）。

展开完整工具参考

项目定位

• get_project — 服务当前操作的项目：路径、有效性、游戏标题
• set_project — 在本次会话中将服务重新指向其他项目目录（无需重启；覆盖 RPGMAKER_PROJECT_PATH）

角色

• create_actor、update_actor、search_actors

职业

• create_class、update_class
• add_class_learning — 添加在指定等级习得的技能（验证技能有效性，并按习得等级排序）
• set_class_param_curve — 替换 8 条参数成长曲线中的一条

技能

• create_skill（完全控制——包括 Skills.json 中的每个字段，如 occasion、hitType、speed、repeats、successRate、tpGain、所需武器类型、message2、note；hitType 默认为：魔法技能使用魔法型，其他伤害技能使用物理型，治疗技能和友方目标范围技能使用必中型）、update_skill、search_skills
• create_damage_skill、create_healing_skill、create_buff_skill、create_state_skill — 面向自然语言的常见技能类型辅助工具

道具与装备

• create_item、update_item、search_items
• create_weapon、update_weapon
• create_armor、update_armor

状态

• create_state、update_state

敌人与队伍

• create_enemy、update_enemy、search_enemies
• create_troop、update_troop、search_troops — create_troop 会验证每个成员引用的敌人是否存在
• build_troop_page — 根据紧凑触发条件（when：turn [a, b]、enemyHpBelow [slot, pct]、actorHpBelow [actorId, pct]、switch、turnEnd，条件之间为 AND 关系）和 span（battle / turn / moment）构建战斗事件页 { conditions, list, span }，无需手动构造包含 12 个字段的条件对象。只读
• add_troop_page — 向队伍追加（或在 position 处插入）一个页面，无需重新发送其他页面；如果 HP 条件指向超出队伍成员范围的位置，则会发出警告

公共事件

• create_common_event、update_common_event
• call_common_event — 构建 code-117 调用命令，并验证目标是否存在

地图与地图树

• get_map（对于大型地图，传入 includeData: false 可省略图块数组）、get_map_infos、get_map_dimensions、update_map
• get_map_region — 读取一段图块 ID（x、y、width、height、layer），而不是整张地图
• create_map — 分配下一个 ID、写入空白地图，并将其登记到树中
• delete_map — 移除地图，并将其子项重新挂到其父项下
• update_map_tree — 批量更改父项、排序、重命名和展开；操作前会检查对象是否存在并防止循环引用

### 地图事件

• get_map_events、get_map_event、search_map_events
• create_map_event、update_map_event、delete_map_event
• add_event_command — 向事件页面追加单条命令
• set_map_tile — 在 z 层的 (x, y) 处设置单个原始图块 ID（不进行自动拼接）

事件与 NPC 使用便捷功能

• create_npc — 一次性创建“对话 NPC”：包含图像、触发条件，以及根据 text 生成的对话列表（可选通过 wrap 自动换行），或显式指定的 commands
• create_chest — 一次性创建宝箱：采用两页自开关惯用模式（给予物品、武器、防具或金币，然后不再触发）
• create_transfer — 一次性创建地图转移，支持两种可用模式：面向固定地标（action_button）或踩上门垫（player_touch）
• set_event_page — 原位合并页面的图像与行为（精灵、触发条件、优先级、移动、标记）

事件命令构建器

只读构建器，返回符合编辑器格式的 EventCommand 序列；使用 insert_event_commands 将其放入命令列表。

• 对话与流程： build_show_text (101/401)、build_show_choices (102/402–404)、build_conditional_branch (111/411/412)、build_flow_command（等待/退出/标签/跳转）
• 游戏状态： build_control_switch (121/123)、build_control_variable (122)、build_change_gold (125)、build_change_items (126–128)、build_change_party_member (129)
• 演出与转场： build_transfer_player (201)、build_play_audio（BGM/BGS/ME/SE）、build_screen_effect（淡入淡出/色调/闪光/震动）、build_picture（显示/擦除）、build_character_effect（动画/气球）
• 场景： build_battle_processing (301)、build_shop_processing (302/605)、build_name_input (303)、build_change_actor（HP/MP/状态/恢复/EXP/等级，311–316）
• 战斗（队伍页面）： build_battle_command — 敌人出现 (335，揭示隐藏成员)、更改敌人状态 (333，单个槽位或整个队伍)、中止战斗 (340)
• 插入： insert_event_commands — 将构建好的序列拼接到地图事件页面（默认的 target）、公共事件主体或队伍战斗事件页面中，然后进行验证

移动路线

• create_move_route — 根据命名模式（巡逻/接近/逃离/游荡/自定义）构建 MoveRoute
• set_movement_route — 插入强制设置移动路线命令（代码 205 + 505 后续行）

插件命令

• scan_plugins — 通过解析 js/plugins/*.js 注释，发现本项目实际拥有的插件命令（启用状态来自 js/plugins.js）
• list_plugin_commands — 查看已知插件命令（将项目扫描结果合并到内置允许列表中）
• create_plugin_command — 构建参数已规范化的代码 357 插件命令

图块、目录与绘制

• describe_tile — 解码原始图块 ID（图块表、自动拼接类型/形状、几何信息）
• get_tile_catalog、find_tile — 查询人类可读名称 ↔ 可绘制图块 ID（find_tile 可通过 searchDescriptions 将搜索范围扩展到自定义图块表的目录描述）
• paint_tiles、fill_area — 使用自动拼接绘制
• paint_blueprint — 在一次写入中，根据 ASCII 蓝图和图例绘制整个区域：每个字符对应 [layer, tile] 对，使用目录名称而非 ID；支持 { wall: { top } } 条目，其垂直连续部分的底部单元会转换为墙侧（正面）类型（顶部 + 8 种类型）；清除过时的上层图块；返回各层计数以及 #/. 通行性地图
• place_object — 放置多图块 B/C 类物体，并报告其通行性占用范围

图块表标记（通行性 / 地形）

• get_tile_flags — 解码图块的通行性/星形/梯子/草丛/柜台/伤害/地形标记
• check_passability — 针对地图单元格的分层通行性判定结果
• set_tile_flags — 编辑图块标记（非破坏性合并；自动应用到自动拼接类型的全部 48 个形状槽位）

资源

• list_assets — 枚举可用资源的基本文件名（角色、脸部、图块表、图片、音频等）

Web 导出

• export_web — 构建适用于 itch.io 或任何静态托管服务的精简 HTML5 部署包：包含 index.html、js/、css/、fonts/、icon/ 和 data/*.json，以及仅包含有引用的 img/、audio/、movies/ 文件（数据文件中的每个字符串、核心引擎脚本和插件中的字符串字面量、插件的 @default；始终保留 img/system/，并保留每个已保留音轨的所有 .ogg/.m4a 变体）。Effekseer 特效也会以相同方式精简：只有当某个 effects/*.efkefc 的名称是真正的特效引用（动画的 effectName、事件中的 Plugin Command 参数，或插件参数/字符串，而不是其他数据字符串；因此，名为 Poison 的状态或动画不会导致保留 Poison.efkefc）时才会保留该文件，并同时保留文件中列出的纹理/模型；如果某个已保留的特效无法解析，则会保留 effects/ 中的所有纹理和模型。若没有任何特效引用，则不会导出 effects/ 文件夹。将文件夹写入 outDir，并在使用 zip（默认值）时写入 <outDir>.zip，其中 index.html 位于压缩包根目录。返回文件数/字节数、保留/丢弃的资源数量和路径（包括特效）、System.advanced 中的屏幕尺寸（将其用作 itch 的嵌入尺寸），以及超出 itch 的 1000 个文件/每文件 200 MB 限制的警告。prune: false 会复制所有资源——如果插件在运行时构建资源名称，请使用此选项。不会在项目内写入任何内容；outDir 不能是项目目录，也不能位于将要复制的文件夹内；只有当现有的非空 outDir 是之前 export_web 的输出时，才会替换它。

无头渲染和试玩

在无头 Chromium 中启动项目自身的 index.html，检查验证器无法检查的内容：地图的外观和实际游玩体验。只读——不会在项目内写入任何内容；除非传入 out，否则 PNG 会写入 <os tmpdir>/rpgmaker-mz-mcp/renders/。传入 inline: true，还可在工具响应中以图像内容的形式返回 PNG。

• render_map — 截取单张地图。默认情况下，它会将整张地图渲染为一张图片（画布会调整为 width×height×48 px，隐藏玩家，冻结自动运行／并行事件，以免过场动画遮住地图，并关闭地图名称横幅）。传入 x 和 y，则会改为获取以该图块为中心的普通 816×624 游戏画面（显示玩家）。showEvents: false 会绘制不带事件的图块；switches 会先打开开关，以查看后续剧情状态；runEvents: true 则允许事件运行。返回 PNG 路径和 problems：包括控制台错误、页面错误和 HTTP 404。缺失的图片会显示为空白，并列在其中，而不会让引擎停留在加载错误画面。地图任一边超过 4800 px 时，必须使用 x／y 视图。

• run_playtest — 在同一个浏览器会话中运行一系列步骤。每个步骤都会返回 ok 和详细信息；运行会在首个失败步骤处停止：

  • load {mapId, x, y, direction?, party?, level?, gold?, switches?, variables?, selfSwitches?, items?, equip?, encounters?} 会在指定位置和状态下开始新游戏。除非设置 encounters: true，否则关闭随机遇敌。
  • startEvent {eventId} 会触发地图事件，并运行至显示文本或进入空闲状态。如果事件让玩家转移地图，该步骤会等待新地图加载，并通过 transferredTo {mapId, x, y} 报告新位置。
  • advanceText {maxMs?} 会按下确认键，直到事件进入空闲状态。若出现未关闭的选项列表或战斗，则会提前停止，并返回显示的消息行（含说话者名称）及任何未关闭的选项。战斗期间显示的文本会单独返回为 battleLines，不会与地图事件的对话混在一起。
  • choose {index} 会选择从 0 开始计数的选项。
  • walk {direction, steps?} 会逐格行走，并报告结束所在的图块（to）。如果某个图块无法进入，会同时报告玩家所在图块（stoppedAt）和阻止进入的图块（blockedTile），便于查找隐形墙。触碰事件触发时会提前停止；如果该事件是门，则会等待转移完成，因此 to 和 transferredTo 指向新地图。eventRunning／messageOpen 会说明事件是否仍在运行（接下来调用 advanceText）。
  • press {button, times?} 和 wait {ms}。
  • autoBattle {troopId?, canEscape?, canLose?, maxMs?} 会自动进行已开始的战斗，或启动 troopId 指定的战斗，使用自动 AI，并在 maxMs 后放弃（默认 60 秒）。它会报告 victory／defeat／escaped、双方最终 HP，以及战斗消息 lines（敌群战斗事件、胜利文本）。战斗会快进：引擎每绘制一帧就运行 20 帧，因此战斗过程与正常情况完全相同（逻辑和概率都一样），只是更快。10 回合的 Boss 战约需 5 秒，而不是 80 秒。在运行时传入 realtime: true 可按正常速度观看战斗，并相应调高 maxMs。只有战斗会加速；地图、行走和对话都以正常速度运行。
  • screenshot {name?} 会保存 PNG。
  • eval {script} 会返回在游戏页面中求值的 JS 表达式的结果，例如 "$gameSwitches.value(3)"。

  返回的文本（lines、battleLines、choices、说话者名称）与消息窗口显示的内容一致。\V[n]、\N[n]、\P[n] 和 \G 会根据当时的游戏状态替换；\C[n]、\I[n]、\{、\. 和 \| 等控制代码会被移除，因此胜利文本会返回为 获得了 92 EXP！。

  响应最后会包含 finalState（场景、地图、位置、金币、队伍）和 problems。如果事件或消息仍在运行（例如 load 后地图的自动运行过场动画），startEvent 和 autoBattle 会拒绝启动，并提示你先调用 advanceText。 要求。 两个工具都需要 playwright-core。它是可选依赖项，因此安装失败不会影响其他工具；这两个工具只会返回一条错误，告诉你如何修复。它们还需要 Chromium。不会下载浏览器：服务会使用 Playwright 缓存（~/Library/Caches/ms-playwright、~/.cache/ms-playwright、%LOCALAPPDATA%\ms-playwright 或 PLAYWRIGHT_BROWSERS_PATH）中最新的 chrome-headless-shell（或完整 Chromium）。如果没有，请运行 npx playwright install chromium-headless-shell，或将 RPGMAKER_MCP_CHROMIUM 设置为任意 Chrome/Chromium 可执行文件。每次调用的启动时间约为 1–2 s，此外还要加上脚本的运行时间。

长时间运行。 带有长过场动画或 realtime 战斗的 run_playtest 脚本可能需要一分钟或更久，超过了许多 MCP 客户端的默认等待时间（TypeScript SDK 会在 60 s 后放弃，并返回 -32001 Request timed out）。如果客户端发送了 progressToken，服务会在每个步骤以及长步骤期间每隔 5 s 发送一次进度通知，因此使用 resetTimeoutOnProgress（或更长超时时间）的客户端会继续等待。如果客户端无法做到这两点，请将脚本拆分为几次较短的运行。

系统与词汇

• get_system、get_game_title、update_game_title
• get_title_screen、update_title_screen — 背景图层、BGM 和“绘制游戏标题”开关
• get_variables、set_variable_name、get_switches、set_switch_name
• get_starting_position、update_starting_position
• get_party、set_party — 初始队伍（set_party 会验证每个角色 ID）
• get_terms、set_term — 菜单词汇
• get_types、set_type_name — 元素／技能／武器／护甲／装备类型名称列表
• set_currency_unit

批量创建

• batch_create — 在一次调用和单次文件写入中创建多个同类型记录（角色、物品、武器、护甲、技能、敌人、状态、职业）；ID 按顺序分配，因此记录可以引用同一批次中较早创建的记录；匹配的 create_* 工具不接受的记录字段会作为警告返回，而不会被悄悄丢弃

删除记录

• delete_record — 通过将对应槽位设为 null，删除一条数据库记录（角色、职业、技能、物品、武器、护甲、敌人、队伍、状态、公共事件），不会导致其他 ID 变动；会报告删除后留下的所有悬空引用，如果存在此类引用则拒绝删除，除非设置 force: true
• reset_table — 清空整张表，但保留 keep 中的 ID（例如，reset_table('skill', { keep: [1, 2] }) 会清除 RTP 技能，但保留攻击／防御）；保留的记录仍位于原 ID 处，会裁剪末尾的空槽，并且会像 delete_record 一样，在存在悬空引用时拒绝操作

索引与验证

• list_names — 获取表的轻量级 { id, name } 索引（角色、物品、技能、地图、敌人等）
• get_database — 获取某张表的完整记录（actors、classes、items、weapons、armors、skills、enemies、troops、states、common_events），也可以通过 id 获取单条记录
• validate_event、validate_project — 验证事件命令结构（只读）
• validate_references — 跨文件 ID 完整性审查（队伍→角色、传送→地图、效果→状态／技能／公共事件、掉落物→物品、“更改物品”／“商店”／“战斗处理”→物品／队伍、遭遇→队伍、地图树循环等）

ID 分配

• list_allocated_ids — 列出已被占用的开关／变量／公共事件 ID，数据来源于项目自身的 JSON；指定 id 后，会列出引用该 ID 的每个位置
• next_free_id — 预留下一个未分配的 ID（或多个 ID），无需手动挑选

输入验证

每个工具都会将其参数声明为 Zod 模式。服务基于 MCP SDK 的高级 McpServer 构建，会在处理器运行之前根据该模式验证传入参数，因此格式错误的调用会被拒绝，并清楚地指出出错字段，返回 Input validation error，而不是将垃圾数据写入磁盘。

事件验证（默认拒绝写入）

事件命令列表会根据已知的 RPG Maker MZ 命令代码表（101 显示文本、201 转移玩家、122 控制变量，……）以及这些命令构成的块结构进行检查。检查结果分为两个等级，等级决定对写入的处理方式：

• 结构性问题 — 已知命令的参数数量错误（包括取决于条件分支的条件类型或控制变量的操作数类型的参数数量）、列表未以代码 0 结束标记结尾、parameters 不是数组、块结构错误（显示选项／条件分支／循环未闭合、分支行或闭合行孤立或缩进错误、选项没有对应的 When 分支），或按钮触发事件被留在不可通行的地块上。这些几乎总是错误，因此事件写入工具会在提交前验证即将写入的结果，并拒绝写入：工具会报错，不会有任何内容写入磁盘。传入 force: true 即可强制写入（只有可能拒绝写入的工具才会注明此参数）。
• 提示性问题 — 无法识别的命令代码（可能只是插件命令）、过长的文本行、未知的资源文件名、选项块的取消处理方式与 When Cancel 分支不一致（存在无效代码，但不构成损坏）。这些情况确实可能出现，因此不会阻止写入；它们会作为 warnings 随正常响应一并返回。

由于检查在提交前运行，若某次写入会被拒绝，那么对应的 dryRun 也会失败，而不会预览一个根本无法执行的写入。

validate_event / validate_project 仍然是只读审计：它们会报告这两个等级的问题（每条结果都包含 severity），且不会更改任何内容。

文本宽度：让它了解你的字体

默认情况下，超长文本行警告按字符数衡量——普通情况下每行 55 个字符，显示脸部图像时为 38 个字符，这适用于 RTP 自带字体，无需设置。如果项目使用了其他字体，这个估算就会朝两个方向之一出错：更窄的字体会让它警告那些本来能轻松容纳的行；更宽或更大的字体则会让它对实际被截断的行保持沉默（在 616px 的窗口中，24px 字形的 38 个字符宽达 912px）。没有一个字符数限制能同时解决这两种情况，因为比例字体中各字形的宽度差异很大——句号的宽度可能只有大写字母的三分之一。

在项目根目录中添加 .rpgmaker-mcp.json，即可用实际测量值替代估算：

{
  "text": {
    "lineBudget": { "noFace": 784, "withFace": 616 },
    "nameBudgetChars": 8,
    "charWidths": { "_default": 13, "a": 11.38, ".": 4.88, " ": 8.12 }
  }
}

• lineBudget — 消息窗口可用宽度，分别设置有和没有脸部图像时的值。如果提供 charWidths，单位为像素；否则单位为字符数（单独使用 lineBudget 时，就是覆盖字符数限制）。
• charWidths — 每个字符的字宽；_default 用于未单独列出的字符。可直接从引擎中获取这些值：在运行中的游戏里使用 Window_Base.textWidth(c.repeat(40)) / 40，即可得到精确结果。
• nameBudgetChars — 假设 \N[3] / \P[1] 渲染所占的宽度。名称由玩家在运行时输入，因此应按名称输入的 maxLength（通常为 8）预算，而不是使用默认名称；否则，测试时能容纳的行可能会被长名称撑溢出。默认值为 0，与之前一样忽略名称转义码。

所有情况都会安全回退：没有文件、JSON 错误或 text 部分格式错误时，都会沿用内置估算，因此配置损坏也不会比没有配置更糟。文件的 mtime 变化时会重新读取，此时警告会报告实际宽度（Show Text line is 650px but the message window fits 616px with a face shown）。

自动换行。 无需手动修复溢出行，只需将 wrap: true 传给 build_show_text 或 create_npc，并编写完整段落：文本会按警告检查所用的宽度（默认估算值或 .rpgmaker-mcp.json 中的度量值）进行词语换行（转义码如 \C[n] 不计入宽度，也不会被拆分），并按需拆分为多个 4 行消息框，每个消息框使用相同的脸部图像和说话者。wrap: true（或 "soft"）会将每条目重新排版为一个段落；"hard" 则会保留每条目和 \n 作为强制换行，只对过长的行进行换行。

引用检查

validate_references 会执行跨文件 ID 完整性审计，与上文的命令结构检查相互独立。它会遍历整个数据库，标记指向不存在对象的引用：没有对应角色的初始队伍成员、目标地图不存在的 Transfer Player、添加了不存在状态的技能效果、掉落未知物品的敌人、循环的地图树父级，以及其他类似问题。默认情况下，每项检查都只发出警告，并会避免在项目仅部分加载时产生误报。

删除记录和重置表

新的 MZ 项目包含带有 RTP 风格的数据库行，其图标、动画和战斗图都指向 RTP 素材。完全替换这些素材后，自然的工作流程就是“清空数据库，然后编写自己的内容”——reset_table 是第一步，delete_record 则用于删除单行记录。

数据库数组采用 索引 = ID 的方式，因此这两个工具都会将槽位设为 null，而不是从数组中移除：不会重新编号，也不会让仍然存在的引用悄悄指向其他记录。reset_table 会让每个 keep ID 保留在原索引处，并删除末尾的空槽位（没有保留任何内容的表会变成 [null]）；之后通过 create_* / batch_create 创建的新记录会从最高的有效 ID 开始分配。

写入之前，这两个工具都会运行 validate_references 审计，分别检查移除记录前后的情况，并只保留因移除记录而新增的问题（原本就已失效的引用不会归咎于这次操作）。删除技能 1（攻击）、技能 2（防御）或状态 1（战斗不能）也始终会报告，因为引擎将这些 ID 硬编码了。如果有任何引用会失效，写入就会被拒绝，不会写入磁盘——传入 force: true 可继续操作，或传入 dryRun: true 预览将删除的内容和可能造成的问题（dry-run 会报告 requiresForce，而不是抛出异常）。扫描范围与 validate_references 相同，并会在 coverage 字段中注明：不会扫描特性、角色初始装备、事件页条件、条件分歧操作数以及脚本／插件命令。

reset_table({ type: 'skill', keep: [1, 2], dryRun: true })   // what goes, what breaks
reset_table({ type: 'skill', keep: [1, 2], force: true })    // do it
batch_create({ type: 'skill', records: [...] })              // author the replacements

ID 分配

开关、变量和公共事件 ID 共用一个全局命名空间，而 RPG Maker 不会阻止后续编辑使用已经被先前内容占用的 ID。这种问题不会明显报错——不会崩溃，也不会被验证器发现，只会在试玩数小时后发现某扇门莫名其妙地已经打开。

list_allocated_ids 会直接从项目文件中回答“哪些 ID 已被占用？”——它绝不会依赖手动维护的列表，因为只要有人在 RPG Maker 编辑器中编辑过，列表就可能过时。如果一个 ID 已被声明（例如 System.json 中的标签、CommonEvents 行），或在任何位置被引用，就会被视为已分配：事件页条件和命令列表、公共事件、敌群页，以及公共事件技能／物品效果。这两方面都很重要——有名称但未使用的开关，是有人预先占用的 ID；已使用但没有名称的开关，则是有人使用却没有登记的 ID。传入 id 可查询更具体的问题：在修改开关 23 之前，它到底在哪里被使用？

next_free_id 会返回下一个尚未分配的 ID（或多个 ID），且严格大于所有已占用的 ID。默认情况下，最高 ID 以下的空缺会保留不动（空缺 ID 往往已记在笔记中，只是还未写入）；只有在有意压缩 ID 时，才使用 reuseGaps: true 填补空缺。此工具为只读工具——它只建议 ID，不会写入，因此请使用 set_switch_name / set_variable_name 为已选用的 ID 命名，让之后编辑的人能看到这一占用记录。当 ID 超出名称列表范围时，这两个工具会扩展 System.json 中的名称列表，因此无需打开编辑器，也总能为 next_free_id 返回的 ID 添加名称。

与命令验证器类似，用法扫描经过精心筛选，并非穷尽所有情况：它会扫描携带开关／变量 ID 的命令（控制开关／变量、条件分歧、角色转移中的“通过变量指定”形式、变更金钱／物品、变更 HP／MP／经验值／等级等），并在每份报告中注明扫描过的命令代码。若某个 ID 仅在 Script（355）或插件命令（357）中使用，就会被视为可用。

试运行预览

每个会写入项目的工具都接受可选的 dryRun 参数。当 dryRun: true 时，工具会计算它_将要_写入的内容，并返回差异，而不会触碰任何文件：

{
  "dryRun": true,
  "wouldChange": [
    {
      "file": "System.json",
      "changed": true,
      "diff": {
        "changes": [{ "path": "gameTitle", "from": "Old Title", "to": "New Title" }],
        "truncated": false
      }
    }
  ],
  "wouldReturn": { "...": "what the tool would have returned, warnings included" }
}

wouldReturn 包含工具原本会生成的响应，因此试运行也会预览写入操作会报告的验证警告，而不仅仅是差异。

所有写入操作都经过同一个处理入口，该入口会跳过无操作写入，并确保磁盘上的 JSON 保持编辑器使用的紧凑单行格式。文件删除（例如 delete_map）也使用相同的试运行机制。

精简写入回显

回显整条记录的写入工具，代价由那个总是承担这笔开销的调用方支付——也就是上下文资源十分有限的 AI 助手。因此，原本会重放命令列表或地图事件的工具默认返回摘要：

工具	回显内容
update_map、resize_map	不含图块 data 或 events 的地图，以及 dataTileCount / eventCount
update_map_event、set_event_page、add_event_command	事件标识 + 各页面的 trigger / priorityType / moveType / 图像 / listLength
insert_event_commands	listLength + listCodes——生成的命令代码，不含参数
create_common_event、update_common_event	标识、触发器配置、listLength + listCodes
create_troop、update_troop、add_troop_page	标识、成员、各页面的 listLength

规则：**保留你会据此断言的内容，省略你只会重新读取的内容。**保留命令代码，因为它们能用于验证拼接是否落在指定位置（302 是否仍在两个 101 之后）；省略命令参数，因为它们正是你刚写入的内容。

在上述任意调用中传入 verbose: true，即可获取旧版的完整记录；也可以通过 get_map / get_map_event / get_database 重新读取。摘要始终会保留 warnings，而试运行的 wouldReturn 也会以同样的方式生成摘要，因此预览和实际调用返回的结构一致。

在一次真实创作会话的六次调用中测得：115,080 → 3,672 个字符（-97%）。一次仅设置地图 BGM 的 update_map 调用，就曾向调用方回显 46,846 个字符的对话内容。

自定义图块集目录技能

默认图块集开箱即已编入目录。随附 RPG Maker .txt 名称辅助文件的非默认图块表（img/tilesets/<Sheet>.txt，每个图块一行 Name|日本語名——商业 DLC 包中包含这类文件）也会自动编入目录：其名称会以 source: 'sidecar' 的形式返回，无需目录文件。每个图块的优先级为：人工验证的（manual）data/tilecatalog/ 条目 > 辅助文件 > 视觉草稿。对于没有辅助文件的自定义（非 RTP）图块集，.claude/skills/tileset-catalog/ 下附带的 Claude 技能会将每张图块表切分为带标签的样本，让 Claude 通过视觉识别命名，并将带版本信息、限定于项目的目录写入 data/tilecatalog/——之后，find_tile / get_tile_catalog 也能解析该图块表中的名称。这些草稿还会记录每个图块的外观，因此当机器生成的名称过于简短、不便搜索时，find_tile 配合 searchDescriptions: true 也能匹配这些描述。该技能附带无依赖的 PNG 编解码器和与引擎完全一致的图块几何规则，因此只要能运行 Node，就能运行该技能。

示例提示词

完成配置后，就可以用自然语言操作项目：

• “创建一个名为 'Fireball' 的火焰技能，消耗 15 MP，对一个敌人造成 a.mat * 4 - b.mdf * 2 点伤害。”
• “在世界地图下添加一张新的城镇地图，尺寸为 30×25，使用 Outside 图块集。”
• “在地图 3 的 (4，4) 位置绘制一个 10×8 的草地矩形，并让它自动生成边界。”
• “在地图 2 的 (8，5) 位置放置一个名为 'Guard'、会说 'Halt! Who goes there?' 的对话 NPC。”
• “让图块集 1 中的水面图块不可通行，并将其地形标记设为 1。”
• “发布前检查我的项目是否存在失效引用。”

开发

npm run build         # Compile TypeScript to dist/
npm run typecheck     # Type-check without emitting (tsc --noEmit)
npm run dev           # Compile in watch mode
npm run lint          # ESLint
npm run lint:fix      # ESLint with autofix
npm run format        # Format with Prettier
npm run format:check  # Check formatting (used in CI)
npm test              # Vitest
npm run sync:tools    # Re-stamp the tool count into the README + SVGs (see below)
npm run sync:version  # Re-stamp package.json's version into the packaging manifests
npm run bundle:mcpb   # Build the one-click Claude Desktop bundle (rpgmaker-mz-mcp.mcpb)

开发期间，你可以跳过构建，使用 tsx 直接从源代码运行服务：将 MCP 客户端的 command 指向 node_modules/.bin/tsx，并将 src/index.ts 作为参数。由于 tsx 不会进行类型检查，提交前请同时运行 npm run typecheck、lint 和测试。

每次推送和拉取请求都会触发 CI，运行 lint、格式检查、工具数量同步检查、测试和构建（参见 .github/workflows/ci.yml）。

保持工具数量同步

对外公布的工具数量显示在几个面向用户的位置：README 正文和徽章，以及 assets/ 中的两个 SVG。npm run sync:tools 会统计 src/tools/ 中的实际工具数量，并更新所有这些位置，因此添加工具后，只需运行一条命令即可更新数量。npm run sync:tools:check（在 CI 中运行）会在任何位置的数量过期时失败。

发布

package.json 是版本号的唯一真实来源；npm run sync:version 会将版本号写入插件清单（.claude-plugin/plugin.json）、MCP 注册表元数据（server.json）和 MCPB 清单（mcpb/manifest.json）。如果这些文件中的版本不一致，CI 和 prepublishOnly 都会失败。发布流程如下：

npm version minor --no-git-tag-version   # or patch/major — bumps package.json only
npm run sync:version                     # stamp it into the other three manifests
git commit -am vX.Y.Z                    # one commit, with every manifest already correct
git tag vX.Y.Z                           # tag it afterwards, so nothing rewrites it
git push && git push origin vX.Y.Z

npm publish                 # publish to npm (runs the full gate via prepublishOnly)
mcp-publisher publish       # update the MCP registry listing (server.json; login: mcp-publisher login github)
npm run bundle:mcpb         # build rpgmaker-mz-mcp.mcpb
gh release create vX.Y.Z rpgmaker-mz-mcp.mcpb --title vX.Y.Z --notes "..."   # publish the GitHub release + attach the bundle

Claude Code 插件无需单独发布——用户安装的版本会从此仓库更新（该插件通过 npx rpgmaker-mz-mcp@latest 运行 npm 包，因此发布新工具只需更新 npm 包）。

最后再打标签，绝不要修改已打标签的提交。 单独运行 npm version 会在 sync:version 更新其他清单前提交并打标签，因此旧流程随后会修改提交，导致标签指向修改前的提交，清单过期，而且提交也脱离了分支。--no-git-tag-version 可以避免这些问题：先创建一个提交，再打标签。按名称推送标签（在这里很容易误用 --follow-tags），并且不要跳过 gh release create——在此之前的步骤都不会创建 GitHub 发布。

项目结构

rpgmaker-mz-mcp/
├── src/
│   ├── index.ts              # McpServer bootstrap: registers every tool, dispatch + dry-run
│   ├── registry.ts           # ToolDefinition shape + shared dryRun schema
│   ├── tools/                # One module per area (actors, items, skills, maps, battle,
│   │                         #   classes, states, common events, moves, plugins, tiles,
│   │                         #   catalog, paint, objects, tilesets, system, assets,
│   │                         #   event-command builders, event pages, list, validation)
│   ├── events/               # Pure event-command builders (no I/O)
│   ├── tiles/                # Tile subsystem: codec, autotile solver, paint core,
│   │                         #   flag codec, and the semantic catalog
│   ├── playtest/             # Headless engine driver: Chromium discovery, static server,
│   │                         #   render_map + run_playtest (optional playwright-core)
│   ├── validation/           # Known-command tables + event/move/plugin/reference validators
│   └── utils/                # File I/O, the commit choke point, and RPG Maker MZ types
├── test/                     # Vitest suite
├── scripts/
│   └── sync-tool-count.mjs   # Re-stamps the tool count into the README + SVGs
├── assets/                   # Banner + architecture SVGs
├── .claude/skills/
│   └── tileset-catalog/      # Vision catalog-bootstrap skill for custom tilesets
├── dist/                     # Compiled JavaScript (gitignored)
└── README.md

安全与最佳实践

1. 使用此服务时，请关闭 RPG Maker MZ 编辑器——该服务会直接写入 JSON 文件，而编辑器可能在保存时覆盖更改。
2. 为项目使用版本控制。结合试运行预览和验证，git 可以作为安全保障（该服务不会自动创建备份）。
3. 提交破坏性编辑前，使用 dryRun: true 预览。
4. 进行重大更改后，请在引擎中测试。

限制

• 直接写入 JSON 文件；为避免冲突，必须关闭编辑器。
• 插件命令会根据项目实际包含的插件进行验证（scan_plugins 会解析插件的 @command/@arg 注释），如果没有匹配项，则回退到内置的小型允许列表。由于 RPG Maker MZ 没有“必需参数”注释，扫描到的参数只会检查是否包含未知名称，不会检查是否缺少参数；没有注释块的插件会未经检查直接通过。
• 此服务不会编辑动画（Animations.json，基于 Effekseer）。

致谢

本项目最初是 k4zuki0539/-rpgmaker-mz-mcp（MIT）的一个分支，该项目提供了最初的 CRUD 脚手架。此后，本项目已远超最初的范围，发展为可完整创作原版关卡设计和游戏逻辑（参见功能），如今作为独立项目维护。感谢原作者奠定了基础。

许可证

MIT

资源

• RPG Maker MZ 官方网站
• Model Context Protocol 文档
• RPG Maker MZ 数据库结构