mcpforunityserver 9.0.8__py3-none-any.whl → 9.2.0__py3-none-any.whl

services/resources/__init__.py

@@ -18,7 +18,7 @@ logger = logging.getLogger("mcp-for-unity-server")
 __all__ = ['register_all_resources']
 
 
-def register_all_resources(mcp: FastMCP):
+def register_all_resources(mcp: FastMCP, *, project_scoped_tools: bool = True):
     """
     Auto-discover and register all resources in the resources/ directory.
 
@@ -46,6 +46,11 @@ def register_all_resources(mcp: FastMCP):
         description = resource_info['description']
         kwargs = resource_info['kwargs']
 
+        if not project_scoped_tools and resource_name == "custom_tools":
+            logger.info(
+                "Skipping custom_tools resource registration (project-scoped tools disabled)")
+            continue
+
         # Check if URI contains query parameters (e.g., {?unity_instance})
         has_query_params = '{?' in uri
 

services/tools/__init__.py

@@ -20,7 +20,7 @@ __all__ = [
 ]
 
 
-def register_all_tools(mcp: FastMCP):
+def register_all_tools(mcp: FastMCP, *, project_scoped_tools: bool = True):
     """
     Auto-discover and register all tools in the tools/ directory.
 
@@ -46,6 +46,11 @@ def register_all_tools(mcp: FastMCP):
         description = tool_info['description']
         kwargs = tool_info['kwargs']
 
+        if not project_scoped_tools and tool_name == "execute_custom_tool":
+            logger.info(
+                "Skipping execute_custom_tool registration (project-scoped tools disabled)")
+            continue
+
         # Apply the @mcp.tool decorator, telemetry, and logging
         wrapped = log_execution(tool_name, "Tool")(func)
         wrapped = telemetry_tool(tool_name)(wrapped)

services/tools/refresh_unity.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import logging
 import time
 from typing import Annotated, Any, Literal
 
@@ -15,6 +16,8 @@ from transport.legacy.unity_connection import async_send_command_with_retry, _ex
 from services.state.external_changes_scanner import external_changes_scanner
 import services.resources.editor_state as editor_state
 
+logger = logging.getLogger(__name__)
+
 
 @mcp_for_unity_tool(
     description="Request a Unity asset database refresh and optionally a script compilation. Can optionally wait for readiness.",
@@ -43,36 +46,65 @@ async def refresh_unity(
     }
 
     recovered_from_disconnect = False
+    # Don't retry on reload - refresh_unity triggers compilation/reload,
+    # so retrying would cause multiple reloads (issue #577)
     response = await unity_transport.send_with_unity_instance(
         async_send_command_with_retry,
         unity_instance,
         "refresh_unity",
         params,
+        retry_on_reload=False,
     )
 
-    # 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 "").lower()
-        reason = _extract_response_reason(response)
-        is_retryable = (
-            hint == "retry"
+    # Handle connection errors during refresh/compile gracefully.
+    # Unity disconnects during domain reload, which is expected behavior - not a failure.
+    # If we sent the command and connection closed, the refresh was likely triggered successfully.
+    # Convert MCPResponse to dict if needed
+    response_dict = response if isinstance(response, dict) else (response.model_dump() if hasattr(response, "model_dump") else response.__dict__)
+    if not response_dict.get("success", True):
+        hint = response_dict.get("hint")
+        err = (response_dict.get("error") or response_dict.get("message") or "").lower()
+        reason = _extract_response_reason(response_dict)
+
+        # Connection closed/timeout during compile = refresh was triggered, Unity is reloading
+        # This is SUCCESS, not failure - don't return error to prevent Claude Code from retrying
+        is_connection_lost = (
+            "connection closed" in err
             or "disconnected" in err
-            or "could not connect" in err  # Connection failed during domain reload
+            or "aborted" in err  # WinError 10053: connection aborted
+            or "timeout" in err
+            or reason == "reloading"
         )
-        if (not wait_for_ready) or (not is_retryable):
-            return MCPResponse(**response)
-        if reason not in {"reloading", "no_unity_session"}:
+
+        if is_connection_lost and compile == "request":
+            # EXPECTED BEHAVIOR: When compile="request", Unity triggers domain reload which
+            # causes connection to close mid-command. This is NOT a failure - the refresh
+            # was successfully triggered. Treating this as success prevents Claude Code from
+            # retrying unnecessarily (which would cause multiple domain reloads - issue #577).
+            # The subsequent wait_for_ready loop (below) will verify Unity becomes ready.
+            logger.info("refresh_unity: Connection lost during compile (expected - domain reload triggered)")
             recovered_from_disconnect = True
+        elif hint == "retry" or "could not connect" in err:
+            # Retryable error - proceed to wait loop if wait_for_ready
+            if not wait_for_ready:
+                return MCPResponse(**response_dict)
+            recovered_from_disconnect = True
+        else:
+            # Non-recoverable error - connection issue unrelated to domain reload
+            logger.warning(f"refresh_unity: Non-recoverable error (compile={compile}): {err[:100]}")
+            return MCPResponse(**response_dict)
 
     # Optional server-side wait loop (defensive): if Unity tool doesn't wait or returns quickly,
     # poll the canonical editor_state resource until ready or timeout.
+    ready_confirmed = False
     if wait_for_ready:
         timeout_s = 60.0
         start = time.monotonic()
 
+        # Blocking reasons that indicate Unity is actually busy (not just stale status)
+        # Must match activityPhase values from EditorStateCache.cs
+        real_blocking_reasons = {"compiling", "domain_reload", "running_tests", "asset_import"}
+
         while time.monotonic() - start < timeout_s:
             state_resp = await editor_state.get_editor_state(ctx)
             state = state_resp.model_dump() if hasattr(
@@ -81,10 +113,28 @@ async def refresh_unity(
                 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
+            if isinstance(advice, dict):
+                # Exit if ready_for_tools is True
+                if advice.get("ready_for_tools") is True:
+                    ready_confirmed = True
+                    break
+                # Also exit if the only blocking reason is "stale_status" (Unity in background)
+                # Staleness means we can't confirm status, not that Unity is actually busy
+                blocking = set(advice.get("blocking_reasons") or [])
+                if not (blocking & real_blocking_reasons):
+                    ready_confirmed = True  # No real blocking reasons, consider ready
+                    break
             await asyncio.sleep(0.25)
 
+        # If we timed out without confirming readiness, log and return failure
+        if not ready_confirmed:
+            logger.warning(f"refresh_unity: Timed out after {timeout_s}s waiting for editor to become ready")
+            return MCPResponse(
+                success=False,
+                message=f"Refresh triggered but timed out after {timeout_s}s waiting for editor readiness.",
+                data={"timeout": True, "wait_seconds": timeout_s},
+            )
+
     # After readiness is restored, clear any external-dirty flag for this instance so future tools can proceed cleanly.
     try:
         inst = unity_instance or await editor_state.infer_single_instance_id(ctx)
@@ -100,4 +150,4 @@ async def refresh_unity(
             data={"recovered_from_disconnect": True},
         )
 
-    return MCPResponse(**response) if isinstance(response, dict) else response
+    return MCPResponse(**response_dict) if isinstance(response, dict) else response

transport/legacy/unity_connection.py

@@ -233,14 +233,21 @@ class UnityConnection:
             logger.error(f"Error during receive: {str(e)}")
             raise
 
-    def send_command(self, command_type: str, params: dict[str, Any] = None) -> dict[str, Any]:
-        """Send a command with retry/backoff and port rediscovery. Pings only when requested."""
+    def send_command(self, command_type: str, params: dict[str, Any] = None, max_attempts: int | None = None) -> dict[str, Any]:
+        """Send a command with retry/backoff and port rediscovery. Pings only when requested.
+
+        Args:
+            command_type: The Unity command to send
+            params: Command parameters
+            max_attempts: Maximum retry attempts (None = use config default, 0 = no retries)
+        """
         # Defensive guard: catch empty/placeholder invocations early
         if not command_type:
             raise ValueError("MCP call missing command_type")
         if params is None:
             return MCPResponse(success=False, error="MCP call received with no parameters (client placeholder?)")
-        attempts = max(config.max_retries, 5)
+        attempts = max(config.max_retries,
+                       5) if max_attempts is None else max_attempts
         base_backoff = max(0.5, config.retry_delay)
 
         def read_status_file(target_hash: str | None = None) -> dict | None:
@@ -734,7 +741,8 @@ def send_command_with_retry(
     *,
     instance_id: str | None = None,
     max_retries: int | None = None,
-    retry_ms: int | None = None
+    retry_ms: int | None = None,
+    retry_on_reload: bool = True
 ) -> dict[str, Any] | MCPResponse:
     """Send a command to a Unity instance, waiting politely through Unity reloads.
 
@@ -744,6 +752,8 @@ def send_command_with_retry(
         instance_id: Optional Unity instance identifier (name, hash, name@hash, etc.)
         max_retries: Maximum number of retries for reload states
         retry_ms: Delay between retries in milliseconds
+        retry_on_reload: If False, don't retry when Unity is reloading (for commands
+            that trigger compilation/reload and shouldn't be re-sent)
 
     Returns:
         Response dictionary or MCPResponse from Unity
@@ -768,11 +778,16 @@ def send_command_with_retry(
     # 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)
+    # If retry_on_reload=False, disable connection-level retries too (issue #577)
+    # Commands that trigger compilation/reload shouldn't retry on disconnect
+    send_max_attempts = None if retry_on_reload else 0
+
+    response = conn.send_command(
+        command_type, params, max_attempts=send_max_attempts)
     retries = 0
     wait_started = None
     reason = _extract_response_reason(response)
-    while _is_reloading_response(response) and retries < max_retries:
+    while retry_on_reload and _is_reloading_response(response) and retries < max_retries:
         if wait_started is None:
             wait_started = time.monotonic()
             logger.debug(
@@ -842,7 +857,8 @@ async def async_send_command_with_retry(
     instance_id: str | None = None,
     loop=None,
     max_retries: int | None = None,
-    retry_ms: int | None = None
+    retry_ms: int | None = None,
+    retry_on_reload: bool = True
 ) -> dict[str, Any] | MCPResponse:
     """Async wrapper that runs the blocking retry helper in a thread pool.
 
@@ -853,6 +869,7 @@ async def async_send_command_with_retry(
         loop: Optional asyncio event loop
         max_retries: Maximum number of retries for reload states
         retry_ms: Delay between retries in milliseconds
+        retry_on_reload: If False, don't retry when Unity is reloading
 
     Returns:
         Response dictionary or MCPResponse on error
@@ -864,7 +881,8 @@ async def async_send_command_with_retry(
         return await loop.run_in_executor(
             None,
             lambda: send_command_with_retry(
-                command_type, params, instance_id=instance_id, max_retries=max_retries, retry_ms=retry_ms),
+                command_type, params, instance_id=instance_id, max_retries=max_retries,
+                retry_ms=retry_ms, retry_on_reload=retry_on_reload),
         )
     except Exception as e:
         return MCPResponse(success=False, error=str(e))

transport/plugin_hub.py

@@ -315,6 +315,23 @@ class PluginHub(WebSocketEndpoint):
         logger.info(
             f"Registered {len(payload.tools)} tools for session {session_id}")
 
+        try:
+            from services.custom_tool_service import CustomToolService
+
+            service = CustomToolService.get_instance()
+            service.register_global_tools(payload.tools)
+        except RuntimeError as exc:
+            logger.debug(
+                "Skipping global custom tool registration: CustomToolService not initialized yet (%s)",
+                exc,
+            )
+        except Exception as exc:
+            logger.warning(
+                "Unexpected error during global custom tool registration; "
+                "custom tools may not be available globally",
+                exc_info=exc,
+            )
+
     async def _handle_command_result(self, payload: CommandResultMessage) -> None:
         cls = type(self)
         lock = cls._lock