@satelliteoflove/godot-mcp 3.21.1 → 3.23.0

package/README.md

@@ -1,20 +1,55 @@
 # godot-mcp
 
-MCP server that connects Claude to your Godot editor. Less copy-paste, more creating.
+[![npm version](https://img.shields.io/npm/v/%40satelliteoflove%2Fgodot-mcp?logo=npm&color=cb3837)](https://www.npmjs.com/package/@satelliteoflove/godot-mcp)
+[![CI](https://github.com/satelliteoflove/godot-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/satelliteoflove/godot-mcp/actions/workflows/ci.yml)
+[![Godot 4.5+](https://img.shields.io/badge/Godot-4.5%2B-478cbf?logo=godotengine&logoColor=white)](https://godotengine.org)
+[![Node 20+](https://img.shields.io/badge/Node-20%2B-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/satelliteoflove/godot-mcp/blob/main/LICENSE)
 
-## Why This Exists
+Give your AI assistant eyes and hands in the Godot editor — and a running game it can actually playtest.
 
-Using AI assistants for game dev means a lot of back-and-forth: copying error messages, describing what's on screen, pasting debug output, manually applying suggested changes. It works, but it's tedious.
+<!-- HERO PLACEHOLDER: short demo GIF goes here (agent running the game, stepping time, reading state). Use an absolute raw.githubusercontent.com URL so it also renders on npm. -->
 
-This MCP gives Claude direct access to your Godot editor. It can see your scene tree, capture screenshots, read errors, and make changes directly. You stay focused on the creative work while the mechanical relay disappears. Faster iterations, less busywork, more time building the game you actually want to make.
+## Why this one?
+
+There are a few Godot MCP servers out there, and most can open a scene and poke at nodes. This one is built around a harder problem: **letting an agent verify its own work.** Run the game, drive it like a player, observe what actually happened, and prove the change did what it claimed — without you ferrying screenshots and error logs back and forth.
+
+The pieces that make that possible, and that you won't find elsewhere:
+
+- **Deterministic playtesting.** Freeze the game clock, step exact slices of game time (or step *until a condition holds*), with inputs riding inside the window. Observation never races the game.
+- **Cheap observation.** Live entity state — positions, velocities, animation state, your own custom data — as structured JSON. Most "what's happening on screen?" questions get answered without spending vision tokens on a screenshot.
+- **Real input.** Named actions with analog strength, joypad buttons and stick vectors, raw keys with modifier combos, relative mouse-look, text typing. Sequences run with precise timing and can prove they changed game state.
+- **Scenario setup.** Run GDScript inside the running game: grant the weapon, skip to wave 3, spawn a test bot — no debug hooks baked into your game code.
+
+Here's what that looks like when an agent tests a boss fight:
+
+```text
+godot_editor        run frozen=true           # boot with game time frozen at frame 0
+godot_exec          GameState.wave = 3        # set up the scenario worth testing
+godot_game_time     step_until "tree.get_nodes_in_group('boss').size() >= 1"
+godot_runtime_state digest                    # exact positions and state — no pixels, no guessing
+godot_game_time     step 500ms + dodge input  # play the moment that matters
+godot_editor        screenshot_game           # and a screenshot when it's actually worth the tokens
+```
+
+Less copy-paste, more creating.
 
 ## Quick Start
 
 ### 1. Configure your AI assistant
 
-Add godot-mcp to your MCP client. See the [Installation Guide](INSTALL.md) for config examples (Claude Desktop, Claude Code, VSCode/Copilot, and more).
+Add godot-mcp to your MCP client. See the [Installation Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/INSTALL.md) for config examples (Claude Desktop, Claude Code, VSCode/Copilot, and more). The short version:
 
-While you're at it, add [minimal-godot-mcp](https://github.com/ryanmazzolini/minimal-godot-mcp) too — it's a complementary server that covers static GDScript diagnostics and the running game's console output. See [Works Well With](#works-well-with).
+```json
+{
+  "mcpServers": {
+    "godot-mcp": {
+      "command": "npx",
+      "args": ["-y", "@satelliteoflove/godot-mcp"]
+    }
+  }
+}
+```
 
 ### 2. Install the Godot addon
 
@@ -22,76 +57,84 @@ While you're at it, add [minimal-godot-mcp](https://github.com/ryanmazzolini/min
 npx @satelliteoflove/godot-mcp --install-addon /path/to/your/godot/project
 ```
 
-Enable in Godot: **Project Settings > Plugins > Godot MCP**
+Enable it in Godot: **Project > Project Settings > Plugins > Godot MCP**
 
-### 3. Go
+### 3. Start building
 
-Open your Godot project, restart your AI assistant, and start building.
+Open your Godot project, restart your AI assistant, and start building. If anything refuses to connect, the [Troubleshooting Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/troubleshooting.md) has you covered.
 
-## What Claude Can Do
+## What's in the box
 
-- **See** your editor, scenes, running game, editor errors, and performance
-- **Inspect** nodes, resources, animations, tilemaps, 3D spatial data
-- **Modify** scenes, nodes, scripts, animations, tilemaps directly
-- **Test** by running the game and injecting input
-- **Learn** by fetching Godot docs on demand
+15 tools, ~90 actions, 3 MCP resources. Full API docs in the [Tools Reference](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/tools/README.md).
 
-## Works Well With
+| Tool | What it does |
+|------|--------------|
+| `godot_scene` | Open, save, and create scenes |
+| `godot_node` | Create, update, delete, and reparent nodes; attach scripts; connect signals |
+| `godot_editor` | Editor state, selection, run/stop/restart, screenshots, editor error log, 2D viewport control |
+| `godot_project` | Project info and settings |
+| `godot_animation` | Query, play, and edit animations down to individual tracks and keyframes |
+| `godot_tilemap` / `godot_gridmap` | Read and edit TileMapLayer and GridMap cells |
+| `godot_resource` | Inspect resources with type-aware output: SpriteFrames, TileSet, Materials, Textures |
+| `godot_scene3d` | 3D transforms, bounding boxes, and visibility for spatial reasoning |
+| `godot_docs` | Fetch Godot documentation as clean markdown, version-matched to your editor |
+| `godot_input` | Inject input into the running game: actions, joypad, raw keys, mouse-look, text |
+| `godot_profiler` | Metric snapshots and per-frame time series with spike detection |
+| `godot_runtime_state` | Live game state as JSON: one-shot digests, watch windows, signal timelines |
+| `godot_game_time` | Freeze, step, and step-until on the game clock — deterministic observation |
+| `godot_exec` | Run GDScript inside the running game for test scenario setup |
 
-[minimal-godot-mcp](https://github.com/ryanmazzolini/minimal-godot-mcp) by [@ryanmazzolini](https://github.com/ryanmazzolini) is another MCP server for Godot, and it's worth running alongside this one. This server drives the editor through an addon — scene and node manipulation, running the game, input injection, runtime state, screenshots, and editor-side errors (`@tool`, import, and addon failures). minimal-godot-mcp needs no addon and provides exactly the functionality this server does not implement: LSP diagnostics for fast static `.gd` checking, and the running game's console output and stderr over DAP.
+A note on shape: this kit deliberately stays at 15 tools rather than 90. Related operations live as actions inside one tool, so your agent's context isn't flooded with tool definitions it won't use.
 
-Neither duplicates the other, and they don't conflict. Install both and you get static analysis and the live game console alongside full editor and runtime control.
+## Things to ask for
 
-**One godot-mcp client at a time, though.** A Godot editor bridge serves a single godot-mcp connection. If a second godot-mcp client connects - for example, a subagent that inherited the same MCP config - it is rejected while the first is active rather than displacing it, so the original session keeps working. The second client retries and connects automatically once the first disconnects. A client that crashes without closing its socket is taken over after a short idle timeout, so a dead session never permanently blocks new connections.
+A feel for what an agent can do with this, in plain prompts:
 
-## Documentation
+- *"Run the game and screenshot the title screen. Does the layout survive 1280x720?"*
+- *"The player can clip through the east wall. Reproduce it, then check the collision shapes and tell me why."*
+- *"Step the game until the second wave spawns and give me every enemy's position and velocity."*
+- *"Hold the left stick at half deflection for two seconds — does the walk animation blend correctly?"*
+- *"Profile ten seconds of gameplay and find what's causing the frame spikes."*
+- *"Add a hit-flash animation to the Player: modulate to red and back over 0.2 seconds."*
 
-- [Installation Guide](INSTALL.md) - MCP client configs for Claude Desktop, Claude Code, VSCode/Copilot, and more
-- [Claude Code Setup Guide](../docs/claude-code-setup.md) - CLAUDE.md template for Godot projects
-- [Runtime State Guide](../docs/runtime-state-guide.md) - Expose game state to agents via the `mcp_watch` group and `_mcp_state()`
-- [Tools Reference](../docs/tools/README.md) - All 12 tools with full API docs
-- [Resources Reference](../docs/resources.md) - MCP resources for reading project data
-- [Contributing](../CONTRIBUTING.md) - Dev setup, adding tools, release process
-- [Changelog](CHANGELOG.md) - Release history
+For richer runtime observation, add key nodes to the `mcp_watch` group or give them a `_mcp_state()` method — see the [Runtime State Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/runtime-state-guide.md).
 
-## Architecture
+## How it works
 
+```text
+┌─────────────────┐   stdio    ┌─────────────────┐  WebSocket   ┌──────────────────┐  debugger   ┌──────────────┐
+│   MCP client    │ ◄────────► │  godot-mcp      │ ◄──────────► │  Bridge addon    │ ◄─────────► │ Running game │
+│ (Claude, etc.)  │            │  server (Node)  │   :6550      │  (Godot editor)  │    wire     │  (autoload)  │
+└─────────────────┘            └─────────────────┘              └──────────────────┘             └──────────────┘
 ```
-[Claude/AI Assistant/MCP Client] <--stdio--> [MCP Server] <--WebSocket:6550--> [Godot MCP Bridge Addon]
-```
-
-WSL2 is supported (auto-detection, host IP discovery, configurable bind modes). See the [Installation Guide](INSTALL.md#wsl-support) for setup details.
-
-## CLI smoke test (paste-ready JSON-RPC)
 
-If you run the server manually via CLI (for example: `npx -y @satelliteoflove/godot-mcp`), you can paste these **stdio JSON-RPC frames** to verify it responds and can reach Godot:
+The server talks to an editor addon over a local WebSocket; the addon reaches into the running game over Godot's own debugger protocol, so the game process needs no extra ports or setup. The addon binds to `127.0.0.1` by default. WSL2 is fully supported (auto-detection, host IP discovery, configurable bind modes) — see the [Installation Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/INSTALL.md#wsl-support).
 
-1) Write in CLI
+Curious about connection lifecycles, the single-client policy, or how frozen-time stepping works under the hood? The [Architecture Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/architecture.md) goes deep.
 
-```json
-{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli-test","version":"0"}}}
-```
+## Works well with minimal-godot-mcp
 
-2) Response
+[minimal-godot-mcp](https://github.com/ryanmazzolini/minimal-godot-mcp) by [@ryanmazzolini](https://github.com/ryanmazzolini) covers exactly what this server doesn't: LSP diagnostics for fast static GDScript checking, and the running game's console output over DAP. This server covers everything that needs an editor bridge. No overlap, no conflict — run both, and your agent gets static analysis and the game console alongside full editor and runtime control.
 
-```json
-{"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{},"resources":{},"logging":{}},"serverInfo":{"name":"godot-mcp","version":"2.11.0"}},"jsonrpc":"2.0","id":1}
-```
+One caveat: a Godot editor serves a single godot-mcp client at a time. Extra clients (a subagent inheriting your MCP config, say) wait their turn rather than hijacking your session — details in [Troubleshooting](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/troubleshooting.md#one-client-at-a-time).
 
-3) Call a tool
-
-```json
-{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"godot_editor","arguments":{"action":"get_state"}}}
-```
+## Documentation
 
-4) Response
+- [Installation Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/INSTALL.md) — MCP client configs for Claude Desktop, Claude Code, VSCode/Copilot, and more
+- [Troubleshooting](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/troubleshooting.md) — connection checklist, CLI smoke test, common fixes
+- [Claude Code Setup Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/claude-code-setup.md) — CLAUDE.md template for Godot projects
+- [Runtime State Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/runtime-state-guide.md) — expose game state to agents via `mcp_watch` and `_mcp_state()`
+- [Tools Reference](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/tools/README.md) — all 15 tools with full API docs
+- [Resources Reference](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/resources.md) — MCP resources for reading project data
+- [Architecture Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/architecture.md) — how the server, addon, and game bridge fit together
+- [Contributing](https://github.com/satelliteoflove/godot-mcp/blob/main/CONTRIBUTING.md) — dev setup, adding tools, release process
+- [Changelog](https://github.com/satelliteoflove/godot-mcp/blob/main/server/CHANGELOG.md) — release history
 
-```json
-{"result":{"content":[{"type":"text","text":"{\n  \"current_scene\": null,\n  \"godot_version\": \"4.5.1-stable (official)\",\n  \"is_playing\": false,\n  \"main_screen\": \"unknown\",\n  \"open_scenes\": []\n}"}]},"jsonrpc":"2.0","id":2}
-```
+## Requirements
 
-Tip: If you enabled **Port override** in the Godot MCP panel, start the server with matching env vars (or export as environment variable):
-`GODOT_HOST=... GODOT_PORT=... npm run start` or `GODOT_HOST=... GODOT_PORT=... npx -y @satelliteoflove/godot-mcp`
+- **Godot 4.5+** (the addon uses the Logger class introduced in 4.5)
+- **Node.js 20+**
+- Any MCP client that speaks stdio
 
 ## Development
 
@@ -102,11 +145,8 @@ npm test
 npm run generate-docs
 ```
 
-## Requirements
-
-- Node.js 20+
-- Godot 4.5+
+Contributions welcome — this project favors tools that solve real, time-wasting problems. Read [CONTRIBUTING.md](https://github.com/satelliteoflove/godot-mcp/blob/main/CONTRIBUTING.md) before building something big, or open an issue and we'll figure out the right shape together.
 
 ## License
 
-MIT
+[MIT](https://github.com/satelliteoflove/godot-mcp/blob/main/LICENSE)

package/addon/command_router.gd

@@ -24,6 +24,7 @@ func setup(plugin: EditorPlugin) -> void:
 	_register_handler(MCPRuntimeStateCommands.new(), plugin)
 	_register_handler(MCPGameTimeCommands.new(), plugin)
 	_register_handler(MCPExecCommands.new(), plugin)
+	_register_handler(MCPMeshCommands.new(), plugin)
 
 
 func _register_handler(handler: MCPBaseCommand, plugin: EditorPlugin) -> void:

package/addon/commands/mesh_commands.gd

@@ -0,0 +1,52 @@
+@tool
+extends MCPBaseCommand
+class_name MCPMeshCommands
+## Relays mesh-integrity commands to the running game's bridge.
+
+# Full validation walks every ArrayMesh surface — generous timeout for big scenes.
+const VALIDATE_TIMEOUT := 20.0
+
+var _last_error: Dictionary = {}
+
+
+func get_commands() -> Dictionary:
+	return {
+		"validate_meshes": validate_meshes,
+	}
+
+
+func validate_meshes(params: Dictionary) -> Dictionary:
+	var result = await _send_and_wait("validate_meshes", [params], VALIDATE_TIMEOUT)
+	if result == null:
+		return _last_error
+	if result is Dictionary:
+		return _success(result)
+	return _success({"data": result})
+
+
+func _send_and_wait(msg_type: String, args: Array, timeout: float):
+	if not EditorInterface.is_playing_scene():
+		_last_error = _error("NOT_RUNNING", "No game is currently running")
+		return null
+
+	var debugger_plugin = _plugin.get_debugger_plugin() if _plugin else null
+	if debugger_plugin == null or not debugger_plugin.has_active_session():
+		_last_error = _error("NO_SESSION", "No active debug session")
+		return null
+
+	var sent: bool = debugger_plugin.send_game_message(msg_type, args)
+	if not sent:
+		_last_error = _error("SEND_FAILED", "Failed to send message to game")
+		return null
+
+	var start_time := Time.get_ticks_msec()
+	while not debugger_plugin.has_response(msg_type):
+		await Engine.get_main_loop().process_frame
+		if (Time.get_ticks_msec() - start_time) / 1000.0 > timeout:
+			debugger_plugin.clear_response(msg_type)
+			_last_error = _error("TIMEOUT", "Timed out waiting for %s response" % msg_type)
+			return null
+
+	var response = debugger_plugin.get_response(msg_type)
+	debugger_plugin.clear_response(msg_type)
+	return response

package/addon/commands/mesh_commands.gd.uid

@@ -0,0 +1 @@
+uid://60lww3uge36h

package/addon/commands/screenshot_commands.gd

@@ -50,11 +50,18 @@ func capture_game_screenshot(params: Dictionary) -> Dictionary:
 func _on_screenshot_received(success: bool, image_base64: String, width: int, height: int, error: String) -> void:
 	_screenshot_pending = false
 	if success:
-		_screenshot_result = _success({
+		var payload := {
 			"image_base64": image_base64,
 			"width": width,
 			"height": height
-		})
+		}
+		# Mesh-integrity warnings ride the same game message (no extra
+		# round-trip, no version-skew timeout); pass them through so the
+		# server can attach the advisory to the image.
+		var dp = _plugin.get_debugger_plugin() if _plugin else null
+		if dp != null and not (dp.last_screenshot_warnings as Array).is_empty():
+			payload["mesh_warnings"] = dp.last_screenshot_warnings
+		_screenshot_result = _success(payload)
 	else:
 		_screenshot_result = _error("CAPTURE_FAILED", error)
 

package/addon/core/mcp_debugger_plugin.gd

@@ -19,6 +19,10 @@ var _active_session_id: int = -1
 # has_active_session() alone is not enough to know input will land (#241).
 var _bridge_ready: bool = false
 var _pending_screenshot: bool = false
+# Mesh-integrity warnings that rode along with the last screenshot result
+# (element 6 of screenshot_result; empty for bridges that predate it). Held
+# here instead of widening the screenshot_received signal signature.
+var last_screenshot_warnings: Array = []
 var _pending_debug_output: bool = false
 var _pending_performance_metrics: bool = false
 var _pending_find_nodes: bool = false
@@ -151,6 +155,7 @@ func _handle_screenshot_result(data: Array) -> void:
 	var width: int = data[2]
 	var height: int = data[3]
 	var error: String = data[4]
+	last_screenshot_warnings = data[5] if data.size() > 5 and data[5] is Array else []
 	screenshot_received.emit(success, image_base64, width, height, error)
 
 

package/addon/game_bridge/mcp_game_bridge.gd

@@ -3,6 +3,7 @@ class_name MCPGameBridge
 
 const DEFAULT_MAX_WIDTH := 1024
 const Onscreen := preload("onscreen.gd")
+const MeshValidator := preload("mesh_validator.gd")
 
 # Cap on frames waited for the main scene to appear before announcing ready
 # anyway. The scene is normally added within a frame or two of the bridge
@@ -18,6 +19,17 @@ var _sampler: MCPRuntimeStateSampler
 # announcement against firing twice and lets the headless test observe it.
 var _ready_announced := false
 
+# On-scene-load mesh-integrity sniff. Corrupt procedural meshes render with no
+# error anywhere (inside-out winding, dropped triangles), so the warning must
+# come TO the agent: the server appends these one-liners to screenshot results
+# — the moment the agent looks at the game is the moment a wrong-looking render
+# becomes actionable. Full diagnosis lives in the validate_meshes command.
+const SNIFF_DELAY_FRAMES := 30  # let _ready-time procedural level builds finish
+const SNIFF_MAX_WARNINGS := 8
+var _mesh_warnings: Array[String] = []
+var _sniff_scene_id: int = 0
+var _sniff_countdown: int = -1
+
 
 func _ready() -> void:
 	# The bridge must keep processing while the scene tree is paused. Input
@@ -95,6 +107,52 @@ func _emit_bridge_ready(scene_path: String) -> void:
 func _process(delta: float) -> void:
 	_game_time_process(delta)
 	_sequence_process(delta)
+	_mesh_sniff_process()
+
+
+func _mesh_sniff_process() -> void:
+	# The autoload ships in exports and _process runs even when _ready bailed
+	# out early — without this gate, non-debug runs (including shipped games)
+	# would pay full mesh-array copies on every scene load for a result
+	# nothing consumes.
+	if not EngineDebugger.is_active():
+		return
+	var tree := get_tree()
+	if tree == null or tree.current_scene == null:
+		return
+	var sid := tree.current_scene.get_instance_id()
+	if sid != _sniff_scene_id:
+		_sniff_scene_id = sid
+		_sniff_countdown = SNIFF_DELAY_FRAMES
+	if _sniff_countdown > 0:
+		_sniff_countdown -= 1
+		if _sniff_countdown == 0:
+			_run_mesh_sniff(tree.current_scene)
+
+
+func _run_mesh_sniff(scene_root: Node) -> void:
+	_mesh_warnings.clear()
+	var stack: Array[Node] = [scene_root]
+	while not stack.is_empty():
+		var n: Node = stack.pop_back()
+		for child in n.get_children():
+			stack.push_back(child)
+		for w in MeshValidator.sniff(n):
+			_mesh_warnings.append(w)
+			if _mesh_warnings.size() >= SNIFF_MAX_WARNINGS:
+				return
+
+
+func _handle_validate_meshes(data: Array) -> void:
+	var params: Dictionary = data[0] if data.size() > 0 and data[0] is Dictionary else {}
+	var max_findings: int = params.get("max_findings", 25)
+	var tree := get_tree()
+	var result: Dictionary
+	if tree == null or tree.current_scene == null:
+		result = {"checked_meshes": 0, "checked_surfaces": 0, "total_findings": 0, "findings": [], "note": "no current scene"}
+	else:
+		result = MeshValidator.validate(tree.current_scene, max_findings)
+	EngineDebugger.send_message("godot_mcp:game_response", ["validate_meshes", result])
 
 
 # Processing is needed by three independent features; only switch it off when
@@ -415,6 +473,9 @@ func _on_debugger_message(message: String, data: Array) -> bool:
 		"exec_clear":
 			_handle_exec_clear(data)
 			return true
+		"validate_meshes":
+			_handle_validate_meshes(data)
+			return true
 	return false
 
 
@@ -442,12 +503,17 @@ func _capture_and_send_screenshot(max_width: int) -> void:
 		image.resize(max_width, new_height, Image.INTERPOLATE_LANCZOS)
 	var png_buffer := image.save_png_to_buffer()
 	var base64 := Marshalls.raw_to_base64(png_buffer)
+	# Element 6 piggybacks the scene's cached mesh-integrity warnings: the
+	# moment the agent LOOKS at a wrong-looking render is when they're
+	# actionable, and riding the same message costs no extra round-trip and
+	# cannot time out on version skew (older receivers ignore the element).
 	EngineDebugger.send_message("godot_mcp:screenshot_result", [
 		true,
 		base64,
 		image.get_width(),
 		image.get_height(),
-		""
+		"",
+		_mesh_warnings.duplicate()
 	])