hi-godot/godot-ai

1. System shape: This repo is a two-process bridge between a live Godot editor and external MCP clients. The Godot-side plugin runs inside the editor, while the Python package exposes the MCP server over HTTP and forwards execution to the editor over WebSocket.

2. Primary request flow: An MCP client sends tool/resource requests to http://127.0.0.1:8000/mcp. The Python server accepts those requests, translates them into editor actions, and sends them through the WebSocket connection on the Godot side. The editor plugin then performs the actual work against Godot APIs such as EditorInterface, SceneTree, and resource/node/script APIs.

3. Godot plugin boundary: plugin/addons/godot_ai is the editor extension. Core entry points like plugin.gd, connection.gd, dispatcher.gd, and mcp_dock.gd manage plugin lifecycle, server connectivity, dispatching, and the dock UI. The dock is the user-facing control plane for server status, client setup, logs, and troubleshooting.

4. Python server boundary: src/godot_ai is the MCP-facing runtime. server.py, asgi.py, transport/websocket.py, and transport/origin_guard.py define the network layer; sessions/registry.py, runtime/direct.py, and orphan_reaper.py manage server/session lifecycle and cleanup. This side is responsible for request routing, guarding origins, and keeping the bridge healthy.

5. Tooling model: The repo is organized by Godot domain, not by UI pages. Under src/godot_ai/tools and src/godot_ai/handlers you get tool endpoints for scene, node, script, filesystem, project, editor, UI, audio, camera, animation, material, particles, signals, input maps, autoloads, and testing. The Python tools layer is the MCP contract; the handlers layer contains the actual operation logic and validation.

6. Resource model: src/godot_ai/resources exposes structured MCP resources for editor/project state such as scenes, scripts, nodes, classes, library data, editor state, and sessions. These are the read-oriented counterpart to tools and are used for discovery, inspection, and pagination-heavy queries.

7. Validation and safety: Several layers enforce safety before editor changes happen: middleware/* normalizes and validates inputs, protocol/* defines envelopes and errors, utils/path_validator.gd and related helpers guard file/path access, and origin_guard.py restricts inbound transport origins. This matters architecturally because the system is effectively remote-controlling an editor, not just calling local functions.

8. Client configuration subsystem: The plugin includes a large client-adaptation layer under plugin/addons/godot_ai/clients, with per-client strategies for Claude Code, Claude Desktop, Cursor, Zed, VS Code, Windsurf, Gemini CLI, etc. client_configurator.gd and the dock panels generate or rewrite the client-side MCP config so external assistants can connect to the local server without manual editing.

9. Observability and runtime support: plugin/addons/godot_ai/runtime, telemetry.gd, and the Python telemetry.py provide logging, structured diagnostics, and anonymous usage telemetry. Supporting utilities like server_lifecycle, server_version_check, update_manager, and uv_cache_cleanup exist because the plugin is responsible for starting, restarting, and recovering the embedded server process reliably.

10. Testing strategy: The repository is split between Python tests in tests/ and Godot integration coverage in test_project/. The test_project folder is a self-contained Godot app used to exercise plugin behavior, editor interactions, and GDScript-side runtime behavior, while tests/integration and tests/unit validate the Python server, transport, protocol, and safety contracts.

11. Build and release posture: The repo is packaged as a Godot addon plus a separately installed Python server. GitHub workflows, script/* helpers, and docs like packaging-distribution.md and testing-strategy.md indicate that release artifacts are validated for both the plugin layout under addons/godot_ai and the Python runtime versioning/compatibility expected by MCP clients.