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

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:

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:
@@ -584,7 +591,7 @@ class UnityConnectionPool:
         raise ConnectionError(
             f"Unity instance '{identifier}' not found. "
             f"Available instances: {available_ids}. "
-            f"Check unity://instances resource for all instances."
+            f"Check mcpforunity://instances resource for all instances."
         )
 
     def get_connection(self, instance_identifier: str | None = None) -> UnityConnection:
@@ -686,28 +693,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(
@@ -716,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.
 
@@ -726,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
@@ -738,15 +766,87 @@ 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)
-
-    response = conn.send_command(command_type, params)
+    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))
+
+    # 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
-    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))
+    wait_started = None
+    reason = _extract_response_reason(response)
+    while retry_on_reload and _is_reloading_response(response) and retries < max_retries:
+        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
 
 
@@ -757,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.
 
@@ -768,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
@@ -779,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))