godot-mcp-runtime 3.0.0 → 3.1.0

package/dist/scripts/godot_operations.gd

@@ -10,11 +10,15 @@ func _init():
 	# Check for debug flag
 	debug_mode = "--debug-godot" in args
 
+	# SceneTree.quit(n) only schedules a quit for end-of-frame in Godot 4.
+	# Every quit(1) must be followed by `return` to halt the failing path,
+	# otherwise control falls through into success-print + scene save.
 	# Find the script argument and determine the positions of operation and params
 	var script_index = args.find("--script")
 	if script_index == -1:
 		log_error("Could not find --script argument")
 		quit(1)
+		return
 
 	var operation_index = script_index + 2
 	var params_index = script_index + 3
@@ -23,6 +27,7 @@ func _init():
 		log_error("Usage: godot --headless --script godot_operations.gd <operation> <json_params>")
 		log_error("Not enough command-line arguments provided.")
 		quit(1)
+		return
 
 	log_debug("All arguments: " + str(args))
 
@@ -42,10 +47,12 @@ func _init():
 		log_error("Failed to parse JSON parameters: " + params_json)
 		log_error("JSON Error: " + json.get_error_message() + " at line " + str(json.get_error_line()))
 		quit(1)
+		return
 
 	if not params:
 		log_error("Failed to parse JSON parameters: " + params_json)
 		quit(1)
+		return
 
 	log_info("Executing operation: " + operation)
 
@@ -90,8 +97,10 @@ func _init():
 		_:
 			log_error("Unknown operation: " + operation)
 			quit(1)
+			return
 
 	quit()
+	return
 
 # Logging functions
 func log_debug(message):
@@ -280,6 +289,7 @@ func create_scene(params):
 	if not scene_root:
 		log_error("Failed to instantiate node of type: " + root_node_type)
 		quit(1)
+		return
 
 	scene_root.name = "root"
 	scene_root.owner = scene_root
@@ -287,51 +297,86 @@ func create_scene(params):
 	if not _ensure_res_dir(full_scene_path):
 		log_error("Failed to create directory for scene: " + full_scene_path)
 		quit(1)
+		return
 
 	if save_scene_to_path(scene_root, full_scene_path):
 		print("Scene created successfully at: " + params.scene_path)
 	else:
 		log_error("Failed to create scene: " + params.scene_path)
 		quit(1)
+		return
 
 # Add a node to an existing scene
+# Apply an add_node mutation without saving. Shared by standalone add_node
+# and batch_scene_operations so both paths validate identically.
+# Returns {"ok": bool, "error": String}; error is empty on success.
+func _apply_add_node(scene_root: Node, op: Dictionary) -> Dictionary:
+	var parent_path = "root"
+	if op.has("parent_node_path"):
+		parent_path = op.parent_node_path
+	var parent = find_node_by_path(scene_root, parent_path)
+	if not parent:
+		return {"ok": false, "error": "Parent node not found: " + parent_path}
+	if not op.has("node_type") or op.node_type == "":
+		return {"ok": false, "error": "node_type is required for add_node"}
+	if not op.has("node_name") or op.node_name == "":
+		return {"ok": false, "error": "node_name is required for add_node"}
+	var new_node = instantiate_class(op.node_type)
+	if not new_node:
+		return {"ok": false, "error": "Failed to instantiate node of type: " + op.node_type}
+	new_node.name = op.node_name
+	if op.has("properties"):
+		for property in op.properties:
+			new_node.set(property, _coerce_property_value(op.properties[property]))
+	parent.add_child(new_node)
+	new_node.owner = scene_root
+	return {"ok": true, "error": ""}
+
+# Apply a load_sprite mutation without saving. Shared by standalone load_sprite
+# and batch_scene_operations.
+func _apply_load_sprite(scene_root: Node, op: Dictionary) -> Dictionary:
+	if not op.has("node_path") or op.node_path == "":
+		return {"ok": false, "error": "node_path is required for load_sprite"}
+	if not op.has("texture_path") or op.texture_path == "":
+		return {"ok": false, "error": "texture_path is required for load_sprite"}
+	var sprite_node = find_node_by_path(scene_root, op.node_path)
+	if not sprite_node:
+		return {"ok": false, "error": "Node not found: " + op.node_path}
+	if not (sprite_node is Sprite2D or sprite_node is Sprite3D or sprite_node is TextureRect):
+		return {"ok": false, "error": "Node is not a sprite-compatible type: " + sprite_node.get_class()}
+	var full_texture_path = normalize_scene_path(op.texture_path)
+	var texture = load(full_texture_path)
+	if not texture:
+		return {"ok": false, "error": "Failed to load texture: " + full_texture_path}
+	if not (texture is Texture2D):
+		return {"ok": false, "error": "Loaded resource is not a Texture2D: " + full_texture_path}
+	# A texture without a resource_path is a runtime-only object — PackedScene.pack()
+	# cannot serialize it, so the assignment would silently vanish on save.
+	if texture.resource_path == "":
+		return {"ok": false, "error": "Texture has no resource_path — likely not imported. Open project in Godot editor once, or run 'godot --headless --editor --quit' to import assets."}
+	sprite_node.texture = texture
+	return {"ok": true, "error": ""}
+
 func add_node(params):
 	printerr("Adding node to scene: " + params.scene_path)
 
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
 
