@satelliteoflove/godot-mcp 2.3.0 → 2.4.1

package/addon/core/base_command.gd

@@ -0,0 +1,58 @@
+@tool
+class_name MCPBaseCommand
+extends RefCounted
+
+var _plugin: EditorPlugin
+
+
+func setup(plugin: EditorPlugin) -> void:
+	_plugin = plugin
+
+
+func get_commands() -> Dictionary:
+	return {}
+
+
+func _success(result: Dictionary) -> Dictionary:
+	return MCPUtils.success(result)
+
+
+func _error(code: String, message: String) -> Dictionary:
+	return MCPUtils.error(code, message)
+
+
+func _get_node(path: String) -> Node:
+	return MCPUtils.get_node_from_path(path)
+
+
+func _serialize_value(value: Variant) -> Variant:
+	return MCPUtils.serialize_value(value)
+
+
+func _require_scene_open() -> Dictionary:
+	var root := EditorInterface.get_edited_scene_root()
+	if not root:
+		return _error("NO_SCENE", "No scene is currently open")
+	return {}
+
+
+func _require_typed_node(path: String, type: String, type_error_code: String = "WRONG_TYPE") -> Variant:
+	var node := _get_node(path)
+	if not node:
+		return _error("NODE_NOT_FOUND", "Node not found: %s" % path)
+	if not node.is_class(type):
+		return _error(type_error_code, "Expected %s, got %s" % [type, node.get_class()])
+	return node
+
+
+func _find_nodes_of_type(root: Node, type: String) -> Array[Dictionary]:
+	var result: Array[Dictionary] = []
+	_find_nodes_recursive(root, type, result)
+	return result
+
+
+func _find_nodes_recursive(node: Node, type: String, result: Array[Dictionary]) -> void:
+	if node.is_class(type):
+		result.append({"path": str(node.get_path()), "name": node.name})
+	for child in node.get_children():
+		_find_nodes_recursive(child, type, result)

package/addon/core/base_command.gd.uid

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

package/addon/core/mcp_debugger_plugin.gd

