mcpforunityserver 8.7.1__py3-none-any.whl → 9.0.1__py3-none-any.whl

services/tools/utils.py

@@ -8,6 +8,7 @@ from typing import Any
 _TRUTHY = {"true", "1", "yes", "on"}
 _FALSY = {"false", "0", "no", "off"}
 
+
 def coerce_bool(value: Any, default: bool | None = None) -> bool | None:
     """Attempt to coerce a loosely-typed value to a boolean."""
     if value is None:
@@ -27,26 +28,26 @@ def coerce_bool(value: Any, default: bool | None = None) -> bool | None:
 def parse_json_payload(value: Any) -> Any:
     """
     Attempt to parse a value that might be a JSON string into its native object.
-    
+
     This is a tolerant parser used to handle cases where MCP clients or LLMs
     serialize complex objects (lists, dicts) into strings. It also handles
     scalar values like numbers, booleans, and null.
-    
+
     Args:
         value: The input value (can be str, list, dict, etc.)
-        
+
     Returns:
         The parsed JSON object/list if the input was a valid JSON string,
         or the original value if parsing failed or wasn't necessary.
     """
     if not isinstance(value, str):
         return value
-        
+
     val_trimmed = value.strip()
-    
+
     # Fast path: if it doesn't look like JSON structure, return as is
     if not (
-        (val_trimmed.startswith("{") and val_trimmed.endswith("}")) or 
+        (val_trimmed.startswith("{") and val_trimmed.endswith("}")) or
         (val_trimmed.startswith("[") and val_trimmed.endswith("]")) or
         val_trimmed in ("true", "false", "null") or
         (val_trimmed.replace(".", "", 1).replace("-", "", 1).isdigit())
@@ -75,3 +76,56 @@ def coerce_int(value: Any, default: int | None = None) -> int | None:
         return int(float(s))
     except Exception:
         return default
+
+
+def coerce_float(value: Any, default: float | None = None) -> float | None:
+    """Attempt to coerce a loosely-typed value to a float-like number."""
+    if value is None:
+        return default
+    try:
+        # Treat booleans as invalid numeric input instead of coercing to 0/1.
+        if isinstance(value, bool):
+            return default
+        if isinstance(value, (int, float)):
+            return float(value)
+        s = str(value).strip()
+        if s.lower() in ("", "none", "null"):
+            return default
+        return float(s)
+    except (TypeError, ValueError):
+        return default
+
+
+def normalize_properties(value: Any) -> tuple[dict[str, Any] | None, str | None]:
+    """
+    Robustly normalize a properties parameter to a dict.
+
+    Handles various input formats from MCP clients/LLMs:
+    - None -> (None, None)
+    - dict -> (dict, None)
+    - JSON string -> (parsed_dict, None) or (None, error_message)
+    - Invalid values -> (None, error_message)
+
+    Returns:
+        Tuple of (parsed_dict, error_message). If error_message is set, parsed_dict is None.
+    """
+    if value is None:
+        return None, None
+
+    # Already a dict - return as-is
+    if isinstance(value, dict):
+        return value, None
+
+    # Try parsing as string
+    if isinstance(value, str):
+        # Check for obviously invalid values from serialization bugs
+        if value in ("[object Object]", "undefined", "null", ""):
+            return None, f"properties received invalid value: '{value}'. Expected a JSON object like {{\"key\": value}}"
+
+        parsed = parse_json_payload(value)
+        if isinstance(parsed, dict):
+            return parsed, None
+
+        return None, f"properties must be a JSON object (dict), got string that parsed to {type(parsed).__name__}"
+
+    return None, f"properties must be a dict or JSON string, got {type(value).__name__}"

transport/legacy/port_discovery.py

@@ -279,9 +279,9 @@ class PortDiscovery:
                     if freshness.tzinfo:
                         from datetime import timezone
                         now = datetime.now(timezone.utc)
-                    
+
                     age_s = (now - freshness).total_seconds()
-                    
+
                     if is_reloading and age_s < 60:
                         pass  # keep it, status="reloading"
                     else:

transport/legacy/unity_connection.py

@@ -584,7 +584,7 @@ class UnityConnectionPool:
         raise ConnectionError(
             f"Unity instance '{identifier}' not found. "
             f"Available instances: {available_ids}. "
-            f"Check unity://instances resource for all instances."
+            f"Check mcpforunity://instances resource for all instances."
         )
 
     def get_connection(self, instance_identifier: str | None = None) -> UnityConnection:

transport/plugin_hub.py

@@ -45,10 +45,14 @@ class PluginHub(WebSocketEndpoint):
     KEEP_ALIVE_INTERVAL = 15
     SERVER_TIMEOUT = 30
     COMMAND_TIMEOUT = 30
+    # Timeout (seconds) for fast-fail commands like ping/read_console/get_editor_state.
+    # Keep short so MCP clients aren't blocked during Unity compilation/reload/unfocused throttling.
+    FAST_FAIL_TIMEOUT = 2.0
     # Fast-path commands should never block the client for long; return a retry hint instead.
     # This helps avoid the Cursor-side ~30s tool-call timeout when Unity is compiling/reloading
     # or is throttled while unfocused.
-    _FAST_FAIL_COMMANDS: set[str] = {"read_console", "get_editor_state", "ping"}
+    _FAST_FAIL_COMMANDS: set[str] = {
+        "read_console", "get_editor_state", "ping"}
 
     _registry: PluginRegistry | None = None
     _connections: dict[str, WebSocket] = {}
@@ -118,7 +122,8 @@ class PluginHub(WebSocketEndpoint):
                 ]
                 for command_id in pending_ids:
                     entry = cls._pending.get(command_id)