-	var parent_path = "root"
-	if params.has("parent_node_path"):
-		parent_path = params.parent_node_path
-
-	var parent = find_node_by_path(scene_root, parent_path)
-	if not parent:
-		log_error("Parent node not found: " + parent_path)
-		quit(1)
-
-	var new_node = instantiate_class(params.node_type)
-	if not new_node:
-		log_error("Failed to instantiate node of type: " + params.node_type)
+	var result = _apply_add_node(scene_root, params)
+	if not result.ok:
+		log_error(result.error)
 		quit(1)
-
-	new_node.name = params.node_name
-
-	if params.has("properties"):
-		var properties = params.properties
-		for property in properties:
-			log_debug("Setting property: " + property + " = " + str(properties[property]))
-			new_node.set(property, _coerce_property_value(properties[property]))
-
-	parent.add_child(new_node)
-	new_node.owner = scene_root
+		return
 
 	if save_scene_to_path(scene_root, params.scene_path):
 		print("Node '" + params.node_name + "' of type '" + params.node_type + "' added successfully")
 	else:
 		log_error("Failed to save scene after adding node")
 		quit(1)
+		return
 
 # Load a sprite into a Sprite2D node
 func load_sprite(params):
@@ -340,37 +385,20 @@ func load_sprite(params):
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
 
-	var sprite_node = find_node_by_path(scene_root, params.node_path)
-	if not sprite_node:
-		log_error("Node not found: " + params.node_path)
-		quit(1)
-
-	if not (sprite_node is Sprite2D or sprite_node is Sprite3D or sprite_node is TextureRect):
-		log_error("Node is not a sprite-compatible type: " + sprite_node.get_class())
-		quit(1)
-
-	var full_texture_path = normalize_scene_path(params.texture_path)
-	var texture = load(full_texture_path)
-	if not texture:
-		log_error("Failed to load texture: " + full_texture_path)
-		quit(1)
-	if not (texture is Texture2D):
-		log_error("Loaded resource is not a Texture2D: " + full_texture_path)
-		quit(1)
-	# A texture without a resource_path is a runtime-only object — PackedScene.pack()
-	# cannot serialize it, so the assignment would silently vanish on save.
-	if texture.resource_path == "":
-		log_error("Texture has no resource_path — likely not imported. Open project in Godot editor once, or run 'godot --headless --editor --quit' to import assets.")
+	var result = _apply_load_sprite(scene_root, params)
+	if not result.ok:
+		log_error(result.error)
 		quit(1)
-
-	sprite_node.texture = texture
+		return
 
 	if save_scene_to_path(scene_root, params.scene_path):
 		print("Sprite loaded successfully with texture: " + params.texture_path)
 	else:
 		log_error("Failed to save scene after loading sprite")
 		quit(1)
+		return
 
 # Export a scene as a MeshLibrary resource
 func export_mesh_library(params):
@@ -379,6 +407,7 @@ func export_mesh_library(params):
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
 
 	var mesh_library = MeshLibrary.new()
 
@@ -420,6 +449,7 @@ func export_mesh_library(params):
 		if not _ensure_res_dir(full_output_path):
 			log_error("Failed to create directory for MeshLibrary: " + full_output_path)
 			quit(1)
+			return
 
 		var error = ResourceSaver.save(mesh_library, full_output_path)
 		if error == OK:
@@ -427,9 +457,11 @@ func export_mesh_library(params):
 		else:
 			log_error("Failed to save MeshLibrary: " + str(error))
 			quit(1)
+			return
 	else:
 		log_error("No valid meshes found in the scene")
 		quit(1)
+		return
 
 # Save changes to a scene file
 func save_scene(params):
@@ -438,6 +470,7 @@ func save_scene(params):
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
 
 	var save_path = params.new_path if params.has("new_path") else params.scene_path
 
@@ -446,6 +479,7 @@ func save_scene(params):
 	else:
 		log_error("Failed to save scene")
 		quit(1)
+		return
 
 # ============================================
 # NODE OPERATIONS
@@ -458,6 +492,7 @@ func delete_nodes(params):
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
 
 	var node_paths: Array = params.node_paths
 	var results: Array = []
@@ -526,6 +561,9 @@ func get_node_properties(params: Dictionary) -> void:
 		return
 
 	var results: Array = []
+	# Class-name → default-instance cache. Reused across all nodes in this call
+	# so we don't instantiate a fresh default per node when changed_only is true.
+	var defaults_cache: Dictionary = {}
 
 	for node_spec in params.nodes:
 		var node_path = node_spec.get("node_path", "")
@@ -534,9 +572,15 @@ func get_node_properties(params: Dictionary) -> void:
 		if node == null:
 			results.append({"nodePath": node_path, "error": "Node not found"})
 		else:
-			var props = _collect_node_properties(node, changed_only)
+			var props = _collect_node_properties(node, changed_only, defaults_cache)
 			results.append({"nodePath": node_path, "nodeType": node.get_class(), "properties": props})
 
+	# Free cached default instances; they were created via instantiate_class.
+	for klass in defaults_cache:
+		var inst = defaults_cache[klass]
+		if inst:
+			inst.free()
+
 	print(JSON.stringify({"results": results}))
 
 # Get full hierarchical tree structure of a scene
@@ -546,6 +590,7 @@ func get_scene_tree(params):
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
 
 	var tree_root = scene_root
 	if params.has("parent_path") and params.parent_path:
@@ -553,6 +598,7 @@ func get_scene_tree(params):
 		if not tree_root:
 			log_error("Parent node not found: " + str(params.parent_path))
 			quit(1)
+			return
 
 	var max_depth = -1
 	if params.has("max_depth"):
@@ -589,22 +635,26 @@ func attach_script(params):
 	var scene_root = load_scene_instance(params.scene_path)
 	if not scene_root:
 		quit(1)
+		return
 
 	var node = find_node_by_path(scene_root, params.node_path)
 	if not node:
 		log_error("Node not found: " + params.node_path)
 		quit(1)
+		return
 
 	var full_script_path = normalize_scene_path(params.script_path)
 
 	if not FileAccess.file_exists(full_script_path):
 		log_error("Script file does not exist: " + full_script_path)
 		quit(1)
+		return
 
 	var script = load(full_script_path)
 	if not script:
 		log_error("Failed to load script: " + full_script_path)
 		quit(1)
+		return
 
 	node.set_script(script)
 
@@ -613,6 +663,7 @@ func attach_script(params):
 	else:
 		log_error("Failed to save scene after attaching script")
 		quit(1)
+		return
 
 # ============================================
 # SIGNAL AND DUPLICATE OPERATIONS
@@ -621,15 +672,19 @@ func attach_script(params):
 # Duplicate a node and its children within a scene
 func duplicate_node(params):
 	var scene_root = load_scene_instance(params.scene_path)
-	if not scene_root: quit(1)
+	if not scene_root:
+		quit(1)
+		return
 
 	var node = find_node_by_path(scene_root, params.node_path)
 	if not node:
 		log_error("Node not found: " + params.node_path)
 		quit(1)
+		return
 	if node == scene_root:
 		log_error("Cannot duplicate the root node")
 		quit(1)
+		return
 
 	var duplicate = node.duplicate()
 	if params.has("new_name"):
@@ -643,33 +698,36 @@ func duplicate_node(params):
 		if not parent:
 			log_error("Target parent not found: " + params.target_parent_path)
 			quit(1)
+			return
 
 	parent.add_child(duplicate)
 	duplicate.owner = scene_root
