MORX GMS2 MCP

让 AI 助手参与 GameMaker 项目的制作、运行、检查与迭代。

MORX GMS2 MCP 是一个本地 stdio MCP 服务：AI 先理解项目，再制作资源、修改 GML、调整动画与显示设置；随后通过隔离的 Windows VM 副本编译运行，读取画面、实例状态、日志和运行时异常，并根据真实反馈继续修改。所有修改默认先预览，写入保留事务备份。

Author, run, observe, and iterate on GameMaker projects with real feedback.

真实闭环 · 安全默认 · 数据输入 · 44 个工具 · MIT

快速开始 · 能做什么 · 连接客户端 · 使用示例 · 运行与观察 · 工具清单 · English

亮点

• 真实运行闭环：编译 → 运行 → 截图 / 实例状态 / 日志 / 异常 → 修改 → 再验证。
• 安全默认：所有修改先预览；写入有 SHA-256 冲突检测、事务备份和撤销。
• 数据输入：KeyPress、Mouse、Collision 等事件可通过桥接数据触发，不依赖物理键鼠。
• 隔离运行：独立项目副本和存档目录；停止后自动清理。
• 不操控 IDE：不抓取桌面、不控制 IDE 图形界面；运行时信息来自游戏内桥接。

能做什么

44 个工具 · 本地 stdio · 默认只读 · 运行默认关闭 · MIT

开发工作流

将需求交给助手，按“理解项目 → 制作与配置 → 运行观察 → 调整并验证”推进。AI 客户端负责理解需求和组织工具调用，MCP 负责执行项目操作。

本仓库提供的接口覆盖项目文件、资源、GML 和隔离运行。运行能力默认关闭，需要 --allow-run 和本机 Runtime 配置；截图和状态来自游戏内的测试桥接，不抓取桌面。IDE 图形界面、原生断点和逐行调试仍需使用 GameMaker 本身。

快速开始

需要 Windows、Python 3.10+、一个由 GameMaker 创建并保存的项目，以及支持本地 stdio 的 MCP 客户端。建议先用独立测试项目熟悉操作；以下命令在 Windows PowerShell 中运行。

1. 安装

推荐用 pipx 安装为独立命令：

pipx install morx-gms2-mcp
morx-gms2-mcp --version

也可以装进 venv：

python -m venv .venv
$mcpPython = (Resolve-Path '.venv\Scripts\python.exe').Path
& $mcpPython -m pip install morx-gms2-mcp
& $mcpPython -m morx_gms2_mcp --version

git clone https://github.com/MKTLMORX/morx-gms2-mcp.git
cd morx-gms2-mcp
python -m venv .venv
$mcpPython = (Resolve-Path '.venv\Scripts\python.exe').Path
& $mcpPython -m pip install .
& $mcpPython -m morx_gms2_mcp --version

依赖版本见 pyproject.toml。

2. 绑定并检查项目

$gameProject = 'D:\Games\MyGame' # 替换为你的测试项目
morx-gms2-mcp bind --project $gameProject
morx-gms2-mcp check --project $gameProject

用 venv 安装时，把 morx-gms2-mcp 换成 & $mcpPython -m morx_gms2_mcp。--project 也接受 .yyp 文件路径。目录须恰有一个现代 GMProject v1 的 .yyp；服务不创建空项目。

连接客户端

3. 生成配置

# 按你使用的客户端选择一条
morx-gms2-mcp client-config --project $gameProject --client codex --write
morx-gms2-mcp client-config --project $gameProject --client claude --write

client-config 只输出配置，不会自动合并；保留文件中已有服务，然后重新加载客户端。Claude Code 可能要求确认项目信任。去掉 --write 可保持资源只读，允许查询和预览，拒绝实际修改；运行能力由 --allow-run 单独控制。使用 venv 时把 morx-gms2-mcp 换成 & $mcpPython -m morx_gms2_mcp。

生成的配置把单次工具调用上限设为 180 秒（Claude Code 的 timeout 以毫秒计），因为 wait_game_frames 等待较多帧时可能合法地阻塞超过默认的 60 秒。较早的 Claude Code 版本若不支持 timeout 字段，可在启动前设置 MCP_TOOL_TIMEOUT=180000。

需要运行能力时，在生成配置时同时传入运行参数：

