用途
rpgmaker-xp-mcp 是一个 MCP 服务器，用于在 RPG Maker XP 工程中以自然语言创建和编辑游戏内容。它直接读写工程中的 .rxdata 文件（角色、技能、物品、地图、事件、脚本、系统数据等），并通过渲染地图预览 PNG，让用户无需打开编辑器即可查看构建结果。它使用 XP 原生的 Ruby 1.8 Marshal 格式，不导出、不转换、也不保存到旁路文件，编辑的就是真实工程，编辑器可以正常打开结果。
该服务器本身没有界面，是供 MCP 客户端连接的后端。常见客户端包括 Claude Code、Claude Desktop、Open WebUI、Cursor、Windsurf 等，也可经由桥接配合 Ollama 本地模型。
主要能力
服务器提供 65 个工具，覆盖多个方面：
- 角色：get_actors、get_actor、update_actor、create_actor、search_actors。XP 角色使用 6×100 的 parameters Table（每级的 MaxHP、MaxSP、STR、DEX、AGI、INT），create_actor 默认生成线性成长曲线；装备槽为 weapon_id 与 armor1_id–armor4_id。
- 物品、武器、防具、技能：get_items、get_weapons、get_armors、get_skills、update_item、search_items、create_weapon、create_armor、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 魔法）决定，负 power 表示治疗；无 buff 系统，可用状态替代。
- 地图与事件：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，事件为以 ID 为键的哈希。create_transfer_event 会校验两端地图存在且在边界内。
- 地图设计与绘制：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 邻接连通性计算无缝边缘变体；scatter_tiles 按目标密度散布杂乱物。图层按用途分配：z0 地形、z1 地面杂物、z2 头顶（可走在后面的树冠与屋顶）。
- 资源校验：validate_assets 扫描所有数据文件中引用的图像与音频文件名并报告磁盘上不存在的引用；validate_connectivity 构建传送图，报告不可达地图、指向缺失地图或越界的地图传送以及死路。
- 图块与渲染：create_tileset_identification_harness、get_tileset_catalog、save_tileset_catalog、validate_tileset_catalog、render_tileset_atlas、render_map。render_map 把地图图层合成为平面俯视 PNG（输出到 Data/.mcp-preview/map<NNN>.png），支持 layers、scale、region、drawGrid、drawEvents、passability 选项；仅为布局预览，不含优先级/头顶绘制顺序、雾、全景或天气，自动图块动画取第 0 帧。
- 资源分类：classify_asset、verify_tileset、register_tileset，用于检测真实内容图块尺寸并识别文件名约定，避免误导入为其他引擎制作的资源。
- 数据库通用访问：get_database、get_database_entry、update_database_entry，可访问没有专用工具的文件（Classes、States、Enemies、Troops、CommonEvents、Tilesets 等）。
- 脚本：get_scripts、get_script、update_script、create_script、search_scripts，带 zlib 处理，脚本源以 [magic, name, zlib 压缩代码] 三元组存储；create_script 按惯例插入到 Main 之上。
- 系统：get_system、get_variables、set_variable_name、get_switches、set_switch_name、get_game_title、update_game_title、update_starting_position。
使用方式
安装包已预构建，无需构建步骤，多数客户端可用 npx 按需启动。使用环境变量 RPGMAKER_PROJECT_PATH 指向包含 Game.rxproj 与 Data/ 的工程文件夹；若 RTP 位置特殊，可另设 RPGMAKER_RTP_PATH，默认指向 Steam 版 RPG Maker XP 安装目录。
在客户端配置的 mcpServers 中加入后重启客户端，可用只读请求验证连接，例如询问“列出我工程中的角色”。若返回名称即配置成功。
使用 Ollama 本地模型时，由于 Ollama 尚无自带 MCP 客户端，可通过桥接访问：Open WebUI 可经 mcpo（OpenAPI 代理）注册 http://localhost:8000/rpgmaker-xp 为工具服务器；也可用 ollmcp 将 MCP 服务器直接连接本地 Ollama 模型。建议选择工具调用能力较强的模型（较新的 Qwen 或 Llama instruct 模型），因为地图创作本质上是多步操作。
重要注意事项
- 运行服务器时请关闭 RPG Maker XP 编辑器：编辑器会把所有数据文件保存在内存中并在保存时重写全部文件，可能覆盖服务器的改动，这是最常见的工作丢失原因。
- 先备份工程：复制整个 Data/ 文件夹。服务器会在会话中首次写入某文件前把原文件复制到 Data/.mcp-backup/，但这是每个文件每会话一个 .bak，下一次会话会覆盖，不构成版本历史。重要工程建议放入 git。
- 修改后请测试游戏：文件结构有效不代表对游戏逻辑正确。
- 地图与事件写入会重新生成 System.magic_number，以模拟编辑器行为；事件命令列表在保存时会被规范化。
- .rxdata 使用 vendored 的 @hyrious/marshal 修补版解析，以修正上游对负多字节整数的解码错误（在 XP 中治疗为负 power，该错误会把治疗技能静默变成伤害技能）。
适用场景与限制
适用于希望用自然语言快速编辑 RPG Maker XP 角色、技能、物品、地图、事件与脚本数据，并在编辑器外预览地图布局的开发者。
限制包括：仅支持 XP，不读取 VX、VX Ace、MV、MZ 工程（数据格式不同）；不生成美术或音频，只能导入、分类和校验已有图形；不会代写 RGSS 脚本，仅把脚本作为数据管理，正确性由用户和模型负责；不能运行或测试游戏，render_map 只显示静态布局预览；不了解 Pokémon Essentials 的自有系统（PBS 文件、插件约定、数据类）；不附带或再分发任何 Enterbrain 素材，RTP 在运行时从本机安装读取。
