使用说明

🎮 RPG制造商MZ MCP服务器

A. 稳定、经过充分测试 模型上下文协议允许Claude等AI助手创建和编辑的服务器 RPG制造商MZ 通过自然语言进行项目。

为什么是另一个？ GitHub上现有的RPG Maker MZ MCP服务器存在严重问题——stdout污染破坏了MCP协议、文件扩展名错误、没有原子写入、没有测试和过时的SDK。这个项目是从头开始构建的，目的是修复所有这些问题。

✨ 特性

功能	本项目	其他
原子文件写入(`.tmp` → `rename`)	✅	❌
汽车 `.bak` 每次写入前备份	✅	❌
读取时的Zod模式验证	✅	❌
仅记录stderr（无stdout污染）	✅	❌
正确 `.rmmzproject` 扩展	✅	❌
通用 `DatabaseManager<T>` （无复制粘贴）	✅	❌
单元和集成测试（42次测试）	✅	❌
MCP SDK v1.26+✅	❌
使用人类可读命令进行事件编辑	✅	部分
AI场景生成工具	✅	❌

🛠 可用工具（共23个）

项目管理（4）

工具	说明
`load_project`	加载现有的RPG Maker MZ项目
`create_project`	使用所有默认数据文件创建新项目
`get_project_info`	获取项目统计数据（地图、演员、物品等）
`list_resources`	列出项目中的图像和音频文件

数据库CRUD（6个工具×8种实体类型）

使用的统一工具 演员、职业、技能、物品、武器、盔甲、敌人和国家:

工具	说明
`list_entities`	列出给定类型的所有实体
`get_entity`	按ID获取实体详细信息
`create_entity`	使用Zod验证创建新实体
`update_entity`	现有实体的部分更新
`delete_entity`	删除实体（保护系统默认值）
`search_entities`	按关键字在名称/描述中搜索

地图管理（5）

工具	说明
`list_maps`	列出所有具有层次结构的地图
`create_map`	使用大小、倾斜集和背景大小创建新地图
`get_map`	获取包括事件在内的地图详细信息
`update_map`	更新地图属性
`delete_map`	删除地图

事件编辑（5）

工具	说明
`list_events`	在地图上列出事件
`create_event`	在某个位置创建新事件
`update_event`	更新事件属性
`add_event_commands`	使用人类可读格式添加命令
`delete_event`	删除事件

支持40多种命令类型 包括 show_text, show_choices, transfer_player, control_switches, play_bgm, battle_processing, shop_processing以及更多。

人工智能场景生成（3）

工具	说明
`generate_scenario`	从主题生成游戏场景大纲
`generate_dialogue`	生成NPC对话作为事件命令
`generate_quest`	设计一个有目标和奖励的任务

这些工具利用了人工智能自身的功能-不需要外部API调用。

📦 安装

# Clone the repository
git clone https://github.com/a951753abc/rpgmaker-mz-mcp.git
cd rpgmaker-mz-mcp

# Install dependencies
npm install

# Build
npm run build

# Verify (42 tests should pass)
npm test

⚙️ 配置

克劳德代码（CLI）

创建一个 .mcp.json 项目目录中的文件：

{
  "mcpServers": {
    "rpgmaker-mz": {
      "command": "node",
      "args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]
    }
  }
}

克劳德桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "rpgmaker-mz": {
      "command": "node",
      "args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]
    }
  }
}

💬 使用示例

连接MCP服务器后，自然地与Claude交谈：

You: Load my RPG Maker MZ project at /Users/me/Games/MyRPG

You: Create a warrior character named "Roland" with high attack

You: Create a 20x15 village map called "Oakwood Village" with Town1 BGM

You: Add an NPC shopkeeper on map 2 at position (8, 6)

You: Add dialogue to the shopkeeper: "Welcome! Take a look at my wares."

You: Generate a quest about rescuing a kidnapped princess

You: Create a healing potion item that restores 200 HP

🏗 建筑

src/
├── index.ts                    # MCP Server entry point (stdio transport)
├── logger.ts                   # stderr-only logger
├── core/
│   ├── file-handler.ts         # Atomic writes + backups + Zod validation
│   ├── project-manager.ts      # Project loading / validation
│   ├── database-manager.ts     # Generic CRUD for all entity types
│   └── version-sync.ts         # System.json versionId auto-sync
├── schemas/
│   ├── database.ts             # Zod schemas for 8 entity types
│   ├── map.ts                  # Map & audio schemas
│   ├── event.ts                # Event & command schemas + converter
│   └── system.ts               # System.json schema
├── tools/
│   ├── project-tools.ts        # 4 project management tools
│   ├── database-tools.ts       # 6 database CRUD tools
│   ├── map-tools.ts            # 5 map management tools
│   ├── event-tools.ts          # 5 event editing tools
│   └── scenario-tools.ts       # 3 AI scenario tools
└── templates/
    └── defaults.ts             # RPG Maker MZ default data templates

关键设计决策

原子写入：写信至 .tmp → fs.rename() 目标。重命名在同一文件系统上是原子性的，可以防止部分写入造成的数据损坏。
自动备份：每一次写作都会创造一个 .bak 覆盖之前的文件，使恢复变得容易。
Zod验证：所有JSON读取都是通过Zod模式验证的，而不是不安全的 as T 类型断言。
通用数据库管理器<T>：一个类处理所有8种实体类型的CRUD，消除了代码重复。
仅记录stderr：MCP为JSON-RPC使用stdout。任何 console.log 会破坏协议。我们使用 console.error 独家。
版本同步：每次数据文件修改都会出现颠簸 System.json versionId，迫使RPG Maker MZ编辑器重新加载。

🧪 发展

# Run tests
npm test

# Watch mode
npm run test:watch

# Build
npm run build