@@ -0,0 +1,149 @@
+@tool
+extends EditorDebuggerPlugin
+class_name MCPDebuggerPlugin
+
+signal screenshot_received(success: bool, image_base64: String, width: int, height: int, error: String)
+signal debug_output_received(output: PackedStringArray)
+signal performance_metrics_received(metrics: Dictionary)
+signal find_nodes_received(matches: Array, count: int, error: String)
+
+var _active_session_id: int = -1
+var _pending_screenshot: bool = false
+var _pending_debug_output: bool = false
+var _pending_performance_metrics: bool = false
+var _pending_find_nodes: bool = false
+
+
+func _has_capture(prefix: String) -> bool:
+	return prefix == "godot_mcp"
+
+
+func _capture(message: String, data: Array, session_id: int) -> bool:
+	match message:
+		"godot_mcp:screenshot_result":
+			_handle_screenshot_result(data)
+			return true
+		"godot_mcp:debug_output_result":
+			_handle_debug_output_result(data)
+			return true
+		"godot_mcp:performance_metrics_result":
+			_handle_performance_metrics_result(data)
+			return true
+		"godot_mcp:find_nodes_result":
+			_handle_find_nodes_result(data)
+			return true
+	return false
+
+
+func _setup_session(session_id: int) -> void:
+	_active_session_id = session_id
+
+
+func _session_stopped() -> void:
+	_active_session_id = -1
+	if _pending_screenshot:
+		_pending_screenshot = false
+		screenshot_received.emit(false, "", 0, 0, "Game session ended")
+	if _pending_debug_output:
+		_pending_debug_output = false
+		debug_output_received.emit(PackedStringArray())
+	if _pending_performance_metrics:
+		_pending_performance_metrics = false
+		performance_metrics_received.emit({})
+	if _pending_find_nodes:
+		_pending_find_nodes = false
+		find_nodes_received.emit([], 0, "Game session ended")
+
+
+func has_active_session() -> bool:
+	if _active_session_id < 0:
+		return false
+	if not EditorInterface.is_playing_scene():
+		_active_session_id = -1
+		return false
+	return true
+
+
+func request_screenshot(max_width: int = 1920) -> void:
+	if _active_session_id < 0:
+		screenshot_received.emit(false, "", 0, 0, "No active game session")
+		return
+	_pending_screenshot = true
+	var session := get_session(_active_session_id)
+	if session:
+		session.send_message("godot_mcp:take_screenshot", [max_width])
+	else:
+		_pending_screenshot = false
+		screenshot_received.emit(false, "", 0, 0, "Could not get debugger session")
+
+
+func _handle_screenshot_result(data: Array) -> void:
+	_pending_screenshot = false
+	if data.size() < 5:
+		screenshot_received.emit(false, "", 0, 0, "Invalid response data")
+		return
+	var success: bool = data[0]
+	var image_base64: String = data[1]
+	var width: int = data[2]
+	var height: int = data[3]
+	var error: String = data[4]
+	screenshot_received.emit(success, image_base64, width, height, error)
+
+
+func request_debug_output(clear: bool = false) -> void:
+	if _active_session_id < 0:
+		debug_output_received.emit(PackedStringArray())
+		return
+	_pending_debug_output = true
+	var session := get_session(_active_session_id)
+	if session:
+		session.send_message("godot_mcp:get_debug_output", [clear])
+	else:
+		_pending_debug_output = false
+		debug_output_received.emit(PackedStringArray())
+
+
+func _handle_debug_output_result(data: Array) -> void:
+	_pending_debug_output = false
+	var output: PackedStringArray = data[0] if data.size() > 0 else PackedStringArray()
+	debug_output_received.emit(output)
+
+
+func request_performance_metrics() -> void:
+	if _active_session_id < 0:
+		performance_metrics_received.emit({})
+		return
+	_pending_performance_metrics = true
+	var session := get_session(_active_session_id)
+	if session:
+		session.send_message("godot_mcp:get_performance_metrics", [])
+	else:
+		_pending_performance_metrics = false
+		performance_metrics_received.emit({})
+
+
+func _handle_performance_metrics_result(data: Array) -> void:
+	_pending_performance_metrics = false
+	var metrics: Dictionary = data[0] if data.size() > 0 else {}
+	performance_metrics_received.emit(metrics)
+
+
+func request_find_nodes(name_pattern: String, type_filter: String, root_path: String) -> void:
+	if _active_session_id < 0:
+		find_nodes_received.emit([], 0, "No active game session")
+		return
+	_pending_find_nodes = true
+	var session := get_session(_active_session_id)
+	if session:
+		session.send_message("godot_mcp:find_nodes", [name_pattern, type_filter, root_path])
+	else:
+		_pending_find_nodes = false
+		find_nodes_received.emit([], 0, "Could not get debugger session")
+
+
+func _handle_find_nodes_result(data: Array) -> void:
+	_pending_find_nodes = false
+	var matches: Array = data[0] if data.size() > 0 else []
+	var count: int = data[1] if data.size() > 1 else 0
+	var error: String = data[2] if data.size() > 2 else ""
+	find_nodes_received.emit(matches, count, error)

package/addon/core/mcp_debugger_plugin.gd.uid

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

package/addon/core/mcp_logger.gd

@@ -0,0 +1,40 @@
+@tool
+class_name MCPLogger extends Logger
+
+static var _output: PackedStringArray = []
+static var _max_lines := 1000
+static var _mutex := Mutex.new()
+
+
+static func _static_init() -> void:
+	OS.add_logger(MCPLogger.new())
+
+
+func _log_message(message: String, error: bool) -> void:
+	_mutex.lock()
+	var prefix := "[ERROR] " if error else ""
+	_output.append(prefix + message)
+	if _output.size() > _max_lines:
+		_output.remove_at(0)
+	_mutex.unlock()
+
+
+func _log_error(function: String, file: String, line: int, code: String,
+				rationale: String, editor_notify: bool, error_type: int,
+				script_backtraces: Array[ScriptBacktrace]) -> void:
+	_mutex.lock()
+	var msg := "[%s:%d] %s: %s" % [file.get_file(), line, code, rationale]
+	_output.append("[ERROR] " + msg)
+	if _output.size() > _max_lines:
+		_output.remove_at(0)
+	_mutex.unlock()
+
+
+static func get_output() -> PackedStringArray:
+	return _output
+
+
+static func clear() -> void:
+	_mutex.lock()
+	_output.clear()
+	_mutex.unlock()

