gms-mcp 0.1.114

GameMaker CLI + MCP server toolset

GameMaker MCP Tools

Project Features

• gms: a Python CLI for GameMaker project operations (asset creation, maintenance, runner, etc).
• gms-mcp: an MCP server that exposes the same operations as MCP tools (Cursor is the primary example client).
• TCP Bridge (optional): live, bidirectional game communication (commands + log capture) via gm_bridge_install, gm_run_command, and gm_run_logs. Bridge lifecycle logging stays off the MCP stdio transport so gm_run(..., enable_bridge=true) does not corrupt JSON-RPC. See documentation/BRIDGE.md.
• Reliability-First Architecture: Custom exception hierarchy, typed result objects, and an execution policy manager replace monolithic exit calls and raw dictionaries. This enables structured error handling, consistent tool integration, and optimized performance (Fast assets, Resilient runner).
• Health & Diagnostics: gm_mcp_health provides a one-click diagnostic tool to verify the local GameMaker environment. gm_diagnostics provides structured, machine-readable project diagnostics (JSON, naming, orphans, references) compatible with IDE problem panels.
• Imported Template Cleanup: gms maintenance normalize-names / gm_maintenance_normalize_names plans naming-convention renames, and applies them only when explicitly requested.
• Runtime Management: gm_runtime_list, gm_runtime_pin, and gm_runtime_verify allow precise control over which GameMaker runtime version is used for builds and execution. Runtime discovery now identifies LTS2026 installs as LTS.
• Cross-Platform Runner Defaults: gm_run / gm_compile now default to the host OS target platform (macOS, Linux, or Windows) when not explicitly provided.
• macOS Local Runner Behavior: local gm_run / gm_compile use Igor's run-based path for IDE-equivalent validation without Developer ID packaging, and macOS background run sessions now track and stop the real Mac_Runner process cleanly. Packaged temp-output runs still resolve .app bundles via Contents/MacOS/ when PackageZip is used.
• GML Symbol Indexing & Code Intelligence: gm_build_index, gm_find_definition, gm_find_references, and gm_list_symbols provide deep, fast, and filtered code analysis (definitions and cross-file references).
• Introspection: complete project inspection with support for all asset types (including extensions and datafiles).
• MCP Resources: addressable project index and asset graph for high-performance agent context loading.
• gms-mcp-init: generates shareable MCP config files for a workspace. Now auto-detects environment variables like GMS_MCP_GMS_PATH to include in the generated config.
• Privacy-Safe Telemetry (opt-in): gms, gms-mcp-init, and MCP usage can send anonymous usage metadata only after explicit consent.

Install (recommended: pipx)

pipx install gms-mcp

If gms-mcp is useful, consider starring the repo on GitHub. Stars help other GameMaker users find it.

PowerShell equivalent:

pipx install gms-mcp

Claude Code Plugin

For Claude Code users, install the plugin for the best experience:

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

This provides:

• Skills: 18 workflow guides + 7 reference docs
• Hooks: Once-daily update reminders and error notifications
• MCP Server: Auto-configured via uvx (no pip install needed)

For Other Tools (Cursor, VSCode, OpenClaw, etc.)

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.

For skill packs, OpenClaw users can install to user or workspace scope:

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

Note: .openclaw/openclaw.json is for settings. Workspace skills are loaded from ./skills/.

For Codex

gms-mcp-init --codex

This writes a workspace .codex/mcp.toml file and prints the codex mcp add registration command.

Global config mode writes directly to ~/.codex/config.toml (merging server entries).

Use the printed command directly, or copy .codex/mcp.toml content into the [mcp_servers] section of your ~/.codex/config.toml.

Codex helpers:

• gms-mcp-init --codex-check prints detected Codex config paths and active server entry, with secret-like values redacted.
• gms-mcp-init --codex-check-json prints the same check output in machine-readable JSON, with secret-like values redacted.
• gms-mcp-init --codex-dry-run-only prints final merged payloads for workspace + global Codex config without writing files.
• gms-mcp-init --codex-app-setup runs one-shot Codex app setup: writes workspace config, previews global merge, then prints check + readiness summary.