morx-gms2-mcp client-config --project $gameProject --client claude --write `
  --allow-run --runtime-root '<Runtime 目录>' --user-directory '<已登录用户目录>'

claude mcp add --scope local --transport stdio morx-gms2-mcp -- morx-gms2-mcp serve --project "D:\Games\MyGame" --write
claude mcp get morx-gms2-mcp

4. 连接并验证

重新加载客户端后，先调用 server_info 核对项目路径、写入模式和运行能力。一个服务固定绑定一个项目；管理多个项目时，分别配置服务。迁移项目后需要重新绑定，绑定文件位于 .codex/gms2-resource-binding.json。

使用示例

连接后，可以向 AI 助手提出这样的请求：

检查当前绑定项目，并列出资源引用错误，先不要修改。

在“脚本/game”分组创建 scr_demo_init，先给我看修改预览。

将我提供的两张等尺寸 PNG 导入为 spr_demo，设置播放速度和原点。

查询 spr_demo 的动画，将帧倒序，让第一帧停留更久，先预览修改。

查询启动房间和 Windows 显示设置，预览将相机设为 320×180、视口设为 960×540，并允许调整窗口大小。

列出备份，预览撤销最近一次资源创建会影响哪些文件。

安装测试桥接并运行当前游戏，等桥接就绪后截图。

查询运行中 obj_player 的 x、y、hp 和 image_index。

向右移动 60 帧，再等待 30 帧后截图；然后停止运行并清理副本。

用数据触发 obj_player 的 KeyPress 事件（E 键），不要发送物理键盘输入。

在游戏窗口客户区 (480,270) 点击一次；默认走窗口消息，不要移动我的真实光标。

依次等待 10 帧、触发 obj_enemy 的碰撞事件并截图，把序列结果一起返回。

使用流程与写入保护

1. 保存 IDE 中尚未落盘的内容，调用 server_info 和 inspect_project。
2. 调用修改工具，默认 dry_run=true，查看拟改文件。
3. 确认目标和请求后以相同参数及 dry_run=false 执行；服务还必须带 --write 启动。没有 --write 时实际写入被拒绝。
4. 再次检查项目；需要时用 run_game 编译运行验证。结构校验不等于编译成功。

例如 create_script 参数：

{"name":"scr_demo_init","group":"脚本/game","code":"function scr_demo_init() { return 1; }","dry_run":true}

预览不会改动游戏资源，但读取/预览可能创建项目锁文件。已有资源和事件拒绝覆盖；已有 GML 用 read_code/update_code 修改，按哈希拒绝过期写入。

每次写入都会在 .codex/gms2-resource-backups/ 保存备份。用 list_backups 查询事务，再将 transaction_id 传给 restore_backup，预览或执行撤销。恢复须从最新未撤销事务开始；发现后续外部改动会拒绝覆盖。撤销新建操作会移除其新建文件。备份包含项目代码、素材和本机路径，不应上传到公共仓库。

跨进程锁只协调本工具，IDE 不遵守此锁。单文件使用原子替换，多文件整体不是原子事务；请勿同时在 IDE 保存和执行 MCP 修改。失败会尝试恢复，有未完成恢复的事务时阻止新写入。

运行与观察

运行能力通过 GameMaker 自带的 Igor 命令行构建 Windows VM 目标，并在用户目录中运行独立副本。它与资源写入开关分开，默认关闭。

install_runtime_bridge → run_game → runtime_status → capture_game / inspect_game / trigger_game_event → stop_game

启用条件

• 服务启动时额外传入 --allow-run、--runtime-root <runtime 目录>、--user-directory <已登录用户目录>；用户目录下应直接有 licence.plist，服务只检查存在性，不读取或复制许可证内容。
• 本机安装 Windows x64 Runtime；绑定项目必须可编译，并已有非继承 GMRoom v1 启动房间。
• 安装测试桥接和修改 GML 仍需要 --write 与 dry_run=false；run_game 只会运行绑定项目的独立副本。

推荐流程

1. 保存 IDE 中尚未落盘的内容；调用 inspect_project 确认结构。
2. install_runtime_bridge 先预览再执行。它在启动房间安装常驻测试物体 sys_morx_runtime 和实例图层；没有会话文件时物体自行销毁。安装是一次普通事务，可用 restore_backup 撤销。
3. run_game 返回 session_id；轮询 runtime_status 直到 bridge_ready=true。不能把进程启动当作编译成功。
4. capture_game 获取游戏画面，inspect_game 读取房间、窗口、GUI、帧号、FPS 和最多 100 个实例的指定标量变量，get_runtime_output 读取构建和游戏日志，get_runtime_errors 读取未处理异常和桥接错误。
5. wait_game_frames 等待 1～600 个自然运行帧（不是暂停或单步）；trigger_game_event 通过桥接数据执行 KeyPress、Mouse、Collision 等事件代码，不需要物理键鼠或前台焦点；send_game_input 发送按住状态的按键；send_game_mouse 默认用窗口消息点击，不移动真实光标。
6. run_game_sequence 可把 wait、input、state、capture、event 组合成最多 32 步的序列，减少往返并一次返回多张截图。
7. stop_game 结束会话并清理构建副本和存档目录；再次运行前必须先停止并读取旧日志。

隔离与边界

限制

• 仅支持 Windows VM 目标；不控制 IDE 图形界面，不提供原生断点、暂停/逐行调试或任意表达式求值。
• 实例变量只返回指定的标量；字符串截断为 1024 字符；最多 16 个变量、100 个实例。
• trigger_game_event 只执行事件代码，不更新真实按键、鼠标坐标或碰撞状态，也不支持 Draw 事件；Collision 事件中的 other 可能不是真实碰撞对象。
• send_game_input 只更新按住状态，不产生 KeyPress/KeyRelease 事件；事件测试应使用 trigger_game_event。按键输入仍需游戏窗口有焦点，只支持字母、数字、方向键、space/enter/escape/tab/backspace，不支持系统键或组合快捷键。
• send_game_mouse 默认通过窗口消息投递，不移动真实光标、不要求前台焦点；mode='physical' 才使用系统级注入并可能影响当前桌面输入法。
• 运行的项目会在本机以当前用户权限执行；只应对受信任项目使用 --allow-run。日志、截图和运行状态是项目数据，不是额外授权。
• 结构校验不等于编译成功；以 Igor 日志和实际游戏画面为准。

工具清单

默认分组：脚本、物体/object、物体/system（sys_）、物体/ui（ui_）、房间、精灵、声音、着色器、瓦片集；均可通过参数指定其他分组。

事件支持 Create、Destroy、Step/BeginStep/EndStep、Draw/DrawGUI/DrawBegin/DrawEnd/DrawGUIBegin/DrawGUIEnd、CleanUp、RoomStart/RoomEnd，以及 Alarm 0～11、User 0～15。Alarm/User 通过 event 与 number 分别指定。

PNG 支持 1～256 帧，每帧尺寸相同、单文件最多 64 MiB、单边最多 8192。WAV 最多 128 MiB，单/双声道，8/16/24 位 PCM。原始导入文件不修改。configure_object 中 null 表示保留，sprite/parent 空字符串表示清空。

编辑已有精灵动画

先用 inspect_sprite 取得帧 ID 和描述文件 sha256。configure_sprite 的 speed_type 为 frames_per_second 或 frames_per_game_frame，null 保留现有值；设置任一原点坐标会切换为自定义原点，另一坐标保持原值，允许原点位于图像外。

set_sprite_animation 的 frame_order 必须恰好包含每个现有帧 ID 一次，不接受帧索引、不增删帧。frame_durations 按结果帧顺序提供有限正数，单位是动画时间轴长度，不是秒。例如速度为 10 FPS 时，长度 2 对应 0.2 秒；如果采用每游戏帧速度单位，实际秒数还取决于游戏帧率。省略顺序则保持当前顺序；省略时长则每帧携带自己的原时长参与重排。

例如，查询到三个帧 ID 后，可预览倒序并调整时长（替换占位值）：

{"name":"spr_demo","frame_order":["<第三帧 ID>","<第二帧 ID>","<第一帧 ID>"],"frame_durations":[2,1,3],"expected_sha256":"<查询得到的 sha256>","dry_run":true}

两个修改工具均建议带 expected_sha256，预览与执行使用相同值；描述文件在其间被修改时会拒绝操作，需重新查询和预览。编辑只改精灵 .yy，保留 PNG、帧 ID 和未知字段，支持原字节撤销。重排也会改变对应图像的 image_index，使用固定索引的游戏代码须自行核对。

inspect_sprite.frames 每项对应一张图像，image_index 为图像索引，start 和 duration 描述该图像在动画时间轴的位置。时间轴总长与图像数量不同：三张图像的时长为 3、1、2 时，时间轴总长为 6，图像数量仍为 3。

支持 GMSprite v2 普通位图：以帧为时间单位、单一帧轨道、图像帧与关键帧一一对应、连续且无重叠。自动延伸、禁用关键帧、子轨道或修饰器不在支持范围内；含广播消息、时刻或事件时允许配置速度与原点，但拒绝重排或调整时长。复杂结构可用 inspect_resource 查看原始描述。

相关概念见 GameMaker 官方精灵编辑器和关键帧结构。

配置项目显示

inspect_display_settings 分别返回 windows 和 room 的文件路径、支持状态及 sha256。省略 room_name 时读取启动房间；缺少 Windows 平台文件时标记不可用，不自动创建。继承房间的查询值仅是本地记录，不解析继承结果。

configure_windows_display 仅修改现有 GMWindowsOptions v2 的以下字段，null 保留：title、start_fullscreen、borderless、resizable、allow_fullscreen_switching、display_cursor、vsync、interpolate_pixels。title 是 Windows 平台显示名称；运行时代码可能覆盖窗口标题或其他启动设置。borderless 只去除边框，不等于铺满显示器的无边框全屏；无边框下窗口手动拉伸不会生效，两个开关同时为 true 时返回提示。缩放策略、安装器、图标、文件系统沙箱及其他平台配置不修改。

configure_room_display 针对非继承 GMRoom v1：

尺寸须为 1～32768 的整数；视口位置为非负整数，可见视口的右/下边界不得超过 32768。null 保留原值，不关闭其他视口；启用后至少一个视口必须可见。继承房间、继承房间设置、继承视口设置或选中的继承视口均拒绝写入，不自动解除继承。

例如预览将 rm_demo 的相机设为 320×180、视口设为 960×540：

{"room_name":"rm_demo","enable_views":true,"view_index":0,"visible":true,"camera_width":320,"camera_height":180,"viewport_width":960,"viewport_height":540,"expected_sha256":"<查询返回的 room.sha256>","dry_run":true}

修改 Windows 选项时传入 windows.sha256，修改房间时使用 room.sha256；预览和执行保留同一哈希。初始窗口大小由首房间及其可见视口决定，实际结果可能受操作系统和运行时代码影响；仅修改后续房间不会自动重设已运行的窗口。GUI 尺寸、运行时窗口切换、无边框全屏模式和应用表面手动调整仍由 GML 管理，本工具不注入代码。参考官方 Windows 选项、房间和视口。

适用范围

运行链路已在上述环境完成真实验收：MCP 创建控制器和桥接，Igor 编译运行，桥接就绪，截图包含 DrawGUI，实例状态可读；瓦片集/瓦片图层、碰撞事件、KeyPress 数据事件、窗口消息鼠标、批量序列和运行时异常捕获均通过，停止后副本与存档已清理。IDE 图形界面未参与该轮验收。

其他 IDE 版本、平台及复杂项目建议先用副本验证。这是独立社区工具，与 GameMaker 官方无隶属关系。

使用前需要了解

• inspect_* 读取磁盘中的项目资源和配置；运行工具通过 Igor 构建并运行隔离副本。服务不控制 IDE 图形界面，不提供原生断点、暂停/逐行调试或任意表达式求值。鼠标默认通过窗口消息投递；只有显式 mode='physical' 才会注入系统级鼠标事件。
• 新建项目仍在 GameMaker 中完成；run_game 负责编译和运行绑定项目的副本。资源热加载行为取决于 IDE，修改后应核对实际加载结果。
• 安装测试桥接会修改源项目的启动房间和 .yyp；这是一次可撤销事务。运行前先停止旧会话，运行副本和存档会在停止后删除。
• 运行的项目以当前用户权限执行；只应对受信任项目启用 --allow-run。
• 不提供资源删除或重命名、覆盖已有 GML/事件、字体/路径/时间线/序列/扩展创建，以及 OGG/MP3 导入。已有 GML 用 read_code/update_code 修改。
• 精灵编辑不增删帧、不缩放、裁剪或调色；显示配置不包含其他平台、GUI 尺寸或运行时窗口切换代码。
• 结构校验只检查工具支持的格式和引用关系，不能代替 Igor 编译或实际游戏运行测试。
• 拒绝越界路径、符号链接及目录联接；名为 参考项目 的目录及其子目录不能绑定。

使用问题和功能建议可提交到 Issues。测试与构建见贡献指南，数据边界见安全说明，版本变化见更新记录。

English quick start

MORX GMS2 MCP provides a local tool foundation for AI-assisted GameMaker development. Let an assistant inspect your project, create and edit resources, build and run an isolated Windows copy, observe the game, and refine the result using real feedback. It exposes 44 stdio tools with previews, backups and rollback.

Use an inspect → author → run and observe → adjust workflow. The AI client coordinates the work; this server handles project files, resources, GML and isolated runs. Runtime observation uses the server's own bridge inside the game, not desktop capture. IDE GUI control and native breakpoint/step debugging remain outside its scope.

1. Install from PyPI with python -m pip install morx-gms2-mcp in a Python 3.10+ virtual environment, or use pipx install morx-gms2-mcp / uvx morx-gms2-mcp. To install from source, clone this repository and run python -m pip install . inside a virtual environment.
2. Create and save a test project in GameMaker. Run python -m morx_gms2_mcp bind --project <project> and then check --project <project>.
3. Generate configuration with client-config --project <project> --client codex or --client claude. Add --write only when resource writes are intended. Merge the result into the client configuration and reconnect.
4. Verify the target with server_info. Mutation tools default to dry_run=true; execution requires both a writable server and explicit dry_run=false.
5. For runtime observation, start with --allow-run and the Runtime/user-folder options, run install_runtime_bridge (preview first), then run_game. Poll runtime_status until bridge_ready=true before calling capture_game, inspect_game, get_runtime_errors, wait_game_frames, trigger_game_event or send_game_mouse. Use run_game_sequence to batch wait/input/state/capture/event steps. Finish with stop_game; the isolated build copy and save directory are removed.

Use inspect_sprite before configure_sprite or set_sprite_animation. Reordering requires every existing frame ID exactly once; durations are positive animation timeline units in the resulting order, not seconds. Omitted durations stay attached to their frames. Pass the returned sha256 as expected_sha256 to reject stale edits. Only ordinary continuous bitmap timelines are supported; events and moments prevent retiming. PNG files are preserved. Reordering changes image indices.

Use inspect_display_settings before configure_windows_display or configure_room_display. Windows edits require an existing GMWindowsOptions v2 file. Room, camera and viewport dimensions are independent; enabling views requires at least one visible viewport. Inherited room display settings are not edited. Use the corresponding Windows or room hash to reject stale writes. Borderless windows and borderless fullscreen are distinct; runtime code and the OS may override startup behavior. GUI sizes and runtime GML are not edited.

Runtime tools are disabled by default. Start the server with --allow-run --runtime-root <runtime> --user-directory <logged-in user folder> in addition to --write when GML edits are needed. install_runtime_bridge adds a managed persistent test object and room instance; preview it first. run_game builds a Windows VM copy under the user's local app data, then returns a session ID. Poll runtime_status until bridge_ready is true. Use capture_game, inspect_game, get_runtime_output and get_runtime_errors to observe. trigger_game_event executes event code from bridge data without physical input; send_game_mouse uses window messages by default and only moves the real cursor with mode='physical'. send_game_input updates held key state only and does not generate KeyPress events. Use run_game_sequence to batch wait/input/state/capture/event steps. stop_game ends the session and removes the build copy and save directory. Only one session is active; the maximum lifetime is 15 minutes. The game runs with your user privileges, so enable --allow-run only for trusted projects.

The verified environment is Windows with GameMaker IDE 2026.0.0.16 / Runtime 2026.0.0.23, targeting Windows VM. The run chain was verified end to end: bridge readiness, capture including DrawGUI content, live instance values, frame waits, tilesets and tile layers, collision events, data-driven KeyPress events, window-message mouse input, batch sequences, runtime error capture, stop and cleanup. IDE GUI interaction was not part of that verification. Test a copy of your project when using other versions or platforms.

Existing GML and events are not overwritten by creation tools; use read_code/update_code for existing code. Do not save in the IDE while the server is writing. Multi-file transactions are not fully atomic. This server does not control the IDE, set breakpoints, pause/step the debugger or evaluate arbitrary expressions. trigger_game_event runs existing event code but does not update real key, mouse or collision state; Draw events are not supported by it. Mouse input uses window messages by default and only moves the real cursor in explicit physical mode. Sprite frame creation/removal, image editing and display options for other platforms are outside its scope.

Licensed under MIT. Contributions and sanitized bug reports are welcome.

参考：MCP Python SDK、MCP 工具规范、Claude Code MCP 配置。