Rpgmakermvultimate Mcp

一个 Model Context Protocol 服务，可让 AI Agent 通过 18 个整合工具检查和编辑磁盘上的真实 RPG Maker MV 项目。查找损坏的引用和开关条件，使用 MV 兼容的指令构建事件，并执行可重复的游戏测试。生成的数据仍需在游戏的图块集和插件中验证。

它提供了通常缺少的三项功能：

⚡ 快速入门

安装 Node.js 20.19.0 或更高版本，并在让 Agent 编辑项目文件前关闭 MV 编辑器。请从项目副本开始操作。

如需了解容器和目录托管，请参阅 Docker 和 Glama 构建配置。

**Windows x64 MCPB 包：**为兼容的 MCPB 客户端下载 v5.21.0。请参阅软件包要求和验证。下面的 npm 配置适用于受支持的各种操作系统。

在 itch.io 和 Smithery 上查找该项目。

添加服务前先检查环境（Windows 上使用 PowerShell）：

npx.cmd -y rpgmaker-mv-mcp --doctor "C:/path/to/your/RPGMakerMV/project"

coreReady: true 表示 Node 和 System 数据检查已通过。headlessReady: true 还表示 Playwright 和 Chromium 已就绪。该检查不会启动浏览器，也不会验证资源或插件。桥接警告不会阻止离线查询。若缺少 Chromium，请运行 npx.cmd playwright install chromium-headless-shell，或将 RPGMAKER_MCP_CHROMIUM 设置为 Chrome 可执行文件的路径。

1 — 将它添加到 MCP 客户端。 无需克隆；此软件包自带可执行文件。

配置

{
  "mcpServers": {
    "rpgmaker-mv": {
      "command": "npx",
      "args": ["-y", "rpgmaker-mv-mcp"],
      "env": {
        "RPGMAKER_PROJECT_PATH": "C:/path/to/your/RPGMakerMV/project"
      }
    }
  }
}

# Claude Code, user scope
claude mcp add rpgmaker --scope user \
  --env RPGMAKER_PROJECT_PATH="C:/path/to/project" \
  -- npx -y rpgmaker-mv-mcp

# From source
git clone https://github.com/DiegoLopez0208/RpgMakerMVUltimate-MCP
cd RpgMakerMVUltimate-MCP
npm install && npm run build
RPGMAKER_PROJECT_PATH=/path/to/your/project npm start

2 — 指定一个项目。 RPGMAKER_PROJECT_PATH 是包含 data/、js/ 和 index.html 的文件夹。服务无需此路径也能启动；如果愿意，也可以在运行时调用 set_project_path。

3 — 先让 Agent 四处查看。

get_project_context { detail: "full" }        → what exists, with real IDs
analyze_project     { view: "overview" }      → health, counts, unreachable maps

兼容 Claude Desktop、Claude Code、opencode 以及任何兼容 MCP 的客户端。

对于 Codex CLI，请使用 codex mcp add rpgmaker --env RPGMAKER_PROJECT_PATH=C:/path/to/project -- npx -y rpgmaker-mv-mcp。在无法启动 npx 的 Windows 客户端中，请使用命令 cmd，并传入参数 ["/c", "npx", "-y", "rpgmaker-mv-mcp"]。重启客户端，然后尝试三个首次生成配方。

🧭 功能

flowchart LR
    A["🤖 Agent"] -->|"generate_map · manage_map_event"| B["📁 Project on disk"]
    B -->|"validate · balance · metrics"| A
    B -->|"playtest"| C["🎮 Running game"]
    C -->|"exceptions · position · screenshots"| A
    A -->|"reload_map"| C

桥接器补上了这个循环的后半部分。在此之前，Agent 只能写入文件，然后寄希望于结果正确。

🗺️ 地图生成

generate_map 提供两种路径。根据项目是否使用 RTP 美术资源来选择。

知识驱动路径

{ "mode": "procedural", "theme": "town", "name": "Riverbend", "width": 40, "height": 30 }

有匹配模板的主题——town、village、dungeon、interior、castle、world 等——会克隆真实地图，而不是绘制杂乱的图块。没有匹配模板的主题（beach、swamp、desert…）则会回退到 Perlin 地形、BSP 地牢和细胞洞穴。战斗主题会自动为现有部队配置随机遇敌；town 和 village 会自动创建可进入的房屋内部，并设置双向传送。

主题 · forest town village castle dungeon cave beach desert swamp ruins interior snow harbor volcano sewer fortress magic_forest magic_interior space_interior space_exterior world

其他模式：blank（空白画布）、themed（简单布局）、template（指定一个内置地图）、batch（一次生成多张地图）、duplicate（复制现有地图）。

与图块集无关的路径

内置模板是原始 MV 地图 JSON，因此其中的图块 ID 只在 RTP 图块表上有意义。更换图块集后，地图就会变成杂乱的图块。semantic 会让布局保持抽象，直到最后一步才进行具体绘制：

manage_system { action: "mine_templates" }               # learn from THIS project
generate_map  { mode: "semantic", tilesetId: 5, rooms: 6, seed: 42 }

• 挖掘会读取你已创建的所有地图，并推导出语义布局（地面／墙壁／水域／道具／门，保持多图块道具的完整性）、图块集配置（标明项目中各角色所用的具体图块），以及令牌相邻计数。不会修改项目中的任何内容——所有数据都会写入 .mcp-cache/。
• 生成会先构建任务——入口 → 钥匙 → 锁门 → 宝藏 → Boss → 出口，以及侧边房间——将其表示为一张图，图中的边是通行的唯一路径，然后再绘制地图。由于锁是图中的一条边，而钥匙位于该边的入口一侧，因此地图在构造时就保证可通关。最后会根据完成后的邻近图块重新计算自动图块形状，而不是逐格猜测。
• 结果包含 markers，用于标明每个任务角色所在的格子；这些位置就是使用 manage_map_event 放置事件的地方。
• 传入挖掘得到的 templateId（例如 "mined-3"），即可将你自己的地图重新绘制到另一种图块集上。

playtest 本身是发后即忘：游戏会启动，但不会返回任何信息。桥接让整个流程闭环。

manage_system { action: "install_bridge_plugin" }   # once per project
manage_system { action: "bridge_start" }            # opens ws://127.0.0.1:32123
manage_system { action: "playtest" }                # the game connects on its own
manage_system { action: "bridge_telemetry", types: ["exception", "log"] }

sequenceDiagram
    participant A as 🤖 Agent
    participant S as 🖥️ MCP server
    participant G as 🎮 Game (nwjs)
    A->>S: edit_map
    S->>S: atomic write to Map002.json
    A->>S: bridge_command reload_map
    S->>G: reload_map
    G->>G: reserveTransfer + _needsMapReload
    G-->>S: reload_complete
    A->>S: take_screenshot
    S->>G: capture_screenshot
    G-->>S: PNG in base64
    S-->>A: path for analyze_image
    A->>S: record_video start / stop
    S->>G: MediaRecorder on the game canvas
    G-->>S: WebM in base64
    S-->>A: path for video evidence

• 📡 遥测 — 异常及其堆栈跟踪、console.error/warn、场景变更、玩家位置、当前正在执行的事件指令（可据此定位卡住的事件）、FPS 和堆内存。读取帧时会同时将其消费，除非传入 peek。
• ♻️ 热重载 — reload_map 会重新读取当前的 MapXXX.json 并重建场景，且不会丢失队伍状态：它通过引擎自身的重载接口 _needsMapReload，预留一次转移到玩家当前位置的操作，而不是手动重建 Spriteset_Map。reload_database 会重新读取一个数据文件；需要重新启动 playtest 的 System.json 和 Tilesets.json 会被拒绝，并附上说明。
• 📸 截图 — take_screenshot { name: "collision-proof" } 通过 MCP 插件捕获实时 playtest 画面，将带时间戳的 PNG 保存到 .mcp-cache/screenshots/，并返回其路径，供检查或作为 QA 证据。此操作不涉及 shell 截图命令。manage_system { action: "bridge_screenshot" } 仍作为兼容别名保留。
• 🎥 视频证据 — record_video { action: "start", name: "npc-dialogue" } 开始无声录制实时游戏画布，并生成 WebM；record_video { action: "stop" } 会将视频保存到 .mcp-cache/recordings/ 并返回其路径。Agent 可以通过允许列表中的 interact 命令和固定按钮输入 press_button，搭建可重复的场景——仍然没有任意脚本或 eval 命令。

🔒 安全性

除非游戏运行在 NW.js 下，并且启动时带有 test 参数，否则插件会在运行任何其他代码之前立即返回。玩家双击启动的已部署版本永远不会执行套接字代码，甚至不会执行 require('fs')。

它会检查每个参数，而不只是像 Utils.isOptionValid 那样检查 argv[0]，因为 playtest 会先传入项目路径。因此，如果有人刻意用字面值 test 参数启动已部署版本，它会通过这一检查——但随后找不到握手文件，也永远不会连接。

服务仅绑定到 127.0.0.1，拒绝任何携带浏览器 Origin 的升级请求（防止跨站 WebSocket 劫持），并要求在 5 秒内提供来自 .mcp-bridge.json 的会话令牌（通过恒定时间比较），否则会断开连接。

命令接口采用固定的允许列表，不包含 eval 原语。

analyze_project 只读且完全离线。它会对整个项目建模一次，让 Agent 能够分析自己并未制作的游戏。

搜索会返回 searchMode: "lexical"、complete、indexedFiles、skippedFiles 和 warnings。complete: false 表示部分数据无法读取；这并不意味着游戏中没有匹配内容。空结果会包含 noResultsReason。请使用项目中实际存在的名称或短语：herrero 不会翻译成 Blacksmith。支持包括日语在内的 Unicode 名称。查询不存在的 ID 时，数据库可能会返回 null；使用该 ID 前请先检查。

索引、概览、验证、图谱、用法、解释和重构也会报告输入不完整。无法读取的文件会显示为验证错误。

离线地图检查

• query_map { view: "ascii", mapId } — 将地图渲染为带事件标记的字符网格。这是查看布局并选择坐标的最简便方式。
• query_map { view: "validate", mapId } — 检查单张地图中的无效图块 ID、失效的传送设置以及缺失的事件终止符。

工具

该服务提供 18 个整合工具。旧版别名为可选项。

对于组合事件逻辑，请先使用 build_event_commands，然后使用 insert_event_commands 并设置 dryRun:true。预览会显示完整的旧命令列表和拟写入的命令列表。有关支持的类型、 嵌套规则、MV 专属差异和验证方法，请参阅事件命令编写。

• 原子性。 每次写入都会先写入临时文件，再将其重命名覆盖目标文件，因此调用中断也不会留下只写入一半的 JSON。
• 有备份。 在 .mcp-backups/ 下保留带时间戳的轮换副本（最近 N 份，RPGMV_BACKUP_KEEP，默认值为 10）。备份失败时会中止替换。写入使用唯一临时文件和每个文件独占的锁；如果检测到自读取数据后发生了更改，则会拒绝写入。请关闭编辑器：它不会遵守 MCP 锁，而且多文件操作并非事务。
• 可预览。 对任何会修改数据的工具传入 dryRun: true，即可准确查看它将写入的内容，而不会触碰磁盘。

⚠️ Agent 工作期间请关闭 RPG Maker 编辑器。 编辑器会将项目保存在内存中，并在保存时覆盖更改。

⚙️ 配置

# OpenAI
VISION_API_URL=https://api.openai.com VISION_API_KEY=sk-... VISION_MODEL=gpt-4o npm start
# Ollama (local, no key)
VISION_API_URL=http://localhost:11434 VISION_MODEL=llava npm start

🎓 Agent 技能

便携式 Agent 技能可教会任何模型无崩溃工作流——使用 generate_map 构建地图，使用 manage_map_event 预设添加内容，绝不手动绘制图块或猜测 ID。文件位于 skill/rpgmaker-mv-mcp/SKILL.md。

# Claude Code / Claude.ai
npx degit DiegoLopez0208/RpgMakerMVUltimate-MCP/skill/rpgmaker-mv-mcp ~/.claude/skills/rpgmaker-mv-mcp
# opencode
npx degit DiegoLopez0208/RpgMakerMVUltimate-MCP/skill/rpgmaker-mv-mcp ~/.opencode/skills/rpgmaker-mv-mcp

也已收录于 awesome-claude-skills。

🚧 已知限制与路线图

• RTP 模板路径中的装饰语义尽力而为；少数多图块物件可能会以单个图块的形式放置。挖掘路径会保留多图块道具的整体结构。
• 城镇和地牢布局会持续改进——计划包括：以中央广场或水井作为地标、房屋成排并朝向道路、添加围栏和庭院、构建更丰富的道路网络，以及增加更多房间类型。
• mode: "semantic" 目前会生成地牢形状的任务。接下来将支持城镇和开放世界任务语法，并使用挖掘所得的邻接计数来进行装饰，而不只是描述。
• balance 会在同一类别中比较相似对象，因此，与随机遭遇相比，首领理应显得像个离群值。请查看标志，而非结论。
• 桥接功能仅支持在 Windows/nwjs 上进行游戏测试，并且需要在项目中安装其插件。
• 视觉 AI 需要使用你自己的端点。

🛠️ 开发

npm install
npm run build      # tsc compile (+ copies knowledge/ into dist/)
npm test           # vitest
npm run typecheck
npm run dev        # tsx watch mode

💬 反馈

项目正在积极开发中，非常欢迎反馈——无论是错误报告、奇怪的地图、缺少的工具，还是各种想法。请提交 GitHub Issue，说明你让 Agent 执行了什么，以及实际得到的结果；导出的地图 JSON 或截图会很有帮助。