游戏制造商MCP工具

![CI](https://github.com/Ampersand-Game-Studios/gms-mcp/actions/workflows/ci.yml) ](https://github.com/Ampersand-Game-Studios/gms-mcp/stargazers)

项目特点

gms：用于GameMaker项目操作（资产创建、维护、运行器等）的Python CLI。
gms-mcp：一个MCP服务器，它公开了与MCP工具相同的操作（Cursor是主要的示例客户端）。
TCP网桥（可选）：通过实时双向游戏通信（命令+日志捕获） gm_bridge_install, gm_run_command，以及 gm_run_logs网桥生命周期日志记录不在MCP stdio传输范围内，因此 gm_run(..., enable_bridge=true) 不会损坏JSON-RPC。看 documentation/BRIDGE.md.
可靠性优先架构：自定义异常层次结构、类型化结果对象和执行策略管理器取代了单体退出调用和原始字典。这实现了结构化错误处理、一致的工具集成和优化的性能（快速资产、弹性运行器）。
健康与诊断: gm_mcp_health 提供了一个一键诊断工具来验证本地GameMaker环境。 gm_diagnostics 提供与IDE问题面板兼容的结构化、机器可读的项目诊断（JSON、命名、孤立项、引用）。
导入的模板清理: gms maintenance normalize-names / gm_maintenance_normalize_names 计划命名约定重命名，并且仅在明确请求时应用它们。
运行时管理: gm_runtime_list, gm_runtime_pin，以及 gm_runtime_verify 允许精确控制用于构建和执行的GameMaker运行时版本。
跨平台运行程序默认值: gm_run / gm_compile 现在默认为主机操作系统目标平台(macOS, Linux，或 Windows)如果没有明确提供。
macOS本地运行者行为：本地 gm_run / gm_compile 使用Igor的基于运行的路径进行IDE等效验证，而无需打包开发人员ID，macOS后台运行会话现在可以跟踪和停止真实的 Mac_Runner 过程干净。打包的温度输出运行仍然可以解决 .app 捆绑通过 Contents/MacOS/ 当 PackageZip 使用。
GML符号索引与代码智能: gm_build_index, gm_find_definition, gm_find_references，以及 gm_list_symbols 提供深入、快速和过滤的代码分析（定义和跨文件引用）。
内省：完成项目检查，支持所有资产类型（包括扩展名和数据文件）。
MCP资源：用于高性能代理上下文加载的可寻址项目索引和资产图。
gms-mcp-init：为工作区生成可共享的MCP配置文件。现在自动检测环境变量，如 GMS_MCP_GMS_PATH 以包含在生成的配置中。
隐私安全遥测（选择加入）: gms, gms-mcp-init，并且MCP使用只有在明确同意后才能发送匿名使用元数据。

安装（推荐：pipx）

pipx install gms-mcp

如果 gms-mcp 是有用的，考虑在GitHub上发布该仓库。明星帮助其他GameMaker用户找到它。

PowerShell等效程序：

pipx install gms-mcp

Claude代码插件

对于Claude Code用户，安装插件以获得最佳体验：

/install-plugin github:Ampersand-Game-Studios/gms-mcp

这提供了：

技能：18个工作流程指南+7个参考文档
钩子：每日一次的更新提醒和错误通知
MCP服务器：通过uvx自动配置（无需安装pip）

其他工具（游标、VSCode、OpenClaw等）

pip install gms-mcp
gms-mcp doctor            # quick package + project-detection + update check
gms-mcp doctor --project  # project-aware environment check
gms-mcp doctor --full     # add runtime selection + bridge status
gms-mcp-init --cursor     # or --vscode, --windsurf, --openclaw, etc.

对于技能包，OpenClaw用户可以安装到用户或工作区范围：

gms skills install --openclaw            # user scope: ~/.openclaw/skills/
gms skills install --openclaw --project  # workspace scope: ./skills/

注： .openclaw/openclaw.json 用于设置。工作空间技能从加载 ./skills/.

食品法典委员会

gms-mcp-init --codex

这将写入一个工作区 .codex/mcp.toml 文件并打印 codex mcp add 注册命令。

全局配置模式直接写入 ~/.codex/config.toml （合并服务器条目）。

直接使用打印命令，或复制 .codex/mcp.toml 内容进入 [mcp_servers] 你的部分 ~/.codex/config.toml.

食品法典助理：

gms-mcp-init --codex-check 打印检测到的Codex配置路径和活动服务器条目，并对类似机密的值进行编辑。
gms-mcp-init --codex-check-json 以机器可读的JSON格式打印相同的检查输出，并对类似secret的值进行编辑。
gms-mcp-init --codex-dry-run-only 打印工作区+全局Codex配置的最终合并有效载荷，而无需写入文件。
gms-mcp-init --codex-app-setup 运行一次性Codex应用程序设置：写入工作区配置，预览全局合并，然后打印检查+准备状态摘要。

遥测

遥测是 default off.

同意是用户范围内的 ~/.gms-mcp/telemetry.json
交互式 gms 和 gms-mcp-init 跑步可以提示一次同意
MCP服务器启动从不在stdio上提示
默认情况下，遥测不包括文件路径、命令参数、stdout/stderr、项目名称、用户名、电子邮件、主机名和持久ID

CLI控件：

gms telemetry status
gms telemetry enable
gms telemetry enable --with-install-id
gms telemetry disable
gms telemetry flush
gms telemetry clear

运行时覆盖：

gms --telemetry=off maintenance auto
gms-mcp-init --telemetry=on --cursor
GMS_MCP_TELEMETRY=off gms asset create script my_script

导入的模板清理

GameMaker的空白模板可能会创建以下资产 room1 这违反了更严格的项目命名规则。保持lint严格，然后显式规范化导入/模板资产：

gms maintenance normalize-names
gms maintenance normalize-names --fix
gms maintenance normalize-names --asset-type room --fix

该命令使用项目的 .gms-mcp.json 命名配置，默认为模拟运行，检测冲突，并通过与相同的引用感知工作流执行真正的重命名 gms workflow rename.

开发/测试端点覆盖：

GMS_MCP_TELEMETRY_ENDPOINT=https://localhost:8787/v1/events gms telemetry flush

地方发展设置

如果你正在做 gms-mcp 代码库本身，请按照以下步骤设置本地开发环境：

在可编辑模式下克隆和安装:

   git checkout dev
   python3.12 -m venv .venv
   source .venv/bin/activate
   python3.12 -m pip install -e ".[dev]"

gms-mcp 需要Python 3.10+；我们推荐Python 3.12 为了地方发展。

运行完整的本地测试套件:

   PYTHONPATH=src python3.12 cli/tests/python/run_all_tests.py

初始化本地和全局MCP服务器以进行测试:

我们建议在Cursor中设置两个单独的MCP服务器配置来测试您的更改：

- 全球(gms-global)：适用于所有GameMaker项目。 - 本地(gms-local)：专门用于测试您当前对服务器所做的更改。

从项目根目录（zsh/bash）运行以下命令：

   # Global setup (names it 'gms-global' in Cursor)
   gms-mcp-init --cursor-global --server-name gms-global --mode python-module --python python3 --non-interactive

   # Local setup (names it 'gms-local' in Cursor)
   gms-mcp-init --cursor --server-name gms-local --mode python-module --python python3 --non-interactive

PowerShell等效程序：

   # Global setup (names it 'gms-global' in Cursor)
   gms-mcp-init --cursor-global --server-name gms-global --mode python-module --python python --non-interactive

   # Local setup (names it 'gms-local' in Cursor)
   gms-mcp-init --cursor --server-name gms-local --mode python-module --python python --non-interactive

在游标中验证:

首选 光标设置>功能>MCP 查看您的新服务器。您可能需要单击“重新加载”或重新启动Cursor以查看更改。

出版（维护者）

每次推送时，都会通过GitHub Actions（PyPI可信发布）自动发布 main 和标签上 v*. 看 RELEASING.md 用于一次性PyPI设置和第一个手动上传助手脚本。

CI覆盖范围

Core CI跨Python在Ubuntu和Windows上运行 3.11-3.13.
运行器/会话回归测试也可以在macOS上跨Python运行 3.11-3.13，包括一个无模拟烟雾测试，该测试构建了一个真实的 .app 包结构并验证可执行路径解析。

质量报告

质量报告在CI期间生成并发布为 quality-reports-* 人工产品。

报告管道支持子流程：启动CLI测试 python -m gms_helpers.gms 或其他子进程现在对最终覆盖工件做出了贡献，而不是默默地贡献辍学 coverage.xml.

TEST_COVERAGE_REPORT.md
MCP_TOOL_VALIDATION_REPORT.md
coverage.xml
pytest_results.xml
quality_summary.json

您可以通过以下方式在本地重新生成这些：

python scripts/generate_quality_reports.py

此命令：

在启用覆盖率的情况下运行Python测试套件
组合任何并行/子流程覆盖率数据
改写 build/reports/coverage.xml
重新生成markdown和JSON质量摘要
跑 cli/tests/python/test_final_verification.py

使用 --skip-test-run 从现有CI工件中重新生成：

python scripts/generate_quality_reports.py --skip-test-run --junit-xml build/reports/pytest_results.xml --coverage-xml build/reports/coverage.xml

对于发布绑定的促销，维护人员应该从repo根本地运行所有三个：

PYTHONPATH=src python cli/tests/python/run_all_tests.py
PYTHONPATH=src python -m pytest cli/tests/python/test_final_verification.py
python scripts/generate_quality_reports.py

X（推特）发布在 `main`

此仓库可以在以下情况下自动发布到X main 已更新。

个性/声音: .github/x-personality.md
Tweet暂存文件: .github/next_tweet.txt

运作原理

当一个承诺落在 main，GitHub操作读取 .github/next_tweet.txt.
如果它包含占位符文本（或为空），则 跳过发布.
如果它包含一条真实的推文，它会发布到X，将该推文记录在缓存的推文历史中，并提交一个空 .github/next_tweet.txt 回到 main 使用一个 [skip ci] 重置提交。
X工作流在专用的自托管跑步者标签上运行 gms-mcp-x 因为GitHub托管的runner IP间歇性地被X阻止或挑战。
该运行器使用预配置的Python 3.13 virtualenv ~/.local/share/actions-runner-gms-mcp-x/x-posting-venv.
同一个跑步者也提供了X的官方 xurl CLI位于 ~/.local/bin/xurl 因此，发布脚本可以重试 /2/tweets 当直接OAuth1请求行为异常时，通过X自己的客户端。
瞬态X API失败会在发布脚本中自动重试，并有限制的后退，因此 503 Retry-After 提示不能超过工作流预算，边缘挑战页面会被重试，而不会将其误报为凭据失败。
如果X在重试后仍然以已知的瞬态错误失败，则工作流会将暂存的推文或常青队列项留在git中，以便稍后重试，而不是标记整个作业失败。
X工作流还强制执行作业/请求超时，因此挂起的API调用无法无限期地阻止队列。
您还可以使用手动重试发布后工作流 Post to X GitHub Actions中的工作流调度。

维护者流程（开发->预发布->主）

因为这个仓库促进了变化 dev -> pre-release -> main，在推特期间准备推文 pre-release -> main 公共关系：

更新 .github/next_tweet.txt 推特（以下 .github/x-personality.md)
升级前确认上述本地验证命令通过
确认GitHub操作 CI 传递 main 推广落地后
合并到 main

与GameMaker项目一起使用（多项目友好）

在每个GameMaker项目工作区（或仓库）中运行此命令以生成配置：

gms-mcp-init --cursor

这写道 .cursor/mcp.json 并尝试自动检测 .yyp 要设置的位置 GM_PROJECT_ROOT.

对于适用于多个项目的一次性设置，请编写Cursor的全局配置：

gms-mcp-init --cursor-global

从当前工作区生成Codex配置：

gms-mcp-init --codex

在中生成全球食品法典条目 ~/.codex/config.toml:

gms-mcp-init --codex-global

全局模式与现有条目合并，因此将多个MCP服务器保存在同一文件中是安全的。

检查当前的Codex配置分辨率：

gms-mcp-init --codex-check

在打印之前，人工和JSON检查输出密文，如env、header和凭据参数值。

预览本地+全球最终合并的Codex有效载荷，无需编写：

gms-mcp-init --codex-dry-run-only

将Codex检查输出打印为JSON（对应用程序自动化有用）：

gms-mcp-init --codex-check-json

一次性Codex应用程序设置（建议用于新工作区）：

gms-mcp-init --codex-app-setup

Codex应用程序快速入门

跑 gms-mcp-init --codex-app-setup 在您的GameMaker工作区中。
确认输出内容 Ready for Codex app: yes.
如果需要，运行 gms-mcp-init --codex-check-json 并验证 active.scope 是 workspace.
使用 gms-mcp-init --codex-dry-run-only 在更改全局配置以安全预览合并的TOML之前。