-	# Recursively set owner on all descendants
-	for child in duplicate.get_children():
-		set_owner_recursive(child, scene_root)
+	# Iterative BFS to set owner on all descendants — avoids recursion depth.
+	var queue: Array = duplicate.get_children()
+	while not queue.is_empty():
+		var current = queue.pop_front()
+		current.owner = scene_root
+		queue.append_array(current.get_children())
 
 	if save_scene_to_path(scene_root, params.scene_path):
 		print("Node duplicated successfully as '" + duplicate.name + "'")
 	else:
 		log_error("Failed to save scene after duplicating node")
 		quit(1)
-
-func set_owner_recursive(node: Node, owner: Node):
-	node.owner = owner
-	for child in node.get_children():
-		set_owner_recursive(child, owner)
+		return
 
 # List signals defined on a node and their current connections
 func get_node_signals(params):
 	var scene_root = load_scene_instance(params.scene_path)
-	if not scene_root: quit(1)
+	if not scene_root:
+		quit(1)
+		return
 
 	var node = find_node_by_path(scene_root, params.node_path)
 	if not node:
 		log_error("Node not found: " + params.node_path)
 		quit(1)
+		return
 
 	var signals = []
 	for sig in node.get_signal_list():
@@ -695,25 +753,31 @@ func get_node_signals(params):
 # Connect a signal from one node to a method on another node
 func connect_signal(params):
 	var scene_root = load_scene_instance(params.scene_path)
-	if not scene_root: quit(1)
+	if not scene_root:
+		quit(1)
+		return
 
 	var source = find_node_by_path(scene_root, params.node_path)
 	if not source:
 		log_error("Source node not found: " + params.node_path)
 		quit(1)
+		return
 
 	var target = find_node_by_path(scene_root, params.target_node_path)
 	if not target:
 		log_error("Target node not found: " + params.target_node_path)
 		quit(1)
+		return
 
 	if not source.has_signal(params.signal):
 		log_error("Signal does not exist: " + params.signal + " on " + source.get_class())
 		quit(1)
+		return
 
 	if not target.has_method(params.method):
 		log_error("Method does not exist: " + params.method + " on " + target.get_class())
 		quit(1)
+		return
 
 	# CONNECT_PERSIST is required for the connection to be serialized into the
 	# packed scene; without it the connection is runtime-only and disappears on save.
@@ -721,31 +785,38 @@ func connect_signal(params):
 	if err != OK:
 		log_error("Failed to connect signal: " + str(err))
 		quit(1)
+		return
 
 	if save_scene_to_path(scene_root, params.scene_path):
 		print("Signal '" + params.signal + "' connected from '" + params.node_path + "' to '" + params.target_node_path + "." + params.method + "'")
 	else:
 		log_error("Failed to save scene after connecting signal")
 		quit(1)
+		return
 
 # Disconnect a signal connection between two nodes
 func disconnect_signal(params):
 	var scene_root = load_scene_instance(params.scene_path)
-	if not scene_root: quit(1)
+	if not scene_root:
+		quit(1)
+		return
 
 	var source = find_node_by_path(scene_root, params.node_path)
 	if not source:
 		log_error("Source node not found: " + params.node_path)
 		quit(1)
+		return
 
 	var target = find_node_by_path(scene_root, params.target_node_path)
 	if not target:
 		log_error("Target node not found: " + params.target_node_path)
 		quit(1)
+		return
 
 	if not source.is_connected(params.signal, Callable(target, params.method)):
 		log_error("Signal connection does not exist")
 		quit(1)
+		return
 
 	source.disconnect(params.signal, Callable(target, params.method))
 
@@ -754,6 +825,7 @@ func disconnect_signal(params):
 	else:
 		log_error("Failed to save scene after disconnecting signal")
 		quit(1)
+		return
 
 # ============================================
 # VALIDATE OPERATION
@@ -764,6 +836,7 @@ func validate_resource(params):
 	if not (params.has("script_path") or params.has("scene_path")):
 		log_error("validate_resource requires script_path or scene_path")
 		quit(1)
+		return
 	var result = _validate_single(params)
 	print(JSON.stringify({"valid": result.valid, "errors": result.errors}))
 
@@ -784,11 +857,20 @@ func _coerce_property_value(value):
 			return Color(value.r, value.g, value.b, a)
 	return value
 
