git clone https://github.com/SerifeusStudio/rpgmaker-xp-mcp.git
cd rpgmaker-xp-mcp
npm install
npm run build

Then use node with the path to dist/index.js as the command in the configs below.

get_actors · get_actor · update_actor · create_actor · search_actors

XP actors use a parameters Table (6×100 — MaxHP, MaxSP, STR, DEX, AGI, INT per level) rather than MZ-style traits. create_actor generates linear growth curves by default. Equipment slots are weapon_id and armor1_id–armor4_id (shield / helmet / body / accessory).

get_items · get_weapons · get_armors · get_skills · update_item · search_items · create_weapon · create_armor

create_weapon/create_armor append to Weapons.rxdata/Armors.rxdata with editor-default fields (override any). Armor kind: 0=shield, 1=helmet, 2=body, 3=accessory.

get_skill · create_skill · create_damage_skill · create_healing_skill · create_state_skill · update_skill · search_skills

XP has no damage formulas. Damage is power scaled by stat-influence rates (atk_f/str_f physical, int_f magical) and reduced by the target's pdef_f/mdef_f. Negative power = healing. There is no create_buff_skill — XP has no buff system, use states.

Scope: 0=none, 1=one enemy, 2=all enemies, 3=one ally, 4=all allies, 5=one ally (HP 0), 6=all allies (HP 0), 7=user.

get_map · get_map_infos · get_map_events · get_map_event · update_map_event · create_map_event · create_transfer_event · search_map_events · add_event_command · add_show_text

Maps live in Data/MapXXX.rxdata. get_map summarises the tile Table unless includeTiles: true. Events are a hash keyed by event ID.

add_show_text handles XP's message structure (first line = code 101, continuations = 401, 4 lines per box). XP specifics: code 101 carries text directly (unlike VX+); choice text is stored redundantly in both the 102 array and the 402 branches and must stay in sync; move routes are 209/509.

create_transfer_event wires two maps together and validates both endpoints exist and are in bounds before writing. Run validate_connectivity afterwards. The full 110-code table is in research/event-commands.md.

get_map_design_guide · get_map_size_advisory · create_map · get_map_tiles · set_map_tiles · fill_region · apply_autotile · scatter_tiles

apply_autotile paints an autotile and computes seamless edge variants per cell from 8-neighbour connectivity — give it an organic blob (ponds, lakes, forest), a cells list (rivers, curved paths), or a region rect (rectangular floors only). scatter_tiles distributes clutter at a target density with an optional focal gradient. Together these avoid the blocky ponds and corner-clustered detail that make maps look programmer-generated. See MAP-DESIGN.md §5b.

Layers (Map.data z, drawn z0→z1→z2 = editor Layer 1/2/3) are assigned by role: z0 terrain (autotiles), z1 ground clutter (priority 0), z2 overhead (priority > 0 — canopies and roofs the player walks behind).

Tile ids: 0 = empty; 48–383 = autotiles (slot=id/48-1, variant=id%48); ≥384 = regular tiles (col=(id-384)%8, row=(id-384)/8).

Load get_map_design_guide before authoring — create_map also returns its core rules inline. get_map_size_advisory reports screen count, target focal points, recommended scatter density and oversize warnings for an existing map.

validate_assets · validate_connectivity

validate_assets scans every data file for referenced graphic and audio filenames — tilesets, autotiles, panoramas, fogs, battlebacks, character, battler and icon graphics, animations, windowskin, title, gameover, transition, BGM/BGS/ME and map event sprites — and reports any with no file on disk. Broken references are otherwise silent until runtime. Checks the project's Graphics/ and Audio/ first, then the RTP, matching base name regardless of extension.

validate_connectivity builds the world transfer graph and reports maps unreachable from the start map, transfers pointing at a missing map or an out-of-bounds tile, and dead ends.

create_tileset_identification_harness · get_tileset_catalog · save_tileset_catalog · validate_tileset_catalog · render_tileset_atlas · render_map

create_tileset_identification_harness builds an evidence-first review bundle: the source sheet, a labelled copy with burned-in tile IDs, isolated transparent tile images, source rows, autotile sources, engine metadata, a catalog template and an interactive browser page. Reviewed labels, intended uses, object grids, layers and confidence live in a separate catalog, so passability or visual resemblance cannot silently become a semantic claim. See TILESET-CATALOG.md.