规范客户端工作流

所有客户端现在都支持相同的规范动作面：

gms-mcp-init \
  --client  \
  --scope  \
  --action

可选：

--config-path /custom/path 覆盖默认配置位置
--safe-profile 强制执行保守的环境默认值

示例：

# Cursor setup + readiness check
gms-mcp-init --client cursor --scope workspace --action app-setup

# Codex machine-readable readiness
gms-mcp-init --client codex --scope workspace --action check-json

# Claude Desktop global plugin sync
gms-mcp-init --client claude-desktop --scope global --action setup

# Gemini alias (Antigravity path)
gms-mcp-init --client gemini --scope global --action app-setup

# OpenClaw app setup + workspace skills install
gms-mcp-init --client openclaw --scope workspace --action app-setup \
  --openclaw-install-skills --openclaw-skills-project

有关奇偶校验状态和支持的默认值，请参阅 documentation/CLIENT_SUPPORT_MATRIX.md.

为其他支持MCP的客户端生成示例配置：

gms-mcp-init --vscode --windsurf --antigravity --openclaw

设置Antigravity全局配置（推荐）：

gms-mcp-init --antigravity-setup

这融合到 ~/.gemini/antigravity/mcp_config.json，以原子方式写入，在覆盖时创建带时间戳的备份，并默认启用保守的安全配置文件：

