mcpforunityserver 9.4.0b20260203025228__py3-none-any.whl

services/tools/set_active_instance.py

@@ -0,0 +1,120 @@
+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
+from transport.plugin_hub import PluginHub
+from core.config import config
+
+
+@mcp_for_unity_tool(
+    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,
+        instance: Annotated[str, "Target instance (Name@hash or hash prefix)"]
+) -> dict[str, Any]:
+    transport = (config.transport_mode or "stdio").lower()
+
+    # Discover running instances based on transport
+    if transport == "http":
+        # In remote-hosted mode, filter sessions by user_id
+        user_id = ctx.get_state(
+            "user_id") if config.http_remote_hosted else None
+        sessions_data = await PluginHub.get_sessions(user_id=user_id)
+        sessions = sessions_data.sessions
+        instances = []
+        for session_id, session in sessions.items():
+            project = session.project or "Unknown"
+            hash_value = session.hash
+            if not hash_value:
+                continue
+            inst_id = f"{project}@{hash_value}"
+            instances.append(SimpleNamespace(
+                id=inst_id,
+                hash=hash_value,
+                name=project,
+                session_id=session_id,
+            ))
+    else:
+        pool = get_unity_connection_pool()
+        instances = pool.discover_all_instances(force_refresh=True)
+
+    if not instances:
+        return {
+            "success": False,
+            "error": "No Unity instances are currently connected. Start Unity and press 'Start Session'."
+        }
+    ids = {inst.id: inst for inst in instances if getattr(inst, "id", None)}
+
+    value = (instance or "").strip()
+    if not value:
+        return {
+            "success": False,
+            "error": "Instance identifier is required. "
+                     "Use mcpforunity://instances to copy a Name@hash or provide a hash prefix."
+        }
+    resolved = None
+    if "@" in value:
+        resolved = ids.get(value)
+        if resolved is None:
+            return {
+                "success": False,
+                "error": f"Instance '{value}' not found. "
+                "Use mcpforunity://instances to copy an exact Name@hash."
+            }
+    else:
+        lookup = value.lower()
+        matches = []
+        for inst in instances:
+            if not getattr(inst, "id", None):
+                continue
+            inst_hash = getattr(inst, "hash", "")
+            if inst_hash and inst_hash.lower().startswith(lookup):
+                matches.append(inst)
+        if not matches:
+            return {
+                "success": False,
+                "error": f"Instance hash '{value}' does not match any running Unity editors. "
+                "Use mcpforunity://instances to confirm the available hashes."
+            }
+        if len(matches) > 1:
+            matching_ids = ", ".join(
+                inst.id for inst in matches if getattr(inst, "id", None)
+            ) or "multiple instances"
+            return {
+                "success": False,
+                "error": f"Instance hash '{value}' is ambiguous ({matching_ids}). "
+                "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 {
+            "success": False,
+            "error": "Internal error: Instance resolution failed."
+        }
+
+    # Store selection in middleware (session-scoped)
+    middleware = get_unity_instance_middleware()
+    # We use middleware.set_active_instance to persist the selection.
+    # 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}",
+        "data": {
+            "instance": resolved.id,
+            "session_key": session_key,
+        },
+    }

services/tools/utils.py

