io.github.Redseb/rpgmaker-mz-mcp

Decode a raw RPG Maker MZ tile id into its tileset sheet (A1–A5, B–E), and for autotiles its kind + shape slot (0–47) and autotile geometry (floor/wall/waterfall). Read-only inspection helper — raw tile ids are opaque integers, this makes one legible. Returns { tileId, empty, sheet, sheetIndex, autotile, kind?, shape?, autotileType? }. Pass `tilesetId` to also inspect the sheet PNG and report `transparent` (true = the tile is see-through and needs an opaque base tile on a lower layer; painting it on layer 0 alone shows the map void) + `transparentPercent`.

Fill a rectangular area of a map with one tile id, with automatic autotiling — a filled autotile region borders itself correctly (and re-borders any same-kind tiles it touches). Flat tiles fill uniformly. Defaults to the lower ground layer (0). For region ids, fill layer 5 with the region number as tileId.

Find tiles in a tileset by a case-insensitive SUBSTRING match on their catalog name — a quick bridge from a name fragment like 'grass' or 'forest' to a paintable tile id. This is a literal substring match, NOT synonym/semantic search: 'water' matches 'Endless Waterfall' but not 'Sea' or 'Pond' (their names lack the substring). To browse the actual tile names first, use get_tile_catalog with a `sheet` filter, then search a fragment you see. Set `searchDescriptions: true` to also match the free-text description a project catalog carries (custom sheets named by the tileset-catalog skill — their names are terse, the descriptions say what the tile looks like); built-in RPG Maker entries have no description, so this only widens the search over custom sheets. Returns matching catalog entries (name, sheet, tile id, autotile kind, `source`, `matchedIn` [which fields matched], `transparent` [true = needs an opaque base on a lower layer], plus `description`/`confidence`/`manual` for project catalog drafts). Covers the default Overworld tileset plus custom sheets cataloged into data/tilecatalog/ (via the tileset-catalog skill). Read-only.

Read a database table in full: actors, classes, items, weapons, armors, skills, enemies, troops, states, or common_events. Returns the raw 1-indexed array (slot 0 is null), or — with `id` — that single record, or null if no such record exists. These are full records: prefer list_names for an id→name index, or search_actors/search_items/search_skills to find records by name, and reach for this only when you need every field. Maps and tilesets are not here: use get_map_infos/get_map and get_tilesets/get_tile_flags. Read-only.

Get the game title

Get map data by ID. The tile `data` array can be huge on a painted map (width*height*6 ints) and blow the MCP token limit, so pass includeData:false to omit it (you get dataTileCount instead) and read tiles with get_map_region when needed. includeData defaults to true for backward compatibility.

Get the width and height (in tiles) of a map

Get a specific event from a map

Get all events from a specific map

Get information about all maps

Read the raw tile ids in a rectangular window of one map layer — a token-cheap alternative to get_map for inspecting part of a painted map. Returns `tiles` as a 2D array (rows top→bottom, each left→right) of raw engine tile ids. The rectangle must lie fully within the map bounds (throws otherwise). layer defaults to 0 (see set_map_tile for the z-layer meanings).

Get the starting party — the actor ids the game begins with. Returns `{ partyMembers }`, rhyming with set_party's input/output shape.

Get the project directory the server is currently operating on: its path, whether it is a valid RPG Maker MZ project, and the game title it holds.

Get the game starting position ({ mapId, x, y })

Get all game switch names

Get system data

Get the game vocabulary/terms: the `basic`, `commands`, `params` string arrays and the `messages` map (menu labels, system messages).

Get the semantic tile catalog for a tileset: the named tiles (e.g. 'Grassland A', 'Forest', 'Sea') in each of its image sheets, each with its representative tile id and a `source` ('builtin' = RPG Maker's own labels; 'project' = a draft name from the vision-bootstrap skill). Project (custom-sheet) entries also carry the skill's `description`, `confidence` ('high'/'medium'/'low'), and `manual` (true = a human verified it) so you can gauge how trustworthy a draft name is. Autotile entries (A1–A4) return the kind's base tile id — feed it to a paint command, which recomputes the shape from neighbours. Covers the default Overworld tileset (World_A1/A2/B/C) plus any custom sheets cataloged into data/tilecatalog/ (via the tileset-catalog skill); still-uncovered sheets are omitted. **Called WITHOUT `sheet` it returns only a per-sheet index (name + entry count) to stay within the tool-output limit — a full tileset can hold thousands of named tiles. Pass `sheet` (filename 'World_A2' or slot role 'A2') to list one sheet's actual tile entries.** Sheet-filtered entries also carry `transparent` (true = the tile is see-through and needs an opaque base tile on a lower layer — painting it on layer 0 alone shows the map void; e.g. trees/objects/overlays). Read-only.

Decode a tileset's flag word for a single tile id into a legible view: 4-direction passability (down/left/right/up — true = walkable that way), the [*] 'star' overlay bit, ladder/bush/counter/damage-floor flags, and terrain tag (0–7). Read-only inspection of data/Tilesets.json flags[]. Note passability here is for the tile in isolation; a real cell's passability layers its stacked tiles — use check_passability for that. Returns { tilesetId, tileId, tile, flags }.

List every tileset in the project with its id, name, mode (0 world / 1 area), and the image sheets it uses (labelled A1–A4, A5, B–E; empty slots omitted). Use this to discover valid tilesetId values (needed by find_tile, get_tile_catalog, paint_tiles, fill_area, place_object, get_tile_flags, set_tile_flags, check_passability) and to see which sheets each tileset is built from. For a plain id→name list, list_names(type:"tilesets") is even cheaper. Read-only.

Get the title screen settings: title1Name/title2Name (background layers, from list_assets("titles1"/"titles2") — title2Name draws over title1Name), titleBgm (the AudioFile that plays while it is shown), and drawTitle (whether the game title text is drawn over the art).

Get one System.json type-name array — the named lists other data references by index: elements, skillTypes, weaponTypes, armorTypes, or equipTypes.

Get all game variable names

Insert a pre-built sequence of event commands (from the build_* builders) into any of the three command lists an MZ project has — the mutating companion to the read-only builders. Splices before the list’s end marker (or at `position`). target "map_event" (the default) needs mapId + eventId + pageIndex; "common_event" needs commonEventId; "troop_page" needs troopId + pageIndex. The resulting list is validated before writing: a structural problem (wrong parameter count for a command code, a list left unterminated) refuses the write and saves nothing — pass force: true to override. Advisory findings (unrecognized code, over-long text line) are returned as `warnings` and never block. Returns { target, id, list, warnings? }.

Show which switch / variable / common-event IDs are already spoken for, derived from the project's own JSON (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. Use this before reusing an id, and pass `id` to answer "where is switch 23 actually used?" before touching it. Returns { count, highest, gaps, declaredCapacity, allocated[], coverage }. Read-only. To claim a fresh id instead, use next_free_id.

List the available asset filenames (extension stripped) for one asset kind — the exact names RPG Maker's data references (a sprite/face/tileset/audio name). Use it to validate a graphic or audio name before wiring it into an event; a wrong filename fails silently at runtime. Fails soft: an unused asset directory returns an empty list.

Cheap names-only index for a database table. Returns { id, name } entries instead of full records — use it to look up or sanity-check IDs before wiring them into events, without paying the token cost of a full get_*/search_* dump.

List every plugin command create_plugin_command can validate (plugin filename → command key → args): the plugins this project actually ships, scanned from their js/plugins/*.js annotations, merged over a small built-in allowlist. Pass pluginName to narrow to one plugin. Read-only. Use scan_plugins for the richer per-project view (arg types/defaults, enabled state); an unlisted plugin command can still be built, it just isn’t validated.

Reserve the next unallocated switch / variable / common-event ID(s) instead of picking one by hand. Ids are handed out strictly above every id already declared or referenced, so two sessions editing the same project over time cannot silently claim the same switch — a collision that never crashes and only surfaces hours into a playtest as a door that is inexplicably already open. Pass `reuseGaps: true` to fill holes below the highest id first (off by default: a hole is often an id claimed in notes but not yet written). Read-only — it suggests ids, it does not write them; name what you take with set_switch_name / set_variable_name so the next session sees the claim.

Expand a top-left flat tile id + a width×height size into the grid of tile ids that object occupies on the sheet — feed the returned `tiles` straight into place_object. This handles the flat sheets' two-half-column layout, where the tile below id N is NOT N+16 (indices 0–127 are the left half of the sheet, 128–255 the right), which is otherwise painful to compute by hand. Get the top-left id from find_tile/get_tile_catalog. Read-only. Throws if topLeftId isn't a flat id or the rectangle runs off the 16×16 sheet; warns if the tileset lacks that sheet.

Paint specific tiles onto a map, with automatic autotiling. Each cell is set to its tile id; if that id is an autotile (A1-A4, e.g. a catalog 'kind' base from find_tile), its shape and its neighbours' shapes are recomputed from same-kind adjacency so borders/corners line up. Flat tiles are painted as-is. Defaults to the lower ground layer (0). Higher-level than set_map_tile, which is a single raw tile with no autotiling.

Place a multi-tile B/C object (a house, tree, fountain, …) on a map and report its passability. `tiles` is the object's block of flat tile ids as rows (top to bottom), each row left to right; a 0 leaves that cell untouched so L-shaped/irregular objects work. Stamped onto the upper tile layer (2) by default so it draws over the ground. Unlike paint_tiles this does NOT autotile (objects are flat sheet tiles) — instead it uses the tileset flags to warn when a footprint cell sits on impassable terrain or overwrites an existing tile, and returns the resulting per-cell passability plus the `collision` cells the object turns into a solid obstacle. Warn-by-default: never refuses a placement. Get tile ids from find_tile/get_tile_catalog.

Resize a map to new width/height, safely repadding every z-layer of its tile data (existing tiles kept where the old and new grids overlap; new cells blank; shrinking crops). This is the ONLY safe way to change a map's dimensions — update_map refuses a width/height change because it would not resize the tile array. Warns about any event left outside the new bounds.

Discover the plugin commands this project actually has, by parsing the @command/@arg annotations in js/plugins/*.js and the enabled/disabled state in js/plugins.js. Use it to find out what create_plugin_command can call and with which args — it reports every command's key, label, description and args (name/type/default), plus whether the plugin is enabled in the editor's Plugin Manager (a disabled plugin's commands never run). create_plugin_command validates against this scan automatically, so you don't need to call this first; it's for discovery. Pass pluginName to narrow to one plugin, or enabledOnly:true to skip plugins that are installed but switched off. Read-only. NOTE: MZ has no 'required argument' annotation, so scanned args are checked for unknown names only, never for missing ones.

Search actors by name or nickname

Search enemies by name (case-insensitive)

Search items by name or description

Search events on a map by name

Search skills by name or description

Search troops by name (case-insensitive)

Replace one of a class's 8 parameter growth curves. paramId is 0-7 ([maxHP,maxMP,atk,def,mat,mdf,agi,luk]); values must match the existing curve length (same max level).

Set the currency unit shown next to gold amounts (e.g. "G", "Gold").

Set a map's random-encounter list (replaces it wholesale) and optionally its encounterStep (average steps between encounters). Each encounter is { troopId, weight?, regionSet? }: weight biases the random pick (default 5), regionSet restricts it to those map region ids (empty/omitted = anywhere). Every troopId is validated against Troops.json — a non-existent troop throws. Prefer this over update_map for encounters (it validates and hides the on-disk shape).

Update an existing event page's graphic and behavior in one call, without rebuilding the whole page or touching its command list: sprite (characterName/characterIndex/direction/pattern or a tileId), trigger, priority, movement (type/speed/frequency/route), and the through/walkAnime/stepAnime/directionFix flags. Graphic fields merge onto the current image; warns (never blocks) on an unknown characterName. Refuses the write if the change would leave the event unreachable (an action-button page with priority `below` on an impassable tile) — pass force: true to override.

Set a single raw tile ID at (x, y) on a given z-layer (0-5). Note: tile IDs are raw engine integers; this is a low-level primitive without autotile/passability awareness.

Insert a forced "Set Movement Route" (event command 205, plus the 505 continuation rows the editor expects) into an event page’s command list, moving a character as part of that page. characterId: -1 player, 0 this event, N event id. Pass a moveRoute from create_move_route. A structurally invalid route or page refuses the write (nothing is saved) — pass force: true to override.

Set the starting party (the actor ids the game begins with, in order). Every id must reference an existing actor.

Point the server at a different RPG Maker MZ project directory for the rest of the session (overrides RPGMAKER_PROJECT_PATH until the server restarts). The directory must contain game.rmmzproject and data/System.json.

Set a switch name. Grows the project's switch list if the id is past the end (padded to the editor's 20-slot block), so an id from next_free_id can always be labelled. Naming a switch as soon as you claim it is what makes it visible to the next session — see list_allocated_ids.

Set one vocabulary term. For category 'basic'/'commands'/'params' the key is a numeric index (as a string); for 'messages' it's a message key (e.g. 'actorDamage'). Returns the updated terms.