GMS_MCP_ENABLE_DIRECT=0
GMS_MCP_REQUIRE_DRY_RUN=1

检查反重力准备情况：

gms-mcp-init --antigravity-check

将反重力检查输出打印为JSON：

gms-mcp-init --antigravity-check-json

反重力检查输出还会在打印之前对env、header和凭据参数值等机密进行编辑。

一次性Antigravity应用程序设置：

gms-mcp-init --antigravity-app-setup

使用自定义反重力配置路径：

gms-mcp-init --antigravity-setup --antigravity-config-path /path/to/mcp_config.json

对于反重力示例配置，也选择保守的安全配置：

gms-mcp-init --antigravity --safe-profile

当 GMS_MCP_REQUIRE_DRY_RUN=1 设置后，您可以使用以下工具允许特定的破坏性工具：

export GMS_MCP_REQUIRE_DRY_RUN_ALLOWLIST=gm_asset_delete,gm_workflow_delete

或者一次生成所有内容：

gms-mcp-init --all

单重/多重 `.yyp`

如果有多个 .yyp 在工作区中检测到项目：

gms-mcp-init 将发出警告，并（在交互时）提示您选择一个。
在非交互式环境中，它默认为 GM_PROJECT_ROOT 到 ${workspaceFolder} （安全）。

强制特定项目根：

gms-mcp-init --cursor --gm-project-root path/to/project

预览输出而不写入文件：

gms-mcp-init --cursor --dry-run

代码智能与内省

MCP服务器提供全面的项目分析功能：

GML符号索引(`gm_build_index`)

为项目中的所有函数、枚举、宏和全局变量构建高性能索引。这是高级代码智能工具所必需的。

符号定义(`gm_find_definition`)

查找项目中任何GML符号的确切位置和文档字符串。

查找参考文献(`gm_find_references`)

在整个代码库中搜索特定函数或变量的所有用法。

列出符号(`gm_list_symbols`)

列出所有项目符号，并按类型、名称子字符串或文件路径进行筛选。

资产列表(`gm_list_assets`)

列出项目中的所有资产，可选择按类型筛选：

支持的类型：脚本、对象、精灵、房间、声音、字体、着色器、路径、时间线、波浪集、动画曲线、序列、注释、文件夹，扩展, 包含文件 （数据文件）

资产读数(`gm_read_asset`)

阅读全文 .yy 按名称或路径为任何资产提供JSON元数据。

参考文献搜索(`gm_search_references`)

使用以下命令在项目文件中搜索模式：

范围: all, gml, yy, scripts, objects, extensions, datafiles
模式：文字字符串或正则表达式
选项：区分大小写，最大结果

资产图(`gm_get_asset_graph`)

使用两种模式构建资产依赖图：

浅（快）：解析 .yy 结构参照文件（父对象、精灵等）
深（完整）：还扫描所有GML代码以查找运行时引用，如 instance_create, sprite_index, audio_play_sound等等。

纹理组(`gm_texture_group_*`)

创建、检查和编辑 .yyp TextureGroups，以及通过批量分配资源（精灵/字体/拼贴集等） textureGroupId.

只读工具：

gm_texture_group_list：列出纹理组+可用配置（桌面/android/ios/etc）
gm_texture_group_read：读取单个纹理组条目
gm_texture_group_members：列出组中的资产（顶级+配置值覆盖）
gm_texture_group_scan：报告缺少引用的组+不匹配（顶级vs配置覆盖）

破坏性工具（所有支持 dry_run=true):

gm_texture_group_create：克隆现有模板组（默认值： Default)
gm_texture_group_update：修补组上的字段（可选通过每个配置 ConfigValues)
gm_texture_group_rename：重命名组并重写资源引用
gm_texture_group_delete：如果被引用，默认情况下为块，除非 reassign_to 被提供
gm_texture_group_assign：通过显式列表或筛选器批量分配资产