-                    future = entry.get("future") if isinstance(entry, dict) else None
+                    future = entry.get("future") if isinstance(
+                        entry, dict) else None
                     if future and not future.done():
                         future.set_exception(
                             PluginDisconnectedError(
@@ -140,18 +145,15 @@ class PluginHub(WebSocketEndpoint):
         future: asyncio.Future = asyncio.get_running_loop().create_future()
         # Compute a per-command timeout:
         # - fast-path commands: short timeout (encourage retry)
-        # - long-running commands (e.g., run_tests): allow caller to request a longer timeout via params
+        # - long-running commands: allow caller to request a longer timeout via params
         unity_timeout_s = float(cls.COMMAND_TIMEOUT)
         server_wait_s = float(cls.COMMAND_TIMEOUT)
         if command_type in cls._FAST_FAIL_COMMANDS:
-            try:
-                fast_timeout = float(os.environ.get("UNITY_MCP_FAST_COMMAND_TIMEOUT", "3"))
-            except Exception:
-                fast_timeout = 3.0
+            fast_timeout = float(cls.FAST_FAIL_TIMEOUT)
             unity_timeout_s = fast_timeout
             server_wait_s = fast_timeout
         else:
-            # Common tools pass a requested timeout in seconds (e.g., run_tests(timeout_seconds=900)).
+            # Common tools pass a requested timeout in seconds (e.g., timeout_seconds=900).
             requested = None
             try:
                 if isinstance(params, dict):
@@ -180,7 +182,8 @@ class PluginHub(WebSocketEndpoint):
             if command_id in cls._pending:
                 raise RuntimeError(
                     f"Duplicate command id generated: {command_id}")
-            cls._pending[command_id] = {"future": future, "session_id": session_id}
+            cls._pending[command_id] = {
+                "future": future, "session_id": session_id}
 
         try:
             msg = ExecuteCommandMessage(
@@ -370,7 +373,8 @@ class PluginHub(WebSocketEndpoint):
             max_wait_s = float(
                 os.environ.get("UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S", "2.0"))
         except ValueError as e:
-            raw_val = os.environ.get("UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S", "2.0")
+            raw_val = os.environ.get(
+                "UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S", "2.0")
             logger.warning(
                 "Invalid UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S=%r, using default 2.0: %s",
                 raw_val, e)
@@ -416,7 +420,7 @@ class PluginHub(WebSocketEndpoint):
             if not target_hash and session_count > 1:
                 raise RuntimeError(
                     "Multiple Unity instances are connected. "
-                    "Call set_active_instance with Name@hash from unity://instances."
+                    "Call set_active_instance with Name@hash from mcpforunity://instances."
                 )
             if wait_started is None:
                 wait_started = time.monotonic()
@@ -437,7 +441,7 @@ class PluginHub(WebSocketEndpoint):
         if session_id is None and not target_hash and session_count > 1:
             raise RuntimeError(
                 "Multiple Unity instances are connected. "
-                "Call set_active_instance with Name@hash from unity://instances."
+                "Call set_active_instance with Name@hash from mcpforunity://instances."
             )
 
         if session_id is None:
@@ -448,7 +452,8 @@ class PluginHub(WebSocketEndpoint):
             )
             # At this point we've given the plugin ample time to reconnect; surface
             # a clear error so the client can prompt the user to open Unity.
-            raise NoUnitySessionError("No Unity plugins are currently connected")
+            raise NoUnitySessionError(
+                "No Unity plugins are currently connected")
 
         return session_id
 
@@ -481,9 +486,11 @@ class PluginHub(WebSocketEndpoint):
         # register_tools (which can be delayed by EditorApplication.delayCall).
         if command_type in cls._FAST_FAIL_COMMANDS and command_type != "ping":
             try:
-                max_wait_s = float(os.environ.get("UNITY_MCP_SESSION_READY_WAIT_SECONDS", "6"))
+                max_wait_s = float(os.environ.get(
+                    "UNITY_MCP_SESSION_READY_WAIT_SECONDS", "6"))
             except ValueError as e:
-                raw_val = os.environ.get("UNITY_MCP_SESSION_READY_WAIT_SECONDS", "6")
+                raw_val = os.environ.get(
+                    "UNITY_MCP_SESSION_READY_WAIT_SECONDS", "6")
                 logger.warning(
                     "Invalid UNITY_MCP_SESSION_READY_WAIT_SECONDS=%r, using default 6.0: %s",
                     raw_val, e)
@@ -499,7 +506,8 @@ class PluginHub(WebSocketEndpoint):
 
                     # The Unity-side dispatcher responds with {status:"success", result:{message:"pong"}}
                     if isinstance(probe, dict) and probe.get("status") == "success":
-                        result = probe.get("result") if isinstance(probe.get("result"), dict) else {}
+                        result = probe.get("result") if isinstance(
+                            probe.get("result"), dict) else {}
                         if result.get("message") == "pong":
                             break
                     await asyncio.sleep(0.1)

transport/unity_instance_middleware.py

@@ -27,7 +27,7 @@ def get_unity_instance_middleware() -> 'UnityInstanceMiddleware':
             if _unity_instance_middleware is None:
                 # Auto-initialize if not set (lazy singleton) to handle import order or test cases
                 _unity_instance_middleware = UnityInstanceMiddleware()
-        
+
     return _unity_instance_middleware
 
 
@@ -102,7 +102,8 @@ class UnityInstanceMiddleware(Middleware):
                     sessions = sessions_data.sessions or {}
                     ids: list[str] = []
                     for session_info in sessions.values():
-                        project = getattr(session_info, "project", None) or "Unknown"
+                        project = getattr(
+                            session_info, "project", None) or "Unknown"
                         hash_value = getattr(session_info, "hash", None)
                         if hash_value:
                             ids.append(f"{project}@{hash_value}")
@@ -183,7 +184,7 @@ class UnityInstanceMiddleware(Middleware):
             # But for stdio transport (no PluginHub needed or maybe partially configured),
             # we should be careful not to clear instance just because PluginHub can't resolve it.
             # The 'active_instance' (Name@hash) might be valid for stdio even if PluginHub fails.
-            
+
             session_id: str | None = None
             # Only validate via PluginHub if we are actually using HTTP transport
             # OR if we want to support hybrid mode. For now, let's be permissive.

transport/unity_transport.py

@@ -105,7 +105,8 @@ async def send_with_unity_instance(
             # Fail fast with a retry hint instead of hanging for COMMAND_TIMEOUT.
             # The client can decide whether retrying is appropriate for the command.
             return normalize_unity_response(
-                MCPResponse(success=False, error=err, hint="retry").model_dump()
+                MCPResponse(success=False, error=err,
+                            hint="retry").model_dump()
             )
 
     if unity_instance:

mcpforunityserver-8.7.1.dist-info/RECORD

@@ -1,71 +0,0 @@
-__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-main.py,sha256=ITxelXUAmr9BoasG0knZifXKp3lWJyml_RLaIwvEyVs,19184
-core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-core/config.py,sha256=czkTtNji1crQcQbUvmdx4OL7f-RBqkVhj_PtHh-w7rs,1623
-core/logging_decorator.py,sha256=D9CD7rFvQz-MBG-G4inizQj0Ivr6dfc9RBmTrw7q8mI,1383
-core/telemetry.py,sha256=eHjYgzd8f7eTwSwF2Kbi8D4TtJIcdaDjKLeo1c-0hVA,19829
-core/telemetry_decorator.py,sha256=ycSTrzVNCDQHSd-xmIWOpVfKFURPxpiZe_XkOQAGDAo,6705
-mcpforunityserver-8.7.1.dist-info/licenses/LICENSE,sha256=bv5lDJZQEqxBgjjc1rkRbkEwpSIHF-8N-1Od0VnEJFw,1066
-models/__init__.py,sha256=JlscZkGWE9TRmSoBi99v_LSl8OAFNGmr8463PYkXin4,179
-models/models.py,sha256=heXuvdBtdats1SGwW8wKFFHM0qR4hA6A7qETn5s9BZ0,1827
-models/unity_response.py,sha256=oJ1PTsnNc5VBC-9OgM59C0C-R9N-GdmEdmz_yph4GSU,1454
-routes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-services/custom_tool_service.py,sha256=ZOb6LsOQc3C9n3iLn5b7QaG3WJ25M-Id3WG_iE1YhMY,11960
-services/registry/__init__.py,sha256=QCwcYThvGF0kBt3WR6DBskdyxkegJC7NymEChgJA-YM,470
-services/registry/resource_registry.py,sha256=T_Kznqgvt5kKgV7mU85nb0LlFuB4rg-Tm4Cjhxt-IcI,1467
-services/registry/tool_registry.py,sha256=9tMwOP07JE92QFYUS4KvoysO0qC9pkBD5B79kjRsSPw,1304
-services/resources/__init__.py,sha256=O5heeMcgCswnQX1qG2nNtMeAZIaLut734qD7t5UsA0k,2801
-services/resources/active_tool.py,sha256=YTbsiy_hmnKH2q7IoM7oYD7pJkoveZTszRiL1PlhO9M,1474
-services/resources/custom_tools.py,sha256=8lyryGhN3vD2LwMt6ZyKIp5ONtxdI1nfcCAlYjlfQnQ,1704
-services/resources/editor_state.py,sha256=8hrNnskSFdsvdKagAYEeZGJ0Oz9QRlkWJjpM4q0XeNo,2013
-services/resources/editor_state_v2.py,sha256=zgss1EEhJo7oZeHnjOXsdJPuFQsHLwpsZmzcDy3ybq0,10874
-services/resources/layers.py,sha256=q4UQ5PUVUVhmM5l3oXID1wa_wOWAS8l5BGXadBgFuwY,1080
-services/resources/menu_items.py,sha256=9SNycjwTXoeS1ZHra0Y1fTyCjSEdPCo34JyxtuqauG8,1021
-services/resources/prefab_stage.py,sha256=C3mn3UapKYVOA8QUNmLsYreG5YiXdlvGm9ypHQeKBeQ,1382
-services/resources/project_info.py,sha256=gSVSFfwP0u2FmxSowOkdbNoSSQHxfQtLfndvoCXTVSw,1323
-services/resources/selection.py,sha256=4rI5Bdkes4uxtMc_5jQhUaqUl-iprhIiTWqnOJl8tmg,1839
-services/resources/tags.py,sha256=7EhmQjMotz85DSSr7cVKYIy7LPT5mmPfrEySr1mTE6w,1049
-services/resources/tests.py,sha256=xDvvgesPSU93nLD_ERQopOpkpq69pbMEqmFsJd0jekI,2063
-services/resources/unity_instances.py,sha256=fR0cVopGQnmF41IFDycwlo2XniKstfJWLGobgJeiabE,4348
-services/resources/windows.py,sha256=--QVsb0oyoBpSjK2D4kPcZFSe2zdR-t_KSHP-e2QNoY,1427
-services/state/external_changes_scanner.py,sha256=qwdiriHR1D11aPiLUbpS7COXtfVOjNj9DpzcSDK067o,9042
-services/tools/__init__.py,sha256=3Qav7fAowZ1_TbDRdZQQQES53gv2lTs-2D7PGECnlbM,2353
-services/tools/batch_execute.py,sha256=_ByjffeXQB9j64mcjaxJmrnbSJrMn0f9_6Zh9BBI_2c,2898
-services/tools/debug_request_context.py,sha256=WQBtQdXSH5stw2MAwIM32H6jGwUVQOgU2r35VUWLlYo,2765
-services/tools/execute_custom_tool.py,sha256=K2qaO4-FTPz0_3j53hhDP9idjC002ugc8C03FtHGTbY,1376
-services/tools/execute_menu_item.py,sha256=FAC-1v_TwOcy6GSxkogDsVxeRtdap0DsPlIngf8uJdU,1184
-services/tools/find_in_file.py,sha256=xp80lqRN2cdZc3XGJWlCpeQEy6WnwyKOj2l5WiHNx0Q,6379
-services/tools/manage_asset.py,sha256=6YjWOl2b58vRwjp-9XbQE9e1l3ajhGookVY8ncQN0wo,7877
-services/tools/manage_editor.py,sha256=_HZRT-_hBakH0g6p7BpxTv3gWpxsaV6KNGRol-qknwo,3243
-services/tools/manage_gameobject.py,sha256=OgFIsoPGiWHOj6-d3Lmtp3xlAW9Tr0c38tV4atAaFAU,14400
-services/tools/manage_material.py,sha256=wZB2H4orhL6wG9TTnmnk-Lj2Gj_zvg7koxW3t319BLU,3545
-services/tools/manage_prefabs.py,sha256=73XzznjFNOm1SazW_Y7l6uGIE7wosMpAIVQs8xpvK9A,3037
-services/tools/manage_scene.py,sha256=oJ1qDX0T06mINZ1hX2AcDp3ItHo-oUz7Uck0yujI9eA,4834
-services/tools/manage_script.py,sha256=lPA5HcS4Al0RiQVz-S6qahFTcPqsk3GSLLXJWHri8P4,27557
-services/tools/manage_scriptable_object.py,sha256=Oi03CJLgepaWR59V-nJiAjnCC8at4YqFhRGpACruqgw,3150
-services/tools/manage_shader.py,sha256=HHnHKh7vLij3p8FAinNsPdZGEKivgwSUTxdgDydfmbs,2882
-services/tools/preflight.py,sha256=VJn61h-9pvoVaCyKL7DTKLfbpoZfNK4fnRmj91c2o8M,4093
-services/tools/read_console.py,sha256=ELryGXGhZi56pqe4cSdrNDaZGBlUydQIeJ5q86fq_Uo,5201
-services/tools/refresh_unity.py,sha256=xlmqMeAxmYEa5l4OduYdDYWSKJPm2QoJg5CrxCJY8_A,3859
-services/tools/run_tests.py,sha256=8CqmgRN6Bata666ytF_S9no4gaFmHCmeZM82ZwNQJ68,4666
-services/tools/script_apply_edits.py,sha256=qPm_PsmsK3mYXnziX_btyk8CaB66LTqpDFA2Y4ebZ4U,47504
-services/tools/set_active_instance.py,sha256=B18Y8Jga0pKsx9mFywXr1tWfy0cJVopIMXYO-UJ1jOU,4136
-services/tools/test_jobs.py,sha256=K6HjkzWPjJNldrp-Vq5gPH7oBkCq_sJZYXkK_Vg6I_I,4059
-services/tools/utils.py,sha256=4ZgfIu178eXZqRyzs8X77B5lKLP1f73OZoGBSDNokJ4,2409
-transport/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-transport/models.py,sha256=6wp7wsmSaeeJEvUGXPF1m6zuJnxJ1NJlCC4YZ9oQIq0,1226
-transport/plugin_hub.py,sha256=77xYWunNw8hHRJuimx3Qrxu9wqlKURpuunkUqkqx9kE,22845
-transport/plugin_registry.py,sha256=nW-7O7PN0QUgSWivZTkpAVKKq9ZOe2b2yeIdpaNt_3I,4359
-transport/unity_instance_middleware.py,sha256=kf1QeA138r7PaC98dcMDYtUPGWZ4EUmZGESc2DdiWQs,10429
-transport/unity_transport.py,sha256=_cFVgD3pzFZRcDXANq4oPFYSoI6jntSGaN22dJC8LRU,3880
-transport/legacy/port_discovery.py,sha256=qM_mtndbYjAj4qPSZEWVeXFOt5_nKczG9pQqORXTBJ0,12768
-transport/legacy/stdio_port_registry.py,sha256=j4iARuP6wetppNDG8qKeuvo1bJKcSlgEhZvSyl_uf0A,2313
-transport/legacy/unity_connection.py,sha256=psMwMDiUXKUSrpP4UO9Lgu5PH-Mu6QPY-r5o81WIkVg,35802
-utils/module_discovery.py,sha256=My48ofB1BUqxiBoAZAGbEaLQYdsrDhMm8MayBP_bUSQ,2005
-utils/reload_sentinel.py,sha256=s1xMWhl-r2XwN0OUbiUv_VGUy8TvLtV5bkql-5n2DT0,373
-mcpforunityserver-8.7.1.dist-info/METADATA,sha256=OzxsNyocEXg1K-ND-AesGUKXM8pQx_7CGUrW_XsKXMg,5712
-mcpforunityserver-8.7.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mcpforunityserver-8.7.1.dist-info/entry_points.txt,sha256=vCtkqw-J9t4pj7JwUZcB54_keVx7DpAR3fYzK6i-s6g,44
-mcpforunityserver-8.7.1.dist-info/top_level.txt,sha256=YKU5e5dREMfCnoVpmlsTm9bku7oqnrzSZ9FeTgjoxJw,58
-mcpforunityserver-8.7.1.dist-info/RECORD,,

services/resources/editor_state_v2.py

@@ -1,270 +0,0 @@
-import time
-import os
-from typing import Any
-
-from fastmcp import Context
-
-from models import MCPResponse
-from services.registry import mcp_for_unity_resource
-from services.tools import get_unity_instance_from_context
-import transport.unity_transport as unity_transport
-from transport.legacy.unity_connection import async_send_command_with_retry
-from services.state.external_changes_scanner import external_changes_scanner
-
-
-def _now_unix_ms() -> int:
-    return int(time.time() * 1000)
-
-
-def _in_pytest() -> bool:
-    # Avoid instance-discovery side effects during the Python integration test suite.
-    return bool(os.environ.get("PYTEST_CURRENT_TEST"))
-
-
-async def _infer_single_instance_id(ctx: Context) -> str | None:
-    """
-    Best-effort: if exactly one Unity instance is connected, return its Name@hash id.
-    This makes editor_state outputs self-describing even when no explicit active instance is set.
-    """
-    if _in_pytest():
-        return None
-
-    try:
-        transport = unity_transport._current_transport()
-    except Exception:
-        transport = None
-
-    if transport == "http":
-        # HTTP/WebSocket transport: derive from PluginHub sessions.
-        try:
-            from transport.plugin_hub import PluginHub
-
-            sessions_data = await PluginHub.get_sessions()
-            sessions = sessions_data.sessions if hasattr(sessions_data, "sessions") else {}
-            if isinstance(sessions, dict) and len(sessions) == 1:
-                session = next(iter(sessions.values()))
-                project = getattr(session, "project", None)
-                project_hash = getattr(session, "hash", None)
-                if project and project_hash:
-                    return f"{project}@{project_hash}"
-        except Exception:
-            return None
-        return None
-
-    # Stdio/TCP transport: derive from connection pool discovery.
-    try:
-        from transport.legacy.unity_connection import get_unity_connection_pool
-
-        pool = get_unity_connection_pool()
-        instances = pool.discover_all_instances(force_refresh=False)
-        if isinstance(instances, list) and len(instances) == 1:
-            inst = instances[0]
-            inst_id = getattr(inst, "id", None)
-            return str(inst_id) if inst_id else None
-    except Exception:
-        return None
-    return None
-
-
-def _build_v2_from_legacy(legacy: dict[str, Any]) -> dict[str, Any]:
-    """
-    Best-effort mapping from legacy get_editor_state payload into the v2 contract.
-    Legacy shape (Unity): {isPlaying,isPaused,isCompiling,isUpdating,timeSinceStartup,...}
-    """
-    now_ms = _now_unix_ms()
-    # legacy may arrive already wrapped as MCPResponse-like {success,data:{...}}
-    state = legacy.get("data") if isinstance(legacy.get("data"), dict) else {}
-
-    return {
-        "schema_version": "unity-mcp/editor_state@2",
-        "observed_at_unix_ms": now_ms,
-        "sequence": 0,
-        "unity": {
-            "instance_id": None,
-            "unity_version": None,
-            "project_id": None,
-            "platform": None,
-            "is_batch_mode": None,
-        },
-        "editor": {
-            "is_focused": None,
-            "play_mode": {
-                "is_playing": bool(state.get("isPlaying", False)),
-                "is_paused": bool(state.get("isPaused", False)),
-                "is_changing": None,
-            },
-            "active_scene": {
-                "path": None,
-                "guid": None,
-                "name": state.get("activeSceneName", "") or "",
-            },
-            "selection": {
-                "count": int(state.get("selectionCount", 0) or 0),
-                "active_object_name": state.get("activeObjectName", None),
-            },
-        },
-        "activity": {
-            "phase": "unknown",
-            "since_unix_ms": now_ms,
-            "reasons": ["legacy_fallback"],
-        },
-        "compilation": {
-            "is_compiling": bool(state.get("isCompiling", False)),
-            "is_domain_reload_pending": None,
-            "last_compile_started_unix_ms": None,
-            "last_compile_finished_unix_ms": None,
-        },
-        "assets": {
-            "is_updating": bool(state.get("isUpdating", False)),
-            "external_changes_dirty": False,
-            "external_changes_last_seen_unix_ms": None,
-            "refresh": {
-                "is_refresh_in_progress": False,
-                "last_refresh_requested_unix_ms": None,
-                "last_refresh_finished_unix_ms": None,
-            },
-        },
-        "tests": {
-            "is_running": False,
-            "mode": None,
-            "started_unix_ms": None,
-            "started_by": "unknown",
-            "last_run": None,
-        },
-        "transport": {
-            "unity_bridge_connected": None,
-            "last_message_unix_ms": None,
-        },
-    }
-
-
-def _enrich_advice_and_staleness(state_v2: dict[str, Any]) -> dict[str, Any]:
-    now_ms = _now_unix_ms()
-    observed = state_v2.get("observed_at_unix_ms")
-    try:
-        observed_ms = int(observed)
-    except Exception:
-        observed_ms = now_ms
-
-    age_ms = max(0, now_ms - observed_ms)
-    # Conservative default: treat >2s as stale (covers common unfocused-editor throttling).
-    is_stale = age_ms > 2000
-
-    compilation = state_v2.get("compilation") or {}
-    tests = state_v2.get("tests") or {}
-    assets = state_v2.get("assets") or {}
-    refresh = (assets.get("refresh") or {}) if isinstance(assets, dict) else {}
-
-    blocking: list[str] = []
-    if compilation.get("is_compiling") is True:
-        blocking.append("compiling")
-    if compilation.get("is_domain_reload_pending") is True:
-        blocking.append("domain_reload")
-    if tests.get("is_running") is True:
-        blocking.append("running_tests")
-    if refresh.get("is_refresh_in_progress") is True:
-        blocking.append("asset_refresh")
-    if is_stale:
-        blocking.append("stale_status")
-
-    ready_for_tools = len(blocking) == 0
-
-    state_v2["advice"] = {
-        "ready_for_tools": ready_for_tools,
-        "blocking_reasons": blocking,
-        "recommended_retry_after_ms": 0 if ready_for_tools else 500,
-        "recommended_next_action": "none" if ready_for_tools else "retry_later",
-    }
-    state_v2["staleness"] = {"age_ms": age_ms, "is_stale": is_stale}
-    return state_v2
-
-
-@mcp_for_unity_resource(
-    uri="unity://editor_state",
-    name="editor_state_v2",
-    description="Canonical editor readiness snapshot (v2). Includes advice and server-computed staleness.",
-)
-async def get_editor_state_v2(ctx: Context) -> MCPResponse:
-    unity_instance = get_unity_instance_from_context(ctx)
-
-    # Try v2 snapshot first (Unity-side cache will make this fast once implemented).
-    response = await unity_transport.send_with_unity_instance(
-        async_send_command_with_retry,
-        unity_instance,
-        "get_editor_state_v2",
-        {},
-    )
-
-    # If Unity returns a structured retry hint or error, surface it directly.
-    if isinstance(response, dict) and not response.get("success", True):
-        return MCPResponse(**response)
-
-    # If v2 is unavailable (older plugin), fall back to legacy get_editor_state and map.
-    if not (isinstance(response, dict) and isinstance(response.get("data"), dict) and response["data"].get("schema_version")):
-        legacy = await unity_transport.send_with_unity_instance(
-            async_send_command_with_retry,
-            unity_instance,
-            "get_editor_state",
-            {},
-        )
-        if isinstance(legacy, dict) and not legacy.get("success", True):
-            return MCPResponse(**legacy)
-        state_v2 = _build_v2_from_legacy(legacy if isinstance(legacy, dict) else {})
-    else:
-        state_v2 = response.get("data") if isinstance(response.get("data"), dict) else {}
-        # Ensure required v2 marker exists even if Unity returns partial.
-        state_v2.setdefault("schema_version", "unity-mcp/editor_state@2")
-        state_v2.setdefault("observed_at_unix_ms", _now_unix_ms())
-        state_v2.setdefault("sequence", 0)
-
-    # Ensure the returned snapshot is clearly associated with the targeted instance.
-    # (This matters when multiple Unity instances are connected and the client is polling readiness.)
-    unity_section = state_v2.get("unity")
-    if not isinstance(unity_section, dict):
-        unity_section = {}
-        state_v2["unity"] = unity_section
-    current_instance_id = unity_section.get("instance_id")
-    if current_instance_id in (None, ""):
-        if unity_instance:
-            unity_section["instance_id"] = unity_instance
-        else:
-            inferred = await _infer_single_instance_id(ctx)
-            if inferred:
-                unity_section["instance_id"] = inferred
-
-    # External change detection (server-side): compute per instance based on project root path.
-    # This helps detect stale assets when external tools edit the filesystem.
-    try:
-        instance_id = unity_section.get("instance_id")
-        if isinstance(instance_id, str) and instance_id.strip():
-            from services.resources.project_info import get_project_info
-
-            # Cache the project root for this instance (best-effort).
-            proj_resp = await get_project_info(ctx)
-            proj = proj_resp.model_dump() if hasattr(proj_resp, "model_dump") else proj_resp
-            proj_data = proj.get("data") if isinstance(proj, dict) else None
-            project_root = proj_data.get("projectRoot") if isinstance(proj_data, dict) else None
-            if isinstance(project_root, str) and project_root.strip():
-                external_changes_scanner.set_project_root(instance_id, project_root)
-
-            ext = external_changes_scanner.update_and_get(instance_id)
-
-            assets = state_v2.get("assets")
-            if not isinstance(assets, dict):
-                assets = {}
-                state_v2["assets"] = assets
-            # IMPORTANT: Unity's cached snapshot may include placeholder defaults; the server scanner is authoritative
-            # for external changes (filesystem edits outside Unity). Always overwrite these fields from the scanner.
-            assets["external_changes_dirty"] = bool(ext.get("external_changes_dirty", False))
-            assets["external_changes_last_seen_unix_ms"] = ext.get("external_changes_last_seen_unix_ms")
-            # Extra bookkeeping fields (server-only) are safe to add under assets.
-            assets["external_changes_dirty_since_unix_ms"] = ext.get("dirty_since_unix_ms")
-            assets["external_changes_last_cleared_unix_ms"] = ext.get("last_cleared_unix_ms")
-    except Exception:
-        # Best-effort; do not fail readiness resource if filesystem scan can't run.
-        pass
-
-    state_v2 = _enrich_advice_and_staleness(state_v2)
-    return MCPResponse(success=True, message="Retrieved editor state (v2).", data=state_v2)
-
-