Telemetry

Telemetry is default off.

• Consent is user-scoped in ~/.gms-mcp/telemetry.json
• Interactive gms and gms-mcp-init runs can prompt once for consent
• MCP server startup never prompts on stdio
• By default telemetry excludes file paths, command arguments, stdout/stderr, project names, usernames, emails, hostnames, and persistent IDs

CLI controls:

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

Runtime overrides:

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

Imported Template Cleanup

GameMaker's blank template may create assets like room1 that violate stricter project naming rules. Keep lint strict, then normalize imported/template assets explicitly:

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

The command uses the project's .gms-mcp.json naming config, defaults to dry-run, detects collisions, and performs real renames through the same reference-aware workflow as gms workflow rename.

Dev/test endpoint override:

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

Local Development Setup

If you are working on the gms-mcp codebase itself, follow these steps to set up a local development environment:

1. Clone and install in editable mode:

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

   gms-mcp requires Python 3.10+; we recommend Python 3.12 for local development.

2. Run the full local test suite:

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

3. Initialize local and global MCP servers for testing: We recommend setting up two separate MCP server configurations in Cursor to test your changes:

   • Global (gms-global): For general use across all your GameMaker projects.
   • Local (gms-local): Specifically for testing your current changes to the server.

   Run these commands from the project root (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 equivalent:

   # 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
   

4. Verify in Cursor: Go to Cursor Settings > Features > MCP to see your new servers. You may need to click "Reload" or restart Cursor to see changes.

Publishing (maintainers)

Publishing is automated via GitHub Actions (PyPI Trusted Publishing) on every push to main and on tags v*. See RELEASING.md for the one-time PyPI setup and the first manual upload helper scripts.

CI Coverage

• Core CI runs on Ubuntu and Windows across Python 3.11-3.13.
• Runner/session regression tests also run on macOS across Python 3.11-3.13, including a mockless smoke test that builds a real .app bundle structure and validates executable path resolution.

Quality Reports

Quality reports are generated during CI and published as quality-reports-* artifacts.

The reporting pipeline is subprocess-aware: CLI tests that launch python -m gms_helpers.gms or other child processes now contribute to the final coverage artifacts instead of silently dropping out of coverage.xml.

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

You can regenerate these locally with:

python scripts/generate_quality_reports.py

This command:

• runs the Python test suite with coverage enabled
• combines any parallel / subprocess coverage data
• rewrites build/reports/coverage.xml
• regenerates the markdown and JSON quality summaries
• runs cli/tests/python/test_final_verification.py
• enforces coverage gates: 85% overall statement coverage and 50% per-module statement coverage by default

Use --skip-test-run to regenerate from existing CI artifacts:

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

Coverage gates can be raised or temporarily narrowed with --min-overall-coverage, --min-module-coverage, and --coverage-gate-exclude. The matching environment variables are GMS_MCP_MIN_OVERALL_COVERAGE, GMS_MCP_MIN_MODULE_COVERAGE, and GMS_MCP_COVERAGE_GATE_EXCLUDE.

For real GameMaker verification on a machine with GameMaker installed, run:

GMS_MCP_REAL_SMOKE_PROJECT=/path/to/project python scripts/run_real_gamemaker_smoke.py --required

The smoke copies the project to a temporary directory, uses smart post-mutation verification, compiles after a high-risk mutation, defers a batchable sprite-frame mutation, then flushes the pending compile once.

For release-bound promotions, maintainers should run these locally from the repo root:

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
GMS_MCP_REAL_SMOKE_PROJECT=/path/to/project python scripts/run_real_gamemaker_smoke.py --required

X posting during release

X posting is handled through Codex/browser automation during release promotion, not through GitHub Actions or the X API.

• Personality / voice: .github/x-personality.md

How it works

• Draft the release post from the released changes, following .github/x-personality.md.
• Verify Chrome is logged into @gms_mcp.
• Use the X web UI to publish the post.
• Verify the post appears on the @gms_mcp profile and record the URL in the release closeout.

Maintainer flow (dev -> pre-release -> main)

Because this repo promotes changes dev -> pre-release -> main, prepare the release post during the pre-release -> main promotion:

• Confirm the local validation commands above pass before promotion
• Confirm GitHub Actions CI passes on main after the promotion lands
• Merge to main
• Publish through the X web UI with Codex if a release post is wanted

Use with a GameMaker project (multi-project friendly)

Run this inside each GameMaker project workspace (or repo) to generate config:

gms-mcp-init --cursor

This writes .cursor/mcp.json and attempts to auto-detect the .yyp location to set GM_PROJECT_ROOT.

For a one-time setup that works across many projects, write Cursor's global config instead:

gms-mcp-init --cursor-global

Generate a Codex config from the current workspace:

gms-mcp-init --codex

Generate a global Codex entry in ~/.codex/config.toml:

gms-mcp-init --codex-global

Global mode merges with existing entries so it is safe to keep multiple MCP servers in the same file.

Inspect current Codex config resolution:

gms-mcp-init --codex-check

Human and JSON check output redact secret-like env, header, and credential argument values before printing.

Preview final merged Codex payloads for local + global without writing:

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

Print Codex check output as JSON (useful for app automation):

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

One-shot Codex app setup (recommended for new workspaces):

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

Codex App Quickstart

1. Run gms-mcp-init --codex-app-setup in your GameMaker workspace.
2. Confirm the output says Ready for Codex app: yes.
3. If needed, run gms-mcp-init --codex-check-json and verify active.scope is workspace.
4. Use gms-mcp-init --codex-dry-run-only before changing global config to preview merged TOML safely.

Canonical Client Workflow

All clients now support the same canonical action surface:

gms-mcp-init \
  --client <cursor|codex|claude-code|claude-desktop|antigravity|gemini|vscode|windsurf|openclaw|generic> \
  --scope <workspace|global> \
  --action <setup|check|check-json|app-setup>

Optional:

• --config-path /custom/path to override default config location
• --safe-profile to enforce conservative env defaults

Examples:

# 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

For parity status and supported defaults, see documentation/CLIENT_SUPPORT_MATRIX.md.

Generate example configs for other MCP-capable clients:

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

Set up Antigravity global config (recommended):

gms-mcp-init --antigravity-setup

This merges into ~/.gemini/antigravity/mcp_config.json, writes atomically, creates a timestamped backup on overwrite, and enables a conservative safety profile by default:

• GMS_MCP_ENABLE_DIRECT=0
• GMS_MCP_REQUIRE_DRY_RUN=1

Check Antigravity readiness:

gms-mcp-init --antigravity-check

Print Antigravity check output as JSON:

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

Antigravity check output also redacts secret-like env, header, and credential argument values before printing.

One-shot Antigravity app setup:

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

Use a custom Antigravity config path:

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

Opt in to the conservative safety profile for Antigravity example configs too:

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

When GMS_MCP_REQUIRE_DRY_RUN=1 is set, you can allow specific destructive tools with:

export GMS_MCP_REQUIRE_DRY_RUN_ALLOWLIST=gm_asset_delete,gm_workflow_delete

Or generate everything at once:

gms-mcp-init --all

Monorepos / multiple .yyp

If multiple .yyp projects are detected in a workspace:

• gms-mcp-init will warn and (when interactive) prompt you to pick one.
• In non-interactive environments, it defaults GM_PROJECT_ROOT to ${workspaceFolder} (safe).

Force a specific project root:

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

Preview output without writing files:

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

Code Intelligence & Introspection

The MCP server provides comprehensive project analysis capabilities:

GML Symbol Indexing (gm_build_index)

Build a high-performance index of all functions, enums, macros, and global variables in the project. This is required for advanced code intelligence tools.

Symbol Definition (gm_find_definition)

Find the exact location and docstrings for any GML symbol in your project.

Find References (gm_find_references)

Search for all usages of a specific function or variable across your entire codebase.

List Symbols (gm_list_symbols)

List all project symbols with filtering by type, name substring, or file path.

Asset Listing (gm_list_assets)

List all assets in your project, optionally filtered by type:

• Supported types: script, object, sprite, room, sound, font, shader, path, timeline, tileset, animcurve, sequence, note, folder, particlesystem, extension, includedfile (datafiles)

Asset Reading (gm_read_asset)

Read the complete .yy JSON metadata for any asset by name or path.

Reference Search (gm_search_references)

Search for patterns across project files with:

• Scopes: all, gml, yy, scripts, objects, extensions, datafiles
• Modes: literal string or regex
• Options: case sensitivity, max results

Asset Graph (gm_get_asset_graph)

Build a dependency graph of assets with two modes:

• Shallow (fast): Parses .yy files for structural references (parent objects, sprites, etc.)
• Deep (complete): Also scans all GML code for runtime references like instance_create, sprite_index, audio_play_sound, etc.

Texture Groups (gm_texture_group_*)

Create, inspect, and edit .yyp TextureGroups, plus bulk-assign assets (sprites/fonts/tilesets/etc) via textureGroupId.

Read-only tools:

• gm_texture_group_list: list texture groups + available configs (desktop/android/ios/etc)
• gm_texture_group_read: read a single texture group entry
• gm_texture_group_members: list assets in a group (top-level + ConfigValues overrides)
• gm_texture_group_scan: report missing groups referenced + mismatches (top-level vs config override)

Destructive tools (all support dry_run=true):

• gm_texture_group_create: clone an existing template group (default: Default)
• gm_texture_group_update: patch fields on a group (optionally per config via ConfigValues)
• gm_texture_group_rename: rename a group and rewrite asset references
• gm_texture_group_delete: blocks by default if referenced unless reassign_to is provided
• gm_texture_group_assign: bulk-assign assets by explicit list or filters

Config scope defaults:

• Assignment updates an asset's top-level textureGroupId only when it is a dict (null is left as-is).
• If configs is omitted, assignment updates only existing ConfigValues entries; pass configs=[...] to create explicit overrides.

MCP Resources

Pre-built, cacheable project data for agents:

• gms://project/index: Complete project structure (assets, folders, room order, configs, audio/texture groups, IDE version)
• gms://project/asset-graph: Asset dependency graph
• gms://system/updates: Returns a human-readable message if a newer version of gms-mcp is available on PyPI or GitHub.

Update Notifier

Shared update status is available through the MCP surfaces below, and supported client hooks can surface a once-daily reminder:

• CLI: gms-mcp doctor is the standard local diagnostics command. gms-mcp doctor --notify remains the update-only startup hook path.
• Tool: gm_check_updates returns structured update info.
• Auto-check: gm_project_info includes a cached updates field.
• Resource: gms://system/updates provides a quick text status.
• Plain pip installs are not guaranteed a proactive reminder unless the client setup includes the bundled startup hook.

Common doctor entry points:

• gms-mcp doctor: quick package/update/project-detection check.
• gms-mcp doctor --project: adds environment, runtime, license, and dependency checks.
• gms-mcp doctor --full: adds runtime selection and bridge status.
• gms-mcp doctor --client codex|claude: validates active client config for the current workspace.
• gms-mcp doctor --project-root /path/to/project: targets an explicit GameMaker project directory.
• gms-mcp doctor --client codex --server-name gms-app: validates a non-default MCP server entry name.
• gms-mcp doctor --json: emits a stable JSON report with overall_status, exit_code, and checks.

Runtime Management

Runtime list/pin/verify operations are exposed as MCP tools:

• gm_runtime_list
• gm_runtime_pin
• gm_runtime_unpin
• gm_runtime_verify

The plain gms CLI has runner commands (gms run compile, gms run start, gms run stop, gms run status), but does not expose separate runtime-management subcommands.

Runner runtime labels:

• VM and GMS2 VM map to Igor VM builds.
• YYC and GMS2 YYC map to Igor YYC builds.
• GMRT and GMRT VM are recognized and rejected with a clear error until GameMaker documents the Igor command-line syntax for GMRT targets.

CLI usage

Run from a project directory (or pass --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