DOCSEARCHbyAlgolia
Submit Docs

Glade MCP (Model Context Protocol)

repository·main·Indexed 41 days ago

https://github.com/glade-tool/glade-mcp

An MCP server that bridges AI clients like Cursor, Claude Code, and Windsurf to game engines including Unity and Godot. It allows AI agents to interact with the editor, manipulate scenes, edit scripts, and run gameplay verification loops. Features include a live play loop for Godot 4, automated scene construction, and a high-efficiency project orientation tool via the context/gather endpoint.

Tokens
20.2K
Snippets
70
Records
98
Agent score
47%

What's inside Glade MCP

  1. Compare GladeKit MCP with other MCP implementations

    main

    GladeKit MCP is a multi-engine Model Context Protocol (MCP) implementation designed for Unity and Godot. It distinguishes itself from other implementations (like unity-mcp or godot-mcp) through several key capabilities:

    • Multi-Engine Support: Automatically detects and manages both Unity and Godot from a single server.
    • Extensive Toolset: Provides hundreds of granular tools (275 for Unity, 115 for Godot) compared to the consolidated or limited toolsets of competitors.
    • Live Editor Integration: Uses HTTP (:8765) and WebSocket (:8766) for live editor sessions.
    • Gameplay Scaffolders: Offers one-call vetted templates for common game elements like controllers, enemies, projectiles, and save systems.
    • Advanced Verification Loop: Includes look_at_game_view screenshots, runtime-event streams, playability probes, and compile_scripts verification.
    • Sophisticated Script Editing: Supports outline/partial reads, anchor edits, and lexical scanning for find_references and rename_symbol.
    • Build & Export: Supports build_player and export_project for both engines.
    • Asset Pipeline: Includes a CC0 asset pipeline with license auditing.
    • Project Context: Uses GLADE.md and live prompts to understand render pipelines, input systems, and skill levels.
    • Semantic Search: Provides semantic script search via OpenAI embeddings (requires user-provided key).
    • Safety & Reliability: Features undo-registered edits, pre-mutation backups, overwrite guards, and per-session token authentication.
    • Testing: Includes extensive test suites (pytest, NUnit, GUT) and schema/bridge parity guards.

  2. Authenticate with the Godot Bridge

    main

    The bridge uses a file-based token system to prevent unauthorized browser access. At startup, the bridge generates a random token and writes it to <home>/.gladekit/godot-bridge-<port>.token.

    To authenticate, include this token in the JSON body of every request (except for the health endpoint). MCP servers, desktop apps, and the eval harness read this file automatically to provide the token.

  3. Security and Safety constraints of the Unity Bridge

    main

    The bridge implements several security measures to protect your project and local environment:

    • Network Isolation: Binds to the loopback address only and enforces localhost access control on every request.
    • Path Traversal Protection: Raw file endpoints reject any path traversal attempts that go outside the current Unity project directory.
    • Asset Import Safety: The import_asset tool validates resolved download hosts against a per-provider allowlist (HTTPS only) and requires licenseAcknowledged: true to proceed.
    • Play-mode Safety: To prevent project corruption, all mutating tools are prohibited from running while the Unity Editor is in Play mode.

  4. Use GLADE.md for permanent project context

    main

    You can provide permanent design intent, conventions, and constraints to the AI by creating a GLADE.md file in your Unity project root (the same directory as Assets/). The MCP server reads this file and injects its content into every request.

    Example GLADE.md content:

    # My Game

Genre: 3D platformer
Player: CharacterController, double jump enabled
Art style: pixel art, 16x16 sprites
Naming: PascalCase for scripts, snake_case for folders
    # My Game