# Dev mode (auto-rebuild on changes)
npm run dev

运行时依赖性（最小）

包装	用途
`@modelcontextprotocol/sdk`	MCP协议实现
`zod`	架构验证

就是这样。只有2个运行时依赖项。

📄 许可证

该项目根据 GNU通用公共许可证v3.0.

您可以自由使用、修改和分发此软件，前提是衍生作品也在同一许可证下分发。

繁体中文

英语 | 繁体中文 | 日本语

简介

一个稳定、经过完整测试的模型上下文协议服务器，让Claude等AI助手能透过自然语言建立和编辑 RPG制造商MZ 项目。

为什么要重新开发？ GitHub上现有的RPG Maker MZ MCP Server都有严重问题—stdout污染导致MCP协议损坏、扩展名错误、没有原子写入、没有测试、SDK过时。本项目从头开发，解决了所有已知问题。

特色

原子写入：先写入 .tmp 暂存盘，再用 fs.rename() 覆盖目标，防止写入中断导致数据损坏
自动备份：每次写入前自动建立 .bak 备份档
Zod验证：读取JSON时透过Zod schema验证，取代不安全的 as T 型别断言
泛型数据库管理器：一个 DatabaseManager<T> 处理所有8种实体的CRUD，消除重复代码
stderr日志：MCP使用stdout进行JSON-RPC通信，任何 console.log 都会破坏协议。本项目只用 console.error
版本同步：每次修改资料档案后自动更新 System.json 的 versionId，强制RPG Maker MZ编辑器重新加载

可用工具（共23个）

类别	工具数	说明
项目管理	4	加载/建立/查询项目信息/列出素材资源
数据库CRUD	6	列出/取得/新增/更新/删除/搜寻（支持角色、职业、技能、道具、武器、防具、敌人、状态）
地图管理	5	列出/建立/查看/更新/删除地图
事件编辑	5	列出/建立/更新/新增指令/删除事件（支持40+种人类可读指令格式）
AI剧情生成	3	生成游戏剧情大纲/ NPC对话/任务设计

使用示例

连接MCP Server后，用自然语言跟Claude对话即可：

你：載入我的 RPG Maker MZ 專案，路徑是 /Users/me/Games/MyRPG

你：建立一個戰士角色，名字叫「羅蘭」，攻擊力要高

你：建立一張 20x15 的村莊地圖，叫做「橡木村」，背景音樂用 Town1

你：在地圖 2 的座標 (8, 6) 放一個 NPC 商人

你：幫商人加一段對話：「歡迎光臨！請看看我的商品。」

你：幫我設計一個拯救被綁架公主的任務

你：建立一個回復 200 HP 的治療藥水

安装与设定

git clone https://github.com/a951753abc/rpgmaker-mz-mcp.git
cd rpgmaker-mz-mcp
npm install
npm run build
npm test  # 42 個測試應全部通過

在你的项目目录建立 .mcp.json：

{
  "mcpServers": {
    "rpgmaker-mz": {
      "command": "node",
      "args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]
    }
  }
}

日本语

英语 | 繁体中文 | 日本语

概要

稳定性高，经过充分测试的，之模型上下文协议服务器。Claude等AI助手用自然语言 RPG制造商MZ（RPG Tuckle MZ）的项目可制作、编辑。

为什么是新开发的？ GitHub上的现有RPG Maker MZ MCP服务器存在严重问题—由于stdout污染导致的MCP协议损坏、错误的文件扩展名、无原子能写入、无测试、旧SDK。本项目从零开始解决了这一切。

特徴

原子写入：.tmp 写入临时文件→ fs.rename() 中所述修改相应参数的值。防止写入过程中的数据损坏
自动备份：写入前自动 .bak 创建备份
Zod验证：读取JSON时通过Zod架构进行验证。不安全 as T 消除类型断言
通用数据库管理器：DatabaseManager<T> 一个处理全部8种实体的CRUD。消除重复代码
专用记录：MCP将stdout用于JSON-RPC通信。console.log 是破坏协议console.error 仅使用
版本同步：每次更改数据文件时 System.json 的，之 versionId 自动更新，强制重新装入RPG校验MZ编辑器

23个可用工具

｜类别｜工具数｜说明｜ |---------|:---:|------| ｜项目管理｜4｜读取/创建/信息获取/资源列表｜数据库CRUD｜6｜一览/取得/制作/更新/删除/检索（反应器、职业、技能、物品、武器、防具、敌人角色、状态对应）｜｜地图管理｜5｜一览表/创建/详细信息/更新/删除｜｜事件编辑｜5｜一览/制作/更新/命令追加/删除（支持40以上的人能读的命令形式）｜生成AI剧本=3游戏剧本概要/NPC会话/任务设计的生成

使用例

连接MCP服务器后，只需用自然语言与Claude交谈即可：

あなた：/Users/me/Games/MyRPG にある RPGツクールMZ のプロジェクトを読み込んで

あなた：「ローランド」という名前の戦士キャラクターを作って、攻撃力を高めに

あなた：20x15 の村マップを作って、名前は「オークウッド村」、BGMは Town1 で

あなた：マップ 2 の座標 (8, 6) に NPC の商人を配置して

あなた：商人にセリフを追加して：「いらっしゃいませ！商品をご覧ください。」

あなた：さらわれた姫を救出するクエストを設計して

あなた：HP を 200 回復する回復薬を作って

安装和配置

git clone https://github.com/a951753abc/rpgmaker-mz-mcp.git
cd rpgmaker-mz-mcp
npm install
npm run build
npm test  # 42 テストがすべてパスするはず

在项目目录中 .mcp.json 创建：

{
  "mcpServers": {
    "rpgmaker-mz": {
      "command": "node",
      "args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]
    }
  }
}