mcpforunityserver 8.2.3__py3-none-any.whl

services/tools/manage_gameobject.py

@@ -0,0 +1,240 @@
+import json
+import math
+from typing import Annotated, Any, Literal, Union
+
+from fastmcp import Context
+from services.registry import mcp_for_unity_tool
+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
+from services.tools.utils import coerce_bool, parse_json_payload
+
+
+@mcp_for_unity_tool(
+    description="Performs CRUD operations on GameObjects and components."
+)
+async def manage_gameobject(
+    ctx: Context,
+    action: Annotated[Literal["create", "modify", "delete", "find", "add_component", "remove_component", "set_component_property", "get_components", "get_component", "duplicate", "move_relative"], "Perform CRUD operations on GameObjects and components."] | None = None,
+    target: Annotated[str,
+                      "GameObject identifier by name or path for modify/delete/component actions"] | None = None,
+    search_method: Annotated[Literal["by_id", "by_name", "by_path", "by_tag", "by_layer", "by_component"],
+                             "How to find objects. Used with 'find' and some 'target' lookups."] | None = None,
+    name: Annotated[str,
+                    "GameObject name for 'create' (initial name) and 'modify' (rename) actions ONLY. For 'find' action, use 'search_term' instead."] | None = None,
+    tag: Annotated[str,
+                   "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[Union[list[float], str],
+                        "Position - [x,y,z] or string '[x,y,z]' for client compatibility"] | None = None,
+    rotation: Annotated[Union[list[float], str],
+                        "Rotation - [x,y,z] or string '[x,y,z]' for client compatibility"] | None = None,
+    scale: Annotated[Union[list[float], str],
+                     "Scale - [x,y,z] or string '[x,y,z]' for client compatibility"] | None = None,
+    components_to_add: Annotated[list[str],
+                                 "List of component names to add"] | None = None,
+    primitive_type: Annotated[str,
+                              "Primitive type for 'create' action"] | None = None,
+    save_as_prefab: Annotated[bool | str,
+                              "If True, saves the created GameObject as a prefab (accepts true/false or 'true'/'false')"] | None = None,
+    prefab_path: Annotated[str, "Path for prefab creation"] | None = None,
+    prefab_folder: Annotated[str,
+                             "Folder for prefab creation"] | None = None,
+    # --- Parameters for 'modify' ---
+    set_active: Annotated[bool | str,
+                          "If True, sets the GameObject active (accepts true/false or 'true'/'false')"] | None = None,
+    layer: Annotated[str, "Layer name"] | None = None,
+    components_to_remove: Annotated[list[str],
+                                    "List of component names to remove"] | None = None,
+    component_properties: Annotated[Union[dict[str, dict[str, Any]], str],
+                                    """Dictionary of component names to their properties to set. For example:
+                                    `{"MyScript": {"otherObject": {"find": "Player", "method": "by_name"}}}` assigns GameObject
+                                    `{"MyScript": {"playerHealth": {"find": "Player", "component": "HealthComponent"}}}` assigns Component
+                                    Example set nested property:
+                                    - Access shared material: `{"MeshRenderer": {"sharedMaterial.color": [1, 0, 0, 1]}}`"""] | None = None,
+    # --- Parameters for 'find' ---
+    search_term: Annotated[str,
+                           "Search term for 'find' action ONLY. Use this (not 'name') when searching for GameObjects."] | None = None,
+    find_all: Annotated[bool | str,
+                        "If True, finds all GameObjects matching the search term (accepts true/false or 'true'/'false')"] | None = None,
+    search_in_children: Annotated[bool | str,
+                                  "If True, searches in children of the GameObject (accepts true/false or 'true'/'false')"] | None = None,
+    search_inactive: Annotated[bool | str,
+                               "If True, searches inactive GameObjects (accepts true/false or 'true'/'false')"] | None = None,
+    # -- Component Management Arguments --
+    component_name: Annotated[str,
+                              "Component name for 'add_component' and 'remove_component' actions"] | None = None,
+    # Controls whether serialization of private [SerializeField] fields is included
+    includeNonPublicSerialized: Annotated[bool | str,
+                                          "Controls whether serialization of private [SerializeField] fields is included (accepts true/false or 'true'/'false')"] | None = None,
+    # --- Parameters for 'duplicate' ---
+    new_name: Annotated[str,
+                        "New name for the duplicated object (default: SourceName_Copy)"] | None = None,
+    offset: Annotated[Union[list[float], str],
+                      "Offset from original/reference position - [x,y,z] or string '[x,y,z]'"] | None = None,
+    # --- Parameters for 'move_relative' ---
+    reference_object: Annotated[str,
+                               "Reference object for relative movement (required for move_relative)"] | None = None,
+    direction: Annotated[Literal["left", "right", "up", "down", "forward", "back", "front", "backward", "behind"],
+                        "Direction for relative movement (e.g., 'right', 'up', 'forward')"] | None = None,
+    distance: Annotated[float,
+                       "Distance to move in the specified direction (default: 1.0)"] | None = None,
+    world_space: Annotated[bool | str,
+                          "If True (default), use world space directions; if False, use reference object's local directions"] | None = None,
+) -> dict[str, Any]:
+    # Get active instance from session state
+    # Removed session_state import
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    if action is None:
+        return {
+            "success": False,
+            "message": "Missing required parameter 'action'. Valid actions: create, modify, delete, find, add_component, remove_component, set_component_property, get_components, get_component, duplicate, move_relative"
+        }
+
+    # Coercers to tolerate stringified booleans and vectors
+    def _coerce_vec(value, default=None):
+        if value is None:
+            return default
+        
+        # First try to parse if it's a string
+        val = parse_json_payload(value)
+        
+        def _to_vec3(parts):
+            try:
+                vec = [float(parts[0]), float(parts[1]), float(parts[2])]
+            except (ValueError, TypeError):
+                return default
+            return vec if all(math.isfinite(n) for n in vec) else default
+            
+        if isinstance(val, list) and len(val) == 3:
+            return _to_vec3(val)
+            
+        # Handle legacy comma-separated strings "1,2,3" that parse_json_payload doesn't handle (since they aren't JSON arrays)
+        if isinstance(val, str):
+            s = val.strip()
+            # minimal tolerant parse for "[x,y,z]" or "x,y,z"
+            if s.startswith("[") and s.endswith("]"):
+                s = s[1:-1]
+            # support "x,y,z" and "x y z"
+            parts = [p.strip()
+                     for p in (s.split(",") if "," in s else s.split())]
+            if len(parts) == 3:
+                return _to_vec3(parts)
+        return default
+
+    position = _coerce_vec(position, default=position)
+    rotation = _coerce_vec(rotation, default=rotation)
+    scale = _coerce_vec(scale, default=scale)
+    offset = _coerce_vec(offset, default=offset)
+    save_as_prefab = coerce_bool(save_as_prefab)
+    set_active = coerce_bool(set_active)
+    find_all = coerce_bool(find_all)
+    search_in_children = coerce_bool(search_in_children)
+    search_inactive = coerce_bool(search_inactive)
+    includeNonPublicSerialized = coerce_bool(includeNonPublicSerialized)
+    world_space = coerce_bool(world_space, default=True)
+
+    # Coerce 'component_properties' from JSON string to dict for client compatibility
+    component_properties = parse_json_payload(component_properties)
+    
+    # Ensure final type is a dict (object) if provided
+    if component_properties is not None and not isinstance(component_properties, dict):
+        return {"success": False, "message": "component_properties must be a JSON object (dict)."}
+        
+    try:
+        # Map tag to search_term when search_method is by_tag for backward compatibility
+        if action == "find" and search_method == "by_tag" and tag is not None and search_term is None:
+            search_term = tag
+
+        # Validate parameter usage to prevent silent failures
+        if action == "find":
+            if name is not None:
+                return {
+                    "success": False,
+                    "message": "For 'find' action, use 'search_term' parameter, not 'name'. Remove 'name' parameter. Example: search_term='Player', search_method='by_name'"
+                }
+            if search_term is None:
+                return {
+                    "success": False,
+                    "message": "For 'find' action, 'search_term' parameter is required. Use search_term (not 'name') to specify what to find."
+                }
+
+        if action in ["create", "modify"]:
+            if search_term is not None:
+                return {
+                    "success": False,
+                    "message": f"For '{action}' action, use 'name' parameter, not 'search_term'."
+                }
+
+        # Prepare parameters, removing None values
+        params = {
+            "action": action,
+            "target": target,
+            "searchMethod": search_method,
+            "name": name,
+            "tag": tag,
+            "parent": parent,
+            "position": position,
+            "rotation": rotation,
+            "scale": scale,
+            "componentsToAdd": components_to_add,
+            "primitiveType": primitive_type,
+            "saveAsPrefab": save_as_prefab,
+            "prefabPath": prefab_path,
+            "prefabFolder": prefab_folder,
+            "setActive": set_active,
+            "layer": layer,
+            "componentsToRemove": components_to_remove,
+            "componentProperties": component_properties,
+            "searchTerm": search_term,
+            "findAll": find_all,
+            "searchInChildren": search_in_children,
+            "searchInactive": search_inactive,
+            "componentName": component_name,
+            "includeNonPublicSerialized": includeNonPublicSerialized,
+            # Parameters for 'duplicate'
+            "new_name": new_name,
+            "offset": offset,
+            # Parameters for 'move_relative'
+            "reference_object": reference_object,
+            "direction": direction,
+            "distance": distance,
+            "world_space": world_space,
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+
+        # --- Handle Prefab Path Logic ---
+        # Check if 'saveAsPrefab' is explicitly True in params
+        if action == "create" and params.get("saveAsPrefab"):
+            if "prefabPath" not in params:
+                if "name" not in params or not params["name"]:
+                    return {"success": False, "message": "Cannot create default prefab path: 'name' parameter is missing."}
+                # Use the provided prefab_folder (which has a default) and the name to construct the path
+                constructed_path = f"{prefab_folder}/{params['name']}.prefab"
+                # Ensure clean path separators (Unity prefers '/')
+                params["prefabPath"] = constructed_path.replace("\\", "/")
+            elif not params["prefabPath"].lower().endswith(".prefab"):
+                return {"success": False, "message": f"Invalid prefab_path: '{params['prefabPath']}' must end with .prefab"}
+        # Ensure prefabFolder itself isn't sent if prefabPath was constructed or provided
+        # The C# side only needs the final prefabPath
+        params.pop("prefabFolder", None)
+        # --------------------------------
+
+        # Use centralized retry helper with instance routing
+        response = await send_with_unity_instance(
+            async_send_command_with_retry,
+            unity_instance,
+            "manage_gameobject",
+            params,
+        )
+
+        # Check if the response indicates success
+        # If the response is not successful, raise an exception with the error message
+        if isinstance(response, dict) and response.get("success"):
+            return {"success": True, "message": response.get("message", "GameObject operation successful."), "data": response.get("data")}
+        return response if isinstance(response, dict) else {"success": False, "message": str(response)}
+
+    except Exception as e:
+        return {"success": False, "message": f"Python error managing GameObject: {e!s}"}

services/tools/manage_material.py

@@ -0,0 +1,95 @@
+"""
+Defines the manage_material tool for interacting with Unity materials.
+"""
+import json
+from typing import Annotated, Any, Literal, Union
+
+from fastmcp import Context
+from services.registry import mcp_for_unity_tool
+from services.tools import get_unity_instance_from_context
+from services.tools.utils import parse_json_payload
+from transport.unity_transport import send_with_unity_instance
+from transport.legacy.unity_connection import async_send_command_with_retry
+
+
+@mcp_for_unity_tool(
+    description="Manages Unity materials (set properties, colors, shaders, etc)."
+)
+async def manage_material(
+    ctx: Context,
+    action: Annotated[Literal[
+        "ping",
+        "create",
+        "set_material_shader_property",
+        "set_material_color",
+        "assign_material_to_renderer",
+        "set_renderer_color",
+        "get_material_info"
+    ], "Action to perform."],
+    
+    # Common / Shared
+    material_path: Annotated[str, "Path to material asset (Assets/...)"] | None = None,
+    property: Annotated[str, "Shader property name (e.g., _BaseColor, _MainTex)"] | None = None,
+
+    # create
+    shader: Annotated[str, "Shader name (default: Standard)"] | None = None,
+    properties: Annotated[Union[dict[str, Any], str], "Initial properties to set {name: value}."] | None = None,
+    
+    # set_material_shader_property
+    value: Annotated[Union[list, float, int, str, bool, None], "Value to set (color array, float, texture path/instruction)"] | None = None,
+    
+    # set_material_color / set_renderer_color
+    color: Annotated[Union[list[float], list[int], str], "Color as [r,g,b] or [r,g,b,a]."] | None = None,
+    
+    # assign_material_to_renderer / set_renderer_color
+    target: Annotated[str, "Target GameObject (name, path, or find instruction)"] | None = None,
+    search_method: Annotated[Literal["by_name", "by_path", "by_tag", "by_layer", "by_component"], "Search method for target"] | None = None,
+    slot: Annotated[int | str, "Material slot index"] | None = None,
+    mode: Annotated[Literal["shared", "instance", "property_block"], "Assignment/modification mode"] | None = None,
+    
+) -> dict[str, Any]:
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    # Parse inputs that might be stringified JSON
+    color = parse_json_payload(color)
+    properties = parse_json_payload(properties)
+    value = parse_json_payload(value)
+
+    # Coerce slot to int if it's a string
+    if slot is not None:
+        if isinstance(slot, str):
+            try:
+                slot = int(slot)
+            except ValueError:
+                return {
+                    "success": False,
+                    "message": f"Invalid slot value: '{slot}' must be a valid integer"
+                }
+
+    # Prepare parameters for the C# handler
+    params_dict = {
+        "action": action.lower(),
+        "materialPath": material_path,
+        "shader": shader,
+        "properties": properties,
+        "property": property,
+        "value": value,
+        "color": color,
+        "target": target,
+        "searchMethod": search_method,
+        "slot": slot,
+        "mode": mode
+    }
+
+    # Remove None values
+    params_dict = {k: v for k, v in params_dict.items() if v is not None}
+
+    # Use centralized async retry helper with instance routing
+    result = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "manage_material",
+        params_dict,
+    )
+    
+    return result if isinstance(result, dict) else {"success": False, "message": str(result)}