package/addon/core/mcp_logger.gd.uid

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

package/addon/core/mcp_utils.gd

@@ -0,0 +1,129 @@
+@tool
+class_name MCPUtils
+extends RefCounted
+
+
+static func success(result: Dictionary) -> Dictionary:
+	return {
+		"status": "success",
+		"result": result
+	}
+
+
+static func error(code: String, message: String) -> Dictionary:
+	return {
+		"status": "error",
+		"error": {
+			"code": code,
+			"message": message
+		}
+	}
+
+
+static func get_node_from_path(path: String) -> Node:
+	var root := EditorInterface.get_edited_scene_root()
+	if not root:
+		return null
+
+	if path == "/root" or path == "/" or path == str(root.get_path()):
+		return root
+
+	if path.begins_with("/root/"):
+		var parts := path.split("/")
+		if parts.size() >= 3:
+			if parts[2] == root.name:
+				var relative_path := "/".join(parts.slice(3))
+				if relative_path.is_empty():
+					return root
+				return root.get_node_or_null(relative_path)
+
+	if path.begins_with("/"):
+		path = path.substr(1)
+
+	return root.get_node_or_null(path)
+
+
+static func serialize_value(value: Variant) -> Variant:
+	match typeof(value):
+		TYPE_VECTOR2:
+			return {"x": value.x, "y": value.y}
+		TYPE_VECTOR2I:
+			return {"x": value.x, "y": value.y}
+		TYPE_VECTOR3:
+			return {"x": value.x, "y": value.y, "z": value.z}
+		TYPE_VECTOR3I:
+			return {"x": value.x, "y": value.y, "z": value.z}
+		TYPE_COLOR:
+			return {"r": value.r, "g": value.g, "b": value.b, "a": value.a}
+		TYPE_OBJECT:
+			if value == null:
+				return null
+			if value is Resource:
+				return value.resource_path if value.resource_path else str(value)
+			return str(value)
+		_:
+			return value
+
+
+static func deserialize_value(value: Variant) -> Variant:
+	if value is String and value.begins_with("res://"):
+		var resource := load(value)
+		if resource:
+			return resource
+	if value is Dictionary:
+		if value.has("_resource"):
+			return _create_resource(value)
+		if value.has("x") and value.has("y"):
+			if value.has("z"):
+				return Vector3(value.x, value.y, value.z)
+			return Vector2(value.x, value.y)
+		if value.has("r") and value.has("g") and value.has("b"):
+			return Color(value.r, value.g, value.b, value.get("a", 1.0))
+	return value
+
+
+static func _create_resource(spec: Dictionary) -> Resource:
+	var resource_type: String = spec.get("_resource", "")
+	if not ClassDB.class_exists(resource_type):
+		push_error("MCPUtils: Unknown resource type: %s" % resource_type)
+		return null
+	if not ClassDB.is_parent_class(resource_type, "Resource"):
+		push_error("MCPUtils: Type is not a Resource: %s" % resource_type)
+		return null
+
+	var resource: Resource = ClassDB.instantiate(resource_type)
+	if not resource:
+		push_error("MCPUtils: Failed to create resource: %s" % resource_type)
+		return null
+
+	for key in spec:
+		if key == "_resource":
+			continue
+		if key in resource:
+			resource.set(key, deserialize_value(spec[key]))
+
+	return resource
+
+
+static func is_resource_path(path: String) -> bool:
+	return path.begins_with("res://")
+
+
+static func dir_exists(path: String) -> bool:
+	if path.is_empty():
+		return false
+	if is_resource_path(path):
+		var dir := DirAccess.open("res://")
+		return dir != null and dir.dir_exists(path.trim_prefix("res://"))
+	return DirAccess.dir_exists_absolute(path)
+
+
+static func ensure_dir_exists(path: String) -> Error:
+	if dir_exists(path):
+		return OK
+	if is_resource_path(path):
+		var dir := DirAccess.open("res://")
+		if not dir:
+			return ERR_CANT_OPEN
+		return dir.make_dir_recursive(path.trim_prefix("res://"))
+	return DirAccess.make_dir_recursive_absolute(path)

