rpgmaker-xp-mcp

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

然后在下方的配置中，将 node 设为命令，并使用 dist/index.js 的路径。

get_actors · get_actor · update_actor · create_actor · search_actors

XP 演员使用 parameters Table（6×100——每级对应 MaxHP、MaxSP、STR、DEX、AGI、INT），而非 MZ 风格的特性。create_actor 默认会生成线性成长曲线。装备栏位为 weapon_id 和 armor1_id–armor4_id（盾牌／头盔／身体／饰品）。

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

create_weapon／create_armor 会使用编辑器默认字段（可覆盖任意字段），将内容追加到 Weapons.rxdata／Armors.rxdata。护甲 kind：0=盾牌，1=头盔，2=身体，3=饰品。

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

XP 没有伤害公式。伤害由 power 按属性影响比率缩放（物理攻击使用 atk_f／str_f，魔法攻击使用 int_f），并受目标的 pdef_f／mdef_f 减免。**负数 power = 治疗。**没有 create_buff_skill——XP 没有增益系统，请使用状态。

范围：0=无，1=单个敌人，2=所有敌人，3=单个盟友，4=所有盟友， 5=单个盟友（HP 0），6=所有盟友（HP 0），7=使用者。

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

地图位于 Data/MapXXX.rxdata。除非设置 includeTiles: true，否则 get_map 会汇总图块 Table。事件是以事件 ID 为键的哈希表。

add_show_text 会处理 XP 的消息结构（首行为代码 101，后续行为 401，每个文本框 4 行）。XP 特有规则：代码 101 直接携带文本（不同于 VX+）；选项文本会同时冗余存储在 102 数组和 402 分支中，必须保持同步；移动路线代码为 209／509。

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

apply_autotile 会绘制自动图块，并根据 8 邻接关系为每个单元计算无缝边缘变体——可提供有机形状的 blob（池塘、湖泊、森林）、cells 列表（河流、弯曲路径），或 region 矩形（仅适用于矩形地板）。scatter_tiles 会按目标密度分散杂物，也可选择使用焦点渐变。二者结合使用，可以避免出现块状池塘和细节挤在角落的问题，让地图不再显得像程序生成的。参见 MAP-DESIGN.md §5b。

图层（Map.data z，绘制顺序为 z0→z1→z2 = 编辑器图层 1/2/3）按用途分配：z0 地形（自动图块），z1 地面杂物（优先级 0），z2 高空元素（优先级 > 0——玩家会从树冠和屋顶后方走过）。

图块 ID：0 = 空；48–383 = 自动图块（slot=id/48-1，variant=id%48）；≥384 = 普通图块（col=(id-384)%8，row=(id-384)/8）。

制作地图前请先加载 get_map_design_guide——create_map 也会直接返回其中的核心规则。get_map_size_advisory 会报告现有地图的屏幕数量、目标焦点数量、建议的散布密度和超大地图警告。

validate_assets · validate_connectivity

validate_assets 会扫描每个数据文件中引用的图像和音频文件名——图块集、自动图块、全景图、雾效、战斗背景、角色、战斗角色和图标图像、动画、窗口皮肤、标题、游戏结束画面、转场、BGM/BGS/ME 和地图事件精灵——并报告磁盘上不存在文件的引用。否则，这些失效引用要等到运行时才会静默暴露。它会先检查项目的 Graphics/ 和 Audio/，再检查 RTP，并且不论扩展名如何，均按基本文件名匹配。

validate_connectivity 会构建世界地图转移图，并报告无法从起始地图到达的地图、指向缺失地图或越界图块的转移，以及死路。

create_tileset_identification_harness · get_tileset_catalog · save_tileset_catalog · validate_tileset_catalog · render_tileset_atlas · render_map

create_tileset_identification_harness 会生成一个以证据为先的审查包：源图、带有烧录图块 ID 标签的副本、独立的透明图块图像、源行、自动图块源、引擎元数据、目录模板和交互式浏览器页面。经审核的标签、预期用途、对象网格、图层和置信度都保存在独立目录中，因此通行性或视觉相似性不会被悄然当作语义判断。参见 TILESET-CATALOG.md。

render_tileset_atlas 会将图块集渲染为带标签的 PNG——图像按比例缩放并带网格，每个图块都烧录有 ID，显示通行性圆点（红色 = 阻挡，橙色 = 部分阻挡），并附有 7 个自动图块槽位的图例。

render_map 会在编辑器外将地图的图块图层渲染为平面俯视 PNG 预览图，让你能看到自己制作的内容。它会使用图块集图像（ID ≥ 384）及其自动图块（ID 48–383，通过交叉验证的 48 种变体象限表）合成全部三层。选项：layers、scale、region、drawGrid、drawEvents、passability。文件写入 Data/.mcp-preview/map<NNN>.png，并返回路径。