-# Helper: collect node properties into a serializable Dictionary
-func _collect_node_properties(node: Node, changed_only: bool) -> Dictionary:
+# Helper: collect node properties into a serializable Dictionary. When
+# changed_only is true, compares each property against a default instance of
+# the node's class. The defaults_cache dict is keyed by class name so the
+# caller can reuse default instances across many nodes (caller is responsible
+# for freeing the cache when done).
+func _collect_node_properties(node: Node, changed_only: bool, defaults_cache: Dictionary) -> Dictionary:
 	var default_node = null
 	if changed_only:
-		default_node = instantiate_class(node.get_class())
+		var klass = node.get_class()
+		if defaults_cache.has(klass):
+			default_node = defaults_cache[klass]
+		else:
+			default_node = instantiate_class(klass)
+			defaults_cache[klass] = default_node
 
 	var properties = {}
 	var property_list = node.get_property_list()
@@ -823,9 +905,6 @@ func _collect_node_properties(node: Node, changed_only: bool) -> Dictionary:
 			else:
 				properties[prop_name] = str(value)
 
-	if default_node:
-		default_node.free()
-
 	return properties
 
 # Helper: validate a single target dict (script_path or scene_path)
@@ -853,50 +932,6 @@ func validate_batch(params: Dictionary) -> void:
 		results.append(_validate_single(target))
 	print(JSON.stringify({"results": results}))
 
-# Helper: add a node to a scene root without saving (returns error string or "")
-func _batch_add_node(scene_root: Node, op: Dictionary) -> String:
-	var parent_path = "root"
-	if op.has("parent_node_path"):
-		parent_path = op.parent_node_path
-	var parent = find_node_by_path(scene_root, parent_path)
-	if not parent:
-		return "Parent node not found: " + parent_path
-	if not op.has("node_type") or op.node_type == "":
-		return "node_type is required for add_node"
-	if not op.has("node_name") or op.node_name == "":
-		return "node_name is required for add_node"
-	var new_node = instantiate_class(op.node_type)
-	if not new_node:
-		return "Failed to instantiate node of type: " + op.node_type
-	new_node.name = op.node_name
-	if op.has("properties"):
-		for property in op.properties:
-			new_node.set(property, _coerce_property_value(op.properties[property]))
-	parent.add_child(new_node)
-	new_node.owner = scene_root
-	return ""
-
-# Helper: set a sprite texture without saving (returns error string or "")
-func _batch_load_sprite(scene_root: Node, op: Dictionary) -> String:
-	if not op.has("node_path") or op.node_path == "":
-		return "node_path is required for load_sprite"
-	if not op.has("texture_path") or op.texture_path == "":
-		return "texture_path is required for load_sprite"
-	var sprite_node = find_node_by_path(scene_root, op.node_path)
-	if not sprite_node:
-		return "Node not found: " + op.node_path
-	if not (sprite_node is Sprite2D or sprite_node is Sprite3D or sprite_node is TextureRect):
-		return "Node is not sprite-compatible: " + sprite_node.get_class()
-	var texture = load(normalize_scene_path(op.texture_path))
-	if not texture:
-		return "Failed to load texture: " + op.texture_path
-	if not (texture is Texture2D):
-		return "Loaded resource is not a Texture2D: " + op.texture_path
-	if texture.resource_path == "":
-		return "Texture has no resource_path — likely not imported. Open project in Godot editor once, or run 'godot --headless --editor --quit' to import assets."
-	sprite_node.texture = texture
-	return ""
-
 # Execute multiple scene operations in a single headless process
 # Scenes are loaded once and cached in memory; mutations accumulate until a save op
 func batch_scene_operations(params: Dictionary) -> void:
@@ -927,18 +962,18 @@ func batch_scene_operations(params: Dictionary) -> void:
 				if scene_root == null:
 					result["error"] = "scene_path required for add_node"
 				else:
-					var err = _batch_add_node(scene_root, op)
-					if err != "":
-						result["error"] = err
+					var apply_result = _apply_add_node(scene_root, op)
+					if not apply_result.ok:
+						result["error"] = apply_result.error
 					else:
 						result["success"] = true
 			"load_sprite":
 				if scene_root == null:
 					result["error"] = "scene_path required for load_sprite"
 				else:
-					var err = _batch_load_sprite(scene_root, op)
-					if err != "":
-						result["error"] = err
+					var apply_result = _apply_load_sprite(scene_root, op)
+					if not apply_result.ok:
+						result["error"] = apply_result.error
 					else:
 						result["success"] = true
 			"save":

package/dist/scripts/mcp_bridge.gd

@@ -6,7 +6,11 @@ extends Node
 # Wire format: 4-byte big-endian length prefix + UTF-8 JSON payload.
 # Max frame size 16 MiB; oversize frames close the offending peer.
 
-const DEFAULT_BRIDGE_PORT := 9900
+# Port is baked into this script at inject time by BridgeManager.inject — the
+# integer literal below is rewritten in the project copy. The 9900 here is the
+# source-of-truth default that ships with the script so it remains runnable
+# standalone (e.g. validate, manual debugging).
+const PORT := 9900  # MCP_BRIDGE_PORT_BAKED
 const MAX_FRAME_BYTES := 16 * 1024 * 1024
 const FRAME_HEADER_BYTES := 4
 
@@ -18,31 +22,19 @@ class PeerState:
 	var handling: bool = false   # true while a command is awaiting a response
 
 var tcp_server: TCPServer
-var port: int = DEFAULT_BRIDGE_PORT
 var session_token: String = ""
 var _peers: Array = []   # Array[PeerState]
-
-func _resolve_port() -> int:
-	var raw := OS.get_environment("MCP_BRIDGE_PORT")
-	if raw == "":
-		return DEFAULT_BRIDGE_PORT
-	if not raw.is_valid_int():
-		return DEFAULT_BRIDGE_PORT
-	var parsed := int(raw)
-	if parsed <= 0 or parsed > 65535:
-		return DEFAULT_BRIDGE_PORT
-	return parsed
+var _shutting_down: bool = false  # One-shot: set true in shutdown(); never reset (autoload is recreated on next session)
 
 func _ready() -> void:
 	process_mode = Node.PROCESS_MODE_ALWAYS
 	session_token = OS.get_environment("MCP_SESSION_TOKEN")
-	port = _resolve_port()
 	tcp_server = TCPServer.new()
-	var err = tcp_server.listen(port, "127.0.0.1")
+	var err = tcp_server.listen(PORT, "127.0.0.1")
 	if err != OK:
-		push_error("McpBridge: Failed to listen on port %d (error %d)" % [port, err])
+		push_error("McpBridge: Failed to listen on port %d (error %d)" % [PORT, err])
 	else:
-		print("McpBridge: Listening on TCP port %d" % port)
+		print("McpBridge: Listening on TCP port %d" % PORT)
 
 	if OS.get_environment("MCP_BACKGROUND") == "1":
 		DisplayServer.window_set_flag(DisplayServer.WINDOW_FLAG_NO_FOCUS, true)
@@ -64,15 +56,15 @@ func _process(_delta: float) -> void:
 		peer.stream = stream
 		_peers.append(peer)
 
-	var dead: Array = []
-	for peer in _peers:
+	# Backwards iteration so remove_at() doesn't shift entries we haven't seen
+	# yet, and avoids the O(n) cost of Array.erase() per removal.
+	var i := _peers.size()
+	while i > 0:
+		i -= 1
+		var peer = _peers[i]
 		_poll_peer(peer)
 		if peer.stream == null or peer.stream.get_status() != StreamPeerTCP.STATUS_CONNECTED:
-			dead.append(peer)
-
-	if not dead.is_empty():
-		for peer in dead:
-			_peers.erase(peer)
+			_peers.remove_at(i)
 
 func _poll_peer(peer: PeerState) -> void:
 	peer.stream.poll()
@@ -591,6 +583,7 @@ func _serialize_value(value: Variant) -> Variant:
 # --- Shutdown ---
 
 func _handle_shutdown(peer: PeerState) -> void:
+	_shutting_down = true
 	_send_response(peer, {"status": "shutting_down"})
 	# Let the response flush before we tear the listener down. A new command
 	# arriving in this 2-frame window would dispatch against a peer that's
@@ -633,6 +626,8 @@ func _close_all_peers() -> void:
 	_peers.clear()
 
 func _exit_tree() -> void:
+	if not _shutting_down:
+		push_warning("McpBridge: removed from tree without shutdown — bridge connection will be lost")
 	_close_all_peers()
 	if tcp_server != null:
 		tcp_server.stop()