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

main.py

@@ -30,7 +30,8 @@ try:  # pragma: no cover - startup safety guard
     )
     for _name in _typing_names:
         if not hasattr(builtins, _name) and hasattr(_typing, _name):
-            setattr(builtins, _name, getattr(_typing, _name))  # type: ignore[attr-defined]
+            # type: ignore[attr-defined]
+            setattr(builtins, _name, getattr(_typing, _name))
 except Exception:
     pass
 
@@ -234,10 +235,10 @@ mcp = FastMCP(
     instructions="""
 This server provides tools to interact with the Unity Game Engine Editor.
 
-I have a dynamic tool system. Always check the unity://custom-tools resource first to see what special capabilities are available for the current project.
+I have a dynamic tool system. Always check the mcpforunity://custom-tools resource first to see what special capabilities are available for the current project.
 
 Targeting Unity instances:
-- Use the resource unity://instances to list active Unity sessions (Name@hash).
+- Use the resource mcpforunity://instances to list active Unity sessions (Name@hash).
 - When multiple instances are connected, call set_active_instance with the exact Name@hash before using tools/resources. The server will error if multiple are connected and no active instance is set.
 
 Important Workflows:

{mcpforunityserver-8.7.1.dist-info → mcpforunityserver-9.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpforunityserver
-Version: 8.7.1
+Version: 9.0.0
 Summary: MCP for Unity Server: A Unity package for Unity Editor integration via the Model Context Protocol (MCP).
 Author-email: Marcus Sanatan <msanatan@gmail.com>, David Sarno <david.sarno@gmail.com>, Wu Shutong <martinwfire@gmail.com>
 License-Expression: MIT
@@ -108,7 +108,7 @@ Use this to run the latest released version from the repository. Change the vers
       "command": "uvx",
       "args": [
         "--from",
-        "git+https://github.com/CoplayDev/unity-mcp@v8.7.1#subdirectory=Server",
+        "git+https://github.com/CoplayDev/unity-mcp@v9.0.0#subdirectory=Server",
         "mcp-for-unity",
         "--transport",
         "stdio"

mcpforunityserver-9.0.0.dist-info/RECORD

@@ -0,0 +1,72 @@
+__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+main.py,sha256=2JiIIoWXnhEhEOg-YN-KWNG-tB_uGscR1U7dK_hQO88,19207
+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-9.0.0.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
+services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+services/custom_tool_service.py,sha256=VYqKcP0BZLTo9SGyNMtoLhFbzRlF8oCeMjeNdTScJiU,12320
+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=zDuWRK1uz853TrMNv0w8vhZVOxemDPoI4QAkXSIezN8,1480
+services/resources/custom_tools.py,sha256=3t0mKAL9PkJbv8S4DpRFU8D-NlRWkCd2geO6QnlQo7I,1716
+services/resources/editor_state.py,sha256=pQdcsWGcKV7-6icpcVXtFD35CHUXodANc0jXkljVdLs,10823
+services/resources/gameobject.py,sha256=RM28kfsV208zdTy-549U2_nwSPiAHYo6SqXy22k4tC8,9116
+services/resources/layers.py,sha256=wE-mSgZsknGrXKu-0Cppv6NeijszD7beFf88dizT0ZI,1086
+services/resources/menu_items.py,sha256=9SNycjwTXoeS1ZHra0Y1fTyCjSEdPCo34JyxtuqauG8,1021
+services/resources/prefab_stage.py,sha256=RyVskG-P9lb4szbsTDhPpyDMb0ptLskr0BnoYJylhw0,1388
+services/resources/project_info.py,sha256=ggiUj9rJUvIddxorKu9yqJiHTWOnxyywkjjsKXhIyqA,1329
+services/resources/selection.py,sha256=MALwKkM9xsKing2bALNVTVLWzDTE_b26EVbnVUGZivU,1845
+services/resources/tags.py,sha256=IKZWiZhBO_HkJqFXqBvWeIcMxhGN_QXkonzuAEFsEfg,1055
+services/resources/tests.py,sha256=xDvvgesPSU93nLD_ERQopOpkpq69pbMEqmFsJd0jekI,2063
+services/resources/unity_instances.py,sha256=XRR5YCDe8v_FXG45VlSdEPaqu7Qlbnm4NYIRzK5brjc,4354
+services/resources/windows.py,sha256=FyzPEtEmfKiXYh1lviemZ7-bFyjkAR61_seSTXQA9rk,1433
+services/state/external_changes_scanner.py,sha256=ZiXu8ZcK5B-hv7CaJLmnEIa9JxzgOBpdmrsRDY2eK5I,9052
+services/tools/__init__.py,sha256=3Qav7fAowZ1_TbDRdZQQQES53gv2lTs-2D7PGECnlbM,2353
+services/tools/batch_execute.py,sha256=hjh67kgWvQDHyGd2N-Tfezv9WAj5x_pWTt_Vybmmq7s,3501
+services/tools/debug_request_context.py,sha256=Duq5xiuSmRO5GdvWAlZhCfOfmrwvK7gGkRC4wYnXmXk,2907
+services/tools/execute_custom_tool.py,sha256=hiZbm2A9t84f92jitzvkE2G4CMOIUiDVm7u5B8K-RbU,1527
+services/tools/execute_menu_item.py,sha256=k4J89LlXmEGyo9z3NK8Q0vREIzr11ucF_9tN_JeQq9M,1248
+services/tools/find_gameobjects.py,sha256=Qpfd_oQG0fluz8S1CfriGh1FmLnZ080-ZEZOrAsij8U,3602
+services/tools/find_in_file.py,sha256=SxhMeo8lRrt0OiGApGZSFUnq671bxVfK8qgAsHxLua8,6493
+services/tools/manage_asset.py,sha256=St_iWQWg9icztnRthU78t6JNhJN0AlC6ELiZhn-SNZU,5990
+services/tools/manage_components.py,sha256=Z74QWrOdJyvQBRqIk3ZNYhUxyyH-R0Er1cEkt-70Hcg,5025
+services/tools/manage_editor.py,sha256=ShvlSBQRfoNQ0DvqBWak_Hi3MB7tv2WkMKEhrKQipk0,3279
+services/tools/manage_gameobject.py,sha256=fOuaYoQAZ1OgCnfSMZboqISRUr6bIuaBcG6XV-iVN_M,15092
+services/tools/manage_material.py,sha256=0i5gsTXkahzq_5qEByXvsMHxMpWuMBJH3HzbEr8GQns,5520
+services/tools/manage_prefabs.py,sha256=5waHRvxbdVA9N60tvf9m1f9NTRPspyxZOh4GZfuCfII,3179
+services/tools/manage_scene.py,sha256=-ARtRuj7ZNk_14lmMSORnQs0qTAYKBTPtUfk0sNDo6A,5370
+services/tools/manage_script.py,sha256=MzPw0xXjtbdjEyjvUfLem9fa3GVE-WGvCr4WEVfW9Cs,28461
+services/tools/manage_scriptable_object.py,sha256=tezG_mbGzPLNpL3F7l5JJLyyjJN3rJi1thGMU8cpOC4,3659
+services/tools/manage_shader.py,sha256=bucRKzQww7opy6DK5nf6isVaEECWWqJ-DVkFulp8CV8,3185
+services/tools/manage_vfx.py,sha256=eeqf4xUYw_yT2rALIGHrHLJCpemx9H__S3zCjj_GZsI,34054
+services/tools/preflight.py,sha256=0nvo0BmZMdIGop1Ha_vypkjn2VLiRvskF0uxh_SlZgE,4162
+services/tools/read_console.py,sha256=k1brS1yR-wyMgdhL6TPL-j4KJCD0CKSWrHYiTh-gj9Y,5452
+services/tools/refresh_unity.py,sha256=IcShwasfveDGxXQ3YdbaQP3ICCt8e8O_q_NsnDa8glw,4054
+services/tools/run_tests.py,sha256=9M9noRsZWjqcCfUWo5XVVtGNggxg5HpPvmkobs2lu-A,8082
+services/tools/script_apply_edits.py,sha256=0f-SaP5NUYGuivl4CWHjR8F-CXUpt3-5qkHpf_edn1U,47677
+services/tools/set_active_instance.py,sha256=pdmC1SxFijyzzjeEyC2N1bXk-GNMu_iXsbCieIpa-R4,4242
+services/tools/utils.py,sha256=uk--6w_-O0eVAxczackXbgKde2ONmsgci43G3wY7dfA,4258
+transport/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+transport/models.py,sha256=6wp7wsmSaeeJEvUGXPF1m6zuJnxJ1NJlCC4YZ9oQIq0,1226
+transport/plugin_hub.py,sha256=ku8CdK6kdxUrRMd9zjUn7fFARx8rMZ2FWD7zWGuN2Ys,23083
+transport/plugin_registry.py,sha256=nW-7O7PN0QUgSWivZTkpAVKKq9ZOe2b2yeIdpaNt_3I,4359
+transport/unity_instance_middleware.py,sha256=DD8gs-peMRmRJz9CYwaHEh4m75LTYPDjVuKuw9sArBw,10438
+transport/unity_transport.py,sha256=G6aMC1qR31YZOBZs4fxQbSQBHuXBP1d5Qn0MJaB3yGs,3908
+transport/legacy/port_discovery.py,sha256=JDSCqXLodfTT7fOsE0DFC1jJ3QsU6hVaYQb7x7FgdxY,12728
+transport/legacy/stdio_port_registry.py,sha256=j4iARuP6wetppNDG8qKeuvo1bJKcSlgEhZvSyl_uf0A,2313
+transport/legacy/unity_connection.py,sha256=UZ6tztBO9VlXNiV0jN66k5QMrtTIGAOdGxwtcLnkXLU,35808
+utils/module_discovery.py,sha256=My48ofB1BUqxiBoAZAGbEaLQYdsrDhMm8MayBP_bUSQ,2005
+utils/reload_sentinel.py,sha256=s1xMWhl-r2XwN0OUbiUv_VGUy8TvLtV5bkql-5n2DT0,373
+mcpforunityserver-9.0.0.dist-info/METADATA,sha256=Nj5uKhcyIwsnrAdL6wX_EVE6lUbF6iyv1y4cHADM24k,5712
+mcpforunityserver-9.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mcpforunityserver-9.0.0.dist-info/entry_points.txt,sha256=vCtkqw-J9t4pj7JwUZcB54_keVx7DpAR3fYzK6i-s6g,44
+mcpforunityserver-9.0.0.dist-info/top_level.txt,sha256=UYGWDnyTlnS7PnuZNw8-gM_jWcdmcHwffK_2yBRl6Cc,51
+mcpforunityserver-9.0.0.dist-info/RECORD,,

{mcpforunityserver-8.7.1.dist-info → mcpforunityserver-9.0.0.dist-info}/top_level.txt

@@ -2,7 +2,6 @@ __init__
 core
 main
 models
-routes
 services
 transport
 utils

services/custom_tool_service.py

@@ -266,15 +266,14 @@ class CustomToolService:
             return None
         return {"message": str(response)}
 
-    def _safe_response(self, response):
-        if isinstance(response, dict):
-            return response
-        if response is None:
-            return None
-        return {"message": str(response)}
-
 
 def compute_project_id(project_name: str, project_path: str) -> str:
+    """
+    DEPRECATED: Computes a SHA256-based project ID.
+    This function is no longer used as of the multi-session fix.
+    Unity instances now use their native project_hash (SHA1-based) for consistency
+    across stdio and WebSocket transports.
+    """
     combined = f"{project_name}:{project_path}"
     return sha256(combined.encode("utf-8")).hexdigest().upper()[:16]
 
@@ -307,7 +306,13 @@ def resolve_project_id_for_unity_instance(unity_instance: str | None) -> str | N
             )
 
         if target:
-            return compute_project_id(target.name, target.path)
+            # Return the project_hash from Unity (not a computed SHA256 hash).
+            # This matches the hash Unity uses when registering tools via WebSocket.
+            if target.hash:
+                return target.hash
+            logger.warning(
+                f"Unity instance {target.id} has empty hash; cannot resolve project ID")
+            return None
     except Exception:
         logger.debug(
             f"Failed to resolve project id via connection pool for {unity_instance}")

services/resources/active_tool.py

@@ -31,7 +31,7 @@ class ActiveToolResponse(MCPResponse):
 
 
 @mcp_for_unity_resource(
-    uri="unity://editor/active-tool",
+    uri="mcpforunity://editor/active-tool",
     name="editor_active_tool",
     description="Currently active editor tool (Move, Rotate, Scale, etc.) and transform handle settings."
 )

services/resources/custom_tools.py

@@ -22,7 +22,7 @@ class CustomToolsResourceResponse(MCPResponse):
 
 
 @mcp_for_unity_resource(
-    uri="unity://custom-tools",
+    uri="mcpforunity://custom-tools",
     name="custom_tools",
     description="Lists custom tools available for the active Unity project.",
 )
@@ -31,7 +31,7 @@ async def get_custom_tools(ctx: Context) -> CustomToolsResourceResponse | MCPRes
     if not unity_instance:
         return MCPResponse(
             success=False,
-            message="No active Unity instance. Call set_active_instance with Name@hash from unity://instances.",
+            message="No active Unity instance. Call set_active_instance with Name@hash from mcpforunity://instances.",
         )
 
     project_id = resolve_project_id_for_unity_instance(unity_instance)

services/resources/editor_state.py

@@ -1,51 +1,304 @@
-from pydantic import BaseModel
+import os
+import time
+from typing import Any
+
 from fastmcp import Context
+from pydantic import BaseModel
 
 from models import MCPResponse
 from services.registry import mcp_for_unity_resource
 from services.tools import get_unity_instance_from_context
-from transport.unity_transport import send_with_unity_instance
+from services.state.external_changes_scanner import external_changes_scanner
+import transport.unity_transport as unity_transport
 from transport.legacy.unity_connection import async_send_command_with_retry
 
 
+class EditorStateUnity(BaseModel):
+    instance_id: str | None = None
+    unity_version: str | None = None
+    project_id: str | None = None
+    platform: str | None = None
+    is_batch_mode: bool | None = None
+
+
+class EditorStatePlayMode(BaseModel):
+    is_playing: bool | None = None
+    is_paused: bool | None = None
+    is_changing: bool | None = None
+
+
+class EditorStateActiveScene(BaseModel):
+    path: str | None = None
+    guid: str | None = None
+    name: str | None = None
+
+
+class EditorStateEditor(BaseModel):
+    is_focused: bool | None = None
+    play_mode: EditorStatePlayMode | None = None
+    active_scene: EditorStateActiveScene | None = None
+
+
+class EditorStateActivity(BaseModel):
+    phase: str | None = None
+    since_unix_ms: int | None = None
+    reasons: list[str] | None = None
+
+
+class EditorStateCompilation(BaseModel):
+    is_compiling: bool | None = None
+    is_domain_reload_pending: bool | None = None
+    last_compile_started_unix_ms: int | None = None
+    last_compile_finished_unix_ms: int | None = None
+    last_domain_reload_before_unix_ms: int | None = None
+    last_domain_reload_after_unix_ms: int | None = None
+
+
+class EditorStateRefresh(BaseModel):
+    is_refresh_in_progress: bool | None = None
+    last_refresh_requested_unix_ms: int | None = None
+    last_refresh_finished_unix_ms: int | None = None
+
+
+class EditorStateAssets(BaseModel):
+    is_updating: bool | None = None
+    external_changes_dirty: bool | None = None
+    external_changes_last_seen_unix_ms: int | None = None
+    external_changes_dirty_since_unix_ms: int | None = None
+    external_changes_last_cleared_unix_ms: int | None = None
+    refresh: EditorStateRefresh | None = None
+
+
+class EditorStateLastRun(BaseModel):
+    finished_unix_ms: int | None = None
+    result: str | None = None
+    counts: Any | None = None
+
+
+class EditorStateTests(BaseModel):
+    is_running: bool | None = None
+    mode: str | None = None
+    current_job_id: str | None = None
+    started_unix_ms: int | None = None
+    started_by: str | None = None
+    last_run: EditorStateLastRun | None = None
+
+
+class EditorStateTransport(BaseModel):
+    unity_bridge_connected: bool | None = None
+    last_message_unix_ms: int | None = None
+
+
+class EditorStateAdvice(BaseModel):
+    ready_for_tools: bool | None = None
+    blocking_reasons: list[str] | None = None
+    recommended_retry_after_ms: int | None = None
+    recommended_next_action: str | None = None
+
+
+class EditorStateStaleness(BaseModel):
+    age_ms: int | None = None
+    is_stale: bool | None = None
+
+
 class EditorStateData(BaseModel):
-    """Editor state data fields."""
-    isPlaying: bool = False
-    isPaused: bool = False
-    isCompiling: bool = False
-    isUpdating: bool = False
-    timeSinceStartup: float = 0.0
-    activeSceneName: str = ""
-    selectionCount: int = 0
-    activeObjectName: str | None = None
+    schema_version: str
+    observed_at_unix_ms: int
+    sequence: int
+    unity: EditorStateUnity | None = None
+    editor: EditorStateEditor | None = None
+    activity: EditorStateActivity | None = None
+    compilation: EditorStateCompilation | None = None
+    assets: EditorStateAssets | None = None
+    tests: EditorStateTests | None = None
+    transport: EditorStateTransport | None = None
+    advice: EditorStateAdvice | None = None
+    staleness: EditorStateStaleness | None = None
+
+
+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.
+    """
+    await ctx.info("If exactly one Unity instance is connected, return its Name@hash id.")
+
+    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 _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
 
-class EditorStateResponse(MCPResponse):
-    """Dynamic editor state information that changes frequently."""
-    data: EditorStateData = EditorStateData()
+    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",
+    uri="mcpforunity://editor/state",
     name="editor_state",
-    description="Current editor runtime state including play mode, compilation status, active scene, and selection summary. Refresh frequently for up-to-date information."
+    description="Canonical editor readiness snapshot. Includes advice and server-computed staleness.",
 )
-async def get_editor_state(ctx: Context) -> EditorStateResponse | MCPResponse:
-    """Get current editor runtime state."""
+async def get_editor_state(ctx: Context) -> MCPResponse:
     unity_instance = get_unity_instance_from_context(ctx)
-    response = await send_with_unity_instance(
+
+    response = await unity_transport.send_with_unity_instance(
         async_send_command_with_retry,
         unity_instance,
         "get_editor_state",
-        {}
+        {},
     )
-    # When Unity is reloading/unresponsive (often when unfocused), transports may return
-    # a retryable MCPResponse payload with success=false and no data. Do not attempt to
-    # coerce that into EditorStateResponse (it would fail validation); return it as-is.
-    if isinstance(response, dict):
-        if not response.get("success", True):
-            return MCPResponse(**response)
-        if response.get("data") is None:
-            return MCPResponse(success=False, error="Editor state missing 'data' payload", data=response)
-        return EditorStateResponse(**response)
-    return response
+
+    # 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)
+
+    state_v2 = response.get("data") if isinstance(
+        response, dict) and isinstance(response.get("data"), dict) else {}
+    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.
+    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.
+    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
+
+            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
+            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")
+            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:
+        pass
+
+    state_v2 = _enrich_advice_and_staleness(state_v2)
+
+    try:
+        if hasattr(EditorStateData, "model_validate"):
+            validated = EditorStateData.model_validate(state_v2)
+        else:
+            validated = EditorStateData.parse_obj(
+                state_v2)  # type: ignore[attr-defined]
+        data = validated.model_dump() if hasattr(
+            validated, "model_dump") else validated.dict()
+    except Exception as e:
+        return MCPResponse(
+            success=False,
+            error="invalid_editor_state",
+            message=f"Editor state payload failed validation: {e}",
+            data={"raw": state_v2},
+        )
+
+    return MCPResponse(success=True, message="Retrieved editor state.", data=data)