rpgmaker-mv-mcp

RPG Maker MV MCP 服务

一个 Model Context Protocol 服务，可将 AI 助手 （Claude Code、Claude Desktop 或任何 MCP 客户端）变成 RPG Maker MV 项目的协作开发者，并自动备份它修改的所有内容。

你可以向助手提出这样的问题：

“创建一个火球技能：造成魔法伤害，a.mat * 4 - b.mdf * 2，消耗 12 MP，火属性。” “找出游戏中所有提到市长的事件。” “在城堡门口添加一个会说‘站住！来者何人？’的守卫。” “重新平衡所有武器：攻击力全面提升 10%。” “验证项目——有没有损坏的内容？”

亮点

• 完整数据库访问 — 通过精简的通用 CRUD 接口，访问全部 12 种数据库类型（actors、classes、skills、items、weapons、 armors、enemies、troops、states、animations、tilesets、common events）以及 System.json。
• 高级技能构建器 — 只需提供名称和公式，即可创建完整且符合编辑器要求的伤害 / 治疗 / 增益 / 状态技能。
• 地图和事件 — 创建地图，创建 / 编辑 / 删除事件，批量插入事件指令，添加对话并自动拆分消息框，还可查阅内置的事件指令代码参考。
• 图块集和地图绘制 — 检查图块集（图块表、自动图块类型、通行性），查看图块表图像，切换地图的图块集，并通过矩形、洪水填充和单个格子绘制地面、水面、墙壁和物件。自动图块的边缘和角落会完全按照编辑器的方式计算，因此绘制的地图在游戏中效果正确。render_map 会以文本形式显示结果。
• 查看地图 — render_map_image 将地图渲染为 PNG，包含真实的图块集图像、自动图块、阴影、事件精灵、带编号的事件标记、区域 ID 和可选网格，让助手能够查看自己创建的内容，而不是盲目操作。
• 地图连接器 — connect_maps 一次调用即可在两张地图上双向放置传送玩家门（包括出生格、淡入淡出和音效）；list_map_connections 会显示地图关系图、单向门、无效目标以及无法抵达的地图。
• 批量编辑与平衡调整 — bulk_update_records（“所有武器的攻击力 +10%”）支持试运行差异对比；generate_param_curve / generate_enemy_scaling 用于生成属性曲线；balance_report 可检查职业曲线、伤害与敌人 HP 的关系以及敌人威胁度；simulate_battle 使用真实伤害公式进行队伍对队伍的蒙特卡洛模拟。
• 本地化 — export_texts / import_texts 通过 CSV 或 JSON 导入导出游戏中的所有文本（数据库、系统术语、地图名称、对话、选项、战斗事件），保留控制代码，并将较长对话拆分到额外的消息框中。
• 技能文件、提示词和资源 — 内置 SKILL.md 工作流指南、作为 MCP 资源提供的参考表，以及现成提示词（new_town、balance_check 等），参见 技能、提示词和资源。
• 全局搜索 — 跨所有数据库进行子字符串搜索，并搜索每张地图上的所有事件，包括事件指令列表内部（查找显示某句对话或运行某段脚本的事件）。
• 插件管理 — 启用 / 禁用 / 配置插件、搭建新插件框架、编辑插件源代码，所有操作均采用编辑器自己的 js/plugins.js 格式。
• 游戏测试控制 — 通过 NW.js 启动游戏（自动检测常见安装位置）并捕获 stdout/stderr，或通过内置 HTTP 服务托管游戏，供浏览器访问。
• 创作辅助工具 — build_dialogue_tree 可将嵌套对话和选项、过场效果（淡入淡出、音频、图片、移动路线等）以及游戏流程指令（战斗、商店、物品、队伍、场景等）编译为缩进正确的事件指令；create_event_from_template 一次调用即可创建宝箱、上锁的门、旅店、商店、存档点和 NPC。参见 过场和游戏流程节点。
• 资源 — import_asset 将图像和声音复制到项目中，list_assets 显示已有资源及其用途，preview_asset 让助手查看图像。参见 资源。
• 地图生成和印章 — generate_map 可生成带有入口 / 出口 / 宝箱标记的种子地牢和洞穴；capture_stamp / place_stamp 可重复使用手工制作的地图片段。 参见 地图生成和印章。
• 分析 — audit_assets、lint_events 和 simulate_event 可在不启动游戏的情况下检查事件或整个项目，参见 分析。find_usages 会显示某个 ID 在何处被读取、写入或使用，check_references 会查找指向不存在记录的引用，analyze_progression 则会分析哪些地图和事件能够抵达，参见 使用情况和进度分析。
• 安全保障 — 每个文件在每个会话首次修改前都会快照到 .mcp-backups/；restore_backup 可回滚任何更改，validate_project 可在发布前发现无效引用，而 变更集可让你暂存一批编辑、一步提交并撤销。

安装

需要 Node.js 18+。

快速开始（npm）

Claude Code 或 Claude Desktop 用户最简单的方式：

npm install -g @xerolo44/rpgmaker-mv-mcp

然后进行配置（见下文）。该软件包可在 npmjs.com 和 MCP Registry 上获取。

配置 Claude Code

claude mcp add rpgmaker-mv -- npx @xerolo44/rpgmaker-mv-mcp --project "/path/to/YourGame"

配置 Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "rpgmaker-mv": {
      "command": "npx",
      "args": [
        "@xerolo44/rpgmaker-mv-mcp",
        "--project", "/path/to/YourGame"
      ]
    }
  }
}

--project 是可选的；如果不指定，请让助手先调用 set_project。也可以在会话过程中切换项目。

自定义连接器／基于 URL 的客户端（HTTPS）——实验性功能

某些客户端（例如“添加自定义连接器”界面）不会启动本地进程，而是连接到一个 URL。请以 HTTPS 模式运行服务：

node dist/index.js --http [port]   # default port 3939

这会在 https://127.0.0.1:<port>/mcp 启动一个 Streamable HTTP MCP 端点，且仅绑定到 localhost（无法从网络访问——每个请求都会根据连接套接字的地址进行检查，而不只是绑定地址）。首次运行时会生成一个用于 localhost/127.0.0.1 的自签名 TLS 证书，并缓存在项目旁的 .certs/ 中（已加入 gitignore）。

**状态：**该端点已在协议层面完成全面验证（握手、会话管理，以及首个版本中的 41 个工具均通过 curl 直接在 HTTPS 上进行了测试）。但无法保证某个 GUI 连接器添加流程会接受 localhost 自签名证书——有些可以（因为它们会像打开普通网页一样打开 URL，所以在手动选择“仍然继续”后即可），另一些则会静默拒绝，因为其后台连接检查不信任本地生成的证书，也不会向用户显示错误。如果添加连接器时一直转圈并最终失败，且没有任何提示，很可能就是这个原因。这是该客户端处理信任的方式所导致的限制，并非此服务的问题。目前使用此服务可靠且无需额外操作的方式是上文介绍的 stdio 模式（Claude Code CLI／Claude Desktop 的本地服务配置）。只有客户端明确要求使用 URL 时，才使用 --http。

连接器要正常工作，服务进程必须保持运行——请先在单独的终端窗口中启动服务，再添加连接器，并保持该窗口打开。

工具参考（78 个工具）

分组	工具
项目	set_project、get_project_info
数据库	list_records、get_record、update_record、create_record、get_system、update_system、set_switch_name、set_variable_name
技能辅助工具	create_damage_skill、create_healing_skill、create_buff_skill、create_state_skill
搜索	search_records、search_map_events
地图与事件	list_maps、get_map、create_map、update_map、get_event、update_event、create_event、delete_event、add_event_command、add_dialogue、event_command_reference
创作	build_dialogue_tree、create_event_from_template
图块集与绘制	get_tileset_info、get_tileset_image、set_map_tileset、paint_tiles、render_map、render_map_image、render_diff
生成	generate_map、capture_stamp、place_stamp、list_stamps
地图连接	connect_maps、list_map_connections
批量处理与平衡	bulk_update_records、generate_param_curve、generate_enemy_scaling、balance_report、simulate_battle
本地化	export_texts、import_texts
技能文件	install_skills
插件	list_plugins、configure_plugin、add_plugin、remove_plugin、create_plugin、read_plugin、write_plugin
游戏测试	playtest_start、playtest_status、playtest_log、playtest_stop
分析	audit_assets、lint_events、simulate_event、find_usages、check_references、analyze_progression
资源	import_asset、list_assets、preview_asset
安全	list_backups、restore_backup、validate_project、editor_status、begin_changeset、commit_changeset、discard_changeset、undo_changeset

每个工具的描述都面向 AI 使用：参数语义、RPG Maker 的特殊之处（目标范围、命令代码、从 1 开始索引的数组），以及相关工具的指引都包含在架构中，因此助手无需外部文档即可使用此服务。

工具配置

默认情况下会注册全部 78 个工具。有些客户端更适合使用较短的工具列表，因此你可以通过 --tools（逗号分隔的列表）或环境变量 RPGMV_TOOLS 只注册部分工具组：

claude mcp add rpgmaker-mv -- npx @xerolo44/rpgmaker-mv-mcp --project "/path/to/YourGame" --tools maps,tiles,render,authoring

工具组：project、database、maps、tiles、render、plugins、playtest、search、maintenance（备份、验证、editor_status 和变更集工具）、connect、balance、localization、authoring、generation、analysis、assets。project（set_project、get_project_info）始终启用，all（默认值）会启用所有工具组，未知的组名称会导致服务退出并显示一条消息。无论使用哪种配置，install_skills、资源和提示词始终可用。

各工具组包含的工具（77 个工具，另加始终启用的 install_skills，共 78 个）：

• project（2）：set_project、get_project_info
• database（12）：list_records、get_record、update_record、create_record、get_system、set_switch_name、set_variable_name、update_system、create_damage_skill、create_healing_skill、create_buff_skill、create_state_skill
• maps（11）：list_maps、get_map、update_map、get_event、update_event、create_event、delete_event、add_event_command、add_dialogue、create_map、event_command_reference
• tiles（5）：get_tileset_info、get_tileset_image、set_map_tileset、paint_tiles、render_map
• render（2）：render_map_image、render_diff
• plugins（7）：list_plugins、configure_plugin、add_plugin、remove_plugin、create_plugin、read_plugin、write_plugin
• playtest（4）：playtest_start、playtest_status、playtest_log、playtest_stop
• search（2）：search_records、search_map_events
• maintenance（8）：list_backups、restore_backup、editor_status、validate_project、begin_changeset、commit_changeset、discard_changeset、undo_changeset
• connect（2）：connect_maps、list_map_connections
• balance（5）：bulk_update_records、generate_param_curve、generate_enemy_scaling、balance_report、simulate_battle
• localization（2）：export_texts、import_texts
• authoring（2）：build_dialogue_tree、create_event_from_template
• generation（4）：generate_map、capture_stamp、place_stamp、list_stamps
• analysis（6）：audit_assets、lint_events、simulate_event、find_usages、check_references、analyze_progression
• assets（3）：import_asset、list_assets、preview_asset

变更集（支持撤销的事务性编辑）

进行多步骤更改时，请将其包装在变更集中，而不是让每次调用都直接写入磁盘：

1. begin_changeset {label} — 从现在起，每个编辑工具都会将结果暂存到内存中。读取操作（get_map、get_record、list_plugins 等）可以看到暂存的更改，但提交之前不会写入磁盘；游戏测试只能看到已提交的文件。
2. 按照平常的方式进行编辑。
3. commit_changeset 会一步写入所有暂存文件（先验证暂存的 .json 文件；如果其中任何文件无效，则不会写入任何内容，且变更集会保持打开状态），并返回逐文件摘要。也可以使用 discard_changeset 丢弃所有更改。
4. undo_changeset 会根据 .mcp-backups/changesets/ 中的日志回滚最近一次提交（可重复调用以继续回退）。它会将文件恢复为该次提交之前的状态，因此之后对这些文件所做的更改也会被覆盖。

同一时间只能有一个变更集处于打开状态；有变更集打开时，restore_backup 会被拒绝，而 set_project 会丢弃该变更集。如果进程在提交过程中退出，下次打开项目时，未完成的提交会被回滚（先备份磁盘上找到的文件），且 set_project / editor_status 会报告这一情况。与往常一样，请保持 RPG Maker 编辑器关闭。

技能、提示词和资源

除了工具，服务器还提供三种内置指导，供 MCP 客户端使用：

技能文件（skills/<name>/SKILL.md）是为助手编写的简短工作流指南。它们以资源形式提供（rpgmaker://skills/<name>），也可以通过 install_skills 工具复制到你的游戏项目中，这样 Claude Code 就会在该项目中自动加载这些文件 （.claude/skills/，或为 ~/.claude/skills/ 设置 scope: "user"）：

技能	涵盖内容
rpgmaker-mv-workflow	安全规则、数据约定、各种任务应使用的工具、发布前的资产与分析
rpgmaker-map-building	规划 → 绘制 → 查看 → 修复的循环、图层、图块选择、地图连接
rpgmaker-event-writing	对话、选项、缩进规则、开关、一次性宝箱、触发器
rpgmaker-balancing	目标、报告／模拟工作流、曲线、通过试运行进行批量编辑
rpgmaker-localization	导出／导入工作流、控制代码、消息长度
rpgmaker-plugin-dev	插件头部、引擎方法别名、插件命令、测试

资源 — rpgmaker://reference/event-commands、trait-codes、damage-formulas 和 database-fields 是助手最常用的查阅表，无需调用工具即可使用。

提示词 — 现成的工作流，在支持 MCP 提示词的客户端中会显示为命令： new_town、design_dungeon、add_quest、balance_check、review_dialogue、translate_game 和 project_health。

地图生成与印章

generate_map 会生成一座地牢（由走廊连接的房间）或一个洞穴（一个自然连通的区域），既可以生成到现有的空地图（mapId），也可以创建新地图（create，同时会在 MapInfos.json 中注册）。生成结果是确定性的：相同的 seed、尺寸和选项会生成相同的布局，并且始终会返回所用的种子。除非传入 overwrite: true，否则如果地图上已有图块或事件，生成操作会被拒绝。

• 图块配置。 地图会按照配置（floor、wall、可选的 wallTop、可选的加权 decor）进行绘制。如果未提供配置，系统会根据图块集自身的数据推荐配置（地板使用可通行的 A2 类型，墙壁使用阻挡通行的 A4 类型），并通过 profileUsed / profileNotes 返回。如果地板不可通行、墙壁无法阻挡移动，或从入口无法到达所有区域，则不会写入任何内容。
• 标记。 markers（默认：入口和出口，不含宝箱）会放置空事件，命名为 Entrance、Exit 和 Chest 1..n，优先级为 0，因此不会阻挡玩家。它们只是占位符：使用 connect_maps 连接门（传入 allowOverlap，或先对标记使用 delete_event），并使用 create_event_from_template 填充宝箱。
• 尺寸。 地牢至少需要 14x7（或 7x14）；洞穴在约 13x13 起生成较为可靠（MV 默认的 17x13 在测试中从未失败），而 9x9 到 12x12 以及狭长地图在许多种子下会失败；请尝试其他种子或更大的地图。
• 查看效果。 使用 render_map_image（尝试启用 showPassability）和 render_diff。墙面经过简化，仅有一行，装饰也比较稀疏；哪些内容经过了检查、哪些没有，请参阅 CHANGELOG.md。