package/addon/core/mcp_utils.gd.uid

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

package/addon/game_bridge/mcp_game_bridge.gd

@@ -0,0 +1,195 @@
+extends Node
+class_name MCPGameBridge
+
+const DEFAULT_MAX_WIDTH := 1920
+
+var _logger: _MCPGameLogger
+
+
+func _ready() -> void:
+	if not EngineDebugger.is_active():
+		return
+	_logger = _MCPGameLogger.new()
+	OS.add_logger(_logger)
+	EngineDebugger.register_message_capture("godot_mcp", _on_debugger_message)
+	print("[MCP Game Bridge] Initialized")
+
+
+func _exit_tree() -> void:
+	if EngineDebugger.is_active():
+		EngineDebugger.unregister_message_capture("godot_mcp")
+
+
+func _on_debugger_message(message: String, data: Array) -> bool:
+	match message:
+		"take_screenshot":
+			_take_screenshot_deferred.call_deferred(data)
+			return true
+		"get_debug_output":
+			_handle_get_debug_output(data)
+			return true
+		"get_performance_metrics":
+			_handle_get_performance_metrics()
+			return true
+		"find_nodes":
+			_handle_find_nodes(data)
+			return true
+	return false
+
+
+func _take_screenshot_deferred(data: Array) -> void:
+	var max_width: int = data[0] if data.size() > 0 else DEFAULT_MAX_WIDTH
+	await RenderingServer.frame_post_draw
+	_capture_and_send_screenshot(max_width)
+
+
+func _capture_and_send_screenshot(max_width: int) -> void:
+	var viewport := get_viewport()
+	if viewport == null:
+		_send_screenshot_error("NO_VIEWPORT", "Could not get game viewport")
+		return
+	var image := viewport.get_texture().get_image()
+	if image == null:
+		_send_screenshot_error("CAPTURE_FAILED", "Failed to capture image from viewport")
+		return
+	if max_width > 0 and image.get_width() > max_width:
+		var scale_factor := float(max_width) / float(image.get_width())
+		var new_height := int(image.get_height() * scale_factor)
+		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)
+	EngineDebugger.send_message("godot_mcp:screenshot_result", [
+		true,
+		base64,
+		image.get_width(),
+		image.get_height(),
+		""
+	])
+
+
+func _send_screenshot_error(code: String, message: String) -> void:
+	EngineDebugger.send_message("godot_mcp:screenshot_result", [
+		false,
+		"",
+		0,
+		0,
+		"%s: %s" % [code, message]
+	])
+
+
+func _handle_get_debug_output(data: Array) -> void:
+	var clear: bool = data[0] if data.size() > 0 else false
+	var output := _logger.get_output() if _logger else PackedStringArray()
+	if clear and _logger:
+		_logger.clear()
+	EngineDebugger.send_message("godot_mcp:debug_output_result", [output])
+
+
+func _handle_find_nodes(data: Array) -> void:
+	var name_pattern: String = data[0] if data.size() > 0 else ""
+	var type_filter: String = data[1] if data.size() > 1 else ""
+	var root_path: String = data[2] if data.size() > 2 else ""
+
+	var tree := get_tree()
+	var scene_root := tree.current_scene if tree else null
+	if not scene_root:
+		EngineDebugger.send_message("godot_mcp:find_nodes_result", [[], 0, "No scene running"])
+		return
+
+	var search_root: Node = scene_root
+	if not root_path.is_empty():
+		search_root = _get_node_from_path(root_path, scene_root)
+		if not search_root:
+			EngineDebugger.send_message("godot_mcp:find_nodes_result", [[], 0, "Root not found: " + root_path])
+			return
+
+	var matches: Array = []
+	_find_recursive(search_root, scene_root, name_pattern, type_filter, matches)
+	EngineDebugger.send_message("godot_mcp:find_nodes_result", [matches, matches.size(), ""])
+
+
+func _get_node_from_path(path: String, scene_root: Node) -> Node:
+	if path == "/" or path.is_empty():
+		return scene_root
+
+	if path.begins_with("/root/"):
+		var parts := path.split("/")
+		if parts.size() >= 3 and parts[2] == scene_root.name:
+			var relative := "/".join(parts.slice(3))
+			if relative.is_empty():
+				return scene_root
+			return scene_root.get_node_or_null(relative)
+
+	if path.begins_with("/"):
+		path = path.substr(1)
+
+	return scene_root.get_node_or_null(path)
+
+
+func _find_recursive(node: Node, scene_root: Node, name_pattern: String, type_filter: String, results: Array) -> void:
+	var name_matches := name_pattern.is_empty() or node.name.matchn(name_pattern)
+	var type_matches := type_filter.is_empty() or node.is_class(type_filter)
+
+	if name_matches and type_matches:
+		var path := "/root/" + scene_root.name
+		var relative := scene_root.get_path_to(node)
+		if relative != NodePath("."):
+			path += "/" + str(relative)
+		results.append({"path": path, "type": node.get_class()})
+
+	for child in node.get_children():
+		_find_recursive(child, scene_root, name_pattern, type_filter, results)
+
+
+func _handle_get_performance_metrics() -> void:
+	var metrics := {
+		"fps": Performance.get_monitor(Performance.TIME_FPS),
+		"frame_time_ms": Performance.get_monitor(Performance.TIME_PROCESS) * 1000.0,
+		"physics_time_ms": Performance.get_monitor(Performance.TIME_PHYSICS_PROCESS) * 1000.0,
+		"navigation_time_ms": Performance.get_monitor(Performance.TIME_NAVIGATION_PROCESS) * 1000.0,
+		"render_objects": int(Performance.get_monitor(Performance.RENDER_TOTAL_OBJECTS_IN_FRAME)),
+		"render_draw_calls": int(Performance.get_monitor(Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME)),
+		"render_primitives": int(Performance.get_monitor(Performance.RENDER_TOTAL_PRIMITIVES_IN_FRAME)),
+		"physics_2d_active_objects": int(Performance.get_monitor(Performance.PHYSICS_2D_ACTIVE_OBJECTS)),
+		"physics_2d_collision_pairs": int(Performance.get_monitor(Performance.PHYSICS_2D_COLLISION_PAIRS)),
+		"physics_2d_island_count": int(Performance.get_monitor(Performance.PHYSICS_2D_ISLAND_COUNT)),
+		"object_count": int(Performance.get_monitor(Performance.OBJECT_COUNT)),
+		"object_resource_count": int(Performance.get_monitor(Performance.OBJECT_RESOURCE_COUNT)),
+		"object_node_count": int(Performance.get_monitor(Performance.OBJECT_NODE_COUNT)),
+		"object_orphan_node_count": int(Performance.get_monitor(Performance.OBJECT_ORPHAN_NODE_COUNT)),
+		"memory_static": int(Performance.get_monitor(Performance.MEMORY_STATIC)),
+		"memory_static_max": int(Performance.get_monitor(Performance.MEMORY_STATIC_MAX)),
+	}
+	EngineDebugger.send_message("godot_mcp:performance_metrics_result", [metrics])
+
+
+class _MCPGameLogger extends Logger:
+	var _output: PackedStringArray = []
+	var _max_lines := 1000
+	var _mutex := Mutex.new()
+
+	func _log_message(message: String, error: bool) -> void:
+		_mutex.lock()
+		var prefix := "[ERROR] " if error else ""
+		_output.append(prefix + message)
+		if _output.size() > _max_lines:
+			_output.remove_at(0)
+		_mutex.unlock()
+
+	func _log_error(function: String, file: String, line: int, code: String,
+					rationale: String, editor_notify: bool, error_type: int,
+					script_backtraces: Array[ScriptBacktrace]) -> void:
+		_mutex.lock()
+		var msg := "[%s:%d] %s: %s" % [file.get_file(), line, code, rationale]
+		_output.append("[ERROR] " + msg)
+		if _output.size() > _max_lines:
+			_output.remove_at(0)
+		_mutex.unlock()
+
+	func get_output() -> PackedStringArray:
+		return _output
+
+	func clear() -> void:
+		_mutex.lock()
+		_output.clear()
+		_mutex.unlock()

