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

services/tools/preflight.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import Any
+
+from models import MCPResponse
+
+
+def _in_pytest() -> bool:
+    # Integration tests in this repo stub transports and do not run against a live Unity editor.
+    # Preflight must be a no-op in that environment to avoid breaking the existing test suite.
+    return bool(os.environ.get("PYTEST_CURRENT_TEST"))
+
+
+def _busy(reason: str, retry_after_ms: int) -> MCPResponse:
+    return MCPResponse(
+        success=False,
+        error="busy",
+        message=reason,
+        hint="retry",
+        data={"reason": reason, "retry_after_ms": int(retry_after_ms)},
+    )
+
+
+async def preflight(
+    ctx,
+    *,
+    requires_no_tests: bool = False,
+    wait_for_no_compile: bool = False,
+    refresh_if_dirty: bool = False,
+    max_wait_s: float = 30.0,
+) -> MCPResponse | None:
+    """
+    Server-side preflight guard used by tools so they behave safely even if the client never reads resources.
+
+    Returns:
+      - MCPResponse busy/retry payload when the tool should not proceed right now
+      - None when the tool should proceed normally
+    """
+    if _in_pytest():
+        return None
+
+    # Load canonical v2 state (server enriches advice + staleness).
+    try:
+        from services.resources.editor_state_v2 import get_editor_state_v2
+        state_resp = await get_editor_state_v2(ctx)
+        state = state_resp.model_dump() if hasattr(state_resp, "model_dump") else state_resp
+    except Exception:
+        # If we cannot determine readiness, fall back to proceeding (tools already contain retry logic).
+        return None
+
+    if not isinstance(state, dict) or not state.get("success", False):
+        # Unknown state; proceed rather than blocking (avoids false positives when Unity is reachable but status isn't).
+        return None
+
+    data = state.get("data")
+    if not isinstance(data, dict):
+        return None
+
+    # Optional refresh-if-dirty
+    if refresh_if_dirty:
+        assets = data.get("assets")
+        if isinstance(assets, dict) and assets.get("external_changes_dirty") is True:
+            try:
+                from services.tools.refresh_unity import refresh_unity
+                await refresh_unity(ctx, mode="if_dirty", scope="all", compile="request", wait_for_ready=True)
+            except Exception:
+                # Best-effort only; fall through to normal tool dispatch.
+                pass
+
+    # Tests running: fail fast for tools that require exclusivity.
+    if requires_no_tests:
+        tests = data.get("tests")
+        if isinstance(tests, dict) and tests.get("is_running") is True:
+            return _busy("tests_running", 5000)
+
+    # Compilation: optionally wait for a bounded time.
+    if wait_for_no_compile:
+        deadline = time.monotonic() + float(max_wait_s)
+        while True:
+            compilation = data.get("compilation") if isinstance(data, dict) else None
+            is_compiling = isinstance(compilation, dict) and compilation.get("is_compiling") is True
+            is_domain_reload_pending = isinstance(compilation, dict) and compilation.get("is_domain_reload_pending") is True
+            if not is_compiling and not is_domain_reload_pending:
+                break
+            if time.monotonic() >= deadline:
+                return _busy("compiling", 500)
+            await asyncio.sleep(0.25)
+
+            # Refresh state for the next loop iteration.
+            try:
+                from services.resources.editor_state_v2 import get_editor_state_v2
+                state_resp = await get_editor_state_v2(ctx)
+                state = state_resp.model_dump() if hasattr(state_resp, "model_dump") else state_resp
+                data = state.get("data") if isinstance(state, dict) else None
+                if not isinstance(data, dict):
+                    return None
+            except Exception:
+                return None
+
+    # Staleness: if the snapshot is stale, proceed (tools will still run), but callers that read resources can back off.
+    # In future we may make this strict for some tools.
+    return None
+
+

services/tools/read_console.py

@@ -11,8 +11,15 @@ from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
 
 
+def _strip_stacktrace_from_list(items: list) -> None:
+    """Remove stacktrace fields from a list of log entries."""
+    for item in items:
+        if isinstance(item, dict) and "stacktrace" in item:
+            item.pop("stacktrace", None)
+
+
 @mcp_for_unity_tool(
-    description="Gets messages from or clears the Unity Editor console. Note: For maximum client compatibility, pass count as a quoted string (e.g., '5')."
+    description="Gets messages from or clears the Unity Editor console. Defaults to 10 most recent entries. Use page_size/cursor for paging. Note: For maximum client compatibility, pass count as a quoted string (e.g., '5')."
 )
 async def read_console(
     ctx: Context,
@@ -21,10 +28,12 @@ async def read_console(
     types: Annotated[list[Literal['error', 'warning',
                                   'log', 'all']], "Message types to get"] | None = None,
     count: Annotated[int | str,
-                     "Max messages to return (accepts int or string, e.g., 5 or '5')"] | None = None,
+                     "Max messages to return in non-paging mode (accepts int or string, e.g., 5 or '5'). Ignored when paging with page_size/cursor."] | None = None,
     filter_text: Annotated[str, "Text filter for messages"] | None = None,
     since_timestamp: Annotated[str,
                                "Get messages after this timestamp (ISO 8601)"] | None = None,
+    page_size: Annotated[int | str, "Page size for paginated console reads. Defaults to 50 when omitted."] | None = None,
+    cursor: Annotated[int | str, "Opaque cursor for paging (0-based offset). Defaults to 0."] | None = None,
     format: Annotated[Literal['plain', 'detailed',
                               'json'], "Output format"] | None = None,
     include_stacktrace: Annotated[bool | str,
@@ -35,11 +44,13 @@ async def read_console(
     unity_instance = get_unity_instance_from_context(ctx)
     # Set defaults if values are None
     action = action if action is not None else 'get'
-    types = types if types is not None else ['error', 'warning', 'log']
-    format = format if format is not None else 'detailed'
+    types = types if types is not None else ['error', 'warning']
+    format = format if format is not None else 'plain'
     # Coerce booleans defensively (strings like 'true'/'false')
 
-    include_stacktrace = coerce_bool(include_stacktrace, default=True)
+    include_stacktrace = coerce_bool(include_stacktrace, default=False)
+    coerced_page_size = coerce_int(page_size, default=None)
+    coerced_cursor = coerce_int(cursor, default=None)
 
     # Normalize action if it's a string
     if isinstance(action, str):
@@ -56,7 +67,7 @@ async def read_console(
         count = coerce_int(count)
 
     if action == "get" and count is None:
-        count = 200
+        count = 10
 
     # Prepare parameters for the C# handler
     params_dict = {
@@ -65,6 +76,8 @@ async def read_console(
         "count": count,
         "filterText": filter_text,
         "sinceTimestamp": since_timestamp,
+        "pageSize": coerced_page_size,
+        "cursor": coerced_cursor,
         "format": format.lower() if isinstance(format, str) else format,
         "includeStacktrace": include_stacktrace
     }
@@ -83,16 +96,13 @@ async def read_console(
         # Strip stacktrace fields from returned lines if present
         try:
             data = resp.get("data")
-            # Handle standard format: {"data": {"lines": [...]}}
-            if isinstance(data, dict) and "lines" in data and isinstance(data["lines"], list):
-                for line in data["lines"]:
-                    if isinstance(line, dict) and "stacktrace" in line:
-                        line.pop("stacktrace", None)
-            # Handle legacy/direct list format if any
+            if isinstance(data, dict):
+                for key in ("lines", "items"):
+                    if key in data and isinstance(data[key], list):
+                        _strip_stacktrace_from_list(data[key])
+                        break
             elif isinstance(data, list):
-                for line in data:
-                    if isinstance(line, dict) and "stacktrace" in line:
-                        line.pop("stacktrace", None)
+                _strip_stacktrace_from_list(data)
         except Exception:
             pass
     return resp if isinstance(resp, dict) else {"success": False, "message": str(resp)}

services/tools/refresh_unity.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Annotated, Any, Literal
+
+from fastmcp import Context
+
+from models import MCPResponse
+from services.registry import mcp_for_unity_tool
+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, _extract_response_reason
+from services.state.external_changes_scanner import external_changes_scanner
+
+
+@mcp_for_unity_tool(
+    description="Request a Unity asset database refresh and optionally a script compilation. Can optionally wait for readiness."
+)
+async def refresh_unity(
+    ctx: Context,
+    mode: Annotated[Literal["if_dirty", "force"], "Refresh mode"] = "if_dirty",
+    scope: Annotated[Literal["assets", "scripts", "all"], "Refresh scope"] = "all",
+    compile: Annotated[Literal["none", "request"], "Whether to request compilation"] = "none",
+    wait_for_ready: Annotated[bool, "If true, wait until editor_state.advice.ready_for_tools is true"] = True,
+) -> MCPResponse | dict[str, Any]:
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    params: dict[str, Any] = {
+        "mode": mode,
+        "scope": scope,
+        "compile": compile,
+        "wait_for_ready": bool(wait_for_ready),
+    }
+
+    recovered_from_disconnect = False
+    response = await unity_transport.send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "refresh_unity",
+        params,
+    )
+
+    # Option A: treat disconnects / retry hints as recoverable when wait_for_ready is true.
+    # Unity can legitimately disconnect during refresh/compile/domain reload, so callers should not
+    # interpret that as a hard failure (#503-style loops).
+    if isinstance(response, dict) and not response.get("success", True):
+        hint = response.get("hint")
+        err = (response.get("error") or response.get("message") or "")
+        reason = _extract_response_reason(response)
+        is_retryable = (hint == "retry") or ("disconnected" in str(err).lower())
+        if (not wait_for_ready) or (not is_retryable):
+            return MCPResponse(**response)
+        if reason not in {"reloading", "no_unity_session"}:
+            recovered_from_disconnect = True
+
+    # Optional server-side wait loop (defensive): if Unity tool doesn't wait or returns quickly,
+    # poll the canonical editor_state v2 resource until ready or timeout.
+    if wait_for_ready:
+        timeout_s = 60.0
+        start = time.monotonic()
+        from services.resources.editor_state_v2 import get_editor_state_v2
+
+        while time.monotonic() - start < timeout_s:
+            state_resp = await get_editor_state_v2(ctx)
+            state = state_resp.model_dump() if hasattr(state_resp, "model_dump") else state_resp
+            data = (state or {}).get("data") if isinstance(state, dict) else None
+            advice = (data or {}).get("advice") if isinstance(data, dict) else None
+            if isinstance(advice, dict) and advice.get("ready_for_tools") is True:
+                break
+            await asyncio.sleep(0.25)
+
+    # After readiness is restored, clear any external-dirty flag for this instance so future tools can proceed cleanly.
+    try:
+        from services.resources.editor_state_v2 import _infer_single_instance_id
+
+        inst = unity_instance or await _infer_single_instance_id(ctx)
+        if inst:
+            external_changes_scanner.clear_dirty(inst)
+    except Exception:
+        pass
+
+    if recovered_from_disconnect:
+        return MCPResponse(
+            success=True,
+            message="Refresh recovered after Unity disconnect/retry; editor is ready.",
+            data={"recovered_from_disconnect": True},
+        )
+
+    return MCPResponse(**response) if isinstance(response, dict) else response

services/tools/run_tests.py

@@ -10,6 +10,7 @@ from services.tools import get_unity_instance_from_context
 from services.tools.utils import coerce_int
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
+from services.tools.preflight import preflight
 
 
 class RunTestsSummary(BaseModel):
@@ -42,7 +43,7 @@ class RunTestsResponse(MCPResponse):
 
 
 @mcp_for_unity_tool(
-    description="Runs Unity tests for the specified mode"
+    description="Runs Unity tests synchronously (blocks until complete). Prefer run_tests_async for non-blocking execution with progress polling."
 )
 async def run_tests(
     ctx: Context,
@@ -54,9 +55,13 @@ async def run_tests(
     assembly_names: Annotated[list[str] | str, "Assembly names to filter tests by"] | None = None,
     include_failed_tests: Annotated[bool, "Include details for failed/skipped tests only (default: false)"] = False,
     include_details: Annotated[bool, "Include details for all tests (default: false)"] = False,
-) -> RunTestsResponse:
+) -> RunTestsResponse | MCPResponse:
     unity_instance = get_unity_instance_from_context(ctx)
 
+    gate = await preflight(ctx, requires_no_tests=True, wait_for_no_compile=True, refresh_if_dirty=True)
+    if isinstance(gate, MCPResponse):
+        return gate
+
     # Coerce string or list to list of strings
     def _coerce_string_list(value) -> list[str] | None:
         if value is None:
@@ -97,5 +102,19 @@ async def run_tests(
         params["includeDetails"] = True
 
     response = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "run_tests", params)
-    await ctx.info(f'Response {response}')
+
+    # If Unity indicates a run is already active, return a structured "busy" response rather than
+    # letting clients interpret this as a generic failure (avoids #503 retry loops).
+    if isinstance(response, dict) and not response.get("success", True):
+        err = (response.get("error") or response.get("message") or "").strip()
+        if "test run is already in progress" in err.lower():
+            return MCPResponse(
+                success=False,
+                error="tests_running",
+                message=err,
+                hint="retry",
+                data={"reason": "tests_running", "retry_after_ms": 5000},
+            )
+        return MCPResponse(**response)
+
     return RunTestsResponse(**response) if isinstance(response, dict) else response

services/tools/test_jobs.py

@@ -0,0 +1,94 @@
+"""Async Unity Test Runner jobs: start + poll."""
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from fastmcp import Context
+
+from models import MCPResponse
+from services.registry import mcp_for_unity_tool
+from services.tools import get_unity_instance_from_context
+from services.tools.preflight import preflight
+import transport.unity_transport as unity_transport
+from transport.legacy.unity_connection import async_send_command_with_retry
+
+
+@mcp_for_unity_tool(description="Starts a Unity test run asynchronously and returns a job_id immediately. Preferred over run_tests for long-running suites. Poll with get_test_job for progress.")
+async def run_tests_async(
+    ctx: Context,
+    mode: Annotated[Literal["EditMode", "PlayMode"], "Unity test mode to run"] = "EditMode",
+    test_names: Annotated[list[str] | str, "Full names of specific tests to run"] | None = None,
+    group_names: Annotated[list[str] | str, "Same as test_names, except it allows for Regex"] | None = None,
+    category_names: Annotated[list[str] | str, "NUnit category names to filter by"] | None = None,
+    assembly_names: Annotated[list[str] | str, "Assembly names to filter tests by"] | None = None,
+    include_failed_tests: Annotated[bool, "Include details for failed/skipped tests only (default: false)"] = False,
+    include_details: Annotated[bool, "Include details for all tests (default: false)"] = False,
+) -> dict[str, Any] | MCPResponse:
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    gate = await preflight(ctx, requires_no_tests=True, wait_for_no_compile=True, refresh_if_dirty=True)
+    if isinstance(gate, MCPResponse):
+        return gate
+
+    def _coerce_string_list(value) -> list[str] | None:
+        if value is None:
+            return None
+        if isinstance(value, str):
+            return [value] if value.strip() else None
+        if isinstance(value, list):
+            result = [str(v).strip() for v in value if v and str(v).strip()]
+            return result if result else None
+        return None
+
+    params: dict[str, Any] = {"mode": mode}
+    if (t := _coerce_string_list(test_names)):
+        params["testNames"] = t
+    if (g := _coerce_string_list(group_names)):
+        params["groupNames"] = g
+    if (c := _coerce_string_list(category_names)):
+        params["categoryNames"] = c
+    if (a := _coerce_string_list(assembly_names)):
+        params["assemblyNames"] = a
+    if include_failed_tests:
+        params["includeFailedTests"] = True
+    if include_details:
+        params["includeDetails"] = True
+
+    response = await unity_transport.send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "run_tests_async",
+        params,
+    )
+
+    if isinstance(response, dict) and not response.get("success", True):
+        return MCPResponse(**response)
+    return response if isinstance(response, dict) else MCPResponse(success=False, error=str(response)).model_dump()
+
+
+@mcp_for_unity_tool(description="Polls an async Unity test job by job_id.")
+async def get_test_job(
+    ctx: Context,
+    job_id: Annotated[str, "Job id returned by run_tests_async"],
+    include_failed_tests: Annotated[bool, "Include details for failed/skipped tests only (default: false)"] = False,
+    include_details: Annotated[bool, "Include details for all tests (default: false)"] = False,
+) -> dict[str, Any] | MCPResponse:
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    params: dict[str, Any] = {"job_id": job_id}
+    if include_failed_tests:
+        params["includeFailedTests"] = True
+    if include_details:
+        params["includeDetails"] = True
+
+    response = await unity_transport.send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_test_job",
+        params,
+    )
+    if isinstance(response, dict) and not response.get("success", True):
+        return MCPResponse(**response)
+    return response if isinstance(response, dict) else MCPResponse(success=False, error=str(response)).model_dump()
+
+

transport/legacy/unity_connection.py

@@ -686,28 +686,46 @@ def get_unity_connection(instance_identifier: str | None = None) -> UnityConnect
 # Centralized retry helpers
 # -----------------------------
 
-def _is_reloading_response(resp: object) -> bool:
-    """Return True if the Unity response indicates the editor is reloading.
+def _extract_response_reason(resp: object) -> str | None:
+    """Extract a normalized (lowercase) reason string from a response.
 
-    Supports both raw dict payloads from Unity and MCPResponse objects returned
-    by preflight checks or transport helpers.
+    Returns lowercase reason values to enable case-insensitive comparisons
+    by callers (e.g. _is_reloading_response, refresh_unity).
     """
-    # Structured MCPResponse from preflight/transport
     if isinstance(resp, MCPResponse):
-        # Explicit "please retry" hint from preflight
-        if getattr(resp, "hint", None) == "retry":
-            return True
+        data = getattr(resp, "data", None)
+        if isinstance(data, dict):
+            reason = data.get("reason")
+            if isinstance(reason, str):
+                return reason.lower()
         message_text = f"{resp.message or ''} {resp.error or ''}".lower()
-        return "reload" in message_text
+        if "reload" in message_text:
+            return "reloading"
+        return None
 
-    # Raw Unity payloads
     if isinstance(resp, dict):
         if resp.get("state") == "reloading":
-            return True
+            return "reloading"
+        data = resp.get("data")
+        if isinstance(data, dict):
+            reason = data.get("reason")
+            if isinstance(reason, str):
+                return reason.lower()
         message_text = (resp.get("message") or resp.get("error") or "").lower()
-        return "reload" in message_text
+        if "reload" in message_text:
+            return "reloading"
+        return None
 
-    return False
+    return None
+
+
+def _is_reloading_response(resp: object) -> bool:
+    """Return True if the Unity response indicates the editor is reloading.
+
+    Supports both raw dict payloads from Unity and MCPResponse objects returned
+    by preflight checks or transport helpers.
+    """
+    return _extract_response_reason(resp) == "reloading"
 
 
 def send_command_with_retry(
@@ -738,15 +756,82 @@ def send_command_with_retry(
         max_retries = getattr(config, "reload_max_retries", 40)
     if retry_ms is None:
         retry_ms = getattr(config, "reload_retry_ms", 250)
+    try:
+        max_wait_s = float(os.environ.get(
+            "UNITY_MCP_RELOAD_MAX_WAIT_S", "2.0"))
+    except ValueError as e:
+        raw_val = os.environ.get("UNITY_MCP_RELOAD_MAX_WAIT_S", "2.0")
+        logger.warning(
+            "Invalid UNITY_MCP_RELOAD_MAX_WAIT_S=%r, using default 2.0: %s",
+            raw_val, e)
+        max_wait_s = 2.0
+    # Clamp to [0, 30] to prevent misconfiguration from causing excessive waits
+    max_wait_s = max(0.0, min(max_wait_s, 30.0))
 
     response = conn.send_command(command_type, params)
     retries = 0
+    wait_started = None
+    reason = _extract_response_reason(response)
     while _is_reloading_response(response) and retries < max_retries:
-        delay_ms = int(response.get("retry_after_ms", retry_ms)
-                       ) if isinstance(response, dict) else retry_ms
-        time.sleep(max(0.0, delay_ms / 1000.0))
+        if wait_started is None:
+            wait_started = time.monotonic()
+            logger.debug(
+                "Unity reload wait started: command=%s instance=%s reason=%s max_wait_s=%.2f",
+                command_type,
+                instance_id or "default",
+                reason or "reloading",
+                max_wait_s,
+            )
+        if max_wait_s <= 0:
+            break
+        elapsed = time.monotonic() - wait_started
+        if elapsed >= max_wait_s:
+            break
+        delay_ms = retry_ms
+        if isinstance(response, dict):
+            retry_after = response.get("retry_after_ms")
+            if retry_after is None and isinstance(response.get("data"), dict):
+                retry_after = response["data"].get("retry_after_ms")
+            if retry_after is not None:
+                delay_ms = int(retry_after)
+        sleep_ms = max(50, min(int(delay_ms), 250))
+        logger.debug(
+            "Unity reload wait retry: command=%s instance=%s reason=%s retry_after_ms=%s sleep_ms=%s",
+            command_type,
+            instance_id or "default",
+            reason or "reloading",
+            delay_ms,
+            sleep_ms,
+        )
+        time.sleep(max(0.0, sleep_ms / 1000.0))
         retries += 1
         response = conn.send_command(command_type, params)
+        reason = _extract_response_reason(response)
+
+    if wait_started is not None:
+        waited = time.monotonic() - wait_started
+        if _is_reloading_response(response):
+            logger.debug(
+                "Unity reload wait exceeded budget: command=%s instance=%s waited_s=%.3f",
+                command_type,
+                instance_id or "default",
+                waited,
+            )
+            return MCPResponse(
+                success=False,
+                error="Unity is reloading; please retry",
+                hint="retry",
+                data={
+                    "reason": "reloading",
+                    "retry_after_ms": min(250, max(50, retry_ms)),
+                },
+            )
+        logger.debug(
+            "Unity reload wait completed: command=%s instance=%s waited_s=%.3f",
+            command_type,
+            instance_id or "default",
+            waited,
+        )
     return response