RpgMakerMVUltimate MCP vs Rpgmaker Mz MCP

delete_database_entry

DESTRUCTIVE: delete a database entry by nulling it out in its data file (written immediately; not undoable — re-create it if needed; IDs are never reused). References elsewhere are NOT cleaned up and will break at runtime: actors in the starting party, classes assigned to actors, skills in class learnings/enemy actions, items in chests/shops, enemies in troops, states in skill effects, troops in map encounters — check and update those first with query_database/update_database_entry. NEVER delete skill 1 (Attack), skill 2 (Guard) or state 1 (KO); the engine uses them directly. Supported entities: actors, classes, skills, items, weapons, armors, enemies, states, troops, animations. Returns the deleted object for reference; fails with an error if the ID does not exist.

query_map

Read-only: inspect maps. `view` selects what you get: "infos" lists the map tree from MapInfos.json (ids, names, folder parentIds — no mapId needed); "full" returns one complete MapNNN.json (dimensions, 6-layer tile data, events — can be large); "events" lists a map's events (with `query`, filters by name, case-insensitive); "event" returns one event by eventId (null if absent); "validate" lints a map (invalid tile IDs per layer, missing page terminators, transfers to map 0, Self Switch OFF where ON was likely meant) returning {issueCount, issues[]}; "ascii" renders the map as a character grid with event markers and a legend — the cheapest way to "see" a layout and pick coordinates, entirely offline. Fails with an error if the map file does not exist. For player-visible images use analyze_image instead.

generate_map

Create a new map file (next free map ID, registered in MapInfos.json; both files written immediately). `mode` selects the generator: "blank" makes an empty map you paint later (edit_map fill_layer); "themed" generates a simple tile layout for a theme using the tileset's real tiles; "procedural" is the full generator — for themes with matching RTP reference templates (town, dungeon, interior, castle, world, etc.) it CLONES a hand-authored template from the 106 bundled maps (real 3D buildings, walls, furniture), auto-picking the closest size; for themes without templates (beach, swamp, etc.) it generates procedurally (Perlin terrain, BSP dungeons, cellular caves). Same seed + params = same map. Pass templateId to force a specific template, or useTemplate:false to force procedural. 21 themes incl. snow, volcano, sewer, space_interior; "batch" generates several procedural maps in one call from `batch` specs; "duplicate" copies an existing map (transfer events still point at their ORIGINAL destinations — review them); "template" instantiates one of the 106 bundled reference maps by templateId (list them with get_project_context detail "templates"); "semantic" is the tileset-independent generator — it lays out a MISSION (entrance, key, locked door, treasure, boss, exit, side rooms) as a graph and only then paints it, asking the tileset profile which tile plays each role, so the layout works on ANY tileset including DLC and third-party packs, and the key is always reachable before the door it opens. It returns `markers` naming the cell of every mission role, which is where to place events next. Run manage_system action "mine_templates" first so the profile comes from tiles this project actually uses; pass a mined `templateId` (like "mined-3") to re-materialise one of the project OWN maps onto a different tileset instead of generating a new mission. Returns {mapId, ...} — procedural also returns the seed; batch returns all mapIds keyed for edit_map "connect". Fails with an error on unknown theme/template or unwritable files.

edit_map

Modify existing maps; the affected map files / MapInfos.json are written immediately. `action` selects the edit: "fill_layer" overwrites an ENTIRE tile layer with one tile ID (destructive, not undoable; layers: 0-1 ground, 2-3 upper, 4 shadow bits 0-15, 5 region IDs 0-255; tileId 0 clears; find valid IDs with get_project_context detail "tileset"); "set_display_names" sets the player-visible displayName of several maps at once (entries whose map file is missing are reported in `skipped`, not errors); "organize_tree" re-parents maps in the editor tree (purely organizational, gameplay unaffected); "connect" creates a bidirectional pair of transfer events between two maps so the player can walk both ways; "set_encounters" sets the map's random-battle list so enemies appear while walking — `encounters` is [{troopId, weight?, regionSet?}] (weight default 5; regionSet [] = whole map; troopId must exist) plus optional `encounterStep`. WITHOUT encounters set, a map has no random battles. Returns a per-action summary. Fails with an error if a referenced map does not exist (except set_display_names, which skips). For event-level work use manage_map_event.

manage_map_event

Create, modify or remove events on a map; the map file is written immediately. action "create" without preset makes a low-level event at x/y (empty page unless `pages` given; add behavior later with add_command). action "create" WITH preset builds a complete, ready-to-play event: "npc" (2-page dialogue NPC: {name, dialogues[], characterName?, characterIndex?}), "chest" (one-time loot: {items: [{type: item|weapon|armor, id, amount}]} — IDs not validated, confirm with query_database), "teleport" (one-way walk-on transfer zone: {destMapId, destX, destY, trigger?} — destination not validated), "door" (action-button warp into another map, e.g. a house entrance: {destMapId, destX, destY, characterName?, characterIndex?, trigger?, lockedSwitchId?, lockedMessage?}; with lockedSwitchId it shows a "locked" message until that game switch is ON), "shop" ({goods: [[type 0=item/1=weapon/2=armor, id, priceType 0=standard/1=custom, price]]}), "inn" ({cost?} full-recovery flow with gold check), "boss" ({troopId} one-time battle, game over on loss), "puzzle_switch" ({switchX, switchY, doorX, doorY, gameSwitchId, switchName?, doorName?} creates TWO linked events). action "update" overwrites only `fields` on an event; action "convert" RE-PURPOSES an existing event in place — keeping its id, position, name and sprite but replacing its behaviour — via `kind`: "merchant" (a working shop; pass `options.goods` [[type,id,priceType,price]] or the friendly `options.items` [{type,id}], plus optional `options.greeting`), "inn" (`options.cost?` full-recovery flow with gold check), "sign" (`options.text` string or string[] read-only message); ideal for "turn this NPC into a merchant" without re-placing it; "delete" removes it permanently (DESTRUCTIVE); "add_command" appends one command before a page's terminator; "populate" scatters N events of a kind (npc/chest/boss) at random positions (walkability not checked — validate with query_map "ascii"). Returns the created/updated event(s) with ids. Fails with an error if the map (or event, for update/delete) does not exist.