render_tileset_atlas renders a tileset to a labelled PNG — scaled with a grid, each tile's id burned in, passability dots (red = blocked, orange = partial) and a legend of the 7 autotile slots.

render_map renders a map's tile layers to a flat top-down PNG preview outside the editor, so you can see what you built. Composites all three layers using the tileset graphic (ids ≥ 384) and its autotiles (ids 48–383, via a cross-verified 48-variant quadrant table). Options: layers, scale, region, drawGrid, drawEvents, passability. Writes to Data/.mcp-preview/map<NNN>.png and returns the path.

Layout preview only — no priority/overhead draw order, no fog, panorama or weather, and autotile animation uses frame 0.

classify_asset · verify_tileset · register_tileset

Sorting a sheet by canvas dimensions alone silently mis-imports assets authored for other engines, so these detect the true content tile size (edge-periodicity, where a candidate must evenly divide the canvas, biased toward native 32px) and fingerprint the filename: a $/! prefix means a single-object sprite belonging in Characters, not a tileset; A1–A5 means an MV/MZ autotile sheet only when content is not 32px, otherwise it is a battler variant.

verify_tileset writes a grid-overlay preview so scale problems are visible before import. register_tileset adds a guarded Tilesets.rxdata entry with passages/priorities/terrain Tables sized to the sheet, and declines non-native assets unless explicitly forced.

Database — get_database · get_database_entry · update_database_entry

Generic access to every database file, including those without dedicated tools (Classes, States, Enemies, Troops, CommonEvents, Tilesets…). Tileset passability lives in the passages Table: 0 = passable; 1/2/4/8 = down/left/right/up blocked; 15 = impassable; +64 bush; +128 counter.

Scripts — get_scripts · get_script · update_script · create_script · search_scripts

Full RGSS script access with zlib handling. Sources are stored as [magic, name, zlib-deflated code] triples; per-script magic numbers are not meaningful to the editor. create_script inserts above Main by convention. Binary-safe — script data never passes through UTF-8 conversion.

System — get_system · get_variables · set_variable_name · get_switches · set_switch_name · get_game_title · update_game_title · update_starting_position

.rxdata files are parsed with a vendored, bug-fixed copy of @hyrious/marshal (src/vendor/marshal/) and converted to plain JSON. Ruby objects become { "_class": "RPG::Actor", ... } with instance variables as fields (no leading @).

Why vendored: upstream ≤0.3.3 mis-decodes negative multibyte Marshal integers — −150 decodes as +106. In XP, healing is negative power, so that bug silently converted every healing skill into a damage skill on save. Details in research/REPORT.md.

The RGSS binary classes Table (tile and parameter grids), Color and Tone have dedicated codecs. On save, strings are written as raw byte strings with no Ruby 1.9 encoding ivars, or XP's Ruby 1.8 / RGSS104E refuses to load them. The game title lives in Game.ini, not in System data — unlike MZ.

Round-trips of 15 of the 16 template .rxdata files from the RMXP install are byte-identical. The exception is Scripts.rxdata, which the round-trip test excludes rather than fails: it stores zlib-compressed source as binary strings, so it needs the raw path (readRxdataRaw) instead of the UTF-8 one the rest of the database uses. The script tools handle it correctly; only the round-trip test skips it.

• Automatic backups — before the first write to any file in a session, the original is copied to Data/.mcp-backup/<name>.bak (project root for Game.ini). See the warning at the top: one per file per session.
• Save-revision marker — map and event writes regenerate System.magic_number, mirroring the editor, so existing save files reload the changed map instead of keeping a stale copy.
• Event list invariants — command lists are normalised on save: every command gets code/indent/parameters, and the trailing {code: 0, indent: 0, parameters: []} terminator is guaranteed.
• Verified engine math — skill tools document XP's real damage algorithm, extracted from Game_Battler 3, and the helpers are calibrated to default-database conventions (heals are negative power with int_f 50).

The server surfaces its own guidance, so any MCP client gets the conventions — not just one that can read this repository:

• Server instructions are sent on connect (governance + map-design rules) and injected into context by most clients.
• The guides are exposed as MCP resources (rpgmaker-xp://docs/…): map-design, tileset-catalog, authoring, wisdom.
• get_map_design_guide returns the full guide; create_map returns its core rules inline.