配置范围默认值：

任务更新资产的顶层 textureGroupId 只有当它是格言时 （空保持原样）。
如果 configs 省略，仅更新分配 现有的 ConfigValues 条目；通过 configs=[...] 创建显式覆盖。

MCP资源

为代理预先构建的可缓存项目数据：

gms://project/index：完整的项目结构（资产、文件夹、房间顺序、配置、音频/纹理组、IDE版本）
gms://project/asset-graph：资产依赖关系图
gms://system/updates：如果更新版本的 gms-mcp 可以在PyPI或GitHub上找到。

更新提示器

共享更新状态可通过下面的MCP界面获得，支持的客户端挂钩可以显示每日一次的提醒：

命令行界面: gms-mcp doctor 是标准的本地诊断命令。 gms-mcp doctor --notify 仍然是仅更新的启动钩子路径。
工具: gm_check_updates 返回结构化更新信息。
自动检查: gm_project_info 包括缓存 updates 现场。
资源: gms://system/updates 提供快速文本状态。
平原 pip 除非客户端设置中包含捆绑的启动挂钩，否则无法保证安装会收到主动提醒。

常见的医生切入点：

gms-mcp doctor：快速包/更新/项目检测检查。
gms-mcp doctor --project：添加环境、运行时、许可证和依赖性检查。
gms-mcp doctor --full：添加运行时选择和网桥状态。
gms-mcp doctor --client codex|claude：验证当前工作区的活动客户端配置。
gms-mcp doctor --project-root /path/to/project：指向一个明确的GameMaker项目目录。
gms-mcp doctor --client codex --server-name gms-app：验证非默认MCP服务器条目名称。
gms-mcp doctor --json：发出一个稳定的JSON报告 overall_status, exit_code，以及 checks.

CLI使用情况

从项目目录运行（或传递 --project-root):

gms --version
gms --project-root . asset create script my_function --parent-path "folders/Scripts.yy"
gms --project-root . texture-groups list
gms --project-root . texture-groups assign game --type sprite --folder-prefix sprites/ --dry-run

gms MCP

快速接入

详细介绍

游戏制造商MCP工具

项目特点

安装（推荐：pipx）

Claude代码插件

其他工具（游标、VSCode、OpenClaw等）

食品法典委员会

遥测

导入的模板清理

地方发展设置

出版（维护者）

CI覆盖范围

质量报告

X（推特）发布在 `main`

运作原理

维护者流程（开发->预发布->主）

与GameMaker项目一起使用（多项目友好）

Codex应用程序快速入门

规范客户端工作流

单重/多重 `.yyp`

代码智能与内省

GML符号索引(`gm_build_index`)

符号定义(`gm_find_definition`)

查找参考文献(`gm_find_references`)

列出符号(`gm_list_symbols`)

资产列表(`gm_list_assets`)

资产读数(`gm_read_asset`)

参考文献搜索(`gm_search_references`)

资产图(`gm_get_asset_graph`)

纹理组(`gm_texture_group_*`)

MCP资源

更新提示器

CLI使用情况

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

gms MCP

快速接入

详细介绍

游戏制造商MCP工具

项目特点

安装（推荐：pipx）

Claude代码插件

其他工具（游标、VSCode、OpenClaw等）

食品法典委员会

遥测

导入的模板清理

地方发展设置

出版（维护者）

CI覆盖范围

质量报告

X（推特）发布在 main

运作原理

维护者流程（开发->预发布->主）

与GameMaker项目一起使用（多项目友好）

Codex应用程序快速入门

规范客户端工作流

单重/多重 .yyp

代码智能与内省

GML符号索引(gm_build_index)

符号定义(gm_find_definition)

查找参考文献(gm_find_references)

列出符号(gm_list_symbols)

资产列表(gm_list_assets)

资产读数(gm_read_asset)

参考文献搜索(gm_search_references)

资产图(gm_get_asset_graph)

纹理组(gm_texture_group_*)

MCP资源

更新提示器

CLI使用情况

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

X（推特）发布在 `main`

单重/多重 `.yyp`

GML符号索引(`gm_build_index`)

符号定义(`gm_find_definition`)

查找参考文献(`gm_find_references`)

列出符号(`gm_list_symbols`)

资产列表(`gm_list_assets`)

资产读数(`gm_read_asset`)

参考文献搜索(`gm_search_references`)

资产图(`gm_get_asset_graph`)

纹理组(`gm_texture_group_*`)