manage_system

Read or edit project-wide settings in data/System.json (writes are immediate). action "get" returns the requested `section`: "full" (everything — large), "switches" or "variables" (name arrays indexed by ID; unnamed entries are empty strings — use these to find free IDs), or "title". action "set_title" changes the game title shown on the title screen. "name_switch"/"name_variable" label a switch/variable by ID — documentation only, runtime values are untouched, but good names keep event logic readable. "set_starting_position" sets where new games begin {mapId, x, y} — NOT validated against existing maps, verify with query_map "infos" first; does not affect saved games. "create_plugin" authors a new plugin: it writes js/plugins/<name>.js with a correct @plugindesc/@author/@param/@help header (and a classic-MV Game_Interpreter.pluginCommand hook when `commands` are given) and registers it in js/plugins.js (array order = load order). Re-authoring the same `name` overwrites the file and replaces its manifest entry in place. Pair with analyze_project view "plugins" to inspect the project's existing plugins first. "scaffold_project" creates a NEW, editor-openable RPG Maker MV project by cloning NewData, adding `Game.rpgproject` when Steam omits it, and rewriting its title/start position; it refuses to overwrite an existing project and does not switch the active path. "playtest" launches the ACTIVE project through the bundled nwjs runtime. "open_editor" validates the active project, repairs a missing `Game.rpgproject`, and opens that descriptor in RPGMV.exe so the editor loads the project instead of an empty grey shell. Both locate the engine via `install` / RPGMAKER_MV_INSTALL / the default Steam path and are Windows-only. THE LIVE BRIDGE closes the loop between editing and seeing. "install_bridge_plugin" writes js/plugins/McpBridge.js (only active in playtest). "bridge_start" opens a loopback WebSocket and writes its authenticated handshake. "bridge_status" reports whether the game is connected. "bridge_telemetry" drains exceptions, logs, scene changes, player position and executing event commands, optionally filtered by `types`; pass `peek` to retain frames. "bridge_command" supports `reload_map`, `reload_database`, `get_state`, `teleport_player` and `ping`. "take_screenshot" captures the live game through the MCP bridge; `bridge_screenshot` remains as a compatibility alias. "bridge_stop" closes the socket and deletes the handshake file. "mine_templates" learns layouts and semantic tile roles from this project for later semantic generation. Returns the read section or updated values.

take_screenshot

Capture the current RPG Maker MV playtest frame through the authenticated MCP bridge and save it as a PNG under `.mcp-cache/screenshots/`. Returns `{path, bytes, mimeType, name}` so the image can be inspected or attached as QA evidence without shell commands. Requires `manage_system` actions `install_bridge_plugin`, `bridge_start`, and `playtest` first. Optional `name` becomes a safe filename prefix; each capture keeps a timestamp. `manage_system {action:"bridge_screenshot"}` remains available as a compatibility alias.

record_video

Start or stop recording the live RPG Maker MV playtest canvas through the authenticated MCP bridge. `action:"start"` begins a silent WebM capture inside the game runtime; `action:"stop"` saves it under `.mcp-cache/recordings/` and returns `{path, bytes, mimeType, durationMs, name}`. This captures only the game canvas, not the desktop or credentials. Requires the bridge plugin, a running bridge, and a connected playtest. Optional `name`, `fps` (default 30), and `bitrateKbps` (default 2500) control the artifact.

get_project_context

Read-only: pre-digested project knowledge — CALL THIS FIRST in a session. `detail` selects the depth: "full" (default) returns id+name lists for every database, switch/variable names, starting position, and available sprite filenames per img/ folder — everything needed to create content without inventing broken references; "summary" is a cheap health check (entry counts per data file); "assets" scans img/ and Tilesets.json into a complete index (sheet dimensions, autotile kinds, categorized usable tiles, all PNG names); "tileset" returns the categorized usable tile IDs of ONE tileset (ground/water/walls/roof/decoration) for edit_map "fill_layer" — guessing tile IDs produces glitched maps; "templates" lists the 106 bundled reference maps (id, category, theme) usable with generate_map mode "template", optionally filtered by category/theme. Returns one structured object (or array for templates). GOLDEN RULES for good results: (1) build whole maps with generate_map (it stamps real houses/trees and wires encounters) and add content with the manage_map_event presets — do NOT hand-paint tiles or place decorations one tile at a time; (2) never invent tile IDs or sprite/troop/skill IDs — take them from this tool; (3) for enemies to appear, create troops then set encounters (edit_map "set_encounters"), which generate_map does automatically for combat themes.