mcpforunityserver 8.5.0__py3-none-any.whl → 8.7.0__py3-none-any.whl

main.py

@@ -391,6 +391,22 @@ Examples:
         help="HTTP server port (overrides URL port). "
              "Overrides UNITY_MCP_HTTP_PORT environment variable."
     )
+    parser.add_argument(
+        "--unity-instance-token",
+        type=str,
+        default=None,
+        metavar="TOKEN",
+        help="Optional per-launch token set by Unity for deterministic lifecycle management. "
+             "Used by Unity to validate it is stopping the correct process."
+    )
+    parser.add_argument(
+        "--pidfile",
+        type=str,
+        default=None,
+        metavar="PATH",
+        help="Optional path where the server will write its PID on startup. "
+             "Used by Unity to stop the exact process it launched when running in a terminal."
+    )
 
     args = parser.parse_args()
 
@@ -418,6 +434,20 @@ Examples:
     os.environ["UNITY_MCP_HTTP_HOST"] = http_host
     os.environ["UNITY_MCP_HTTP_PORT"] = str(http_port)
 
+    # Optional lifecycle handshake for Unity-managed terminal launches
+    if args.unity_instance_token:
+        os.environ["UNITY_MCP_INSTANCE_TOKEN"] = args.unity_instance_token
+    if args.pidfile:
+        try:
+            pid_dir = os.path.dirname(args.pidfile)
+            if pid_dir:
+                os.makedirs(pid_dir, exist_ok=True)
+            with open(args.pidfile, "w", encoding="ascii") as f:
+                f.write(str(os.getpid()))
+        except Exception as exc:
+            logger.warning(
+                "Failed to write pidfile '%s': %s", args.pidfile, exc)
+
     if args.http_url != "http://localhost:8080":
         logger.info(f"HTTP URL set to: {http_url}")
     if args.http_host:

{mcpforunityserver-8.5.0.dist-info → mcpforunityserver-8.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpforunityserver
-Version: 8.5.0
+Version: 8.7.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.5.0#subdirectory=Server",
+        "git+https://github.com/CoplayDev/unity-mcp@v8.7.0#subdirectory=Server",
         "mcp-for-unity",
         "--transport",
         "stdio"

{mcpforunityserver-8.5.0.dist-info → mcpforunityserver-8.7.0.dist-info}/RECORD

@@ -1,11 +1,11 @@
 __init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-main.py,sha256=OH_Ux5Aj43q1lXPu4AS8zafRnFHZWFYCDZbswReQOac,18011
+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.5.0.dist-info/licenses/LICENSE,sha256=bv5lDJZQEqxBgjjc1rkRbkEwpSIHF-8N-1Od0VnEJFw,1066
+mcpforunityserver-8.7.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
@@ -18,7 +18,8 @@ services/registry/tool_registry.py,sha256=9tMwOP07JE92QFYUS4KvoysO0qC9pkBD5B79kj
 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=acrSyMfdulRgYQIn7wKHqKqyw4uED_oUf9GU-4o4GAg,1497
+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
@@ -28,39 +29,43 @@ services/resources/tags.py,sha256=7EhmQjMotz85DSSr7cVKYIy7LPT5mmPfrEySr1mTE6w,10
 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=Kpqr82cmXH7wxXub3O0D8whksORSqn9nDRjskDe_A_w,7534
+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=kYIouvt-iNUEsY0VIWp4FqagLjo7Up2TwKDhB4Nfxmo,14213
+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=3BhIsbbtGiMNqBMQMqEsB4ajYmtx-VwWl-krOkFR_Bw,4648
+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/read_console.py,sha256=gZWEf0Ru0hvN9oJUZqZ4w-mMBBLm5Z5KAUPv282XbYQ,4091
-services/tools/run_tests.py,sha256=LBVwGasLvmF4k1FiX3DdBQ8udh89WZJFiVHfJRWGvOs,3313
+services/tools/preflight.py,sha256=VJn61h-9pvoVaCyKL7DTKLfbpoZfNK4fnRmj91c2o8M,4093
+services/tools/read_console.py,sha256=MdQcrnVXra9PLu5AFkmARjriObT0miExtQKkFaANznU,4662
+services/tools/refresh_unity.py,sha256=anTEuEzxKTFse6ldZxTsk43zI6ahRBDv3Sg_pMHYRYA,3719
+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=55R00ohrmUI0mk_smc_8BsYTvrQMPX4wwsvqXprj0Vk,15596
+transport/plugin_hub.py,sha256=g_DOhCThgJ9Oco_z3m2qpwDeUcFvvt7Z47xMS0diihw,21497
 transport/plugin_registry.py,sha256=nW-7O7PN0QUgSWivZTkpAVKKq9ZOe2b2yeIdpaNt_3I,4359
-transport/unity_instance_middleware.py,sha256=a-ULWU9b86w0CbYN3meyLxWGxTBXL5CQmBKZmmQ0xZQ,6197
-transport/unity_transport.py,sha256=dvwCjo2jRvnFXd8ruOL36C8W4P1VIQ91qreS2750lPM,3307
+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=ujUX9WX7Gb-fxQveHts3uiepTPzFq8i7-XG7u5gSPuM,32668
 utils/module_discovery.py,sha256=My48ofB1BUqxiBoAZAGbEaLQYdsrDhMm8MayBP_bUSQ,2005
 utils/reload_sentinel.py,sha256=s1xMWhl-r2XwN0OUbiUv_VGUy8TvLtV5bkql-5n2DT0,373
-mcpforunityserver-8.5.0.dist-info/METADATA,sha256=3YWJc7I-EKxcLzMgG0MweNSJm3QR_VYCNTTwwB45UNE,5712
-mcpforunityserver-8.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mcpforunityserver-8.5.0.dist-info/entry_points.txt,sha256=vCtkqw-J9t4pj7JwUZcB54_keVx7DpAR3fYzK6i-s6g,44
-mcpforunityserver-8.5.0.dist-info/top_level.txt,sha256=YKU5e5dREMfCnoVpmlsTm9bku7oqnrzSZ9FeTgjoxJw,58
-mcpforunityserver-8.5.0.dist-info/RECORD,,
+mcpforunityserver-8.7.0.dist-info/METADATA,sha256=m3U2_aFTIAFPWg8YE3v2KcMJmP-Ffz0R-EJsJwoD6pA,5712
+mcpforunityserver-8.7.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mcpforunityserver-8.7.0.dist-info/entry_points.txt,sha256=vCtkqw-J9t4pj7JwUZcB54_keVx7DpAR3fYzK6i-s6g,44
+mcpforunityserver-8.7.0.dist-info/top_level.txt,sha256=YKU5e5dREMfCnoVpmlsTm9bku7oqnrzSZ9FeTgjoxJw,58
+mcpforunityserver-8.7.0.dist-info/RECORD,,

services/resources/editor_state.py

@@ -39,4 +39,13 @@ async def get_editor_state(ctx: Context) -> EditorStateResponse | MCPResponse:
         "get_editor_state",
         {}
     )
-    return EditorStateResponse(**response) if isinstance(response, dict) else response
+    # 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

services/resources/editor_state_v2.py

@@ -0,0 +1,270 @@
+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)
+
+

services/state/external_changes_scanner.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import os
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+
+def _now_unix_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _in_pytest() -> bool:
+    # Keep scanner inert during the Python integration suite unless explicitly invoked.
+    return bool(os.environ.get("PYTEST_CURRENT_TEST"))
+
+
+@dataclass
+class ExternalChangesState:
+    project_root: str | None = None
+    last_scan_unix_ms: int | None = None
+    last_seen_mtime_ns: int | None = None
+    dirty: bool = False
+    dirty_since_unix_ms: int | None = None
+    external_changes_last_seen_unix_ms: int | None = None
+    last_cleared_unix_ms: int | None = None
+    # Cached package roots referenced by Packages/manifest.json "file:" dependencies
+    extra_roots: list[str] | None = None
+    manifest_last_mtime_ns: int | None = None
+
+
+class ExternalChangesScanner:
+    """
+    Lightweight external-changes detector using recursive max-mtime scan.
+
+    This is intentionally conservative:
+    - It only marks dirty when it sees a strictly newer mtime than the baseline.
+    - It scans at most once per scan_interval_ms per instance to keep overhead bounded.
+    """
+
+    def __init__(self, *, scan_interval_ms: int = 1500, max_entries: int = 20000):
+        self._states: dict[str, ExternalChangesState] = {}
+        self._scan_interval_ms = int(scan_interval_ms)
+        self._max_entries = int(max_entries)
+
+    def _get_state(self, instance_id: str) -> ExternalChangesState:
+        return self._states.setdefault(instance_id, ExternalChangesState())
+
+    def set_project_root(self, instance_id: str, project_root: str | None) -> None:
+        st = self._get_state(instance_id)
+        if project_root:
+            st.project_root = project_root
+
+    def clear_dirty(self, instance_id: str) -> None:
+        st = self._get_state(instance_id)
+        st.dirty = False
+        st.dirty_since_unix_ms = None
+        st.last_cleared_unix_ms = _now_unix_ms()
+        # Reset baseline to “now” on next scan.
+        st.last_seen_mtime_ns = None
+
+    def _scan_paths_max_mtime_ns(self, roots: Iterable[Path]) -> int | None:
+        newest: int | None = None
+        entries = 0
+
+        for root in roots:
+            if not root.exists():
+                continue
+
+            # Walk the tree; skip common massive/irrelevant dirs (Library/Temp/Logs).
+            for dirpath, dirnames, filenames in os.walk(str(root)):
+                entries += 1
+                if entries > self._max_entries:
+                    return newest
+
+                dp = Path(dirpath)
+                name = dp.name.lower()
+                if name in {"library", "temp", "logs", "obj", ".git", "node_modules"}:
+                    dirnames[:] = []
+                    continue
+
+                # Allow skipping hidden directories quickly
+                dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+
+                for fn in filenames:
+                    if fn.startswith("."):
+                        continue
+                    entries += 1
+                    if entries > self._max_entries:
+                        return newest
+                    p = dp / fn
+                    try:
+                        stat = p.stat()
+                    except OSError:
+                        continue
+                    m = getattr(stat, "st_mtime_ns", None)
+                    if m is None:
+                        # Fallback when st_mtime_ns is unavailable
+                        m = int(stat.st_mtime * 1_000_000_000)
+                    newest = m if newest is None else max(newest, int(m))
+
+        return newest
+
+    def _resolve_manifest_extra_roots(self, project_root: Path, st: ExternalChangesState) -> list[Path]:
+        """
+        Parse Packages/manifest.json for local file: dependencies and resolve them to absolute paths.
+        Returns a list of Paths that exist and are directories.
+        """
+        manifest_path = project_root / "Packages" / "manifest.json"
+        try:
+            stat = manifest_path.stat()
+        except OSError:
+            st.extra_roots = []
+            st.manifest_last_mtime_ns = None
+            return []
+
+        mtime_ns = getattr(stat, "st_mtime_ns", int(stat.st_mtime * 1_000_000_000))
+        if st.extra_roots is not None and st.manifest_last_mtime_ns == mtime_ns:
+            return [Path(p) for p in st.extra_roots if p]
+
+        try:
+            raw = manifest_path.read_text(encoding="utf-8")
+            doc = json.loads(raw)
+        except Exception:
+            st.extra_roots = []
+            st.manifest_last_mtime_ns = mtime_ns
+            return []
+
+        deps = doc.get("dependencies") if isinstance(doc, dict) else None
+        if not isinstance(deps, dict):
+            st.extra_roots = []
+            st.manifest_last_mtime_ns = mtime_ns
+            return []
+
+        roots: list[str] = []
+        base_dir = manifest_path.parent
+
+        for _, ver in deps.items():
+            if not isinstance(ver, str):
+                continue
+            v = ver.strip()
+            if not v.startswith("file:"):
+                continue
+            suffix = v[len("file:") :].strip()
+            # Handle file:///abs/path or file:/abs/path
+            if suffix.startswith("///"):
+                candidate = Path("/" + suffix.lstrip("/"))
+            elif suffix.startswith("/"):
+                candidate = Path(suffix)
+            else:
+                candidate = (base_dir / suffix).resolve()
+            try:
+                if candidate.exists() and candidate.is_dir():
+                    roots.append(str(candidate))
+            except OSError:
+                continue
+
+        # De-dupe, preserve order
+        deduped: list[str] = []
+        seen = set()
+        for r in roots:
+            if r not in seen:
+                seen.add(r)
+                deduped.append(r)
+
+        st.extra_roots = deduped
+        st.manifest_last_mtime_ns = mtime_ns
+        return [Path(p) for p in deduped if p]
+
+    def update_and_get(self, instance_id: str) -> dict[str, int | bool | None]:
+        """
+        Returns a small dict suitable for embedding in editor_state_v2.assets:
+          - external_changes_dirty
+          - external_changes_last_seen_unix_ms
+          - dirty_since_unix_ms
+          - last_cleared_unix_ms
+        """
+        st = self._get_state(instance_id)
+
+        if _in_pytest():
+            return {
+                "external_changes_dirty": st.dirty,
+                "external_changes_last_seen_unix_ms": st.external_changes_last_seen_unix_ms,
+                "dirty_since_unix_ms": st.dirty_since_unix_ms,
+                "last_cleared_unix_ms": st.last_cleared_unix_ms,
+            }
+
+        now = _now_unix_ms()
+        if st.last_scan_unix_ms is not None and (now - st.last_scan_unix_ms) < self._scan_interval_ms:
+            return {
+                "external_changes_dirty": st.dirty,
+                "external_changes_last_seen_unix_ms": st.external_changes_last_seen_unix_ms,
+                "dirty_since_unix_ms": st.dirty_since_unix_ms,
+                "last_cleared_unix_ms": st.last_cleared_unix_ms,
+            }
+
+        st.last_scan_unix_ms = now
+
+        project_root = st.project_root
+        if not project_root:
+            return {
+                "external_changes_dirty": st.dirty,
+                "external_changes_last_seen_unix_ms": st.external_changes_last_seen_unix_ms,
+                "dirty_since_unix_ms": st.dirty_since_unix_ms,
+                "last_cleared_unix_ms": st.last_cleared_unix_ms,
+            }
+
+        root = Path(project_root)
+        paths = [root / "Assets", root / "ProjectSettings", root / "Packages"]
+        # Include any local package roots referenced by file: deps in Packages/manifest.json
+        try:
+            paths.extend(self._resolve_manifest_extra_roots(root, st))
+        except Exception:
+            pass
+        newest = self._scan_paths_max_mtime_ns(paths)
+        if newest is None:
+            return {
+                "external_changes_dirty": st.dirty,
+                "external_changes_last_seen_unix_ms": st.external_changes_last_seen_unix_ms,
+                "dirty_since_unix_ms": st.dirty_since_unix_ms,
+                "last_cleared_unix_ms": st.last_cleared_unix_ms,
+            }
+
+        if st.last_seen_mtime_ns is None:
+            st.last_seen_mtime_ns = newest
+        elif newest > st.last_seen_mtime_ns:
+            st.last_seen_mtime_ns = newest
+            st.external_changes_last_seen_unix_ms = now
+            if not st.dirty:
+                st.dirty = True
+                st.dirty_since_unix_ms = now
+
+        return {
+            "external_changes_dirty": st.dirty,
+            "external_changes_last_seen_unix_ms": st.external_changes_last_seen_unix_ms,
+            "dirty_since_unix_ms": st.dirty_since_unix_ms,
+            "last_cleared_unix_ms": st.last_cleared_unix_ms,
+        }
+
+
+# Global singleton (simple, process-local)
+external_changes_scanner = ExternalChangesScanner()
+
+