内容
<div align="center">
<img src="assets/banner.svg" alt="RPG Maker MZ MCP 服务器" width="100%" />
# RPG Maker MZ MCP 服务器
[](https://github.com/Redseb/rpgmaker-mz-mcp/actions/workflows/ci.yml)
[](#可用工具)
[](https://modelcontextprotocol.io/)
[](tsconfig.json)
[](package.json)
[](#许可证)
**117 个工具**，让 AI 助手可以直接读取和编写 RPG Maker MZ 项目 - 角色，职业，技能，物品，装备，状态，敌人，部队，共同事件，地图，图块，图块集，事件和系统设置 - 而不是在编辑器中手动编辑所有内容。
_"在世界地图下添加一个城镇，用草地覆盖它，并放置一个出售药水的商人"_ → 完成，在项目中，无需点击编辑器。
</div>
## 快速开始
**Claude 代码（推荐）** - 安装服务器和创作技能为一个插件：
```bash
claude plugin marketplace add Redseb/rpgmaker-mz-mcp
claude plugin install rpgmaker-mz@rpgmaker-mz-mcp
```
您将被提示输入您的 RPG Maker MZ 项目目录（可选 - 您也可以稍后让 Claude 调用 `set_project`）。
**任何其他 MCP 客户端** - 服务器在 npm 上；无需克隆或构建：
```json
{
"mcpServers": {
"rpgmaker-mz": {
"command": "npx",
"args": ["-y", "rpgmaker-mz-mcp@latest"],
"env": { "RPGMAKER_PROJECT_PATH": "/path/to/your/rpgmaker/project" }
}
}
}
```
**Claude 桌面版** - 或者下载一键式 `rpgmaker-mz-mcp.mcpb` 包，从 [Releases](https://github.com/Redseb/rpgmaker-mz-mcp/releases) 中获取并用 Claude 桌面版打开它。
不熟悉？请阅读 [SETUP.md](SETUP.md) 以获取完整的演练指南，并阅读 [EXAMPLES.md](EXAMPLES.md) 以获取端到端示例。
## 目录
- [快速开始](#快速开始)
- [功能](#功能)
- [它是如何组合在一起的](#它是如何组合在一起的)
- [安装](#安装)
- [配置](#配置)
- [使用](#使用)
- [可用工具](#可用工具)
- [输入验证](#输入验证)
- [事件验证（默认抛出）](#事件验证默认抛出)
- [引用校验](#引用校验)
- [干预预览](#干预预览)
- [自定义图块集编目技能](#自定义图块集编目技能)
- [示例提示](#示例提示)
- [开发](#开发)
- [项目结构](#项目结构)
- [安全性和最佳实践](#安全性和最佳实践)
- [限制](#限制)
## 功能
- **数据库 CRUD** - 角色，职业（带有学习和参数曲线），技能（完全控制 + 简化的伤害/治疗/增益/状态助手），物品，武器，护甲，状态，敌人和部队。只有 `name` 是必需的来创建；其他一切都默认为编辑器的真正“新建 X”模板。
- **地图和地图树** - 创建/删除地图，批量重新父/重新排序/重命名并带有循环保护，并且编辑地图属性。新地图在 `MapInfos.json` 中注册，就像编辑器期望的那样。
- **图块绘制（带有自动图块）** - `paint_tiles`/`fill_area` 在六个地图图层的任意一个上设置图块，并从相同种类的邻接性重新计算图块形状（及其邻居），以便填充区域正确地与其边界相邻。`place_object` 印章多图块 B/C 对象（房屋，树）并报告其通行性占用。
- **语义图块编目** - `find_tile "grass"` → 一个可绘制的图块 ID。内置编目适用于每个默认图块集（Overworld，Outside，Inside，Dungeon，SF），源自 RPG Maker 自己的英文名称边车。捆绑的视觉引导技能编目 **自定义** 图块集。
- **通行性和地形** - 读取图块的标志或地图单元格的分层通行性（`get_tile_flags`/`check_passability`），并 **编辑** 通行性/地形标签/行为标志（`set_tile_flags`）。
- **事件命令生成器** - 高级，只读生成器，发出与编辑器编写的 `EventCommand` 序列（包括棘手的递归分支块和延续行），通过 `insert_event_commands` 落地到一个页面。涵盖对话和流程，游戏状态更改，呈现/过渡和场景处理。
- **事件和 NPC 人体工程学** - `create_npc` 放置一个完整的对话 NPC；`set_event_page` 合并一个页面的图形 + 行为（精灵，触发器，优先级，移动，标志）。
- **资产感知** - `list_assets` 枚举有效的角色/面部/图块集/音频名称，以便事件永远不会引用不存在的文件。
- **正确性层** - Zod 验证的输入，默认情况下事件验证（结构无效的写入被拒绝，不会保存并警告），跨文件引用校验器（`validate_references`），以及每次写入的干预预览。
## 它是如何组合在一起的
<div align="center">
<img src="assets/architecture.svg" alt="AI 助手通过 stdio 与 MCP 服务器通信，MCP 服务器读取和写入 RPG Maker MZ 项目的数据文件" width="100%" />
</div>
## 安装
选择一个：
- **Claude 代码插件** *(推荐)* - `claude plugin marketplace add Redseb/rpgmaker-mz-mcp`，然后 `claude plugin install rpgmaker-mz@rpgmaker-mz-mcp`。此捆绑包将 MCP 服务器（通过 npm 包运行）与两个创作技能（`rpgmaker-authoring`，`tileset-catalog`）结合起来 - 技能带有工具无法强制执行的判断，因此这是完整的体验。
- **npm 包** - 配置您的 MCP 客户端以运行 `npx -y rpgmaker-mz-mcp@latest`（参见 [快速开始](#快速开始)）。仅限工具，无技能。
- **MCPB 包（Claude 桌面版）** - 从 [Releases](https://github.com/Redseb/rpgmaker-mz-mcp/releases) 下载 `rpgmaker-mz-mcp.mcpb`，用 Claude 桌面版打开它，然后在安装对话框中选择您的项目文件夹。
- **从源代码**（开发）：
```bash
npm install
npm run build
```
## 配置
将 RPG Maker MZ 项目路径设置为环境变量：
```bash
# 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` 报告当前项目），因此切换游戏不需要编辑配置或重启。
## 使用
### 运行服务器
```bash
npm start # 或：node dist/index.js
```
### 在 Claude 桌面版中配置
最简单的路径是从 [Releases](https://github.com/Redseb/rpgmaker-mz-mcp/releases) 获取 `.mcpb` 包 - 用 Claude 桌面版打开它并选择您的项目文件夹。要手动配置，请将以下内容添加到您的 Claude 桌面版配置文件（`%APPDATA%\Claude\claude_desktop_config.json` 在 Windows 上，`~/Library/Application Support/Claude/claude_desktop_config.json` 在 macOS 上）：
```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"]` 而不是。）
## 可用工具
所有 117 个工具，按区域分组。写入项目的工具接受一个可选的 `dryRun` 参数（参见 [干预预览](#干预预览)）；可以拒绝结构无效写入的工具还接受 `force`（参见 [事件验证](#事件验证默认抛出)）。
<details>
<summary><strong>展开完整的工具参考</strong></summary>
### 项目定位
- `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`（完全控制），`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` 验证每个成员都引用现有的敌人
### 共同事件
- `create_common_event`，`update_common_event`
- `call_common_event` - 构建代码 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` 或显式 `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）
- **插入：** `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
- `paint_tiles`，`fill_area` - 带有自动图块绘制
- `place_object` - 印章多图块 B/C 对象并报告其通行性占用
### 图块集标志（通行性/地形）
- `get_tile_flags` - 解码图块的通行性/星级/梯子/灌木/柜台/损伤/地形标签
- `check_passability` - 地图感知的分层答案
- `set_tile_flags` - **编辑**图块的标志（非破坏性合并；自动应用于所有 48 个图块形状槽）
### 资产
- `list_assets` - 枚举可用的资产基名（角色，面图块，图块集，图片，音频，...）
### 系统和词汇
- `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 顺序分配，因此记录可以引用在同一个批次中较早创建的同伴
### 索引和验证
- `list_names` - 一个表的廉价 `{ id, name }` 索引（角色，物品，技能，地图，敌人，...）
- `get_database` - 来自一个表的完整记录（角色，职业，物品，武器，护甲，技能，敌人，部队，状态，共同事件），或按 `id` 获取单个记录
- `validate_event`，`validate_project` - 事件命令形状验证（只读）
- `validate_references` - 跨文件 ID 完整性审计（派对→角色，转移→地图，效果→状态/技能/共同事件，掉落→物品，地图树循环，...）
</details>
## 输入验证
每个工具都将其参数声明为 [Zod](https://zod.dev) 模式。服务器（在 MCP SDK 的高级 `McpServer` 上构建）**在运行处理程序之前** 将传入参数与其模式进行验证，因此格式错误的调用被拒绝，并带有明确的 `输入验证错误`，指出哪个字段有问题。
## 事件验证（默认抛出）
事件命令列表会针对 RPG Maker MZ 命令代码表进行检查（`101` 显示文本，`201` 转移玩家，`122` 控制变量，...）。发现结果分为两个层次，层级决定了写入时会发生什么：
- **结构性** - 已知命令的参数计数错误，列表未以代码 0 终止，`parameters` 为非数组，或动作按钮事件卡在不可通行图块上。这些几乎总是错误，因此事件写入工具 **验证假设结果，然后拒绝写入**：工具错误， * 没有任何内容到达磁盘 *。传递 `force: true` 强制写入（该参数在恰好可能拒绝的工具上宣传）。
- **建议** - 未识别的命令代码（可能是插件命令），文本行过长，未知资产文件名。这些是合法的可能性，因此它们永远不会阻止; 它们作为 `warnings` 骑在正常响应上。
由于检查在提交 **之前** 运行，因此写操作的 `dryRun` 失败太， 而不是预览永远不会发生的写入。
`validate_event` / `validate_project` 保持只读审计：它们报告两个层级（每个发现都有 `severity`）而不会更改任何内容。
## 引用校验
`validate_references` 执行 **跨文件 ID 完整性审计** - 与上述命令形状检查正交。它遍历整个数据库，并标记引用不存在的内容的引用：起始党成员没有匹配的角色，转移玩家目标一个不存在的地图，一个技能效果添加一个不存在的状态，一个敌人掉落一个未知物品，一个循环地图树父级，等等。每个检查默认情况下都是警告，并针对部分加载的项目上的假阳性进行了保护。
## 干预预览
每个写入项目的工具都接受一个可选的 `dryRun` 参数。当 `dryRun: true` 时，该工具计算它 **将** 写入的内容并返回一个差异而不是触摸任何文件：
```json
{
"dryRun": true,
"wouldChange": [
{
"file": "System.json",
"changed": true,
"diff": {
"changes": [{ "path": "gameTitle", "from": "Old Title", "to": "new title" }],
"truncated": false
}
}
],
"wouldReturn": { "...": "如果工具返回的内容，包括警告" }
}
```
`wouldReturn` 携带该工具将产生的响应，因此干运行也预览了写入将报告的验证警告 - 而不仅仅是差异。
所有写入操作都经过一个单一的阻塞点，该阻塞点跳过无操作写入，并保持编辑器中的 JSON 采用紧凑的单行格式。文件删除（例如 `delete_map`）共享相同的干运行机制。
## 自定义图块集编目技能
默认图块集开箱即用。对于 **自定义**（非 RTP）图块集，`.claude/skills/tileset-catalog/` 下的捆绑 Claude 技能将每个图块剪切成标记样本，Claude 视觉命名它们，并写入一个版本控制的，项目范围的编目到 `data/tilecatalog/` - 之后 `find_tile`/`get_tile_catalog` 也为该图块集解析名称。技能自带依赖项的 PNG 编码器和 Node 引擎精确的图块几何形状，因此它在 Node 任何地方运行。
## 示例提示
## 开发
## 项目结构
## 安全性和最佳实践
## 限制
## 示例提示
配置完成后，使用自然语言驱动您的项目：
- "创建一个名为'火球'的火系技能，消耗15 MP，对单个敌人造成 `a.mat * 4 - b.mdf * 2` 点伤害。"
- "在世界地图下添加一个新的城镇地图，大小为30×25，使用外部 tileset。"
- "在地图3的（4, 4）位置绘制一个10×8的草地矩形，并自动生成边界。"
- "在地图2的（8, 5）位置放置一个名为'守卫'的对话NPC，NPC说'停下！谁在那里？'"
- "使tileset 1中的水图块不可通行，并标记为地形1。"
- "在发布前检查我的项目是否有损坏的引用。"
## 开发
```bash
npm run build # 编译TypeScript到dist/
npm run typecheck # 类型检查（不生成编译文件）
npm run dev # 监视模式编译
npm run lint # ESLint
npm run lint:fix # ESLint 自动修复
npm run format # Prettier格式化
npm run format:check # 检查格式化（用于CI）
npm test # Vitest
npm run sync:tools # 将工具数量重新写入README和SVG（见下文）
npm run sync:version # 将package.json的版本重新写入打包清单
npm run bundle:mcpb # 构建一键Claude Desktop包（rpgmaker-mz-mcp.mcpb）
```
在开发过程中，您可以通过运行源代码服务器来完全跳过构建，使用[tsx](https://tsx.is)：将MCP客户端的`command`指向`node_modules/.bin/tsx`，并将`src/index.ts`作为参数。由于tsx不进行类型检查，请在提交前运行`npm run typecheck`以及lint和测试。
CI在每次推送和拉取请求时运行lint、格式化检查、工具数量同步检查、测试和构建（参见`.github/workflows/ci.yml`）。
### 保持工具数量同步
广告中的工具数量显示在几个面向用户的 spots 中 — README 文本和徽章，以及 `assets/` 中的两个 SVG 文件。`npm run sync:tools` 会统计 `src/tools/` 中的实际工具，并重新写入所有这些文件，因此在添加工具后只需运行一个命令即可更新数字。`npm run sync:tools:check`（在 CI 中运行）如果任何 spots 文件过期，则会失败。
### 发布
`package.json` 是版本号的真实来源；`npm run sync:version` 会将其写入插件清单（`.claude-plugin/plugin.json`）、MCP-registry 元数据（`server.json`）和 MCPB 清单（`mcpb/manifest.json`）。CI 和 `prepublishOnly` 如果版本号不一致，则会失败。发布流程如下：
```bash
npm version minor # 或 patch/major — 更新package.json + 标签
npm run sync:version # 将新版本号写入其他清单
git add -A && git commit --amend --no-edit && git push --follow-tags
npm publish # 发布到npm（通过prepublishOnly运行完整检查）
mcp-publisher publish # 更新MCP注册表列表（server.json；登录：mcp-publisher登录github）
npm run bundle:mcpb # 构建rpgmaker-mz-mcp.mcpb并将其附加到GitHub发布
```
Claude Code插件无需单独发布 — 用户的安装会从此仓库更新（插件通过`npx rpgmaker-mz-mcp@latest`运行npm包，因此更新npm版本即可发布新工具）。
## 项目结构
```
rpgmaker-mz-mcp/
├── src/
│ ├── index.ts # McpServer启动：注册每个工具，分发 + 预览
│ ├── registry.ts # ToolDefinition 形状 + 共享的dryRun模式
│ ├── tools/ # 每个领域一个模块（actors，items，skills，maps，battle，
│ │ # classes，states，common events，moves，plugins，tiles，
│ │ # catalog，paint，objects，tilesets，system，assets，
│ │ # event-command构建器，event pages，list，validation）
│ ├── events/ # 纯event-command构建器（无I/O）
│ ├── tiles/ # Tile子系统：codec，autotile求解器，paint核心，
│ │ # flag codec，和语义目录
│ ├── validation/ # 已知命令表 + event/move/plugin/reference验证器
│ └── utils/ # 文件I/O，提交阻塞点，和RPG Maker MZ类型
├── test/ # Vitest套件
├── scripts/
│ └── sync-tool-count.mjs # 将工具数量重新写入README + SVG
├── assets/ # 徽章 + 架构SVG
├── .claude/skills/
│ └── tileset-catalog/ # 自定义tileset的Vision catalog-bootstrap技能
├── dist/ # 编译的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](https://github.com/k4zuki0539/-rpgmaker-mz-mcp)（MIT）的分支，它提供了原始的CRUD脚手架。自此之后，它已经发展成为一个全新的项目，超越了最初的起点，成为一个完整的原生级别设计和游戏逻辑创作工具（参见[功能](#功能)）。感谢原始作者为该项目打下的基础。
## 许可证
[MIT](https://opensource.org/licenses/MIT)
## 资源
- [RPG Maker MZ 官方网站](https://www.rpgmakerweb.com/products/rpg-maker-mz)
- [模型上下文协议文档](https://modelcontextprotocol.io/)
- [RPG Maker MZ 数据库结构](https://github.com/rpgtkoolmv/rmmz-api-reference)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器