Genre: 3D platformer
Player: CharacterController, double jump enabled
Art style: pixel art, 16x16 sprites
Naming: PascalCase for scripts, snake_case for folders

  5. How the GladeKit MCP Bridge works

    main

    The bridge acts as a local WebSocket server living inside the Godot 4 editor. It exposes a wide array of tools (over 115 in recent versions) that allow AI assistants (like Cursor, Claude Code, or Windsurf) to:

    • Read and Modify the Project: Access the scene tree, nodes, scripts, and resources.
    • Run Play Sessions: Use run_project to spawn a headless Godot subprocess, allowing the AI to observe runtime behavior and debug output without restarting the editor.
    • Automate Scene Construction: Use specialized scaffolders (e.g., create_2d_controller, create_main_menu) to build game components quickly.
    • Manage Signals: Connect, list, and disconnect signals editor-side.

    Key Architectural Features

    • Live Play Loop: Unlike competitors that require relaunching Godot for every tool call, this bridge maintains the editor session while running a separate subprocess for gameplay.
    • Safety Mechanisms: Includes pre-mutation file backups in <project>/.gladekit-backups/ and a readOnlyHint system to allow AI agents to auto-approve read-only queries.
    • Argument Normalization: The bridge automatically converts camelCase keys (like nodePath) to Godot's native snake_case before dispatching tools.

  6. How the GladeKit Godot Bridge architecture works

    main

    The bridge operates as a WebSocket server within Godot using TCPServer and WebSocketPeer.accept_stream().

    Key Architectural Details:

    • Threading: All tool dispatching occurs on the Godot editor main thread inside the _process() tick. This is necessary because Godot's scene-tree APIs are not thread-safe.
    • Latency: While the transport layer (WS polling) runs at ~200Hz, tool execution latency is gated by the editor's frame rate. If Godot is unfocused, the editor throttles the main loop (typically to ~20Hz), increasing tool latency to 50–100ms.
    • Concurrency: The server supports multiple concurrent peers, but tool execution is serialized through a single main-thread queue.
    • Hot Reload: The plugin handles _exit_tree() to close peers and stop the TCP server, allowing for clean re-binding when scripts are reloaded.

  7. How the MCP Eval Harness works

    main

    The harness simulates the full dispatch path without requiring a live LLM. It follows this flow:

    1. The Eval Client calls call_tool().
    2. The MCP Server receives the call, dispatches it, and sanitizes arguments.
    3. The MCP Server sends a POST /api/tools/execute request to the Mock Bridge.
    4. The Mock Bridge returns a JSON response (e.g., {"success": true, ...}).
    5. The MCP Server parses the result and returns a TextContent result to the Eval Client.
    6. The Eval Client asserts that the correct tools were called, parameters matched, and timing was within limits.

    Assertion Model

    Each MCPEvalCase can define:

    • required_tools: A list of tools that MUST be called.
    • any_of_tools: A list where at least one tool must be called.
    • forbidden_tools: A list of tools that MUST NOT be called.
    • param_assertions: Checks for parameter values (exact, contains, or approx).

  8. Understand the three test layers in GladeKit MCP

    main

    The testing strategy is divided into three distinct layers based on scope and speed:

    • Unit tests: Uses pytest to verify schema validity, registry logic, argument sanitization, and task filtering. These are fast (<5s).
    • Integration tests: Uses pytest with a mock HTTP server to test the full MCP→bridge round-trip, including meta-tools and resources. These take medium time (~10s).
    • E2E eval harness: Uses python -m eval.run to test tool dispatch through the MCP server against either a mock or a live Unity instance. This is highly configurable.

  9. Use GLADE.md for Project Context Injection

    main

    You can provide high-level project context (like genre, art style, or naming conventions) by creating a GLADE.md file in your Unity project root (the directory containing Assets/).

    Example GLADE.md content:

    # My Game

Genre: 3D platformer
Naming: snake_case for scripts

    GladeKit automatically injects this content into prompts. You can verify the server sees it by reading the unity://glade-md resource.

    # My Game

Genre: 3D platformer

  10. Unlock Cloud Intelligence features

    main

    Setting the GLADEKIT_API_KEY in your MCP configuration enables advanced cloud-powered features:

    • RAG Knowledge Base: Uses get_relevant_tools to query an engine-aware knowledge base for API corrections and error patterns.
    • Cross-session Persistent Memory: Allows remember_for_session to persist facts across different sessions.
    • Convention Extraction: Distills coding patterns (naming, architecture) from your project history to surface in future sessions.

    If the key is missing, the server degrades gracefully and all standard tools remain functional.

    {
  "mcpServers": {
    "gladekit-mcp": {
      "command": "uvx",
      "args": ["gladekit-mcp"],
      "env": {
        "GLADEKIT_API_KEY": "your-api-key"
      }
    }
  }
}

  11. Configure engine auto-detection

    main
    The Glade MCP server automatically probes ports :8765 (Unity) and :8766 (Godot) to expose the matching tool set. If you are running both editors simultaneously, you can force the server to use a specific engine by setting the GLADEKIT_MCP_FORCE_ENGINE environment variable to either unity or godot.

  12. Install uv for AI client connectivity

    main

    Before connecting your AI client, ensure uv is installed on your system:

    • Mac/Linux:
      curl -LsSf https://astral.sh/uv/install.sh | sh
    • Windows:
      powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
    curl -LsSf https://astral.sh/uv/install.sh | sh