@@ -0,0 +1,348 @@
+"""Shared helper utilities for MCP server tools."""
+
+from __future__ import annotations
+
+import json
+import math
+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:
+        return default
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in _TRUTHY:
+            return True
+        if lowered in _FALSY:
+            return False
+        return default
+    return bool(value)
+
+
+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 in ("true", "false", "null") or
+        (val_trimmed.replace(".", "", 1).replace("-", "", 1).isdigit())
+    ):
+        return value
+
+    try:
+        return json.loads(value)
+    except (json.JSONDecodeError, ValueError):
+        # If parsing fails, assume it was meant to be a literal string
+        return value
+
+
+def coerce_int(value: Any, default: int | None = None) -> int | None:
+    """Attempt to coerce a loosely-typed value to an integer."""
+    if value is None:
+        return default
+    try:
+        if isinstance(value, bool):
+            return default
+        if isinstance(value, int):
+            return value
+        s = str(value).strip()
+        if s.lower() in ("", "none", "null"):
+            return default
+        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__}"
+
+
+def normalize_vector3(value: Any, param_name: str = "vector") -> tuple[list[float] | None, str | None]:
+    """
+    Normalize a vector parameter to [x, y, z] format.
+
+    Handles various input formats from MCP clients/LLMs:
+    - None -> (None, None)
+    - list/tuple [x, y, z] -> ([x, y, z], None)
+    - dict {x, y, z} -> ([x, y, z], None)
+    - JSON string "[x, y, z]" or "{x, y, z}" -> parsed and normalized
+    - comma-separated string "x, y, z" -> ([x, y, z], None)
+
+    Returns:
+        Tuple of (parsed_vector, error_message). If error_message is set, parsed_vector is None.
+    """
+    if value is None:
+        return None, None
+
+    # Handle dict with x/y/z keys (e.g., {"x": 0, "y": 1, "z": 2})
+    if isinstance(value, dict):
+        if all(k in value for k in ("x", "y", "z")):
+            try:
+                vec = [float(value["x"]), float(value["y"]), float(value["z"])]
+                if all(math.isfinite(n) for n in vec):
+                    return vec, None
+                return None, f"{param_name} values must be finite numbers, got {value}"
+            except (ValueError, TypeError, KeyError):
+                return None, f"{param_name} dict values must be numbers, got {value}"
+        return None, f"{param_name} dict must have 'x', 'y', 'z' keys, got {list(value.keys())}"
+
+    # If already a list/tuple with 3 elements, convert to floats
+    if isinstance(value, (list, tuple)) and len(value) == 3:
+        try:
+            vec = [float(value[0]), float(value[1]), float(value[2])]
+            if all(math.isfinite(n) for n in vec):
+                return vec, None
+            return None, f"{param_name} values must be finite numbers, got {value}"
+        except (ValueError, TypeError):
+            return None, f"{param_name} values must be numbers, got {value}"
+
+    # Try parsing as string
+    if isinstance(value, str):
+        # Check for obviously invalid values
+        if value in ("[object Object]", "undefined", "null", ""):
+            return None, f"{param_name} received invalid value: '{value}'. Expected [x, y, z] array or {{x, y, z}} object"
+
+        parsed = parse_json_payload(value)
+
+        # Handle parsed dict
+        if isinstance(parsed, dict):
+            return normalize_vector3(parsed, param_name)
+
+        # Handle parsed list
+        if isinstance(parsed, list) and len(parsed) == 3:
+            try:
+                vec = [float(parsed[0]), float(parsed[1]), float(parsed[2])]
+                if all(math.isfinite(n) for n in vec):
+                    return vec, None
+                return None, f"{param_name} values must be finite numbers, got {parsed}"
+            except (ValueError, TypeError):
+                return None, f"{param_name} values must be numbers, got {parsed}"
+
+        # Handle comma-separated strings "1,2,3", "[1,2,3]", or "(1,2,3)"
+        s = value.strip()
+        if (s.startswith("[") and s.endswith("]")) or (s.startswith("(") and s.endswith(")")):
+            s = s[1:-1]
+        parts = [p.strip() for p in (s.split(",") if "," in s else s.split())]
+        if len(parts) == 3:
+            try:
+                vec = [float(parts[0]), float(parts[1]), float(parts[2])]
+                if all(math.isfinite(n) for n in vec):
+                    return vec, None
+                return None, f"{param_name} values must be finite numbers, got {value}"
+            except (ValueError, TypeError):
+                return None, f"{param_name} values must be numbers, got {value}"
+
+        return None, f"{param_name} must be a [x, y, z] array or {{x, y, z}} object, got: {value}"
+
+    return None, f"{param_name} must be a list, dict, or string, got {type(value).__name__}"
+
+
+def normalize_color(value: Any, output_range: str = "float") -> tuple[list[float] | None, str | None]:
+    """
+    Normalize a color parameter to [r, g, b, a] format.
+
+    Handles various input formats from MCP clients/LLMs:
+    - None -> (None, None)
+    - list/tuple [r, g, b] or [r, g, b, a] -> normalized with optional alpha
+    - dict {r, g, b} or {r, g, b, a} -> converted to list
+    - hex string "#RGB", "#RRGGBB", "#RRGGBBAA" -> parsed to [r, g, b, a]
+    - JSON string -> parsed and normalized
+
+    Args:
+        value: The color value to normalize
+        output_range: "float" for 0.0-1.0 range, "int" for 0-255 range
+
+    Returns:
+        Tuple of (parsed_color, error_message). If error_message is set, parsed_color is None.
+    """
+    if value is None:
+        return None, None
+
+    def _to_output_range(components: list[float], from_hex: bool = False) -> list:
+        """Convert color components to the requested output range."""
+        if output_range == "int":
+            if from_hex:
+                # Already 0-255 from hex parsing
+                return [int(c) for c in components]
+            # Check if input is normalized (0-1) or already 0-255
+            if all(0 <= c <= 1 for c in components):
+                return [int(round(c * 255)) for c in components]
+            return [int(c) for c in components]
+        else:  # float
+            if from_hex:
+                # Convert 0-255 to 0-1
+                return [c / 255.0 for c in components]
+            if any(c > 1 for c in components):
+                return [c / 255.0 for c in components]
+            return [float(c) for c in components]
+
+    # Handle dict with r/g/b keys
+    if isinstance(value, dict):
+        if all(k in value for k in ("r", "g", "b")):
+            try:
+                color = [float(value["r"]), float(value["g"]), float(value["b"])]
+                if "a" in value:
+                    color.append(float(value["a"]))
+                else:
+                    if output_range == "int" and all(0 <= c <= 1 for c in color):
+                        color.append(1.0)
+                    else:
+                        color.append(1.0 if output_range == "float" else 255)
+                return _to_output_range(color), None
+            except (ValueError, TypeError, KeyError):
+                return None, f"color dict values must be numbers, got {value}"
+        return None, f"color dict must have 'r', 'g', 'b' keys, got {list(value.keys())}"
+
+    # Already a list/tuple - validate
+    if isinstance(value, (list, tuple)):
+        if len(value) in (3, 4):
+            try:
+                color = [float(c) for c in value]
+                if len(color) == 3:
+                    if output_range == "int" and all(0 <= c <= 1 for c in color):
+                        color.append(1.0)
+                    else:
+                        color.append(1.0 if output_range == "float" else 255)
+                return _to_output_range(color), None
+            except (ValueError, TypeError):
+                return None, f"color values must be numbers, got {value}"
+        return None, f"color must have 3 or 4 components, got {len(value)}"
+
+    # Try parsing as string
+    if isinstance(value, str):
+        if value in ("[object Object]", "undefined", "null", ""):
+            return None, f"color received invalid value: '{value}'. Expected [r, g, b, a] or {{r, g, b, a}}"
+
+        # Handle hex colors
+        if value.startswith("#"):
+            h = value.lstrip("#")
+            try:
+                if len(h) == 3:
+                    # Short form #RGB -> expand to #RRGGBB
+                    components = [int(c + c, 16) for c in h] + [255]
+                    return _to_output_range(components, from_hex=True), None
+                elif len(h) == 6:
+                    components = [int(h[i:i+2], 16) for i in (0, 2, 4)] + [255]
+                    return _to_output_range(components, from_hex=True), None
+                elif len(h) == 8:
+                    components = [int(h[i:i+2], 16) for i in (0, 2, 4, 6)]
+                    return _to_output_range(components, from_hex=True), None
+            except ValueError:
+                return None, f"Invalid hex color: {value}"
+            return None, f"Invalid hex color length: {value}"
+
+        # Try parsing as JSON
+        parsed = parse_json_payload(value)
+
+        # Handle parsed dict
+        if isinstance(parsed, dict):
+            return normalize_color(parsed, output_range)
+
+        # Handle parsed list
+        if isinstance(parsed, (list, tuple)) and len(parsed) in (3, 4):
+            try:
+                color = [float(c) for c in parsed]
+                if len(color) == 3:
+                    if output_range == "int" and all(0 <= c <= 1 for c in color):
+                        color.append(1.0)
+                    else:
+                        color.append(1.0 if output_range == "float" else 255)
+                return _to_output_range(color), None
+            except (ValueError, TypeError):
+                return None, f"color values must be numbers, got {parsed}"
+
+        # Handle tuple-style strings "(r, g, b)" or "(r, g, b, a)"
+        s = value.strip()
+        if (s.startswith("[") and s.endswith("]")) or (s.startswith("(") and s.endswith(")")):
+            s = s[1:-1]
+        parts = [p.strip() for p in s.split(",")]
+        if len(parts) in (3, 4):
+            try:
+                color = [float(p) for p in parts]
+                if len(color) == 3:
+                    if output_range == "int" and all(0 <= c <= 1 for c in color):
+                        color.append(1.0)
+                    else:
+                        color.append(1.0 if output_range == "float" else 255)
+                return _to_output_range(color), None
+            except (ValueError, TypeError):
+                pass  # Fall through to error message
+
+        return None, f"Failed to parse color string: {value}"
+
+    return None, f"color must be a list, dict, hex string, or JSON string, got {type(value).__name__}"