package/addon/game_bridge/mcp_game_bridge.gd.uid

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

package/addon/plugin.cfg

@@ -0,0 +1,8 @@
+[plugin]
+
+name="Godot MCP"
+description="Model Context Protocol server for AI assistant integration"
+author="godot-mcp"
+version="2.4.1"
+script="plugin.gd"
+godot_version_min="4.5"

package/addon/plugin.gd

@@ -0,0 +1,89 @@
+@tool
+extends EditorPlugin
+
+const WebSocketServer := preload("res://addons/godot_mcp/websocket_server.gd")
+const CommandRouter := preload("res://addons/godot_mcp/command_router.gd")
+const StatusPanel := preload("res://addons/godot_mcp/ui/status_panel.tscn")
+const MCPDebuggerPlugin := preload("res://addons/godot_mcp/core/mcp_debugger_plugin.gd")
+
+const GAME_BRIDGE_AUTOLOAD := "MCPGameBridge"
+const GAME_BRIDGE_PATH := "res://addons/godot_mcp/game_bridge/mcp_game_bridge.gd"
+
+var _websocket_server: WebSocketServer
+var _command_router: CommandRouter
+var _status_panel: Control
+var _debugger_plugin: MCPDebuggerPlugin
+
+
+func _enter_tree() -> void:
+	_command_router = CommandRouter.new()
+	_command_router.setup(self)
+
+	_websocket_server = WebSocketServer.new()
+	_websocket_server.command_received.connect(_on_command_received)
+	_websocket_server.client_connected.connect(_on_client_connected)
+	_websocket_server.client_disconnected.connect(_on_client_disconnected)
+	add_child(_websocket_server)
+
+	_status_panel = StatusPanel.instantiate()
+	add_control_to_bottom_panel(_status_panel, "MCP")
+	_update_status("Waiting for connection...")
+
+	_debugger_plugin = MCPDebuggerPlugin.new()
+	add_debugger_plugin(_debugger_plugin)
+
+	_ensure_game_bridge_autoload()
+
+	_websocket_server.start_server()
+	print("[godot-mcp] Plugin initialized")
+
+
+func _exit_tree() -> void:
+	if _status_panel:
+		remove_control_from_bottom_panel(_status_panel)
+		_status_panel.queue_free()
+
+	if _websocket_server:
+		_websocket_server.stop_server()
+		_websocket_server.queue_free()
+
+	if _debugger_plugin:
+		remove_debugger_plugin(_debugger_plugin)
+		_debugger_plugin = null
+
+	if _command_router:
+		_command_router.free()
+
+	print("[godot-mcp] Plugin disabled")
+
+
+func _ensure_game_bridge_autoload() -> void:
+	if not ProjectSettings.has_setting("autoload/" + GAME_BRIDGE_AUTOLOAD):
+		ProjectSettings.set_setting("autoload/" + GAME_BRIDGE_AUTOLOAD, GAME_BRIDGE_PATH)
+		ProjectSettings.save()
+		print("[godot-mcp] Added MCPGameBridge autoload")
+
+
+func get_debugger_plugin() -> MCPDebuggerPlugin:
+	return _debugger_plugin
+
+
+func _on_command_received(id: String, command: String, params: Dictionary) -> void:
+	var response = await _command_router.handle_command(command, params)
+	response["id"] = id
+	_websocket_server.send_response(response)
+
+
+func _on_client_connected() -> void:
+	_update_status("Connected")
+	print("[godot-mcp] Client connected")
+
+
+func _on_client_disconnected() -> void:
+	_update_status("Disconnected")
+	print("[godot-mcp] Client disconnected")
+
+
+func _update_status(status: String) -> void:
+	if _status_panel and _status_panel.has_method("set_status"):
+		_status_panel.set_status(status)

package/addon/plugin.gd.uid

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