# hi-godot/godot-ai architecture

> Architecture diagram of the GitHub repository hi-godot/godot-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hi-godot/godot-ai
- Repository: https://github.com/hi-godot/godot-ai
- Video tour (about a minute): https://gitdiagram.com/hi-godot/godot-ai/video

## Overview

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.

Main entry points: [`src/godot_ai/asgi.py`](https://github.com/hi-godot/godot-ai/blob/main/src/godot_ai/asgi.py) (ASGI app), [`src/godot_ai/server.py`](https://github.com/hi-godot/godot-ai/blob/main/src/godot_ai/server.py) (MCP server), [`src/godot_ai/transport`](https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/transport) (Transport), [`tests`](https://github.com/hi-godot/godot-ai/tree/main/tests) (Python tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_plugin["Godot plugin"]
  node_node_plugin_entry["Plugin entry<br/>gdscript addon entry<br/>[plugin.gd]"]
  node_node_plugin_conn["Connection<br/>ws lifecycle<br/>[connection.gd]"]
  node_node_plugin_dispatch["Dispatcher<br/>request router<br/>[dispatcher.gd]"]
  node_node_plugin_dock["MCP dock<br/>editor UI<br/>[mcp_dock.gd]"]
  node_node_plugin_clients["Client setup<br/>config adapters"]
  node_node_plugin_handlers["Editor handlers<br/>godot operations"]
  node_node_plugin_utils["Plugin utils<br/>safety/runtime support"]
  node_node_plugin_runtime["Plugin runtime<br/>logging/telemetry"]
end

subgraph group_group_python["Python server"]
  node_node_py_server["MCP server<br/>http/asgi server<br/>[server.py]"]
  node_node_py_asgi["ASGI app<br/>request front door<br/>[asgi.py]"]
  node_node_py_transport["Transport<br/>websocket guard"]
  node_node_py_sessions["Sessions<br/>session registry"]
  node_node_py_runtime["Runtime mode<br/>direct execution"]
  node_node_py_handlers["Tool handlers<br/>mcp operations"]
  node_node_py_tools["Tool catalog<br/>mcp contract"]
  node_node_py_resources["Resources<br/>read models"]
  node_node_py_middleware["Middleware<br/>validation layer"]
  node_node_py_protocol["Protocol<br/>envelope/errors"]
  node_node_py_godot_client["Godot client<br/>editor client"]
end

subgraph group_group_test["Testing"]
  node_node_tests_godot[("Test project<br/>godot integration app")]
  node_node_tests_py["Python tests<br/>pytest suites"]
end

node_node_plugin_entry -->|"initializes"| node_node_plugin_conn
node_node_plugin_entry -->|"creates UI"| node_node_plugin_dock
node_node_plugin_conn -->|"forwards actions"| node_node_plugin_dispatch
node_node_plugin_dispatch -->|"invokes"| node_node_plugin_handlers
node_node_plugin_handlers -->|"validates"| node_node_plugin_utils
node_node_plugin_dock -->|"configures clients"| node_node_plugin_clients
node_node_plugin_dock -->|"shows logs"| node_node_plugin_runtime
node_node_py_server -->|"serves"| node_node_py_asgi
node_node_py_asgi -->|"passes through"| node_node_py_middleware
node_node_py_middleware -->|"uses"| node_node_py_protocol
node_node_py_asgi -->|"advertises"| node_node_py_tools
node_node_py_asgi -->|"serves"| node_node_py_resources
node_node_py_tools -->|"binds to"| node_node_py_handlers
node_node_py_resources -->|"reads via"| node_node_py_handlers
node_node_py_server -->|"bridges over"| node_node_py_transport
node_node_py_transport -->|"connects"| node_node_py_godot_client
node_node_py_server -->|"tracks"| node_node_py_sessions
node_node_py_sessions -->|"coordinates"| node_node_py_runtime
node_node_py_runtime -->|"executes"| node_node_py_handlers
node_node_py_transport -->|"encodes"| node_node_py_protocol
node_node_tests_godot -->|"exercises"| node_node_plugin_entry
node_node_tests_py -->|"verifies"| node_node_py_server
node_node_tests_py -->|"checks"| node_node_py_transport
node_node_tests_py -->|"asserts"| node_node_py_protocol

click node_node_plugin_entry "https://github.com/hi-godot/godot-ai/blob/main/plugin/addons/godot_ai/plugin.gd"
click node_node_plugin_conn "https://github.com/hi-godot/godot-ai/blob/main/plugin/addons/godot_ai/connection.gd"
click node_node_plugin_dispatch "https://github.com/hi-godot/godot-ai/blob/main/plugin/addons/godot_ai/dispatcher.gd"
click node_node_plugin_dock "https://github.com/hi-godot/godot-ai/blob/main/plugin/addons/godot_ai/mcp_dock.gd"
click node_node_plugin_clients "https://github.com/hi-godot/godot-ai/tree/main/plugin/addons/godot_ai/clients"
click node_node_plugin_handlers "https://github.com/hi-godot/godot-ai/tree/main/plugin/addons/godot_ai/handlers"
click node_node_plugin_utils "https://github.com/hi-godot/godot-ai/tree/main/plugin/addons/godot_ai/utils"
click node_node_plugin_runtime "https://github.com/hi-godot/godot-ai/tree/main/plugin/addons/godot_ai/runtime"
click node_node_py_server "https://github.com/hi-godot/godot-ai/blob/main/src/godot_ai/server.py"
click node_node_py_asgi "https://github.com/hi-godot/godot-ai/blob/main/src/godot_ai/asgi.py"
click node_node_py_transport "https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/transport"
click node_node_py_sessions "https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/sessions"
click node_node_py_runtime "https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/runtime"
click node_node_py_handlers "https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/handlers"
click node_node_py_tools "https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/tools"
click node_node_py_resources "https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/resources"
click node_node_py_middleware "https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/middleware"
click node_node_py_protocol "https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/protocol"
click node_node_py_godot_client "https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/godot_client"
click node_node_tests_godot "https://github.com/hi-godot/godot-ai/tree/main/test_project"
click node_node_tests_py "https://github.com/hi-godot/godot-ai/tree/main/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_plugin_entry,node_node_plugin_conn,node_node_plugin_dispatch,node_node_plugin_dock,node_node_plugin_clients,node_node_plugin_handlers,node_node_plugin_utils,node_node_plugin_runtime toneBlue
class node_node_py_server,node_node_py_asgi,node_node_py_transport,node_node_py_sessions,node_node_py_runtime,node_node_py_handlers,node_node_py_tools,node_node_py_resources,node_node_py_middleware,node_node_py_protocol,node_node_py_godot_client toneAmber
class node_node_tests_godot,node_node_tests_py toneMint
```

## Components

### Godot plugin

Editor-side addon running inside the Godot editor.

- [Plugin entry](https://github.com/hi-godot/godot-ai/blob/main/plugin/addons/godot_ai/plugin.gd): gdscript addon entry · Registers the editor plugin and wires startup/shutdown. · `plugin/addons/godot_ai/plugin.gd`
- [Connection](https://github.com/hi-godot/godot-ai/blob/main/plugin/addons/godot_ai/connection.gd): ws lifecycle · Manages server connectivity and bridge state. · `plugin/addons/godot_ai/connection.gd`
- [Dispatcher](https://github.com/hi-godot/godot-ai/blob/main/plugin/addons/godot_ai/dispatcher.gd): request router · Routes incoming actions to the right editor-side handlers. · `plugin/addons/godot_ai/dispatcher.gd`
- [MCP dock](https://github.com/hi-godot/godot-ai/blob/main/plugin/addons/godot_ai/mcp_dock.gd): editor UI · Control panel for status, setup, logs, and troubleshooting. · `plugin/addons/godot_ai/mcp_dock.gd`
- [Client setup](https://github.com/hi-godot/godot-ai/tree/main/plugin/addons/godot_ai/clients): config adapters · Generates or rewrites MCP client configs for external assistants. · `plugin/addons/godot_ai/clients`
- [Editor handlers](https://github.com/hi-godot/godot-ai/tree/main/plugin/addons/godot_ai/handlers): godot operations · Domain handlers that execute scene, node, script, filesystem, and editor actions. · `plugin/addons/godot_ai/handlers`
- [Plugin utils](https://github.com/hi-godot/godot-ai/tree/main/plugin/addons/godot_ai/utils): safety/runtime support · Validation, path guards, lifecycle helpers, logging, updates, and serialization. · `plugin/addons/godot_ai/utils`
- [Plugin runtime](https://github.com/hi-godot/godot-ai/tree/main/plugin/addons/godot_ai/runtime): logging/telemetry · Runtime helpers and telemetry used while the addon is active. · `plugin/addons/godot_ai/runtime`

### Python server

MCP-facing runtime that bridges clients to the editor.

- [MCP server](https://github.com/hi-godot/godot-ai/blob/main/src/godot_ai/server.py): http/asgi server · Entry point for the Python-side MCP runtime. · `src/godot_ai/server.py`
- [ASGI app](https://github.com/hi-godot/godot-ai/blob/main/src/godot_ai/asgi.py): request front door · Exposes the HTTP surface that MCP clients call. · `src/godot_ai/asgi.py`
- [Transport](https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/transport): websocket guard · WebSocket bridge and origin filtering for editor connections. · `src/godot_ai/transport`
- [Sessions](https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/sessions): session registry · Tracks connected editors and server session lifecycle. · `src/godot_ai/sessions`
- [Runtime mode](https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/runtime): direct execution · Direct runtime path used to execute or forward work toward the editor. · `src/godot_ai/runtime`
- [Tool handlers](https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/handlers): mcp operations · Tool endpoints for scene, node, script, filesystem, project, UI, and domain-specific actions. · `src/godot_ai/handlers`
- [Tool catalog](https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/tools): mcp contract · Defines tool surfaces, pagination, domains, and meta-tool wiring. · `src/godot_ai/tools`
- [Resources](https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/resources): read models · Read-oriented MCP resources for scenes, scripts, nodes, project state, classes, and sessions. · `src/godot_ai/resources`
- [Middleware](https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/middleware): validation layer · Normalizes inputs, handles parameter coercion, and improves error reporting. · `src/godot_ai/middleware`
- [Protocol](https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/protocol): envelope/errors · Shared request/response envelope definitions and error taxonomy. · `src/godot_ai/protocol`
- [Godot client](https://github.com/hi-godot/godot-ai/tree/main/src/godot_ai/godot_client): editor client · Client bridge used by the server to talk to the live editor process. · `src/godot_ai/godot_client`

### Testing

Godot integration project and Python test suites.

- [Test project](https://github.com/hi-godot/godot-ai/tree/main/test_project): godot integration app · Self-contained Godot project used to exercise plugin behavior and editor interactions. · `test_project`
- [Python tests](https://github.com/hi-godot/godot-ai/tree/main/tests): pytest suites · Unit and integration coverage for server, transport, protocol, and safety contracts. · `tests`

## Connections

- Plugin entry → Connection: initializes · Plugin startup sets up bridge connectivity.
- Plugin entry → MCP dock: creates UI · Plugin installs the editor dock and control surfaces.
- Connection → Dispatcher: forwards actions · Connected requests are dispatched into editor operations.
- Dispatcher → Editor handlers: invokes · Dispatcher routes work to domain handlers.
- Editor handlers → Plugin utils: validates · Handlers rely on path and input guards before mutating state.
- MCP dock → Client setup: configures clients · Dock and configurator generate external MCP client setup.
- MCP dock → Plugin runtime: shows logs · UI exposes runtime diagnostics and telemetry state.
- MCP server → ASGI app: serves · Server hosts the HTTP entry point for MCP clients.
- ASGI app → Middleware: passes through · Incoming requests are normalized and validated.
- Middleware → Protocol: uses · Middleware relies on shared envelope and error definitions.
- ASGI app → Tool catalog: advertises · Tool definitions form the MCP contract surface.
- ASGI app → Resources: serves · Read-only resources are exposed to clients.
- Tool catalog → Tool handlers: binds to · Tool definitions map onto handler implementations.
- Resources → Tool handlers: reads via · Resource lookups reuse domain handlers and state access.
- MCP server → Transport: bridges over · Editor communication happens through transport layer websockets.
- Transport → Godot client: connects · Transport binds the remote editor client connection.
- MCP server → Sessions: tracks · Server keeps session registry and lifecycle state.
- Sessions → Runtime mode: coordinates · Session state drives direct runtime execution mode.
- Runtime mode → Tool handlers: executes · Runtime invokes the operational handlers.
- Transport → Protocol: encodes · Transport uses protocol envelopes and error handling.
- Test project → Plugin entry: exercises · Integration project validates addon lifecycle and editor behavior.
- Python tests → MCP server: verifies · Python suites cover server, transport, resources, and tools.
- Python tests → Transport: checks · Tests cover origin guard and websocket behavior.
- Python tests → Protocol: asserts · Tests validate protocol and error contracts.