services/tools/manage_prefabs.py

@@ -0,0 +1,62 @@
+from typing import Annotated, Any, Literal
+
+from fastmcp import Context
+from services.registry import mcp_for_unity_tool
+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
+from services.tools.utils import coerce_bool
+
+
+@mcp_for_unity_tool(
+    description="Performs prefab operations (open_stage, close_stage, save_open_stage, create_from_gameobject)."
+)
+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,
+) -> dict[str, Any]:
+    # Get active instance from session state
+    # Removed session_state import
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    try:
+        params: dict[str, Any] = {"action": action}
+
+        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)}
+    except Exception as exc:
+        return {"success": False, "message": f"Python error managing prefabs: {exc}"}

services/tools/manage_scene.py

@@ -0,0 +1,75 @@
+from typing import Annotated, Literal, Any
+
+from fastmcp import Context
+from services.registry import mcp_for_unity_tool
+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
+
+
+@mcp_for_unity_tool(
+    description="Performs CRUD operations on Unity scenes."
+)
+async def manage_scene(
+    ctx: Context,
+    action: Annotated[Literal[
+        "create",
+        "load",
+        "save",
+        "get_hierarchy",
+        "get_active",
+        "get_build_settings",
+        "screenshot",
+    ], "Perform CRUD operations on Unity scenes, and capture a screenshot."],
+    name: Annotated[str, "Scene name."] | None = None,
+    path: Annotated[str, "Scene path."] | None = None,
+    build_index: Annotated[int | str,
+                           "Unity build index (quote as string, e.g., '0')."] | None = None,
+    screenshot_file_name: Annotated[str, "Screenshot file name (optional). Defaults to timestamp when omitted."] | None = None,
+    screenshot_super_size: Annotated[int | str, "Screenshot supersize multiplier (integer ≥1). Optional." ] | None = None,
+) -> dict[str, Any]:
+    # Get active instance from session state
+    # Removed session_state import
+    unity_instance = get_unity_instance_from_context(ctx)
+    try:
+        # Coerce numeric inputs defensively
+        def _coerce_int(value, default=None):
+            if value is None:
+                return default
+            try:
+                if isinstance(value, bool):
+                    return default
+                if isinstance(value, int):
+                    return int(value)
+                s = str(value).strip()
+                if s.lower() in ("", "none", "null"):
+                    return default
+                return int(float(s))
+            except Exception:
+                return default
+
+        coerced_build_index = _coerce_int(build_index, default=None)
+        coerced_super_size = _coerce_int(screenshot_super_size, default=None)
+
+        params: dict[str, Any] = {"action": action}
+        if name:
+            params["name"] = name
+        if path:
+            params["path"] = path
+        if coerced_build_index is not None:
+            params["buildIndex"] = coerced_build_index
+        if screenshot_file_name:
+            params["fileName"] = screenshot_file_name
+        if coerced_super_size is not None:
+            params["superSize"] = coerced_super_size
+
+        # Use centralized retry helper with instance routing
+        response = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "manage_scene", params)
+
+        # Preserve structured failure data; unwrap success into a friendlier shape
+        if isinstance(response, dict) and response.get("success"):
+            return {"success": True, "message": response.get("message", "Scene operation successful."), "data": response.get("data")}
+        return response if isinstance(response, dict) else {"success": False, "message": str(response)}
+
+    except Exception as e:
+        return {"success": False, "message": f"Python error managing scene: {str(e)}"}