内容
# GameMaker MCP 服务器
[](https://www.npmjs.com/package/gamemaker-mcp)
[](https://www.npmjs.com/package/gamemaker-mcp)
[](https://github.com/yearningss/gamemaker-mcp/blob/main/LICENSE)
[](https://github.com/yearningss/gamemaker-mcp)
## 项目描述
GameMaker MCP 服务器是一个针对 GameMaker Studio 的项目感知型本地 MCP 服务器。它为 `.yyp` 项目提供结构化的 MCP 客户端访问：检查、静态分析、受控编辑、对象/房间/着色器操作、快照、验证和官方 Igor 构建。
服务器使用稳定的 `@modelcontextprotocol/sdk` v1 版本，通过 `stdio` 进行通信。它不绑定网络端口。文件操作仅限于一个已配置的项目，现有文本文件使用 SHA-256 乐观并发控制和备份。
## 主要特点
- 86 个 MCP 工具，10 个可重用的工作流提示和 6 个项目资源；
- 零配置工作区自动检测（在 AI 客户端中打开任何 GameMaker 项目文件夹）；
- CLI 安装程序和管理器（`gamemaker-mcp install`、`doctor`、`connect`）；
- 容错的 GameMaker `.yyp`/`.yy` JSON 类文件解析，包括尾随逗号；
- 项目、资产、房间、对象事件、对象继承、精灵、声音、序列、字体、图块集、动画曲线、时间线和着色器检查；
- GML 符号/复杂度诊断、FPS 分析器、i18n 扫描器、绘图状态审计器、健康评分（0-100%）、对象层次树、文档导出器、状态机可视化器、无效 GML 代码检测器和重复代码查找器；
- 预飞行 GML 语法验证器（`gm_gml_validate_snippet`）、Igor 诊断编译器（`gm_project_compile_errors`）、GML 单元测试套件运行器（`gm_test_runner_run`）和 Feather JSDoc 生成器（`gm_gml_docgen`）；
- 精确的 GML 补丁预览和受控写入；
- GameMaker 文件夹、对象、脚本、着色器、对象事件、时间线、测试套件、房间设置、房间实例放置和房间创建代码操作；
- 完整性检查的项目快照和受控恢复；
- GML 有限状态机、粒子系统、GUI 布局和库存系统样板生成器，以及 GML 单元测试框架脚手架；
- 同步编译/运行和持久的后台 Igor 编译/打包作业、状态、等待和取消；
- 自动的 GameMaker 运行时和 `Igor.exe` 发现；
- 项目根路径沙盒、符号链接/连接检查、每个文件限制、只读模式和构建选择加入。
## 要求
- Node.js 20 或更高版本；
- GameMaker `.yyp` 项目；
- 仅 GameMaker Studio 需要编译/打包工具。检查和编辑无需 GameMaker Studio。
## 安装和设置指南
### 方法 1：零配置工作区自动检测（推荐）
在所有 AI 客户端上全局连接 `gamemaker-mcp`：
```powershell
npx gamemaker-mcp@latest connect all
```
**工作原理**：
在 **Claude Desktop**、**Google Antigravity**、**Cursor**、**Codex** 或 **Qwen Code** 中打开任何 GameMaker 项目文件夹。服务器会自动发现并连接到工作区目录中的 `.yyp` 项目文件！
---
### 方法 2：使用显式项目路径的自动单行设置
通过 `npx` 运行自动化安装程序，传递到您的 GameMaker `.yyp` 项目文件或目录的路径：
```powershell
npx gamemaker-mcp@latest install "C:\Path\To\YourGame\YourGame.yyp"
```
该命令自动执行以下操作：
1. 验证 **Node.js** 版本（需要 Node 20+）。
2. 自动检测已安装的 **GameMaker Studio 运行时** 和 `Igor.exe`。
3. 验证您的 GameMaker `.yyp` 项目结构。
4. 在您的项目目录中生成本地的 `mcp-config.json`。
5. 自动配置并连接 **Claude Desktop**、**Google Antigravity**、**Cursor**、**Codex** 和 **Qwen Code**。
---
### 方法 3：全局 CLI 安装
使用 `npm` 全局安装 `gamemaker-mcp`：
```powershell
npm install -g gamemaker-mcp
```
然后从任何终端或 PowerShell 运行命令：
```powershell
# 完整自动设置项目：
gamemaker-mcp install "C:\Projects\MyGame\MyGame.yyp"
# 验证环境、运行时和客户端连接状态：
gamemaker-mcp doctor "C:\Projects\MyGame\MyGame.yyp"
# 连接特定 AI 客户端（claude | antigravity | cursor | codex | qwen | all）：
gamemaker-mcp connect antigravity
gamemaker-mcp connect claude
gamemaker-mcp connect qwen
```
---
### 方法 4：手动客户端配置
如果您更喜欢手动将 MCP 服务器添加到 AI 客户端的配置文件中：
#### 1. Claude Desktop (`%APPDATA%\Claude\claude_desktop_config.json`)
```json
{
"mcpServers": {
"gamemaker": {
"command": "npx",
"args": ["-y", "gamemaker-mcp"],
"env": {
"GAMEMAKER_MCP_MODE": "workspace-write",
"GAMEMAKER_MCP_ALLOW_BUILD": "1"
}
}
}
}
```
#### 2. Google Antigravity (`~/.gemini/antigravity.json`)
```json
{
"mcpServers": {
"gamemaker": {
"command": "npx",
"args": ["-y", "gamemaker-mcp"],
"env": {
"GAMEMAKER_MCP_MODE": "workspace-write",
"GAMEMAKER_MCP_ALLOW_BUILD": "1"
}
}
}
}
```
#### 3. Cursor (`%APPDATA%\Cursor\User\globalStorage\mcp.json`)
```json
{
"mcpServers": {
"gamemaker": {
"command": "npx",
"args": ["-y", "gamemaker-mcp"],
"env": {
"GAMEMAKER_MCP_MODE": "workspace-write",
"GAMEMAKER_MCP_ALLOW_BUILD": "1"
}
}
}
}
```
#### 4. Qwen Code / CLI (`~/.qwen/mcp.json`)
```json
{
"mcpServers": {
"gamemaker": {
"command": "npx",
"args": ["-y", "gamemaker-mcp"],
"env": {
"GAMEMAKER_MCP_MODE": "workspace-write",
"GAMEMAKER_MCP_ALLOW_BUILD": "1"
}
}
}
}
```
## 环境变量
| 变量 | 默认值 | 含义 |
| --- | ---: | --- |
| `GAMEMAKER_PROJECT` | 自动检测 | 项目目录或确切的 `.yyp` 文件（如果省略，则从工作区自动检测） |
| `GAMEMAKER_MCP_MODE` | `read-only` | `read-only` 或 `workspace-write` |
| `GAMEMAKER_MCP_ALLOW_BUILD` | `0` | 启用 Igor 编译/打包操作 |
| `GAMEMAKER_MCP_MAX_FILE_BYTES` | `1048576` | 每个文件文本读写限制 |
| `GAMEMAKER_IGOR` | 自动检测 | `Igor.exe` 的确切路径 |
| `GAMEMAKER_RUNTIME` | 推断 | 与 Igor 配对的运行时目录 |
| `GAMEMAKER_USER_DIR` | 自动检测 | GameMaker 用户/配置目录 |
## 完整工具目录（83 个工具）
### 项目和导航（10 个工具）
| 工具 | 目的 |
| --- | --- |
| `gm_project_info` | 项目身份、IDE/资源版本、资产数量和房间顺序 |
| `gm_runtime_detect` | 已安装的运行时和选定的 Igor 工具链 |
| `gm_asset_list` | 过滤和分页的资产索引 |
| `gm_asset_read` | 资产元数据以及相关的 GML/着色器源代码和哈希值 |
| `gm_file_list` | 过滤的项目文件列表，包含大小/时间和有限哈希值 |
| `gm_file_read` | 允许的文本内容以及 SHA-256 |
| `gm_code_search` | 字面或正则 GML/GLSL 搜索 |
| `gm_project_validate` | 结构化 YYP/YY/资源/事件/着色器验证 |
| `gm_project_statistics` | 资源、文件、行、复杂度、着色器和依赖项统计 |
| `gm_project_autofix` | 扫描并自动修复缺失的 YYP 引用、缺失的着色器文件和损坏的元数据 |
### 静态分析和质量审计（16 个工具）
| 工具 | 目的 |
| --- | --- |
| `gm_gml_analyze` | 函数、符号、调用、复杂度、分隔符错误和风险模式 |
| `gm_shader_analyze` | 入口点、声明、变化兼容性和可移植性诊断 |
| `gm_symbol_references` | 声明、调用、写入、读取和可选元数据引用 |
| `gm_dependency_graph` | 资产依赖项、证据、隔离节点和循环 |
| `gm_unused_assets` | 扫描项目中未引用的精灵、声音、脚本、字体、路径和对象 |
| `gm_gml_profile_check` | 扫描 Step/Draw 事件和循环的 CPU/内存反模式 |
| `gm_i18n_scan` | 扫描 GML 代码中的硬编码字符串文字并建议本地化键 |
| `gm_draw_state_audit` | 审计 Draw 事件的 GPU 状态泄漏（混合模式、alpha、着色器状态） |
| `gm_gml_validate_snippet` | 预飞行 GML 代码的语法分隔符平衡和已弃用内置函数 |
| `gm_project_health_score` | 计算 0-100% 的健康评分、等级（A+ 至 F）和建议 |
| `gm_object_hierarchy` | 构建对象父子继承树以及继承的事件 |
| `gm_doc_export` | 为所有项目资产生成结构化的 Markdown 文档 |
| `gm_gml_duplicate_find` | 扫描项目 GML 文件以检测相同的连续代码块跨资产 |
| `gm_macros_list` | 扫描所有脚本和对象以提取和列出 GML #macro 定义 |
| `gm_state_machine_visualize` | 解析 GML 代码以提取状态和转换，返回 Mermaid stateDiagram-v2 字符串 |
| `gm_gml_dead_code_detect` | 扫描 GML 脚本和对象以检测从未被调用的已声明函数 |
### GML、资产和资源（22 个工具）
| 工具 | 目的 |
| --- | --- |
| `gm_gml_patch_preview` | 无需写入的确切替换计数和更改行预览 |
| `gm_gml_patch` | 确切的受控替换，具有预期的匹配计数 |
| `gm_gml_write` | 原子受控 GML 写入 |
| `gm_gml_docgen` | 生成 Feather 兼容的 JSDoc 头（`/// @function`、`/// @param`、`/// @returns`） |
| `gm_sprite_inspect` | 检查精灵原点（X/Y）、碰撞掩模模式、帧、速度和纹理组 |
| `gm_sprite_create` | 创建具有可配置尺寸、原点和纹理组的新的 GameMaker 精灵资产（`.yy`） |
| `gm_sound_inspect` | 检查声音音频组、压缩类型、采样率、位深度/率、持续时间和音量 |
| `gm_sound_create` | 创建新的 GameMaker 声音资产（`.yy`），链接声音音频文件并具有压缩和音量 |
| `gm_font_create` | 创建具有字体大小、粗体和斜体参数的新 GameMaker 字体资产（`.yy` 元数据） |
| `gm_font_inspect` | 检查 GameMaker 字体资产并返回字体大小、名称、粗体/斜体选项 |
| `gm_tileset_create` | 创建新的 GameMaker 图块集资产（`.yy` 元数据），链接到现有的精灵 |
| `gm_tileset_inspect` | 检查 GameMaker 图块集资产并返回图块大小、边框和链接精灵 |
| `gm_folder_create` | 创建或修复资产浏览器文件夹/YYP 条目 |
| `gm_script_create` | 创建脚本元数据和 GML 源代码 |
| `gm_state_machine_generate` | 生成干净的、基于结构的 GML 有限状态机控制器脚本（`scr_state_machine`） |
| `gm_particle_system_generate` | 生成专业的、基于结构的 GML 粒子系统管理器样板脚本 |
| `gm_gui_layout_generate` | 生成响应式 GML GUI 布局管理器脚本并注册它 |
| `gm_inventory_system_generate` | 生成基于结构的 GML 库存系统管理器脚本并注册它 |
| `gm_asset_rename` | 安全地重命名磁盘上的任何资产、在 YYP/YY 元数据中，并在整个项目范围内重构所有 GML 引用 |
| `gm_note_create` | 创建新的 GameMaker 注释资产（`notes/NoteName/NoteName.txt`），并带有文档文本 |
| `gm_note_inspect` | 读取 GameMaker 注释资产的文本文档内容、行计数、文件路径和 SHA-256 哈希值 |
| `gm_note_update` | 谨慎更新 GameMaker 注释资产的文本内容，并带有 SHA-256 并发检查 |
### 对象和事件（9 个工具）
| 工具 | 目的 |
| --- | --- |
| `gm_object_create` | 创建现代的 GMObject 和 YYP 引用 |
| `gm_object_configure` | 设置标志和精灵/掩模/父级引用 |
| `gm_object_events` | 列出具有稳定键、路径、哈希值和行计数的事件 |
| `gm_object_event_read` | 读取公共命名事件 |
| `gm_object_event_read_raw` | 读取任何事件，按类型/编号/可选碰撞对象 |
| `gm_object_event_upsert` | 添加或替换公共命名事件 |
| `gm_object_event_remove` | 删除公共命名事件；代码删除是可选的 |
| `gm_object_event_remove_raw` | 精确删除任何数字/碰撞事件 |
| `gm_object_event_chain` | 遍历对象的父级层次结构，并返回实现事件文件、行计数和路径 |
### 房间、着色器、序列、时间线和曲线（13 个工具）
| 工具 | 目的 |
| --- | --- |
| `gm_room_inspect` | 房间设置、层、实例、视图、物理和创建代码 |
| `gm_room_configure` | 谨慎的房间大小/持久性/视图/体积更新 |
| `gm_room_creation_code_upsert` | 谨慎的房间创建代码写入/引用更新 |
| `gm_room_instance_add` | 在坐标 (X, Y) 处放置对象实例，并具有缩放、旋转和图层选择 |
| `gm_room_layer_add` | 向房间添加新的实例、背景、图块图或资产图层，深度和可见性可指定 |
| `gm_shader_create` | 创建着色器元数据和顶点/片段阶段 |
| `gm_shader_inspect` | 哈希值、统一变量、属性、变量和接口问题 |
| `gm_shader_update` | 谨慎的每个阶段源代码更新，并预先检查两个哈希值 |
| `gm_sequence_inspect` | 检查序列的序列、长度、播放速度和关键帧 |
| `gm_timeline_create` | 创建新的 GameMaker 时间线资产（`.yy` 元数据），并带有步数时刻和 GML 时刻脚本列表 |
| `gm_timeline_inspect` | 检查 GameMaker 时间线资产，并返回已定义的时刻步数索引和 GML 路径列表 |
| `gm_anim_curve_create` | 创建具有默认线性通道的新动画曲线资产 |
| `gm_anim_curve_inspect` | 检查动画曲线资产并返回已定义的动画通道名称 |
### 快照和完整性（4 个工具）
| 工具 | 目的 |
| --- | --- |
| `gm_snapshot_create` | 创建完整性清单和文本有效载体快照 |
| `gm_snapshot_list` | 列出已保存的快照 |
| `gm_snapshot_inspect` | 验证和比较快照 |
| `gm_snapshot_restore` | 恢复具有完整性检查和备份的记录文件 |
### 构建和 Igor 编译器作业（11 个工具）
| 工具 | 目的 |
| --- | --- |
| `gm_compile_sync` | 通过 Igor.exe 进行同步 Windows VM 编译 |
| `gm_project_compile_errors` | 使用 Igor 编译项目，并返回解析的、结构化的文件/行/消息语法错误 |
| `gm_test_framework_init` | 在项目中初始化 GML 单元测试框架脚本（`scr_test_framework`） |
| `gm_test_suite_create` | 创建新的 GML 测试套件脚本并在单元测试框架中注册它 |
| `gm_test_runner_run` | 注入运行程序代码，在后台构建和运行项目，捕获和解析单元测试结果 |
| `gm_job_compile_start` | 启动持久的后台 Igor `compile` 作业 |
| `gm_job_package_zip_start` | 启动持久的后台 Igor `package-zip` 作业 |
| `gm_job_status` | 读取实时/持久的作业状态和工件信息 |
| `gm_job_wait` | 等待终端作业状态 |
| `gm_job_cancel` | 终止活动构建作业 |
| `gm_job_list` | 列出持久构建作业历史 |
### 客户端配置（1 个工具）
| 工具 | 目的 |
| --- | --- |
| `gm_connection_config` | 检查和生成 stdio 客户端配置 |
## 资源和提示
### 资源（6）
- `gamemaker://project/info` — 实时的项目摘要和资源元数据。
- `gamemaker://project/statistics` — 实时的资源、行数、复杂度、依赖项统计。
- `gamemaker://runtimes` — 检测到的 GameMaker Studio 运行时和 Igor.exe 路径。
- `gamemaker://gml/rules` — GML 2024+ 强制标准语法和编码规则，用于 AI 模型上下文。
- `gamemaker://snapshots` — 已记录的项目完整性快照列表。
- `gamemaker://jobs/history` — Igor 构建和打包作业历史。
### 工作流提示（10）
- `create-state-machine`：为 GameMaker 对象生成强大的、干净的状态机模式。
- `optimize-draw-events`：审计和优化 Draw 事件以获得最大 FPS。
- `refactor-gml-script`：清理、现代化和为 GML 脚本添加 Feather JSDoc 头。
- `add-object-event`：逐步指导安全添加和配置对象事件。
- `create-script`：使用严格的 Feather JSDoc 头搭建新脚本。
- `create-shader`：搭建顶点/片段 GLSL ES 着色器对。
- `inspect-room`：详细分析房间设置、层和实例。
- `analyze-project`：对项目健康和架构进行全面诊断审查。
- `create-snapshot`：在进行多文件重构前的安全工作流。
- `repair-project`：损坏的资源引用的诊断和修复指南。
## 推荐工作流
1. 使用 `gm_project_info`、`gm_asset_list` 和分析工具进行检查。
2. 在进行多文件更改之前，创建带有标签的快照。
3. 读取每个受影响的文件并保留返回的 SHA-256。
4. 在适用情况下预览确切的 GML 补丁。
5. 应用最小的受控编辑。如果哈希值过期，请停止并重新读取。
6. 在元数据更改后运行 `gm_project_validate`。
7. 使用 `gm_job_start` 编译受信任的项目，然后使用 `gm_job_wait` 和 `gm_job_log`。
备份存储在 `.gamemaker-mcp/backups` 下；快照和作业历史存储在 `.gamemaker-mcp/snapshots` 和 `.gamemaker-mcp/jobs` 下。
## 测试任何项目
烟雾命令启动内置的 MCP 服务器，以只读模式列出其工具，并调用项目信息、验证、统计、GML 分析和着色器分析：
```powershell
npm run smoke -- "C:\path\to\Game.yyp"
```
## 安全模型
- 工具文件路径相对于项目；拒绝绝对路径、遍历、NUL 字节和符号链接/连接逃逸；
- 仅允许写入文本扩展名白名单；
- 默认情况下禁用写入和 Igor 操作；
- 现有文件写入需要调用者进行 SHA-256 读取，除非使用明确支持的强制路径；
- 元数据编辑通过 `jsonc-parser` 保留未知字段并创建备份；
- Igor 从具有允许列表操作和 `shell: false` 的固定可执行文件启动；
- **仅编译/打包受信任的 GameMaker 项目**：GameMaker 本身可以运行项目编译器批处理文件、扩展和构建钩子；
- stdout 保留用于 MCP JSON-RPC；服务器诊断输出到 stderr。
服务器故意不公开任意 shell 命令、任意 YY/YPP 覆盖、批量资产删除或 GUI 自动化。 二进制精灵/音频导入在当前安全、文本聚焦范围之外仍然不被支持。
连接信息
猜你喜欢
暂无推荐服务器