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

services/tools/preflight.py

@@ -42,11 +42,12 @@ async def preflight(
     if _in_pytest():
         return None
 
-    # Load canonical v2 state (server enriches advice + staleness).
+    # Load canonical editor 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
+        from services.resources.editor_state import get_editor_state
+        state_resp = await get_editor_state(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
@@ -80,9 +81,12 @@ async def preflight(
     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
+            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:
@@ -91,9 +95,10 @@ async def preflight(
 
             # 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
+                from services.resources.editor_state import get_editor_state
+                state_resp = await get_editor_state(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
@@ -103,5 +108,3 @@ async def preflight(
     # 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

@@ -4,6 +4,8 @@ Defines the read_console tool for accessing Unity Editor console messages.
 from typing import Annotated, Any, Literal
 
 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
 from services.tools.utils import coerce_int, coerce_bool
@@ -19,7 +21,10 @@ def _strip_stacktrace_from_list(items: list) -> None:
 
 
 @mcp_for_unity_tool(
-    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')."
+    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'). The 'get' action is read-only; 'clear' modifies ephemeral UI state (not project data).",
+    annotations=ToolAnnotations(
+        title="Read Console",
+    ),
 )
 async def read_console(
     ctx: Context,
@@ -32,8 +37,10 @@ async def read_console(
     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,
+    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,
@@ -44,7 +51,7 @@ 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']
+    types = types if types is not None else ['error', 'warning', 'log']
     format = format if format is not None else 'plain'
     # Coerce booleans defensively (strings like 'true'/'false')
 

services/tools/refresh_unity.py

@@ -5,6 +5,7 @@ import time
 from typing import Annotated, Any, Literal
 
 from fastmcp import Context
+from mcp.types import ToolAnnotations
 
 from models import MCPResponse
 from services.registry import mcp_for_unity_tool
@@ -12,17 +13,25 @@ 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
+import services.resources.editor_state as editor_state
 
 
 @mcp_for_unity_tool(
-    description="Request a Unity asset database refresh and optionally a script compilation. Can optionally wait for readiness."
+    description="Request a Unity asset database refresh and optionally a script compilation. Can optionally wait for readiness.",
+    annotations=ToolAnnotations(
+        title="Refresh Unity",
+        destructiveHint=True,
+    ),
 )
 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,
+    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)
 
@@ -48,33 +57,34 @@ async def refresh_unity(
         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())
+        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.
+    # poll the canonical editor_state 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
+            state_resp = await editor_state.get_editor_state(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)
+        inst = unity_instance or await editor_state.infer_single_instance_id(ctx)
         if inst:
             external_changes_scanner.clear_dirty(inst)
     except Exception:

services/tools/run_tests.py

@@ -1,16 +1,19 @@
-"""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
+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 transport.legacy.unity_connection import async_send_command_with_retry
 from services.tools.preflight import preflight
+import transport.unity_transport as unity_transport
+from transport.legacy.unity_connection import async_send_command_with_retry
 
 
 class RunTestsSummary(BaseModel):
@@ -38,31 +41,83 @@ class RunTestsResult(BaseModel):
     results: list[RunTestsTestResult] | None = None
 
 
-class RunTestsResponse(MCPResponse):
-    data: RunTestsResult | 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 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 synchronously (blocks until complete). Prefer run_tests_async for non-blocking execution with progress polling."
+    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,
-    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 | MCPResponse:
+    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)
 
     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:
             return None
@@ -74,47 +129,101 @@ 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
+    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
 
-    # Add filter parameters if provided
-    test_names_list = _coerce_string_list(test_names)
-    if test_names_list:
-        params["testNames"] = test_names_list
+    response = await unity_transport.send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "run_tests",
+        params,
+    )
 
-    group_names_list = _coerce_string_list(group_names)
-    if group_names_list:
-        params["groupNames"] = group_names_list
+    if isinstance(response, dict):
+        if not response.get("success", True):
+            return MCPResponse(**response)
+        return RunTestsStartResponse(**response)
+    return MCPResponse(success=False, error=str(response))
 
-    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
+@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)
 
-    # Add verbosity parameters
+    params: dict[str, Any] = {"job_id": job_id}
     if include_failed_tests:
         params["includeFailedTests"] = True
     if include_details:
         params["includeDetails"] = True
 
-    response = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "run_tests", params)
-
-    # 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
+    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 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}",