印章是可重复使用的地图片段。capture_stamp 会将一个矩形区域（最多 64x64，包括全部六个图层，默认还包括其中的事件）保存到 <project>/.mcp-stamps/<name>.json； place_stamp 会将其粘贴到使用相同图块集的地图上，左上角位于 (x, y)；list_stamps 则会列出已有印章。放置时会替换所有图层上的对应矩形，依据周围环境重新塑造自动图块边缘，且不会裁切；不支持旋转或镜像。

资源

三个工具用于处理项目的图像和音频文件（img/* 和 audio/*，共 18 个文件夹）：

• import_asset {source, folder, name?, overwrite?} 将电脑上的文件复制到 <project>/<folder>/<name>.<ext>。source 必须是本地驱动器上常规文件的绝对路径（不接受相对路径、网络共享、设备或符号链接）。文件类型仅根据文件的标头读取，并且必须符合文件夹要求：img/* 接受具有 PNG 签名和标头的文件，audio/* 接受以 OggS（Ogg）开头或含有 ftyp box（M4A）的文件。扩展名根据标头确定，绝不根据源文件名确定。文件不会被转换或调整尺寸，也不会检查文件其余部分。图像大小上限为 32 MiB，音频大小上限为 128 MiB。
• list_assets {folder?, includeUsage?, limit?} 列出一个或所有文件夹中的文件，并显示大小、PNG 尺寸、警告（标头与扩展名不匹配、图片尺寸不符合文件夹要求、隔行扫描的 PNG），以及对于参考扫描所涵盖的文件夹，显示 usedBy 和 unused。未使用表示数据库、地图、公共事件或队伍中没有名称完全匹配（区分大小写）的引用；通过名称加载文件的插件或脚本不会被检测到。
• preview_asset {folder, name, maxSize?} 将 img/* 文件夹中的 PNG 作为图像返回（使用最近邻算法缩放，使较长边不超过 maxSize 像素）；对于 img/characters 和 img/faces，还会按照名称推断图片表格布局。拒绝预览隔行扫描的 PNG、超过 32 MiB 的文件和超过 1,600 万像素的图像；无法预览音频。

名称规则。 名称长度为 1–64 个字符，只能包含 A-Z a-z 0-9 space _ ! $ ( ) -，且必须以字母、数字、! 或 $ 开头，不能以空格结尾，不能包含句点（扩展名会自动添加）或路径分隔符，也不能是 Windows 保留设备名（CON、NUL、COM1、LPT1 等）。在 img/characters 中，如果名称开头连续的 ! 和 $ 字符中包含 $（$Boss、!$Chest），则表示单角色图片；! 表示地图上没有垂直偏移。

备份和变更集。 只有设置 overwrite: true，才会替换同名文件（不区分大小写）。与其他编辑一样，服务器会在会话中首次更改文件时，将其快照保存到 .mcp-backups/（list_backups、restore_backup），因此备份保存的是会话开始前的文件（直到再次调用 set_project 并重新开始快照）：在同一服务器会话中创建或已被替换过的文件，不会保留该文件中间版本的备份。二进制文件无法暂存，因此打开变更集时会拒绝执行 import_asset；请先提交或丢弃变更集。导入被拒绝时不会写入任何内容。对于音频，如果缺少 .ogg 或 .m4a 配套文件，会显示警告（MV 的 Web 构建需要两种文件）。

过场动画和游戏流程节点

除了对话、选项、条件、开关、变量和传送之外，build_dialogue_tree 还会将这些节点编译为缩进正确的命令。与 MV 编辑器一样，每个选项、if/else 和战斗分支的末尾，都会在正文缩进处添加一行空白 {code: 0}（空分支只有这一行）；引擎会跳过它。

• 过场动画： wait、fade（淡出 / 淡入）、tint、flash、shake、weather、playAudio、 fadeAudio、showPicture、erasePicture、animation、balloon 和 moveRoute。路线由步骤列表组成（up、turnLeft、{wait: 10}、{jump: {x, y}}、{switchOn: 5}、{speed: 4}、 ……）；重复路线（repeat: true）不会结束，因此无法等待它完成，而且会拒绝显式的 wait: true。
• 游戏流程： battle（包含 onWin、onEscape 和 onLose 正文；与编辑器一样，只有启用 canEscape 或 canLose，或 onWin 中有节点时，才会写入这些分支及其结束命令；如果两者都没有，战斗就只是一个命令，后面接着执行后续内容；若某个分支的复选框未勾选，则会拒绝该分支的正文）、shop、callCommon、label / jump、exit、comment、 gold、item（物品、武器和护甲）、party、learnSkill、recoverAll、nameInput、 plugin（插件命令行）和 scene（菜单、存档、游戏结束、标题画面）。

示例：作为 tree 参数传入（或设置 dryRun: true，仅查看命令）：

[
  { "fade": "out" },
  { "battle": { "troopId": 3, "canLose": true,
      "onWin": [{ "gold": 200 }],
      "onLose": [{ "say": "Defeated..." }, { "scene": "gameOver" }] } },
  { "fade": "in" },
  { "shop": { "goods": [{ "type": "item", "id": 1 }, { "type": "weapon", "id": 2, "price": 300 }] } }
]

simulate_event 可以试运行结果：会跳过演出类命令并计入 cosmetic，而 battleResult（win、escape 或 lose）会决定运行哪个战斗分支。命令布局已对照官方 MV 核心脚本核验，代码块和移动路线结构也已对照公开 MV 项目的真实地图文件核验，但并未在实际游戏中运行，因此请对重要事件进行游戏测试；限制请参阅 CHANGELOG.md。

分析

无需运行游戏即可执行的检查：

• audit_assets — 检查项目引用的每个图像和音频文件（角色、敌人、图块集、地图、事件页、一组事件命令（脸图、图片、音频、战斗背景、视差背景、角色和载具图像）、System）是否存在；还会列出大小写不匹配的情况（在 Windows 上正常，在 Linux/macOS/网页平台上会出错），并可选择列出未使用的文件。结果会列出未扫描的内容（例如插件参数），因此“未使用”的文件可能包括仅供插件使用的文件。
• lint_events — 对地图、公共事件和队伍中的事件命令列表执行静态检查：块结构和结束符是否错误、命令是否无法到达、消息行是否过长、传送目标地图是否缺失或目标图块是否越界、调用的公共事件是否缺失，以及开关/变量是否未命名。每条发现都附有位置；行长限制为近似值。
• simulate_event {mapId, eventId, ...} — 根据你提供的状态（开关、变量、独立开关、金币、道具、选项答案）对单个事件页进行试运行，并返回显示的消息、所做的更改、最终传送到的位置，以及无法模拟的命令。支持消息、选项、条件、循环、公共事件、开关/变量/独立开关/金币/道具更改、传送、插件命令、标签和跳转；战斗会执行由 battleResult（win、escape 或 lose，默认为 win）选择的分支；动画和气球图标（212、213）、画面淡入淡出、色调、闪烁和震动（221-225）、等待（230）、显示/移动/擦除图片（231、232、235）、天气（236）、播放/淡出音频（241、242、245、246、249、250、251）和移动路线（205）会被忽略，并且只计入 cosmetic（移动路线中的开关 ON/OFF 步骤仍会执行）；脚本、图片旋转和色调（233、234）以及其他命令会列为不支持并跳过。它绝不会触碰项目。
• editor_status — 报告 RPG Maker 编辑器进程是否似乎正在运行（仅限 Windows；其他平台为 null），以及此服务写入的哪些文件后来被其他程序修改过，通常是编辑器覆盖了这些文件。此工具仅报告状态。

用法与进度分析

这些工具会读取整个项目（包括暂存的更改集数据），且绝不会运行游戏。

• find_usages {kind, id, limit?} 列出读取、写入或使用某个开关、变量、物品、武器、防具、技能、状态、角色、职业、敌人、部队、公共事件或地图的所有位置，例如 Map003 event 5 page 1 command index 12 或 Enemies #4 dropItems（地图、事件和公共事件 ID 是实际 ID，页码从 1 开始，与编辑器一致；命令索引从 0 开始，是 lint_events 也会报告的位置），并提供精确计数和警告：开关或变量已读取但从未设置（或已设置但从未读取）、没有任何事件调用的公共事件、没有任何事件转入的地图、没有名称的 ID。重命名、删除或重复使用某个 ID 前，请先使用此工具。
• check_references {limit?} 查找指向不存在记录的引用：例如执行“战斗处理”时指定部队 1，但不存在部队 1；商店物品 7、“学习技能”技能 12、角色 5、转移至已删除地图、敌人掉落物品或职业技能学习指定了不存在的记录。它会检查 find_usages 建立索引的所有引用（事件命令、页面条件、敌人掉落物品和行动、职业技能学习、角色职业和装备、部队成员、物品和技能效果、遇敌列表、System startMapId 和 partyMembers），根据类型和 ID 汇总发现项，提供计数和最多三个位置，并在 notes 中列出未检查的内容。ID 0（“无”）永远不会被报告，也不会检查开关和变量。数据库文件缺失或无法读取时，会在 notes 中列出文件名，而不是报告所有记录都缺失。请在发布前，以及删除或重命名记录后运行此工具。
• analyze_progression {goal?, includeGraph?, limit?} 从起始地图开始追踪游戏进程，并报告可到达和不可到达的地图、没有出口的地图、永远无法运行的事件页（附上第一个永远不满足的条件）、已读取但从未设置或已设置但从未读取的开关和变量，以及通俗易懂的摘要。goal（{switch}、{mapId} 或 {event: {mapId, eventId}}）会添加结论和目标受阻原因，includeGraph 会添加地图转移的 Mermaid 流程图。

分析可以证明什么。 这是对游戏过程的过度近似：只要页面条件可能成立，该页面就可能运行；页面运行时，其所有命令都会生效。开关只会开启，物品不会丢失。因此，在此模型下，不可到达 和 从未设置 是已证明的结论，而 可到达 仅表示“未被排除”。

分析无法检测什么。 事件命令内部的条件（分支、选项）、伤害公式（会执行 JavaScript，并能设置开关和变量）、脚本命令和插件命令、目标由变量指定的转移和战斗、已启用的插件及其参数和备注（这些可以调用公共事件、设置开关或移动玩家），以及载具的起始地图。它不会模拟开关关闭，也不会检测软锁。find_usages 也不会为每条命令建立索引，而 check_references 只能检查索引中包含的内容（脚本或插件命令、备注、插件参数、伤害公式和通过变量指定的命令中的引用对它不可见）；完整列表请见 CHANGELOG.md。check_references 根据记录的 id 字段判断记录是否存在，而不是根据数组位置（find_usages 则是如此），因此，如果表格行的 ID 与其位置不同，结果可能不准确。find_usages、check_references 和 analyze_progression 会在内存中构建项目索引：如果恶意或机器生成的项目包含大量覆盖整个 ID 范围的“控制开关 / 变量”命令，可能会消耗大量内存和时间（测试中，5000 个事件扩展为约 1000 万条引用时，测得约 1.2 GB 内存占用）。 可信度。 只要项目包含脚本或插件命令、由变量指定的传送或战斗，或已启用的插件（或者无法读取地图或 js/plugins.js），uncertainty.confidence 就会是 low，并且摘要会说明原因。如果只有命令内部的条件或伤害公式执行了分析无法识别的操作，则仍为 high。只有在可信度为 high 时，才应相信 不可达 和 无效 结果；几乎所有使用自定义插件的项目都会报告 low。find_usages 的“从不……”警告也遵循同样的规则：如果脚本或插件命令可能会使用该 ID，警告会附带说明。

平衡工具简介

批量编辑、曲线生成器和 import_texts 默认以试运行方式运行——它们会返回差异，不会写入任何内容，除非你传入 dryRun: false。simulate_battle 和 balance_report 使用项目的实际职业曲线、装备、特性和伤害公式（安全地求值：公式运行前会根据允许列表进行检查）。它们不会模拟状态、增益或道具，因此请将其作为参考，并对重要战斗进行游戏测试。

备份

会话首次修改任何文件时，原始文件都会被复制到 <project>/.mcp-backups/<session-timestamp>/，并保留其相对路径。最多保留 10 个会话。list_backups 会显示可用的备份；restore_backup 会恢复单个文件或整个会话——恢复前会先备份当前状态，因此恢复操作也可以撤销。

如果游戏项目使用版本控制，请将 .mcp-backups/ 和 .mcp-stamps/ 添加到游戏项目的 .gitignore 中（如果想共享印记，则不要添加 .mcp-stamps/）。变更集日志位于 .mcp-backups/changesets/ 下，不会被清理。

重要说明

• 服务器编辑文件期间，请关闭 RPG Maker MV 编辑器（或不要在编辑器中保存）。 编辑器会将整个数据库保存在内存中，并在保存时覆盖 JSON 文件，丢弃外部所做的更改。重新在编辑器中打开项目，即可查看在此处所做的编辑。
• MV 中的数据库数组从索引 1 开始，索引 0 为 null；工具会自动处理，ID 始终与数组位置一致。
• 也接受 MZ 项目（.rmmzproject）——其数据格式几乎相同——但尚未经过测试。
• 本版本已知的限制（未验证的编辑器进程名称、未检查生成地图的视觉质量、没有脚本化游戏测试运行器等）列于 CHANGELOG.md。
• 使用 paint_tiles 绘制图块（update_map 会拒绝修改 data）。通过 get_tileset_info / get_tileset_image 选择图块；图块所在图块表必须在地图的图块集内指定图像，否则图块会不可见，因此调用会被拒绝。
• render_map_image 会读取 img/ 中的图块集和角色图像（无法显示使用加密 .rpgmvp 文件的部署版本）；没有可用图像的图块表会以纯色绘制，并在答复中列出。水面会以第一帧动画绘制。
• export_texts 会写入项目（默认为 localization/）；覆盖文件前会先备份，并按键保留现有译文。
• NW.js 游戏测试会按顺序自动检测 Steam 和 KADOKAWA 安装路径、项目自带的 Game.exe，以及 RPGMAKER_MV_NWJS 环境变量。
• 在浏览器游戏测试模式下，控制台输出会保留在浏览器开发者工具中——需要使用 playtest_log 时，请使用 NW.js 模式。

从源代码构建

适用于贡献者，或希望在本地构建的用户：

git clone https://github.com/Xerolo44/RPG-Maker-MV-MCP.git
cd RPG-Maker-MV-MCP
npm install
npm run build

然后使用本地构建版本搭配 Claude Code：

claude mcp add rpgmaker-mv -- node "$(pwd)/dist/index.js" --project "/path/to/YourGame"

开发

npm run build   # compile TypeScript to dist/
npm run test:unit  # node:test unit tests in test/ (PNG, formulas, renderer, battle maths, generators, ...)
npm run smoke      # end-to-end test: real stdio client against a generated MV project
npm test           # build + unit tests (test/) + smoke test (what CI runs)

请参阅 CONTRIBUTING.md 了解项目结构和指南，参阅 CHANGELOG.md 了解发布历史，并参阅 SECURITY.md 了解工具的信任模型（工具拥有完整的文件系统访问权限——在将 --http 模式开放给本机以外的设备前，请先阅读）。

许可证

MIT