rpgmaker-mz-mcp

Overview Schema Source Related Servers Discussions Admin

create_npc

Build a placed, talking NPC event on an RPG Maker MZ map in one call: set a sprite, trigger, and dialogue lines, with sensible defaults for a basic action-button NPC.

Instructions

Create a complete, placed NPC event on a map in one call — a graphic + trigger + a talk list. Provide text (built into a Show Text sequence, with optional face/speaker; wrap: true word-wraps paragraphs into 4-line message boxes) or an explicit commands array (commands wins if both given). Defaults to a solid, action-button NPC facing down. Warns (never blocks) on an unknown characterName, and on NO graphic at all (an NPC with no characterName is invisible in-game — use create_map_event for an intentionally-invisible trigger). The one-shot "make a talking NPC that says X" primitive.

Input Schema

TableJSON Schema

Name	Required	Description
`x`	Yes	X tile position
`y`	Yes	Y tile position
`name`	Yes	Event name (editor label)
`text`	No	Dialogue lines shown when the NPC is triggered (built as Show Text)
`wrap`	No	Auto word-wrap to the message-window width (the same width the line-length warning uses) and split into 4-line boxes. true/"soft" reflows all lines as one paragraph; "hard" keeps each entry (and \n) as a forced line break. Default off (one line per entry, verbatim).
`force`	No	Write even if validation finds structural problems (wrong parameter count, unterminated command list). Off by default: such a write is refused and nothing is written. Advisory warnings never block regardless.
`mapId`	Yes	The ID of the map to place the NPC on
`dryRun`	No	Preview only: return a diff of what would change without writing to disk.
`pattern`	No	Sprite frame 0–2 (default 1 = idle when a sprite is set)
`through`	No	Let the player pass through (default false)
`trigger`	No	What starts the event (default action_button)
`commands`	No	Explicit command list (from the build_* tools); overrides `text` if given
`faceName`	No	text: face image basename (from list_assets("faces"))
`priority`	No	Stacking vs. the player (default same = solid)
`direction`	No	Facing direction (default down)
`faceIndex`	No	text: face index 0–7
`speakerName`	No	text: MZ name-box speaker name
`characterName`	No	Sprite sheet basename (from list_assets("characters"))
`characterIndex`	No	Sprite index 0–7 in the sheet

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.4.0Sep 28, 2026

addedInput schema / properties / wrap

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "enum": [
+        "soft",
+        "hard"
+      ],
+      "type": "string"
+    }
+  ],
+  "description": "Auto word-wrap to the message-window width (the same width the line-length warning uses) and split into 4-line boxes. true/\"soft\" reflows all lines as one paragraph; \"hard\" keeps each entry (and \\n) as a forced line break. Default off (one line per entry, verbatim)."
+}

First observedv1.2.0Jul 31, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and does well: it discloses defaults (solid, action-button, facing down), that warnings never block, that an NPC with no characterName is invisible in-game, and the override precedence for commands. It doesn't cover permissions or return format, but for this domain that is minor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose before detailing the text/commands branch, and each sentence carries load (composite construction, override rule, defaults, warnings, alternative tool). It is dense but not padded, though a reader must parse several clauses packed into two long sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 19-parameter mutation tool with no annotations and no output schema, the description covers the salient behavior (defaults, non-blocking warnings, invisibility pitfall, text/commands interplay). Remaining parameter detail is fully documented in the schema, so an agent has what it needs to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning beyond the schema: how `text` is compiled into a Show Text sequence, how `wrap: true` reflows into 4-line boxes, and that `commands` overrides `text`. These relationships are not derivable from the flat per-parameter schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (create) and resource (a complete, placed NPC event on a map) plus the composite nature of the call (graphic + trigger + talk list). It also explicitly distinguishes itself from the sibling create_map_event, so an agent can tell them apart without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names an alternative (create_map_event) and the condition selecting it (intentionally-invisible trigger), and explains the text-vs-commands choice with a tie-breaker ('commands wins if both given'). It stops short of enumerating when other event-creation siblings apply, but the common cross-roads are covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

create_npc

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools