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

services/tools/run_tests.py

@@ -1,15 +1,24 @@
-"""Tool for executing Unity Test Runner suites."""
-from typing import Annotated, Literal, Any
+"""Async Unity Test Runner jobs: start + poll."""
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Annotated, Any, Literal
 
 from fastmcp import Context
-from pydantic import BaseModel, Field
+from mcp.types import ToolAnnotations
+from pydantic import BaseModel
 
 from models import MCPResponse
 from services.registry import mcp_for_unity_tool
 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 services.tools.preflight import preflight
+import transport.unity_transport as unity_transport
 from transport.legacy.unity_connection import async_send_command_with_retry
+from utils.focus_nudge import nudge_unity_focus, should_nudge
+
+logger = logging.getLogger(__name__)
 
 
 class RunTestsSummary(BaseModel):
@@ -34,28 +43,86 @@ class RunTestsTestResult(BaseModel):
 class RunTestsResult(BaseModel):
     mode: str
     summary: RunTestsSummary
-    results: list[RunTestsTestResult]
+    results: list[RunTestsTestResult] | None = None
+
+
+class RunTestsStartData(BaseModel):
+    job_id: str
+    status: str
+    mode: str | None = None
+    include_details: bool | None = None
+    include_failed_tests: bool | None = None
+
+
+class RunTestsStartResponse(MCPResponse):
+    data: RunTestsStartData | None = None
+
+
+class TestJobFailure(BaseModel):
+    full_name: str | None = None
+    message: str | None = None
+
+
+class TestJobProgress(BaseModel):
+    completed: int | None = None
+    total: int | None = None
+    current_test_full_name: str | None = None
+    current_test_started_unix_ms: int | None = None
+    last_finished_test_full_name: str | None = None
+    last_finished_unix_ms: int | None = None
+    stuck_suspected: bool | None = None
+    editor_is_focused: bool | None = None
+    blocked_reason: str | None = None
+    failures_so_far: list[TestJobFailure] | None = None
+    failures_capped: bool | None = None
 
 
-class RunTestsResponse(MCPResponse):
-    data: RunTestsResult | None = None
+class GetTestJobData(BaseModel):
+    job_id: str
+    status: str
+    mode: str | None = None
+    started_unix_ms: int | None = None
+    finished_unix_ms: int | None = None
+    last_update_unix_ms: int | None = None
+    progress: TestJobProgress | None = None
+    error: str | None = None
+    result: RunTestsResult | None = None
+
+
+class GetTestJobResponse(MCPResponse):
+    data: GetTestJobData | None = None
 
 
 @mcp_for_unity_tool(
-    description="Runs Unity tests for the specified mode"
+    description="Starts a Unity test run asynchronously and returns a job_id immediately. Poll with get_test_job for progress.",
+    annotations=ToolAnnotations(
+        title="Run Tests",
+        destructiveHint=True,
+    ),
 )
 async def run_tests(
     ctx: Context,
-    mode: Annotated[Literal["EditMode", "PlayMode"], "Unity test mode to run"] = "EditMode",
-    timeout_seconds: Annotated[int | str, "Optional timeout in seconds for the test run"] | None = None,
-    test_names: Annotated[list[str] | str, "Full names of specific tests to run (e.g., 'MyNamespace.MyTests.TestMethod')"] | 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 (tests marked with [Category] attribute)"] | None = None,
-    assembly_names: Annotated[list[str] | str, "Assembly names to filter tests by"] | None = None,
-) -> RunTestsResponse:
+    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,
+) -> RunTestsStartResponse | MCPResponse:
     unity_instance = get_unity_instance_from_context(ctx)
 
-    # Coerce string or list to list of strings
+    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
@@ -67,27 +134,121 @@ async def run_tests(
         return None
 
     params: dict[str, Any] = {"mode": mode}
-    ts = coerce_int(timeout_seconds)
-    if ts is not None:
-        params["timeoutSeconds"] = ts
-
-    # Add filter parameters if provided
-    test_names_list = _coerce_string_list(test_names)
-    if test_names_list:
-        params["testNames"] = test_names_list
-
-    group_names_list = _coerce_string_list(group_names)
-    if group_names_list:
-        params["groupNames"] = group_names_list
-
-    category_names_list = _coerce_string_list(category_names)
-    if category_names_list:
-        params["categoryNames"] = category_names_list
-
-    assembly_names_list = _coerce_string_list(assembly_names)
-    if assembly_names_list:
-        params["assemblyNames"] = assembly_names_list
-
-    response = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "run_tests", params)
-    await ctx.info(f'Response {response}')
-    return RunTestsResponse(**response) if isinstance(response, dict) else response
+    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",
+        params,
+    )
+
+    if isinstance(response, dict):
+        if not response.get("success", True):
+            return MCPResponse(**response)
+        return RunTestsStartResponse(**response)
+    return MCPResponse(success=False, error=str(response))
+
+
+@mcp_for_unity_tool(
+    description="Polls an async Unity test job by job_id.",
+    annotations=ToolAnnotations(
+        title="Get Test Job",
+        readOnlyHint=True,
+    ),
+)
+async def get_test_job(
+    ctx: Context,
+    job_id: Annotated[str, "Job id returned by run_tests"],
+    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,
+    wait_timeout: Annotated[int | None,
+                            "If set, wait up to this many seconds for tests to complete before returning. "
+                            "Reduces polling frequency and avoids client-side loop detection. "
+                            "Recommended: 30-60 seconds. Returns immediately if tests complete sooner."] = None,
+) -> GetTestJobResponse | 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
+
+    async def _fetch_status() -> dict[str, Any]:
+        return await unity_transport.send_with_unity_instance(
+            async_send_command_with_retry,
+            unity_instance,
+            "get_test_job",
+            params,
+        )
+
+    # If wait_timeout is specified, poll server-side until complete or timeout
+    if wait_timeout and wait_timeout > 0:
+        deadline = asyncio.get_event_loop().time() + wait_timeout
+        poll_interval = 2.0  # Poll Unity every 2 seconds
+
+        while True:
+            response = await _fetch_status()
+
+            if not isinstance(response, dict):
+                return MCPResponse(success=False, error=str(response))
+
+            if not response.get("success", True):
+                return MCPResponse(**response)
+
+            # Check if tests are done
+            data = response.get("data", {})
+            status = data.get("status", "")
+            if status in ("succeeded", "failed", "cancelled"):
+                return GetTestJobResponse(**response)
+
+            # Check if Unity needs a focus nudge to make progress
+            # This handles OS-level throttling (e.g., macOS App Nap) that can
+            # stall PlayMode tests when Unity is in the background.
+            progress = data.get("progress", {})
+            editor_is_focused = progress.get("editor_is_focused", True)
+            last_update_unix_ms = data.get("last_update_unix_ms")
+            current_time_ms = int(time.time() * 1000)
+
+            if should_nudge(
+                status=status,
+                editor_is_focused=editor_is_focused,
+                last_update_unix_ms=last_update_unix_ms,
+                current_time_ms=current_time_ms,
+                stall_threshold_ms=10_000,  # 10 seconds without progress
+            ):
+                logger.info(f"Test job {job_id} appears stalled (unfocused Unity), attempting nudge...")
+                nudged = await nudge_unity_focus(focus_duration_s=0.5)
+                if nudged:
+                    logger.info(f"Test job {job_id} nudge completed")
+
+            # Check timeout
+            remaining = deadline - asyncio.get_event_loop().time()
+            if remaining <= 0:
+                # Timeout reached, return current status
+                return GetTestJobResponse(**response)
+
+            # Wait before next poll (but don't exceed remaining time)
+            await asyncio.sleep(min(poll_interval, remaining))
+    
+    # No wait_timeout - return immediately (original behavior)
+    response = await _fetch_status()
+    if isinstance(response, dict):
+        if not response.get("success", True):
+            return MCPResponse(**response)
+        return GetTestJobResponse(**response)
+    return MCPResponse(success=False, error=str(response))

services/tools/script_apply_edits.py

@@ -4,6 +4,7 @@ import re
 from typing import Annotated, Any, Union
 
 from fastmcp import Context
+from mcp.types import ToolAnnotations
 
 from services.registry import mcp_for_unity_tool
 from services.tools import get_unity_instance_from_context
@@ -228,7 +229,7 @@ def _normalize_script_locator(name: str, path: str) -> tuple[str, str]:
     - name = "SmartReach.cs", path = "Assets/Scripts/Interaction"
     - name = "Assets/Scripts/Interaction/SmartReach.cs", path = ""
     - path = "Assets/Scripts/Interaction/SmartReach.cs" (name empty)
-    - name or path using uri prefixes: unity://path/..., file://...
+    - name or path using uri prefixes: mcpforunity://path/..., file://...
     - accidental duplicates like "Assets/.../SmartReach.cs/SmartReach.cs"
 
     Returns (name_without_extension, directory_path_under_Assets).
@@ -237,8 +238,8 @@ def _normalize_script_locator(name: str, path: str) -> tuple[str, str]:
     p = (path or "").strip()
 
     def strip_prefix(s: str) -> str:
-        if s.startswith("unity://path/"):
-            return s[len("unity://path/"):]
+        if s.startswith("mcpforunity://path/"):
+            return s[len("mcpforunity://path/"):]
         if s.startswith("file://"):
             return s[len("file://"):]
         return s
@@ -309,8 +310,10 @@ def _err(code: str, message: str, *, expected: dict[str, Any] | None = None, rew
 # Natural-language parsing removed; clients should send structured edits.
 
 
-@mcp_for_unity_tool(name="script_apply_edits", description=(
-    """Structured C# edits (methods/classes) with safer boundaries - prefer this over raw text.
+@mcp_for_unity_tool(
+    name="script_apply_edits",
+    description=(
+        """Structured C# edits (methods/classes) with safer boundaries - prefer this over raw text.
     Best practices:
     - Prefer anchor_* ops for pattern-based insert/replace near stable markers
     - Use replace_method/delete_method for whole-method changes (keeps signatures balanced)
@@ -356,7 +359,12 @@ def _err(code: str, message: str, *, expected: dict[str, Any] | None = None, rew
     ],
     }
     ]"""
-))
+    ),
+    annotations=ToolAnnotations(
+        title="Script Apply Edits",
+        destructiveHint=True,
+    ),
+)
 async def script_apply_edits(
     ctx: Context,
     name: Annotated[str, "Name of the script to edit"],
@@ -372,7 +380,7 @@ async def script_apply_edits(
     unity_instance = get_unity_instance_from_context(ctx)
     await ctx.info(
         f"Processing script_apply_edits: {name} (unity_instance={unity_instance or 'default'})")
-        
+
     # Parse edits if they came as a stringified JSON
     edits = parse_json_payload(edits)
     if not isinstance(edits, list):

services/tools/set_active_instance.py

@@ -2,6 +2,8 @@ from typing import Annotated, Any
 from types import SimpleNamespace
 
 from fastmcp import Context
+from mcp.types import ToolAnnotations
+
 from services.registry import mcp_for_unity_tool
 from transport.legacy.unity_connection import get_unity_connection_pool
 from transport.unity_instance_middleware import get_unity_instance_middleware
@@ -10,7 +12,10 @@ from transport.unity_transport import _current_transport
 
 
 @mcp_for_unity_tool(
-    description="Set the active Unity instance for this client/session. Accepts Name@hash or hash."
+    description="Set the active Unity instance for this client/session. Accepts Name@hash or hash.",
+    annotations=ToolAnnotations(
+        title="Set Active Instance",
+    ),
 )
 async def set_active_instance(
         ctx: Context,
@@ -51,7 +56,7 @@ async def set_active_instance(
         return {
             "success": False,
             "error": "Instance identifier is required. "
-                     "Use unity://instances to copy a Name@hash or provide a hash prefix."
+                     "Use mcpforunity://instances to copy a Name@hash or provide a hash prefix."
         }
     resolved = None
     if "@" in value:
@@ -60,7 +65,7 @@ async def set_active_instance(
             return {
                 "success": False,
                 "error": f"Instance '{value}' not found. "
-                         "Use unity://instances to copy an exact Name@hash."
+                "Use mcpforunity://instances to copy an exact Name@hash."
             }
     else:
         lookup = value.lower()
@@ -75,7 +80,7 @@ async def set_active_instance(
             return {
                 "success": False,
                 "error": f"Instance hash '{value}' does not match any running Unity editors. "
-                         "Use unity://instances to confirm the available hashes."
+                "Use mcpforunity://instances to confirm the available hashes."
             }
         if len(matches) > 1:
             matching_ids = ", ".join(
@@ -84,10 +89,10 @@ async def set_active_instance(
             return {
                 "success": False,
                 "error": f"Instance hash '{value}' is ambiguous ({matching_ids}). "
-                         "Provide the full Name@hash from unity://instances."
+                "Provide the full Name@hash from mcpforunity://instances."
             }
         resolved = matches[0]
-    
+
     if resolved is None:
         # Should be unreachable due to logic above, but satisfies static analysis
         return {
@@ -101,7 +106,7 @@ async def set_active_instance(
     # The session key is an internal detail but useful for debugging response.
     middleware.set_active_instance(ctx, resolved.id)
     session_key = middleware.get_session_key(ctx)
-    
+
     return {
         "success": True,
         "message": f"Active instance set to {resolved.id}",

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: