mcpforunityserver 9.3.0__py3-none-any.whl → 9.3.0b20260128055651__py3-none-any.whl

services/resources/prefab.py

@@ -0,0 +1,191 @@
+"""
+MCP Resources for reading Prefab data from Unity.
+
+These resources provide read-only access to:
+- Prefab info by asset path (mcpforunity://prefab/{path})
+- Prefab hierarchy by asset path (mcpforunity://prefab/{path}/hierarchy)
+- Currently open prefab stage (mcpforunity://editor/prefab-stage - see prefab_stage.py)
+"""
+from typing import Any
+from urllib.parse import unquote
+from pydantic import BaseModel
+from fastmcp import Context
+
+from models import MCPResponse
+from services.registry import mcp_for_unity_resource
+from services.tools import get_unity_instance_from_context
+from transport.unity_transport import send_with_unity_instance
+from transport.legacy.unity_connection import async_send_command_with_retry
+
+
+def _normalize_response(response: dict | MCPResponse | Any) -> MCPResponse:
+    """Normalize Unity transport response to MCPResponse."""
+    if isinstance(response, dict):
+        return MCPResponse(**response)
+    if isinstance(response, MCPResponse):
+        return response
+    # Fallback: wrap unexpected types in an error response
+    return MCPResponse(success=False, error=f"Unexpected response type: {type(response).__name__}")
+
+
+def _decode_prefab_path(encoded_path: str) -> str:
+    """
+    Decode a URL-encoded prefab path.
+    Handles paths like 'Assets%2FPrefabs%2FMyPrefab.prefab' -> 'Assets/Prefabs/MyPrefab.prefab'
+    """
+    return unquote(encoded_path)
+
+
+# =============================================================================
+# Static Helper Resource (shows in UI)
+# =============================================================================
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://prefab-api",
+    name="prefab_api",
+    description="Documentation for Prefab resources. Use manage_asset action=search filterType=Prefab to find prefabs, then access resources below."
+)
+async def get_prefab_api_docs(_ctx: Context) -> MCPResponse:
+    """
+    Returns documentation for the Prefab resource API.
+
+    This is a helper resource that explains how to use the parameterized
+    Prefab resources which require an asset path.
+    """
+    docs = {
+        "overview": "Prefab resources provide read-only access to Unity prefab assets.",
+        "workflow": [
+            "1. Use manage_asset action=search filterType=Prefab to find prefabs",
+            "2. Use the asset path to access detailed data via resources below",
+            "3. Use manage_prefabs tool for prefab stage operations (open, save, close)"
+        ],
+        "path_encoding": {
+            "note": "Prefab paths must be URL-encoded when used in resource URIs",
+            "example": "Assets/Prefabs/MyPrefab.prefab -> Assets%2FPrefabs%2FMyPrefab.prefab"
+        },
+        "resources": {
+            "mcpforunity://prefab/{encoded_path}": {
+                "description": "Get prefab asset info (type, root name, components, variant info)",
+                "example": "mcpforunity://prefab/Assets%2FPrefabs%2FPlayer.prefab",
+                "returns": ["assetPath", "guid", "prefabType", "rootObjectName", "rootComponentTypes", "childCount", "isVariant", "parentPrefab"]
+            },
+            "mcpforunity://prefab/{encoded_path}/hierarchy": {
+                "description": "Get full prefab hierarchy with nested prefab information",
+                "example": "mcpforunity://prefab/Assets%2FPrefabs%2FPlayer.prefab/hierarchy",
+                "returns": ["prefabPath", "total", "items (with name, instanceId, path, componentTypes, prefab nesting info)"]
+            },
+            "mcpforunity://editor/prefab-stage": {
+                "description": "Get info about the currently open prefab stage (if any)",
+                "returns": ["isOpen", "assetPath", "prefabRootName", "mode", "isDirty"]
+            }
+        },
+        "related_tools": {
+            "manage_prefabs": "Open/close prefab stages, save changes, create prefabs from GameObjects",
+            "manage_asset": "Search for prefab assets, get asset info",
+            "manage_gameobject": "Modify GameObjects in open prefab stage",
+            "manage_components": "Add/remove/modify components on prefab GameObjects"
+        }
+    }
+    return MCPResponse(success=True, data=docs)
+
+
+# =============================================================================
+# Prefab Info Resource
+# =============================================================================
+
+# TODO: Use these typed response classes for better type safety once
+# we update the endpoints to validate response structure more strictly.
+
+
+class PrefabInfoData(BaseModel):
+    """Data for a prefab asset."""
+    assetPath: str
+    guid: str = ""
+    prefabType: str = "Regular"
+    rootObjectName: str = ""
+    rootComponentTypes: list[str] = []
+    childCount: int = 0
+    isVariant: bool = False
+    parentPrefab: str | None = None
+
+
+class PrefabInfoResponse(MCPResponse):
+    """Response containing prefab info data."""
+    data: PrefabInfoData | None = None
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://prefab/{encoded_path}",
+    name="prefab_info",
+    description="Get detailed information about a prefab asset by URL-encoded path. Returns prefab type, root object name, component types, child count, and variant info."
+)
+async def get_prefab_info(ctx: Context, encoded_path: str) -> MCPResponse:
+    """Get prefab asset info by path."""
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    # Decode the URL-encoded path
+    decoded_path = _decode_prefab_path(encoded_path)
+
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "manage_prefabs",
+        {
+            "action": "get_info",
+            "prefabPath": decoded_path
+        }
+    )
+
+    return _normalize_response(response)
+
+
+# =============================================================================
+# Prefab Hierarchy Resource
+# =============================================================================
+
+class PrefabHierarchyItem(BaseModel):
+    """Single item in prefab hierarchy."""
+    name: str
+    instanceId: int
+    path: str
+    activeSelf: bool = True
+    childCount: int = 0
+    componentTypes: list[str] = []
+    prefab: dict[str, Any] = {}
+
+
+class PrefabHierarchyData(BaseModel):
+    """Data for prefab hierarchy."""
+    prefabPath: str
+    total: int = 0
+    items: list[PrefabHierarchyItem] = []
+
+
+class PrefabHierarchyResponse(MCPResponse):
+    """Response containing prefab hierarchy data."""
+    data: PrefabHierarchyData | None = None
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://prefab/{encoded_path}/hierarchy",
+    name="prefab_hierarchy",
+    description="Get the full hierarchy of a prefab with nested prefab information. Returns all GameObjects with their components and nesting depth."
+)
+async def get_prefab_hierarchy(ctx: Context, encoded_path: str) -> MCPResponse:
+    """Get prefab hierarchy by path."""
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    # Decode the URL-encoded path
+    decoded_path = _decode_prefab_path(encoded_path)
+
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "manage_prefabs",
+        {
+            "action": "get_hierarchy",
+            "prefabPath": decoded_path
+        }
+    )
+
+    return _normalize_response(response)

services/tools/manage_components.py

@@ -37,7 +37,7 @@ async def manage_components(
     # For set_property action - single property
     property: Annotated[str,
                         "Property name to set (for set_property action)"] | None = None,
-    value: Annotated[Any,
+    value: Annotated[str | int | float | bool | dict | list ,
                      "Value to set (for set_property action)"] | None = None,
     # For add/set_property - multiple properties
     properties: Annotated[

services/tools/manage_gameobject.py

@@ -13,32 +13,40 @@ from services.tools.utils import coerce_bool, parse_json_payload, coerce_int
 from services.tools.preflight import preflight
 
 
-def _normalize_vector(value: Any, default: Any = None) -> list[float] | None:
+def _normalize_vector(value: Any, param_name: str = "vector") -> tuple[list[float] | None, str | None]:
     """
     Robustly normalize a vector parameter to [x, y, z] format.
     Handles: list, tuple, JSON string, comma-separated string.
-    Returns None if parsing fails.
+    Returns (parsed_vector, error_message). If error_message is set, parsed_vector is None.
     """
     if value is None:
-        return default
+        return None, None
 
     # 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])]
-            return vec if all(math.isfinite(n) for n in vec) else default
+            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 default
+            return None, f"{param_name} values must be numbers, got {value}"
 
     # Try parsing as JSON 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 (list or JSON string)"
+
         parsed = parse_json_payload(value)
         if isinstance(parsed, list) and len(parsed) == 3:
             try:
                 vec = [float(parsed[0]), float(parsed[1]), float(parsed[2])]
-                return vec if all(math.isfinite(n) for n in vec) else default
+                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):
-                pass
+                return None, f"{param_name} values must be numbers, got {parsed}"
 
         # Handle legacy comma-separated strings "1,2,3" or "[1,2,3]"
         s = value.strip()
@@ -48,11 +56,15 @@ def _normalize_vector(value: Any, default: Any = None) -> list[float] | None:
         if len(parts) == 3:
             try:
                 vec = [float(parts[0]), float(parts[1]), float(parts[2])]
-                return vec if all(math.isfinite(n) for n in vec) else default
+                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):
-                pass
+                return None, f"{param_name} values must be numbers, got {value}"
+
+        return None, f"{param_name} must be a [x, y, z] array (list or JSON string), got: {value}"
 
-    return default
+    return None, f"{param_name} must be a list or JSON string, got {type(value).__name__}"
 
 
 def _normalize_component_properties(value: Any) -> tuple[dict[str, dict[str, Any]] | None, str | None]:
@@ -103,12 +115,12 @@ async def manage_gameobject(
                    "Tag name - used for both 'create' (initial tag) and 'modify' (change tag)"] | None = None,
     parent: Annotated[str,
                       "Parent GameObject reference - used for both 'create' (initial parent) and 'modify' (change parent)"] | None = None,
-    position: Annotated[list[float],
-                        "Position as [x, y, z] array"] | None = None,
-    rotation: Annotated[list[float],
-                        "Rotation as [x, y, z] euler angles array"] | None = None,
-    scale: Annotated[list[float],
-                     "Scale as [x, y, z] array"] | None = None,
+    position: Annotated[list[float] | str,
+                        "Position as [x, y, z] array (list or JSON string)"] | None = None,
+    rotation: Annotated[list[float] | str,
+                        "Rotation as [x, y, z] euler angles array (list or JSON string)"] | None = None,
+    scale: Annotated[list[float] | str,
+                     "Scale as [x, y, z] array (list or JSON string)"] | None = None,
     components_to_add: Annotated[list[str],
                                  "List of component names to add"] | None = None,
     primitive_type: Annotated[str,
@@ -157,8 +169,8 @@ async def manage_gameobject(
     # --- Parameters for 'duplicate' ---
     new_name: Annotated[str,
                         "New name for the duplicated object (default: SourceName_Copy)"] | None = None,
-    offset: Annotated[list[float],
-                      "Offset from original/reference position as [x, y, z] array"] | None = None,
+    offset: Annotated[list[float] | str,
+                      "Offset from original/reference position as [x, y, z] array (list or JSON string)"] | None = None,
     # --- Parameters for 'move_relative' ---
     reference_object: Annotated[str,
                                 "Reference object for relative movement (required for move_relative)"] | None = None,
@@ -183,11 +195,19 @@ async def manage_gameobject(
             "message": "Missing required parameter 'action'. Valid actions: create, modify, delete, duplicate, move_relative. For finding GameObjects use find_gameobjects tool. For component operations use manage_components tool."
         }
 
-    # --- Normalize vector parameters using robust helper ---
-    position = _normalize_vector(position)
-    rotation = _normalize_vector(rotation)
-    scale = _normalize_vector(scale)
-    offset = _normalize_vector(offset)
+    # --- Normalize vector parameters with detailed error handling ---
+    position, position_error = _normalize_vector(position, "position")
+    if position_error:
+        return {"success": False, "message": position_error}
+    rotation, rotation_error = _normalize_vector(rotation, "rotation")
+    if rotation_error:
+        return {"success": False, "message": rotation_error}
+    scale, scale_error = _normalize_vector(scale, "scale")
+    if scale_error:
+        return {"success": False, "message": scale_error}
+    offset, offset_error = _normalize_vector(offset, "offset")
+    if offset_error:
+        return {"success": False, "message": offset_error}
 
     # --- Normalize boolean parameters ---
     save_as_prefab = coerce_bool(save_as_prefab)

services/tools/manage_material.py

@@ -82,8 +82,8 @@ async def manage_material(
                      "Value to set (color array, float, texture path/instruction)"] | None = None,
 
     # set_material_color / set_renderer_color
-    color: Annotated[list[float],
-                     "Color as [r, g, b] or [r, g, b, a] array."] | None = None,
+    color: Annotated[list[float] | str,
+                     "Color as [r, g, b] or [r, g, b, a] array (list or JSON string)."] | None = None,
 
     # assign_material_to_renderer / set_renderer_color
     target: Annotated[str,

services/tools/manage_prefabs.py

@@ -5,13 +5,28 @@ 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_bool
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
-from services.tools.utils import coerce_bool
+from services.tools.preflight import preflight
+
+
+# Required parameters for each action
+REQUIRED_PARAMS = {
+    "get_info": ["prefab_path"],
+    "get_hierarchy": ["prefab_path"],
+    "create_from_gameobject": ["target", "prefab_path"],
+    "modify_contents": ["prefab_path"],
+}
 
 
 @mcp_for_unity_tool(
-    description="Performs prefab operations (open_stage, close_stage, save_open_stage, create_from_gameobject).",
+    description=(
+        "Manages Unity Prefab assets via headless operations (no UI, no prefab stages). "
+        "Actions: get_info, get_hierarchy, create_from_gameobject, modify_contents. "
+        "Use modify_contents for headless prefab editing - ideal for automated workflows. "
+        "Use manage_asset action=search filterType=Prefab to list prefabs."
+    ),
     annotations=ToolAnnotations(
         title="Manage Prefabs",
         destructiveHint=True,
@@ -19,50 +34,132 @@ from services.tools.utils import coerce_bool
 )
 async def manage_prefabs(
     ctx: Context,
-    action: Annotated[Literal["open_stage", "close_stage", "save_open_stage", "create_from_gameobject"], "Perform prefab operations."],
-    prefab_path: Annotated[str,
-                           "Prefab asset path relative to Assets e.g. Assets/Prefabs/favorite.prefab"] | None = None,
-    mode: Annotated[str,
-                    "Optional prefab stage mode (only 'InIsolation' is currently supported)"] | None = None,
-    save_before_close: Annotated[bool,
-                                 "When true, `close_stage` will save the prefab before exiting the stage."] | None = None,
-    target: Annotated[str,
-                      "Scene GameObject name required for create_from_gameobject"] | None = None,
-    allow_overwrite: Annotated[bool,
-                               "Allow replacing an existing prefab at the same path"] | None = None,
-    search_inactive: Annotated[bool,
-                               "Include inactive objects when resolving the target name"] | None = None,
+    action: Annotated[
+        Literal[
+            "create_from_gameobject",
+            "get_info",
+            "get_hierarchy",
+            "modify_contents",
+        ],
+        "Prefab operation to perform.",
+    ],
+    prefab_path: Annotated[str, "Prefab asset path (e.g., Assets/Prefabs/MyPrefab.prefab)."] | None = None,
+    target: Annotated[str, "Target GameObject: scene object for create_from_gameobject, or object within prefab for modify_contents (name or path like 'Parent/Child')."] | None = None,
+    allow_overwrite: Annotated[bool, "Allow replacing existing prefab."] | None = None,
+    search_inactive: Annotated[bool, "Include inactive GameObjects in search."] | None = None,
+    unlink_if_instance: Annotated[bool, "Unlink from existing prefab before creating new one."] | None = None,
+    # modify_contents parameters
+    position: Annotated[list[float], "New local position [x, y, z] for modify_contents."] | None = None,
+    rotation: Annotated[list[float], "New local rotation (euler angles) [x, y, z] for modify_contents."] | None = None,
+    scale: Annotated[list[float], "New local scale [x, y, z] for modify_contents."] | None = None,
+    name: Annotated[str, "New name for the target object in modify_contents."] | None = None,
+    tag: Annotated[str, "New tag for the target object in modify_contents."] | None = None,
+    layer: Annotated[str, "New layer name for the target object in modify_contents."] | None = None,
+    set_active: Annotated[bool, "Set active state of target object in modify_contents."] | None = None,
+    parent: Annotated[str, "New parent object name/path within prefab for modify_contents."] | None = None,
+    components_to_add: Annotated[list[str], "Component types to add in modify_contents."] | None = None,
+    components_to_remove: Annotated[list[str], "Component types to remove in modify_contents."] | None = None,
 ) -> dict[str, Any]:
-    # Get active instance from session state
-    # Removed session_state import
+    # Back-compat: map 'name' → 'target' for create_from_gameobject (Unity accepts both)
+    if action == "create_from_gameobject" and target is None and name is not None:
+        target = name
+
+    # Validate required parameters
+    required = REQUIRED_PARAMS.get(action, [])
+    for param_name in required:
+        # Use updated local value for target after back-compat mapping
+        param_value = target if param_name == "target" else locals().get(param_name)
+        # Check for None and empty/whitespace strings
+        if param_value is None or (isinstance(param_value, str) and not param_value.strip()):
+            return {
+                "success": False,
+                "message": f"Action '{action}' requires parameter '{param_name}'."
+            }
+
     unity_instance = get_unity_instance_from_context(ctx)
 
+    # Preflight check for operations to ensure Unity is ready
     try:
+        gate = await preflight(ctx, wait_for_no_compile=True, refresh_if_dirty=True)
+        if gate is not None:
+            return gate.model_dump()
+    except Exception as exc:
+        return {
+            "success": False,
+            "message": f"Unity preflight check failed: {exc}"
+        }
+
+    try:
+        # Build parameters dictionary
         params: dict[str, Any] = {"action": action}
 
+        # Handle prefab path parameter
         if prefab_path:
             params["prefabPath"] = prefab_path
-        if mode:
-            params["mode"] = mode
-        save_before_close_val = coerce_bool(save_before_close)
-        if save_before_close_val is not None:
-            params["saveBeforeClose"] = save_before_close_val
+
         if target:
             params["target"] = target
+
         allow_overwrite_val = coerce_bool(allow_overwrite)
         if allow_overwrite_val is not None:
             params["allowOverwrite"] = allow_overwrite_val
+
         search_inactive_val = coerce_bool(search_inactive)
         if search_inactive_val is not None:
             params["searchInactive"] = search_inactive_val
-        response = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "manage_prefabs", params)
 
-        if isinstance(response, dict) and response.get("success"):
-            return {
-                "success": True,
-                "message": response.get("message", "Prefab operation successful."),
-                "data": response.get("data"),
-            }
-        return response if isinstance(response, dict) else {"success": False, "message": str(response)}
+        unlink_if_instance_val = coerce_bool(unlink_if_instance)
+        if unlink_if_instance_val is not None:
+            params["unlinkIfInstance"] = unlink_if_instance_val
+
+        # modify_contents parameters
+        if position is not None:
+            params["position"] = position
+        if rotation is not None:
+            params["rotation"] = rotation
+        if scale is not None:
+            params["scale"] = scale
+        if name is not None:
+            params["name"] = name
+        if tag is not None:
+            params["tag"] = tag
+        if layer is not None:
+            params["layer"] = layer
+        set_active_val = coerce_bool(set_active)
+        if set_active_val is not None:
+            params["setActive"] = set_active_val
+        if parent is not None:
+            params["parent"] = parent
+        if components_to_add is not None:
+            params["componentsToAdd"] = components_to_add
+        if components_to_remove is not None:
+            params["componentsToRemove"] = components_to_remove
+
+        # Send command to Unity
+        response = await send_with_unity_instance(
+            async_send_command_with_retry, unity_instance, "manage_prefabs", params
+        )
+
+        # Return Unity response directly; ensure success field exists
+        # Handle MCPResponse objects (returned on error) by converting to dict
+        if hasattr(response, 'model_dump'):
+            return response.model_dump()
+        if isinstance(response, dict):
+            if "success" not in response:
+                response["success"] = False
+            return response
+        return {
+            "success": False,
+            "message": f"Unexpected response type: {type(response).__name__}"
+        }
+
+    except TimeoutError:
+        return {
+            "success": False,
+            "message": "Unity connection timeout. Please check if Unity is running and responsive."
+        }
     except Exception as exc:
-        return {"success": False, "message": f"Python error managing prefabs: {exc}"}
+        return {
+            "success": False,
+            "message": f"Error managing prefabs: {exc}"
+        }