@baixfeng/godot-mcp-cli 1.0.11

package/README.md

@@ -0,0 +1,187 @@
+# Godot MCP CLI
+
+A Command Line Interface (CLI) for AI assistants to interact with Godot Engine, built on the Model Context Protocol (MCP). The CLI is the recommended way to use this tool as it saves context tokens compared to direct MCP integration.
+
+[![npm version](https://img.shields.io/npm/v/godot-mcp-cli.svg)](https://www.npmjs.com/package/godot-mcp-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## When to Use What
+
+| Method | Best For | Token Usage |
+|--------|----------|-------------|
+| **CLI** (recommended) | AI coding assistants, scripting, automation | Low - only tool output in context |
+| **MCP** | Direct MCP client integration | High - full protocol in context |
+
+## Features
+
+### Core Functionality
+- **Full Godot Project Access**: AI assistants can access and modify scripts, scenes, nodes, and project resources
+- **Flexible Scene Inspection**: Retrieve hierarchy with `get_editor_scene_structure`, including properties and scripts
+- **Runtime Scene Inspection**: Snapshot live scene tree from running games with `get_runtime_scene_structure`
+- **Runtime Expression Evaluation**: Execute expressions in live games using `evaluate_runtime`
+- **Dynamic Script Access**: Read scripts via `godot://script/{path}` and metadata via `godot://script/{path}/metadata`
+- **Script Editing Tools**: Create, edit, or template scripts directly through MCP commands
+- **Node Management**: Create, remove, list, and inspect nodes with automatic path normalization
+- **Scene Operations**: Create, delete, open, and save scenes; query project info and current scene state
+- **Asset Management**: List assets by type and enumerate project files
+- **Project Reload**: Restart editor, reload scenes, or rescan filesystem for external changes
+- **Debug Output Access**: Snapshot logs with `get_debug_output` or tail them live via `stream_debug_output`
+- **Stack Trace Capture**: Pull the editor's Stack Trace text or grab structured frames via `get_stack_trace_panel` / `get_stack_frames_panel`
+- **Editor Automation**: Execute GDScript in editor context via `execute_editor_script`
+
+### **Debugger Integration**
+- **Breakpoint Management**: Set, remove, and list breakpoints across scripts with `debugger_set_breakpoint`
+- **Execution Control**: Pause, resume, and step through code with `debugger_pause_execution`, `debugger_step_over`
+- **Real-time Events**: Live notifications for breakpoint hits and execution changes
+- **Call Stack Inspection**: Access current call stack and frame information with `debugger_get_call_stack`
+- **Session Management**: Support for multiple debug sessions
+- **Runtime Debugging**: Full integration with Godot's debugging system
+- **Event-driven Architecture**: Receive breakpoint hits and execution state changes in real-time
+
+### **Input Simulation**
+- **Action Simulation**: Press, release, and tap input actions (`simulate_action_press`, `simulate_action_tap`)
+- **Mouse Control**: Click, move, and drag operations (`simulate_mouse_click`, `simulate_drag`)
+- **Keyboard Input**: Simulate key presses with modifier support (`simulate_key_press`)
+- **Input Sequences**: Execute complex input combos with precise timing (`simulate_input_sequence`)
+- **Action Discovery**: List all available input actions in the project (`get_input_actions`)
+
+## Installation
+
+### Option 1: Install via npm (Recommended)
+
+```bash
+npm install -g godot-mcp-cli
+```
+
+### Option 2: Build from Source
+
+```bash
+git clone https://github.com/nguyenchiencong/godot-mcp-cli.git
+cd godot-mcp-cli/server
+npm install
+npm run build
+npm link
+```
+
+## Quick Setup
+
+### 1. Install the Addon to Your Godot Project
+
+```bash
+godot-mcp install-addon "path/to/your/project"
+```
+
+Or manually copy the `addons/godot_mcp` folder to your Godot project's `addons` directory.
+
+### 2. Enable the Plugin in Godot
+
+1. Open your project in Godot
+2. Go to Project > Project Settings > Plugins
+3. Enable the "Godot MCP" plugin
+
+## Using the CLI (Recommended)
+
+The CLI is the most efficient way for AI assistants to interact with Godot. It consumes fewer tokens than the MCP protocol.
+
+### Basic Commands
+
+```bash
+# List all available tools
+godot-mcp --list-tools
+
+# Get help for a specific tool
+godot-mcp --help get_debug_output
+
+# Execute tools
+godot-mcp get_debug_output
+godot-mcp get_project_info
+godot-mcp run_project
+
+# With arguments
+godot-mcp debugger_set_breakpoint --script-path res://test_debugger.gd --line 42
+godot-mcp simulate_action_tap --action ui_accept
+godot-mcp simulate_mouse_click --x 400 --y 300
+```
+
+### CLI Examples
+
+```bash
+# Scene and node operations
+godot-mcp get_current_scene
+godot-mcp get_editor_scene_structure --include-properties true
+godot-mcp list_nodes --parent-path "."
+
+# Debugging
+godot-mcp run_project
+godot-mcp debugger_get_current_state
+godot-mcp debugger_pause_execution
+godot-mcp debugger_resume_execution
+
+# Input simulation (requires running game)
+godot-mcp get_input_actions
+godot-mcp simulate_action_tap --action "ui_accept"
+godot-mcp simulate_key_press --key "SPACE"
+
+# Reload operations
+godot-mcp rescan_filesystem
+godot-mcp reload_scene
+godot-mcp reload_project
+```
+
+For more CLI options, see the [CLI Documentation](docs/cli.md).
+
+## Using the MCP Protocol
+
+For direct MCP client integration, add this configuration:
+
+### STDIO Transport (after npm install -g)
+```json
+{
+  "mcpServers": {
+    "godot-mcp": {
+      "command": "godot-mcp",
+      "env": { "MCP_TRANSPORT": "stdio" }
+    }
+  }
+}
+```
+
+### STDIO Transport (from source)
+```json
+{
+  "mcpServers": {
+    "godot-mcp": {
+      "command": "node",
+      "args": ["path/to/godot-mcp-cli/server/dist/index.js"],
+      "env": { "MCP_TRANSPORT": "stdio" }
+    }
+  }
+}
+```
+
+### SSE Transport
+```json
+{
+  "mcpServers": {
+    "godot-mcp": {
+      "url": "http://localhost:8083/sse"
+    }
+  }
+}
+```
+
+## Documentation
+
+- [Installation Guide](docs/installation-guide.md)
+- [Command Reference](docs/command-reference.md)
+- [Architecture](docs/architecture.md)
+- [CLI Usage](docs/cli.md)
+- [Tool Prompt Guide](docs/tool-prompt-guide.md)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request to the [GitHub repository](https://github.com/nguyenchiencong/godot-mcp-cli).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/addons/godot_mcp/command_handler.gd

@@ -0,0 +1,161 @@
+@tool
+class_name MCPCommandHandler
+extends Node
+
+var _websocket_server
+var _command_processors = []
+
+func _ready():
+	print("Command handler initializing...")
+	await get_tree().process_frame
+	_websocket_server = get_parent()
+	print("WebSocket server reference set: ", _websocket_server)
+	
+	# Initialize command processors
+	_initialize_command_processors()
+	
+	print("Command handler initialized and ready to process commands")
+
+func _initialize_command_processors():
+	# Create and add all required command processors
+	var node_commands = MCPNodeCommands.new()
+	var script_commands = MCPScriptCommands.new()
+	var scene_commands = MCPSceneCommands.new()
+	var project_commands = MCPProjectCommands.new()
+	var editor_commands = MCPEditorCommands.new()
+	var editor_script_commands = MCPEditorScriptCommands.new()
+	var debugger_commands = MCPDebuggerCommands.new()
+	var input_commands = MCPInputCommands.new()
+	
+	# Set server reference for all processors
+	node_commands._websocket_server = _websocket_server
+	script_commands._websocket_server = _websocket_server
+	scene_commands._websocket_server = _websocket_server
+	project_commands._websocket_server = _websocket_server
+	editor_commands._websocket_server = _websocket_server
+	editor_script_commands._websocket_server = _websocket_server
+	debugger_commands._websocket_server = _websocket_server
+	input_commands._websocket_server = _websocket_server
+	
+	# Add them to our processor list
+	_command_processors.append(node_commands)
+	_command_processors.append(script_commands)
+	_command_processors.append(scene_commands)
+	_command_processors.append(project_commands)
+	_command_processors.append(editor_commands)
+	_command_processors.append(editor_script_commands)
+	_command_processors.append(debugger_commands)
+	_command_processors.append(input_commands)
+	
+	# Try to load optional command classes
+	var script_resource_commands = _try_load_optional_command("res://addons/godot_mcp/mcp_script_resource_commands.gd")
+	var enhanced_commands = _try_load_optional_command("res://addons/godot_mcp/mcp_enhanced_commands.gd")
+	var asset_commands = _try_load_optional_command("res://addons/godot_mcp/mcp_asset_commands.gd")
+	
+	# Add required processors as children for proper lifecycle management
+	add_child(node_commands)
+	add_child(script_commands)
+	add_child(scene_commands)
+	add_child(project_commands)
+	add_child(editor_commands)
+	add_child(editor_script_commands)
+	add_child(debugger_commands)
+	add_child(input_commands)
+	
+	print("Command processors initialized:")
+	print("- Node Commands")
+	print("- Script Commands")
+	print("- Scene Commands")
+	print("- Project Commands")
+	print("- Editor Commands")
+	print("- Editor Script Commands")
+	print("- Debugger Commands")
+	print("- Input Commands")
+	
+	if script_resource_commands:
+		print("- Script Resource Commands")
+	if enhanced_commands:
+		print("- Enhanced Commands")
+	if asset_commands:
+		print("- Asset Commands")
+
+func _try_load_optional_command(path: String) -> Node:
+	if FileAccess.file_exists(path):
+		var script = load(path)
+		if script:
+			var command = Node.new()
+			command.set_script(script)
+			command._websocket_server = _websocket_server
+			_command_processors.append(command)
+			add_child(command)
+			return command
+	return null
+
+func _handle_command(client_id: int, command: Dictionary) -> void:
+	var command_type = command.get("type", "")
+	var params = command.get("params", {})
+	var command_id = command.get("commandId", "")
+	
+	print("Processing command: %s" % command_type)
+	
+	# Special handling for enhanced commands
+	var enhanced_commands = [
+		"get_editor_scene_structure",
+		"get_runtime_scene_structure",
+		"get_debug_output",
+		"get_editor_errors",
+		"get_stack_trace_panel",
+		"get_stack_frames_panel",
+		"evaluate_runtime",
+		"clear_debug_output",
+		"clear_editor_errors",
+		"subscribe_debug_output",
+		"unsubscribe_debug_output",
+		"update_node_transform"
+	]
+	if command_type in enhanced_commands:
+		# Try to find enhanced commands processor first
+		for processor in _command_processors:
+			if processor.get_script() and processor.get_script().resource_path.ends_with("mcp_enhanced_commands.gd"):
+				var handled = await _call_processor(processor, client_id, command_type, params, command_id)
+				if handled:
+					print("Command %s handled by Enhanced Commands processor" % command_type)
+					return
+	
+	# Try each processor until one handles the command
+	for processor in _command_processors:
+		var handled = await _call_processor(processor, client_id, command_type, params, command_id)
+		if handled:
+			print("Command %s handled by %s" % [command_type, processor.get_class()])
+			return
+
+	# If no processor handled the command, send an error
+	_send_error(client_id, "Unknown command: %s" % command_type, command_id)
+
+func _send_error(client_id: int, message: String, command_id: String) -> void:
+	var response = {
+		"status": "error",
+		"message": message
+	}
+	
+	if not command_id.is_empty():
+		response["commandId"] = command_id
+	
+	_websocket_server.send_response(client_id, response)
+	print("Error: %s" % message)
+
+func _processor_requires_await(processor: Node) -> bool:
+	if processor is MCPDebuggerCommands:
+		return true
+	if processor is MCPInputCommands:
+		return true
+	if processor.get_script():
+		var path := String(processor.get_script().resource_path)
+		if path.ends_with("mcp_enhanced_commands.gd"):
+			return true
+	return false
+
+func _call_processor(processor: Node, client_id: int, command_type: String, params: Dictionary, command_id: String) -> bool:
+	if _processor_requires_await(processor):
+		return await processor.process_command(client_id, command_type, params, command_id)
+	return processor.process_command(client_id, command_type, params, command_id)

package/addons/godot_mcp/command_handler.gd.uid

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

package/addons/godot_mcp/commands/base_command_processor.gd

@@ -0,0 +1,221 @@
+@tool
+class_name MCPBaseCommandProcessor
+extends Node
+
+# Signal emitted when a command has completed processing
+signal command_completed(client_id, command_type, result, command_id)
+
+# Reference to the server - passed by the command handler
+var _websocket_server = null
+
+# Must be implemented by subclasses
+func process_command(client_id: int, command_type: String, params: Dictionary, command_id: String) -> bool:
+	push_error("BaseCommandProcessor.process_command called directly")
+	return false
+
+# Helper functions common to all command processors
+func _send_success(client_id: int, result: Dictionary, command_id: String) -> void:
+	var response = {
+		"status": "success",
+		"result": result
+	}
+	
+	if not command_id.is_empty():
+		response["commandId"] = command_id
+	
+	# Emit the signal for local processing (useful for testing)
+	command_completed.emit(client_id, "success", result, command_id)
+	
+	# Send to websocket if available
+	if _websocket_server:
+		_websocket_server.send_response(client_id, response)
+
+func _send_error(client_id: int, message: String, command_id: String) -> void:
+	var response = {
+		"status": "error",
+		"message": message
+	}
+	
+	if not command_id.is_empty():
+		response["commandId"] = command_id
+	
+	# Emit the signal for local processing (useful for testing)
+	var error_result = {"error": message}
+	command_completed.emit(client_id, "error", error_result, command_id)
+	
+	# Send to websocket if available
+	if _websocket_server:
+		_websocket_server.send_response(client_id, response)
+	print("Error: %s" % message)
+
+# Common utility methods
+func _get_editor_node(path: String) -> Node:
+	var plugin = Engine.get_meta("GodotMCPPlugin")
+	if not plugin:
+		print("GodotMCPPlugin not found in Engine metadata")
+		return null
+		
+	var editor_interface = plugin.get_editor_interface()
+	var edited_scene_root = editor_interface.get_edited_scene_root()
+	
+	if not edited_scene_root:
+		print("No edited scene found")
+		return null
+
+	var normalized_path = _normalize_node_path(path)
+	if normalized_path.is_empty():
+		return edited_scene_root
+
+	var node = edited_scene_root.get_node_or_null(normalized_path)
+	if node:
+		return node
+
+	var root_name = edited_scene_root.name
+	if normalized_path == root_name:
+		return edited_scene_root
+
+	var root_prefix = root_name + "/"
+	if normalized_path.begins_with(root_prefix):
+		var trimmed_path = normalized_path.substr(root_prefix.length())
+		if trimmed_path.is_empty():
+			return edited_scene_root
+		node = edited_scene_root.get_node_or_null(trimmed_path)
+		if node:
+			return node
+
+	return null
+
+# Enhanced version of _get_editor_node to improve node path resolution
+func _get_editor_node_enhanced(path: String) -> Node:
+	# First try the standard method
+	var node = _get_editor_node(path)
+	if node:
+		return node
+		
+	# If not found, try additional resolution methods
+	var plugin = Engine.get_meta("GodotMCPPlugin")
+	if not plugin:
+		return null
+		
+	var editor_interface = plugin.get_editor_interface()
+	var edited_scene_root = editor_interface.get_edited_scene_root()
+	
+	if not edited_scene_root:
+		return null
+	
+	var normalized_path = _normalize_node_path(path)
+	if normalized_path.is_empty():
+		return edited_scene_root
+
+	var lower_path = normalized_path.to_lower()
+	var root_name_lower = edited_scene_root.name.to_lower()
+
+	if lower_path == root_name_lower:
+		return edited_scene_root
+
+	var parts = normalized_path.split("/")
+	if parts.size() > 1 and parts[0].to_lower() == root_name_lower:
+		var sub_path = ""
+		for i in range(1, parts.size()):
+			if i > 1:
+				sub_path += "/"
+			sub_path += parts[i]
+		
+		if sub_path.is_empty():
+			return edited_scene_root
+		
+		var node_with_root_prefix = edited_scene_root.get_node_or_null(sub_path)
+		if node_with_root_prefix:
+			return node_with_root_prefix
+		
+		normalized_path = sub_path
+		lower_path = normalized_path.to_lower()
+	
+	if normalized_path.find("/") == -1:
+		for child in edited_scene_root.get_children():
+			if child.name.to_lower() == lower_path:
+				return child
+	
+	return null
+
+# Helper function to mark a scene as modified
+func _mark_scene_modified() -> void:
+	var plugin = Engine.get_meta("GodotMCPPlugin")
+	if not plugin:
+		print("GodotMCPPlugin not found in Engine metadata")
+		return
+	
+	var editor_interface = plugin.get_editor_interface()
+	var edited_scene_root = editor_interface.get_edited_scene_root()
+	
+	if edited_scene_root:
+		# This internally marks the scene as modified in the editor
+		editor_interface.mark_scene_as_unsaved()
+
+# Helper function to access the EditorUndoRedoManager
+func _get_undo_redo():
+	var plugin = Engine.get_meta("GodotMCPPlugin")
+	if not plugin or not plugin.has_method("get_undo_redo"):
+		print("Cannot access UndoRedo from plugin")
+		return null
+		
+	return plugin.get_undo_redo()
+
+# Helper function to parse property values from string to proper Godot types
+func _parse_property_value(value):
+	# Only try to parse strings that look like they could be Godot types
+	if typeof(value) == TYPE_STRING and (
+		value.begins_with("Vector") or 
+		value.begins_with("Transform") or 
+		value.begins_with("Rect") or 
+		value.begins_with("Color") or
+		value.begins_with("Quat") or
+		value.begins_with("Basis") or
+		value.begins_with("Plane") or
+		value.begins_with("AABB") or
+		value.begins_with("Projection") or
+		value.begins_with("Callable") or
+		value.begins_with("Signal") or
+		value.begins_with("PackedVector") or
+		value.begins_with("PackedString") or
+		value.begins_with("PackedFloat") or
+		value.begins_with("PackedInt") or
+		value.begins_with("PackedColor") or
+		value.begins_with("PackedByteArray") or
+		value.begins_with("Dictionary") or
+		value.begins_with("Array")
+	):
+		var expression = Expression.new()
+		var error = expression.parse(value, [])
+		
+		if error == OK:
+			var result = expression.execute([], null, true)
+			if not expression.has_execute_failed():
+				print("Successfully parsed %s as %s" % [value, result])
+				return result
+			else:
+				print("Failed to execute expression for: %s" % value)
+		else:
+				print("Failed to parse expression: %s (Error: %d)" % [value, error])
+	
+	# Otherwise, return value as is
+	return value
+
+func _normalize_node_path(path: String) -> String:
+	var normalized = path.strip_edges()
+	if normalized.is_empty() or normalized == "." or normalized == "/root":
+		return ""
+	
+	while normalized.begins_with("/root/"):
+		normalized = normalized.substr(6)
+	
+	while normalized.begins_with("./"):
+		normalized = normalized.substr(2)
+	
+	if normalized.begins_with("/"):
+		normalized = normalized.substr(1)
+	
+	if normalized.begins_with("."):
+		normalized = normalized.substr(1)
+	
+	return normalized.strip_edges()

package/addons/godot_mcp/commands/base_command_processor.gd.uid

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