@satelliteoflove/godot-mcp 2.3.0 → 2.4.1

package/README.md

@@ -1,33 +1,26 @@
-# @satelliteoflove/godot-mcp
+# godot-mcp
 
-MCP server for Godot Engine 4.5+, enabling AI assistants to interact with your Godot projects.
+An MCP server that gives Claude direct visibility into your Godot editor and running game. Instead of copy-pasting debug output or describing what you're seeing, Claude can observe it directly.
 
-## Features
+## Core Capabilities
 
-- **8 MCP tools** across 7 categories
-- **3 MCP resources** for reading scene trees, scripts, and project files
-- Screenshot capture from editor viewports and running games
-- Full animation support (query, playback, editing)
-- TileMapLayer and GridMap editing
-- Resource inspection for SpriteFrames, TileSets, Materials, and Textures
-- Debug output capture from running games
+- Live editor state - what scene is open, what's selected, which panel you're in
+- Runtime debug output from the running game
+- Viewport awareness - where the camera is pointed (2D and 3D)
+- Screenshots of the editor or running game
+- Scene tree and node properties at runtime
 
-## Installation
+## Design Goals
 
-```bash
-npx @satelliteoflove/godot-mcp
-```
-
-## Setup
+- **Observation over automation** - help Claude understand what's happening so it can help you solve problems
+- **Minimal token footprint** - more room for actual conversation
+- **Friction-free maintenance** - version mismatch detection and one-command updates
 
-1. Download the addon from [GitHub Releases](https://github.com/satelliteoflove/godot-mcp/releases)
-2. Extract to your project's `addons` directory
-3. Enable it in Project Settings > Plugins
-4. Configure your MCP client (see below)
+## Quick Start
 
-### Claude Desktop
+### 1. Configure Your AI Assistant
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+**Claude Desktop** - Add to config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
 ```json
 {
@@ -40,9 +33,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 }
 ```
 
-### Claude Code
-
-Add to `.mcp.json`:
+**Claude Code** - Add to `.mcp.json`:
 
 ```json
 {
@@ -55,9 +46,49 @@ Add to `.mcp.json`:
 }
 ```
 
-## Documentation
+### 2. Install the Godot Addon
+
+```bash
+npx @satelliteoflove/godot-mcp --install-addon /path/to/your/godot/project
+```
+
+Then enable the addon in Godot: Project Settings > Plugins > Godot MCP.
+
+### 3. Start Using
+
+Open your Godot project (with addon enabled), restart your AI assistant, and start building.
+
+**Version Sync:** The MCP server auto-updates via npx. If the addon version falls behind, use `project` tool with `addon_status` action to check compatibility, then re-run the install command to update.
 
-See the [GitHub repository](https://github.com/satelliteoflove/godot-mcp) for full documentation.
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `scene` | Manage scenes: open, save, or create scenes |
+| `node` | Manage scene nodes: get properties, find, create, update, delete, reparent, attach/detach scripts |
+| `editor` | Control the Godot editor: get state (includes viewport/camera info), manage selection, run/stop project, get debug output, get performance metrics, capture screenshots, set 2D viewport position/zoom |
+| `project` | Get project information and settings |
+| `animation` | Query, control, and edit animations |
+| `tilemap` | Query and edit TileMapLayer data: list layers, get info, get/set cells, convert coordinates |
+| `gridmap` | Query and edit GridMap data: list gridmaps, get info, get/set cells |
+| `resource` | Manage Godot resources: inspect Resource files by path |
+
+See [docs/](docs/) for detailed API reference, including the [Claude Code Setup Guide](docs/claude-code-setup.md).
+
+## Architecture
+
+```
+[AI Assistant] <--stdio--> [MCP Server] <--WebSocket--> [Godot Addon]
+```
+
+## Development
+
+```bash
+cd server
+npm install && npm run build
+npm test
+npm run generate-docs
+```
 
 ## Requirements
 

package/addon/command_router.gd

@@ -0,0 +1,39 @@
+@tool
+extends RefCounted
+class_name MCPCommandRouter
+
+var _commands: Dictionary = {}
+var _handlers: Array[MCPBaseCommand] = []
+
+
+func setup(plugin: EditorPlugin) -> void:
+	_register_handler(MCPSystemCommands.new(), plugin)
+	_register_handler(MCPSceneCommands.new(), plugin)
+	_register_handler(MCPNodeCommands.new(), plugin)
+	_register_handler(MCPScriptCommands.new(), plugin)
+	_register_handler(MCPSelectionCommands.new(), plugin)
+	_register_handler(MCPProjectCommands.new(), plugin)
+	_register_handler(MCPFileCommands.new(), plugin)
+	_register_handler(MCPDebugCommands.new(), plugin)
+	_register_handler(MCPScreenshotCommands.new(), plugin)
+	_register_handler(MCPAnimationCommands.new(), plugin)
+	_register_handler(MCPTilemapCommands.new(), plugin)
+	_register_handler(MCPResourceCommands.new(), plugin)
+	_register_handler(MCPScene3DCommands.new(), plugin)
+
+
+func _register_handler(handler: MCPBaseCommand, plugin: EditorPlugin) -> void:
+	handler.setup(plugin)
+	_handlers.append(handler)
+	var cmds := handler.get_commands()
+	for cmd_name in cmds:
+		_commands[cmd_name] = cmds[cmd_name]
+
+
+func handle_command(command: String, params: Dictionary):
+	if not _commands.has(command):
+		return MCPUtils.error("UNKNOWN_COMMAND", "Unknown command: %s" % command)
+
+	var callable: Callable = _commands[command]
+	var result = await callable.call(params)
+	return result

package/addon/command_router.gd.uid

@@ -0,0 +1 @@
+uid://cwxw8hh1su5cg