# rpgmaker-mz-mcp **Category:** πŸ—„οΈ Databases **Repository:** https://github.com/Redseb/rpgmaker-mz-mcp **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/rpgmaker-mz-mcp ## Description MCP server for RPG Maker MZ: maps, tile painting, events, database editing, and validation. ## Claude Desktop Quick Installation Heuristic fallback β€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "rpgmaker-mz-mcp": { "command": "npx", "args": ["-y","rpgmaker-mz-mcp"] } } ``` ## Documentation & README
RPG Maker MZ MCP Server # RPG Maker MZ MCP Server [![CI](https://github.com/Redseb/rpgmaker-mz-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Redseb/rpgmaker-mz-mcp/actions/workflows/ci.yml) [![Tools](https://img.shields.io/badge/tools-119-e94560.svg)](#available-tools) [![MCP](https://img.shields.io/badge/MCP-stdio-e94560.svg)](https://modelcontextprotocol.io/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178c6.svg)](tsconfig.json) [![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-3fa796.svg)](package.json) [![License: MIT](https://img.shields.io/badge/License-MIT-3fa796.svg)](#license) **119 tools** that let an AI assistant read and write an RPG Maker MZ project directly β€” actors, classes, skills, items, equipment, states, enemies, troops, common events, maps, tiles, tilesets, events, and system settings β€” instead of hand-editing everything in the editor. _"Add a town under the world map, paint it with grass, and drop in a shopkeeper who sells potions"_ β†’ done, in-project, no editor clicks.
## Quick start **Claude Code (recommended)** β€” installs the server *and* the authoring skills as one plugin: ```bash claude plugin marketplace add Redseb/rpgmaker-mz-mcp claude plugin install rpgmaker-mz@rpgmaker-mz-mcp ``` You'll be prompted for your RPG Maker MZ project directory (optional β€” you can also just ask Claude to `set_project` later). **Any other MCP client** β€” the server is on npm; no clone or build needed: ```json { "mcpServers": { "rpgmaker-mz": { "command": "npx", "args": ["-y", "rpgmaker-mz-mcp@latest"], "env": { "RPGMAKER_PROJECT_PATH": "/path/to/your/rpgmaker/project" } } } } ``` **Claude Desktop** β€” either the JSON config above, or download the one-click `rpgmaker-mz-mcp.mcpb` bundle from [Releases](https://github.com/Redseb/rpgmaker-mz-mcp/releases) and open it with Claude Desktop. New here? Read [SETUP.md](SETUP.md) for the full walkthrough and [EXAMPLES.md](EXAMPLES.md) for end-to-end recipes. ## Contents - [Quick start](#quick-start) - [Capabilities](#capabilities) - [How it fits together](#how-it-fits-together) - [Installation](#installation) - [Configuration](#configuration) - [Usage](#usage) - [Available tools](#available-tools) - [Input validation](#input-validation) - [Event validation (throw-by-default)](#event-validation-throw-by-default) - [Reference linting](#reference-linting) - [Dry-run preview](#dry-run-preview) - [Custom-tileset catalog skill](#custom-tileset-catalog-skill) - [Example prompts](#example-prompts) - [Development](#development) - [Project structure](#project-structure) - [Safety and best practices](#safety-and-best-practices) - [Limitations](#limitations) ## Capabilities - **Database CRUD** β€” actors, classes (with learnings & param curves), skills (full-control + simplified damage/heal/buff/state helpers), items, weapons, armors, states, enemies, and troops. Only a `name` is required to create; everything else falls back to the editor's true "New X" template. - **Maps & the map tree** β€” create/delete maps, batch-reparent/reorder/rename with a cycle guard, and edit map properties. New maps register in `MapInfos.json` exactly as the editor expects. - **Tile painting (with automatic autotiling)** β€” `paint_tiles`/`fill_area` set tiles on any of the six map layers and recompute autotile shapes (and their neighbours') from same-kind adjacency, so a filled region borders itself correctly. `place_object` stamps multi-tile B/C objects (houses, trees) and reports their passability footprint. - **Semantic tile catalog** β€” `find_tile "grass"` β†’ a paintable tile id. Built-in catalogs for every default tileset (Overworld, Outside, Inside, Dungeon, SF), sourced from RPG Maker's own English name sidecars. A bundled vision-bootstrap skill catalogs **custom** tilesets. - **Passability & terrain** β€” read a tile's flags or a map cell's layered passability (`get_tile_flags`/`check_passability`), and **edit** passability/terrain-tag/behaviour flags (`set_tile_flags`). - **Event-command builders** β€” high-level, read-only builders that emit the exact `EventCommand` sequences the editor writes (including tricky recursive branch blocks and continuation rows), landed on a page via `insert_event_commands`. Covers dialogue & flow, game-state changes, presentation/transitions, and scene processing. - **Event & NPC ergonomics** β€” `create_npc` places a complete talking NPC in one call; `set_event_page` merges a page's graphic + behavior in place. - **Asset awareness** β€” `list_assets` enumerates valid character/face/tileset/audio names so events never reference a missing file. - **Correctness layer** β€” Zod-validated inputs, throw-by-default event validation (a structurally invalid write is refused, not saved-and-warned-about), a cross-file reference linter (`validate_references`), and a dry-run/diff preview on every write. ## How it fits together
AI assistant talks to the MCP server over stdio, which reads and writes the RPG Maker MZ project's data files
## Installation Pick one: - **Claude Code plugin** *(recommended)* β€” `claude plugin marketplace add Redseb/rpgmaker-mz-mcp`, then `claude plugin install rpgmaker-mz@rpgmaker-mz-mcp`. This bundles the MCP server (run via npx from the npm package) together with the two authoring skills (`rpgmaker-authoring`, `tileset-catalog`) β€” the skills carry the judgment the tools don't enforce, so this is the full experience. - **npm package** β€” configure your MCP client to run `npx -y rpgmaker-mz-mcp@latest` (see [Quick start](#quick-start)). Tools only, no skills. - **MCPB bundle (Claude Desktop)** β€” download `rpgmaker-mz-mcp.mcpb` from [Releases](https://github.com/Redseb/rpgmaker-mz-mcp/releases), open it with Claude Desktop, and pick your project folder in the install dialog. - **From source** (development): ```bash npm install npm run build ``` ## Configuration Set the RPG Maker MZ project path as an environment variable: ```bash # macOS/Linux export RPGMAKER_PROJECT_PATH=/path/to/your/rpgmaker/project # Windows set RPGMAKER_PROJECT_PATH=C:\path\to\your\rpgmaker\project ``` The path must point to a directory containing `game.rmmzproject` and a `data/` directory with `System.json`. The environment variable is only the startup default: the `set_project` tool can retarget a running server at a different project (and `get_project` reports the current one), so switching games doesn't require editing config or restarting. ## Usage ### Running the server ```bash npm start # or: node dist/index.js ``` ### Configuring in Claude Desktop The easiest path is the `.mcpb` bundle from [Releases](https://github.com/Redseb/rpgmaker-mz-mcp/releases) β€” open it with Claude Desktop and pick your project folder. To configure by hand instead, add to your Claude Desktop configuration file (`%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "mcpServers": { "rpgmaker-mz": { "command": "npx", "args": ["-y", "rpgmaker-mz-mcp@latest"], "env": { "RPGMAKER_PROJECT_PATH": "/path/to/your/rpgmaker/project" } } } } ``` (For a from-source checkout, use `"command": "node"` with `"args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]` instead.) ## Available tools All 119 tools, grouped by area. Tools that write to the project accept an optional `dryRun` argument (see [Dry-run preview](#dry-run-preview)); those that can refuse a structurally invalid write also accept `force` (see [Event validation](#event-validation-throw-by-default)).
Expand the full tool reference ### Project targeting - `get_project` β€” the project the server is operating on: path, validity, game title - `set_project` β€” retarget the server at another project directory for the rest of the session (no restart; overrides `RPGMAKER_PROJECT_PATH`) ### Actors - `create_actor`, `update_actor`, `search_actors` ### Classes - `create_class`, `update_class` - `add_class_learning` β€” attach a skill learned at a level (validates the skill, keeps learnings level-sorted) - `set_class_param_curve` β€” replace one of the 8 parameter growth rows ### Skills - `create_skill` (full control), `update_skill`, `search_skills` - `create_damage_skill`, `create_healing_skill`, `create_buff_skill`, `create_state_skill` β€” natural-language-friendly helpers for common skill types ### Items & equipment - `create_item`, `update_item`, `search_items` - `create_weapon`, `update_weapon` - `create_armor`, `update_armor` ### States - `create_state`, `update_state` ### Enemies & troops - `create_enemy`, `update_enemy`, `search_enemies` - `create_troop`, `update_troop`, `search_troops` β€” `create_troop` validates that every member references an existing enemy ### Common events - `create_common_event`, `update_common_event` - `call_common_event` β€” builds the code-117 call command and validates the target exists ### Maps & the map tree - `get_map` (pass `includeData: false` to omit the tile array on a big map), `get_map_infos`, `get_map_dimensions`, `update_map` - `get_map_region` β€” read a window of tile ids (x, y, width, height, layer) instead of the whole map - `create_map` β€” allocates the next id, writes a blank map, and registers it in the tree - `delete_map` β€” removes a map and reparents its children onto its parent - `update_map_tree` β€” batch reparent/reorder/rename/expand with an up-front existence check and cycle guard ### Map events - `get_map_events`, `get_map_event`, `search_map_events` - `create_map_event`, `update_map_event`, `delete_map_event` - `add_event_command` β€” append a single command to an event page - `set_map_tile` β€” set a single raw tile id at (x, y) on a z-layer (no autotiling) ### Event & NPC ergonomics - `create_npc` β€” one-shot "talking NPC": graphic + trigger + a talk list from `text` or explicit `commands` - `create_chest` β€” one-shot treasure chest: the two-page self-switch idiom (give item/weapon/armor/gold, then never again) - `create_transfer` β€” one-shot map transfer, in either working idiom: face a solid landmark (`action_button`) or step on a doormat (`player_touch`) - `set_event_page` β€” merge a page's graphic + behavior (sprite, trigger, priority, movement, flags) in place ### Event-command builders Read-only builders that return editor-faithful `EventCommand` sequences; land them on a command list with `insert_event_commands`. - **Dialogue & flow:** `build_show_text` (101/401), `build_show_choices` (102/402–404), `build_conditional_branch` (111/411/412), `build_flow_command` (wait/exit/label/jump) - **Game state:** `build_control_switch` (121/123), `build_control_variable` (122), `build_change_gold` (125), `build_change_items` (126–128), `build_change_party_member` (129) - **Presentation & transitions:** `build_transfer_player` (201), `build_play_audio` (BGM/BGS/ME/SE), `build_screen_effect` (fade/tint/flash/shake), `build_picture` (show/erase), `build_character_effect` (animation/balloon) - **Scenes:** `build_battle_processing` (301), `build_shop_processing` (302/605), `build_name_input` (303), `build_change_actor` (HP/MP/state/recover/EXP/level, 311–316) - **Insertion:** `insert_event_commands` β€” splice a built sequence into a map event page (the default `target`), a common event body, or a troop battle-event page, then validate ### Move routes - `create_move_route` β€” build a `MoveRoute` from a named pattern (patrol/approach/flee/wander/custom) - `set_movement_route` β€” insert a forced Set Movement Route (code 205 + 505 continuation rows) ### Plugin commands - `scan_plugins` β€” discover the plugin commands this project actually has, by parsing `js/plugins/*.js` annotations (+ enabled state from `js/plugins.js`) - `list_plugin_commands` β€” view the known plugin commands (the project scan merged over a built-in allowlist) - `create_plugin_command` β€” build a code-357 plugin command with normalized args ### Tiles, catalog & painting - `describe_tile` β€” decode a raw tile id (sheet, autotile kind/shape, geometry) - `get_tile_catalog`, `find_tile` β€” resolve human names ↔ paintable tile ids (`find_tile` can widen the search to a custom sheet's catalog descriptions with `searchDescriptions`) - `paint_tiles`, `fill_area` β€” paint with automatic autotiling - `place_object` β€” stamp a multi-tile B/C object and report its passability footprint ### Tileset flags (passability / terrain) - `get_tile_flags` β€” decode a tile's passability/star/ladder/bush/counter/damage/terrain-tag - `check_passability` β€” the map-aware, layered answer for a cell - `set_tile_flags` β€” **edit** a tile's flags (non-destructive merge; auto-applies to all 48 shape slots of an autotile kind) ### Assets - `list_assets` β€” enumerate available asset basenames (characters, faces, tilesets, pictures, audio, …) ### System & vocabulary - `get_system`, `get_game_title`, `update_game_title` - `get_title_screen`, `update_title_screen` β€” background layers, BGM, and the "draw game title" toggle - `get_variables`, `set_variable_name`, `get_switches`, `set_switch_name` - `get_starting_position`, `update_starting_position` - `get_party`, `set_party` β€” the starting party (`set_party` validates every actor id) - `get_terms`, `set_term` β€” menu vocabulary - `get_types`, `set_type_name` β€” element/skill/weapon/armor/equip type-name lists - `set_currency_unit` ### Batch creation - `batch_create` β€” create many records of one type (actors, items, weapons, armors, skills, enemies, states, classes) in a single call and a **single file write**; ids allocate sequentially, so a record can reference a sibling made earlier in the same batch ### Index & validation - `list_names` β€” cheap `{ id, name }` index for a table (actors, items, skills, maps, enemies, …) - `get_database` β€” full records from one table (actors, classes, items, weapons, armors, skills, enemies, troops, states, common_events), or a single record by `id` - `validate_event`, `validate_project` β€” event-command-shape validation (read-only) - `validate_references` β€” cross-file id-integrity audit (partyβ†’actor, transferβ†’map, effectβ†’state/skill/common-event, dropsβ†’item, map-tree cycles, …) ### ID allocation - `list_allocated_ids` β€” which switch / variable / common-event IDs are already spoken for, derived from the project's own JSON; with `id`, every place that one is referenced - `next_free_id` β€” reserve the next unallocated ID(s) instead of picking one by hand
## Input validation Every tool declares its arguments as a [Zod](https://zod.dev) schema. The server (built on the MCP SDK's high-level `McpServer`) validates incoming arguments against that schema **before** a handler runs, so malformed calls are rejected with a clear `Input validation error` naming the offending field instead of writing garbage to disk. ## Event validation (throw-by-default) Event command lists are checked against a table of known RPG Maker MZ command codes (`101` Show Text, `201` Transfer Player, `122` Control Variables, …), and against the **block structure** those commands form. Findings come in two tiers, and the tier decides what happens to the write: - **Structural** β€” a wrong parameter count for a known command (including the counts that depend on a Conditional Branch's condition type or a Control Variables operand type), a list not terminated by the code-`0` end marker, a non-array `parameters`, a broken block (a Show Choices/Conditional Branch/Loop that is never closed, a branch or closer row orphaned or written at the wrong indent, a choice with no `When` branch), or an action-button event stranded on an impassable tile. These are almost always bugs, so the event-writing tools **validate the would-be result before committing and refuse the write**: the tool errors and *nothing reaches disk*. Pass `force: true` to write anyway (the argument is advertised on exactly the tools that can refuse). - **Advisory** β€” an unrecognized command code (which may simply be a plugin command), an over-long text line, an unknown asset filename, a choice block whose Cancel routing and `When Cancel` branch disagree (dead code, not corruption). These are legitimately possible, so they never block; they ride along as `warnings` on the normal response. Because the check runs *before* the commit, a `dryRun` of a write that would be refused fails too, rather than previewing a write that could never happen. `validate_event` / `validate_project` remain read-only audits: they report both tiers (each finding carries a `severity`) without changing anything. ### Text width: teaching it your font The over-long-text-line warning is measured in **characters** by default β€” 55 per line, 38 when a face graphic is shown β€” which suits the stock RTP font and needs no setup. If your project ships a different font, that estimate goes wrong in one of two directions: a **narrower** font makes it warn on lines that fit comfortably, and a **wider or larger** one makes it stay quiet on lines that really are cut off (38 characters of a 24px glyph is 912px in a 616px window). No single character limit fixes both, because glyph widths in a proportional font span a wide range β€” a full stop can be a third the width of a capital. Drop a **`.rpgmaker-mcp.json`** in the project root to replace the estimate with a real measurement: ```json { "text": { "lineBudget": { "noFace": 784, "withFace": 616 }, "nameBudgetChars": 8, "charWidths": { "_default": 13, "a": 11.38, ".": 4.88, " ": 8.12 } } } ``` - **`lineBudget`** β€” the message window's usable width, without and with a face graphic. In pixels if you give `charWidths`, otherwise in characters (a bare `lineBudget` is just a character-limit override). - **`charWidths`** β€” per-character advance; `_default` covers anything unlisted. Get these from the engine itself: `Window_Base.textWidth(c.repeat(40)) / 40` in a running game is exact. - **`nameBudgetChars`** β€” how wide to assume `\N[3]` / `\P[1]` renders. A name is typed by the player at runtime, so budget the Name Input `maxLength` (usually 8) rather than the default name, or a long name overflows a line that fitted while you were testing. Defaults to `0`, which ignores name escapes as before. Everything fails soft: no file, bad JSON, or a malformed `text` section leaves the built-in estimate in place, so a broken config is never worse than no config. The file is re-read when its mtime changes, and warnings then report real widths (`Show Text line is 650px but the message window fits 616px with a face shown`). ## Reference linting `validate_references` performs a **cross-file id-integrity audit** β€” orthogonal to the command-shape check above. It walks the whole database and flags references that point at something that doesn't exist: a starting party member with no matching actor, a Transfer Player targeting a missing map, a skill effect that adds a non-existent state, an enemy dropping an unknown item, a cyclic map-tree parent, and more. Every check is warn-by-default and guarded against false positives on partially-loaded projects. ## ID allocation Switches, variables and common-event IDs are one global namespace, and nothing in RPG Maker stops a later edit from claiming an ID an earlier one already used. The failure is silent β€” no crash, no validator hit, just a door that is inexplicably already open hours into a playtest. `list_allocated_ids` answers "what's taken?" **from the project files themselves** β€” never a hand-maintained list, which would drift the moment someone edited in the RPG Maker editor. An ID counts as allocated if it is *declared* (a `System.json` label, a `CommonEvents` row) **or** *referenced* anywhere: event page conditions and command lists, common events, troop pages, and Common Event skill/item effects. Both halves matter β€” a named-but-unused switch is a claim someone staked, and a used-but-unnamed one is a claim nobody wrote down. Pass `id` to ask the narrower question: where is switch 23 actually used, before I touch it? `next_free_id` hands back the next unallocated ID(s), strictly above everything already taken. Holes below the highest ID are left alone by default (a hole is often an ID claimed in notes but not yet written); `reuseGaps: true` fills them when you're compacting deliberately. It's read-only β€” it suggests IDs, it doesn't write them, so name what you take with `set_switch_name` / `set_variable_name` to make the claim visible to whoever edits next. Those two grow the `System.json` name list when the ID is past the end, so an ID from `next_free_id` can always be labelled without opening the editor. Like the command validator, the usage scan is **curated, not exhaustive**: it covers the commands that carry switch/variable IDs (Control Switches/Variables, Conditional Branch, the "designation by variable" forms of Transfer Player, Change Gold/Items, Change HP/MP/EXP/Level, …), and every report states the command codes it scanned. An ID used only from a `Script` (355) or a plugin command (357) will read as free. ## Dry-run preview Every tool that writes to the project accepts an optional `dryRun` argument. When `dryRun: true`, the tool computes what it _would_ write and returns a diff instead of touching any files: ```json { "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` carries the response the tool would have produced, so a dry-run also previews the validation warnings a write would have reported β€” not just the diff. All writes go through a single choke point that skips no-op writes and keeps the on-disk JSON in the editor's compact single-line format. File deletions (e.g. `delete_map`) share the same dry-run machinery. ## Quiet write echoes A write tool that echoes the whole record back costs the one caller that always pays for it β€” an AI assistant, whose context is the scarce resource. So the tools that would otherwise replay a command list or a map's events **return a summary by default**: | tool | echoes | |---|---| | `update_map`, `resize_map` | the map without its tile `data` or its `events`, plus `dataTileCount` / `eventCount` | | `update_map_event`, `set_event_page`, `add_event_command` | event identity + per-page `trigger` / `priorityType` / `moveType` / graphic / `listLength` | | `insert_event_commands` | `listLength` + `listCodes` β€” the resulting command **codes**, without the parameters | | `create_common_event`, `update_common_event` | identity, trigger wiring, `listLength` + `listCodes` | | `create_troop`, `update_troop` | identity, members, per-page `listLength` | The rule: **keep what you would assert on, drop what you would only re-read.** Command codes stay, because they are how you verify a splice landed where you asked (`is the 302 still after the two 101s`); command parameters go, because they are what you just wrote. Pass **`verbose: true`** on any of those calls for the old full record, or read it back with `get_map` / `get_map_event` / `get_database`. `warnings` always survive summarization, and a dry-run's `wouldReturn` is summarized the same way so a preview and the real call report the same shape. Measured on six calls from one real authoring session: **115,080 β†’ 3,672 characters (-97%)**. A single `update_map` that set a map's BGM was echoing 46,846 characters of dialogue back at the caller. ## Custom-tileset catalog skill The default tilesets are cataloged out of the box. For a **custom** (non-RTP) tileset, a bundled Claude skill under `.claude/skills/tileset-catalog/` slices each sheet into labelled samples, has Claude vision-name them, and writes a versioned, project-scoped catalog to `data/tilecatalog/` β€” after which `find_tile`/`get_tile_catalog` resolve names for that sheet too. Those drafts also record what each tile *looks like*, so `find_tile` with `searchDescriptions: true` can match that text when a machine-drafted name is too terse to search by. The skill ships a dependency-free PNG codec and engine-exact tile geometry, so it runs anywhere Node does. ## Example prompts Once configured, drive your project in natural language: - "Create a fire skill 'Fireball' costing 15 MP that deals `a.mat * 4 - b.mdf * 2` to one enemy." - "Add a new town map under the world map, 30Γ—25, using the Outside tileset." - "Paint grass in a 10Γ—8 rectangle at (4, 4) on map 3 and let it auto-border." - "Place a talking NPC named 'Guard' at (8, 5) on map 2 who says 'Halt! Who goes there?'" - "Make the water tiles on tileset 1 impassable and tag them terrain 1." - "Check my project for broken references before I ship." ## Development ```bash 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) ``` During development you can skip the build entirely by running the server from source with [tsx](https://tsx.is): point your MCP client's `command` at `node_modules/.bin/tsx` with `src/index.ts` as the argument. Since tsx doesn't type-check, run `npm run typecheck` alongside lint and tests before committing. CI runs lint, format check, tool-count sync check, tests, and build on every push and pull request (see `.github/workflows/ci.yml`). ### Keeping the tool count in sync The advertised tool count lives in a few human-facing spots β€” the README prose and badge, and the two SVGs in `assets/`. `npm run sync:tools` counts the real tools from `src/tools/` and re-stamps all of them, so bumping the number after adding a tool is one command. `npm run sync:tools:check` (run in CI) fails if any spot is stale. ### Releasing `package.json` is the source of truth for the version; `npm run sync:version` stamps it into the plugin manifest (`.claude-plugin/plugin.json`), the MCP-registry metadata (`server.json`), and the MCPB manifest (`mcpb/manifest.json`). CI and `prepublishOnly` fail if they drift. A release is: ```bash 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 ``` The Claude Code plugin needs no separate publish β€” users' installs update from this repo (the plugin runs the npm package via `npx rpgmaker-mz-mcp@latest`, so bumping npm is what ships new tools). **Tag last, and never amend a tagged commit.** `npm version` on its own commits *and* tags before `sync:version` has stamped the other manifests, so the old recipe amended afterwards β€” which left the tag pointing at the pre-amend commit, with stale manifests and off the branch entirely. `--no-git-tag-version` avoids the whole problem: one commit, then the tag. Push the tag by name (`--follow-tags` is easy to get wrong here), and don't skip `gh release create` β€” nothing before it creates the GitHub release. ## Project structure ``` 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 β”‚ β”œβ”€β”€ 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 ``` ## Safety and best practices 1. **Close the RPG Maker MZ editor** while using this server β€” it writes JSON files directly, and the editor can overwrite changes on save. 2. **Use version control** for your project. Combined with dry-run previews and validation, git is the safety net (the server does not make automatic backups). 3. **Preview destructive edits** with `dryRun: true` before committing them. 4. **Test in-engine** after significant changes. ## Limitations - Writes JSON files directly; the editor must be closed to avoid conflicts. - Plugin commands are validated against the plugins your project actually ships (`scan_plugins` parses their `@command`/`@arg` annotations), falling back to a small built-in allowlist. Since RPG Maker MZ has no "required argument" annotation, scanned args are checked for unknown names only, never for missing ones; a plugin with no annotation block passes through unchecked. - Animations (`Animations.json`, Effekseer-based) are not edited by this server. ## Acknowledgements This project started life as a fork of [k4zuki0539/-rpgmaker-mz-mcp](https://github.com/k4zuki0539/-rpgmaker-mz-mcp) (MIT), which provided the original CRUD scaffolding. It has since grown well beyond that starting point β€” into full vanilla level-design and game-logic authoring (see [Capabilities](#capabilities)) β€” and is now maintained as its own project. Thanks to the original author for the foundation. ## License [MIT](https://opensource.org/licenses/MIT) ## Resources - [RPG Maker MZ Official Website](https://www.rpgmakerweb.com/products/rpg-maker-mz) - [Model Context Protocol Documentation](https://modelcontextprotocol.io/) - [RPG Maker MZ Database Structure](https://github.com/rpgtkoolmv/rmmz-api-reference)