仅提供布局预览——不包含优先级/高空元素绘制顺序、雾效、全景图或天气，自动图块动画使用第 0 帧。

classify_asset · verify_tileset · register_tileset 仅按画布尺寸对图块表排序，会悄悄错误导入为其他引擎制作的素材。因此，这些工具会检测真实的内容图块尺寸（通过边缘周期性判断候选尺寸，候选尺寸必须能整除画布，并优先选择原生的 32px），并根据文件名进行识别：$/! 前缀表示属于 Characters 的单个对象精灵，而非图块集；只有当内容尺寸不是 32px 时，A1–A5 才表示 MV/MZ 自动图块表，否则就是战斗者变体。

verify_tileset 会生成网格叠加预览，让你在导入前看清缩放问题。register_tileset 会添加受保护的 Tilesets.rxdata 条目，其通行度/优先级/地形 Table 的大小与图块表匹配；对于非原生素材，除非明确强制，否则会拒绝添加。

数据库 — get_database · get_database_entry · update_database_entry

通用访问所有数据库文件，包括没有专用工具的文件（Classes、States、Enemies、Troops、CommonEvents、Tilesets……）。图块集的通行设置位于 passages Table 中：0 = 可通行；1/2/4/8 = 阻挡下/左/右/上方；15 = 不可通行；+64 灌木；+128 计数器。

脚本 — get_scripts · get_script · update_script · create_script · search_scripts

完整访问 RGSS 脚本，并处理 zlib。源码以 [magic, name, zlib-deflated code] 三元组的形式存储；每个脚本的 magic number 对编辑器没有实际意义。按照惯例，create_script 会在 Main 上方插入脚本。二进制安全——脚本数据不会经过 UTF-8 转换。

系统 — get_system · get_variables · set_variable_name · get_switches · set_switch_name · get_game_title · update_game_title · update_starting_position

.rxdata 文件使用随附的、修复过错误的 @hyrious/marshal 副本（src/vendor/marshal/） 进行解析，并转换为普通 JSON。Ruby 对象会转换为 { "_class": "RPG::Actor", ... }，实例变量作为字段（不带开头的 @）。

随附副本的原因： 上游版本 ≤0.3.3 会错误解码负的多字节 Marshal 整数——−150 会被解码为 +106。在 XP 中，治疗的威力为负数，因此这个错误会在保存时 悄无声息地把每个治疗技能都变成伤害技能。详情见 research/REPORT.md。

RGSS 二进制类 Table（图块和参数网格）、Color 和 Tone 都有专用编解码器。保存时，字符串会以原始字节字符串写入，不附带 Ruby 1.9 编码实例变量，否则 XP 的 Ruby 1.8 / RGSS104E 会拒绝加载它们。 游戏标题保存在 Game.ini 中，而不是 System 数据中——这点与 MZ 不同。

RMXP 安装目录中 16 个模板 .rxdata 文件里，有 15 个往返转换后字节完全一致。唯一例外是 Scripts.rxdata，往返测试会排除它而不是报错：它将 zlib 压缩的源代码存储为二进制字符串，因此需要使用原始路径（readRxdataRaw），而不是数据库其余部分使用的 UTF-8 路径。脚本工具能够正确处理它；只有往返测试会跳过它。

• 自动备份 — 在会话中首次写入任何文件之前，会将原文件复制到 Data/.mcp-backup/<name>.bak（Game.ini 则复制到项目根目录）。请参阅顶部的警告：每个文件每个会话备份一次。
• 保存修订标记 — 写入地图和事件时会重新生成 System.magic_number，与编辑器的行为一致，确保现有存档重新加载已更改的地图，而不是保留过期副本。
• 事件列表不变量 — 保存时会规范化命令列表：每条命令都会包含 code/indent/parameters，并确保末尾有 {code: 0, indent: 0, parameters: []} 终止符。
• 经验证的引擎数学逻辑 — 技能工具会说明从 Game_Battler 3 提取的 XP 实际伤害算法，辅助函数也经过校准，符合默认数据库惯例（治疗技能的威力为负数，int_f 为 50）。

服务会提供自己的指引，因此任何 MCP 客户端都能获取这些规范——而不仅限于能够读取此仓库的客户端：

• 服务说明会在连接时发送（治理规则 + 地图设计规则），并由大多数客户端注入上下文。
• 指南以 MCP 资源（rpgmaker-xp://docs/…）形式提供： map-design、tileset-catalog、authoring、wisdom。
• get_map_design_guide 会返回完整指南；create_map 会内联返回核心规则。