mcpforunityserver 9.4.0b20260203025228__py3-none-any.whl

services/tools/manage_components.py

@@ -0,0 +1,131 @@
+"""
+Tool for managing components on GameObjects in Unity.
+Supports add, remove, and set_property operations.
+"""
+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 parse_json_payload, normalize_properties
+from services.tools.preflight import preflight
+
+
+@mcp_for_unity_tool(
+    description="Manages components on GameObjects (add, remove, set_property). For reading component data, use the mcpforunity://scene/gameobject/{id}/components resource."
+)
+async def manage_components(
+    ctx: Context,
+    action: Annotated[
+        Literal["add", "remove", "set_property"],
+        "Action to perform: add (add component), remove (remove component), set_property (set component property)"
+    ],
+    target: Annotated[
+        str | int,
+        "Target GameObject - instance ID (preferred) or name/path"
+    ],
+    component_type: Annotated[
+        str,
+        "Component type name (e.g., 'Rigidbody', 'BoxCollider', 'MyScript')"
+    ],
+    search_method: Annotated[
+        Literal["by_id", "by_name", "by_path"],
+        "How to find the target GameObject"
+    ] | None = None,
+    # For set_property action - single property
+    property: Annotated[str,
+                        "Property name to set (for set_property action)"] | None = None,
+    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[
+        dict[str, Any],
+        "Dictionary of property names to values. Example: {\"mass\": 5.0, \"useGravity\": false}"
+    ] | None = None,
+) -> dict[str, Any]:
+    """
+    Manage components on GameObjects.
+
+    Actions:
+    - add: Add a new component to a GameObject
+    - remove: Remove a component from a GameObject  
+    - set_property: Set one or more properties on a component
+
+    Examples:
+    - Add Rigidbody: action="add", target="Player", component_type="Rigidbody"
+    - Remove BoxCollider: action="remove", target=-12345, component_type="BoxCollider"
+    - Set single property: action="set_property", target="Enemy", component_type="Rigidbody", property="mass", value=5.0
+    - Set multiple properties: action="set_property", target="Enemy", component_type="Rigidbody", properties={"mass": 5.0, "useGravity": false}
+    """
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    gate = await preflight(ctx, wait_for_no_compile=True, refresh_if_dirty=True)
+    if gate is not None:
+        return gate.model_dump()
+
+    if not action:
+        return {
+            "success": False,
+            "message": "Missing required parameter 'action'. Valid actions: add, remove, set_property"
+        }
+
+    if not target:
+        return {
+            "success": False,
+            "message": "Missing required parameter 'target'. Specify GameObject instance ID or name."
+        }
+
+    if not component_type:
+        return {
+            "success": False,
+            "message": "Missing required parameter 'component_type'. Specify the component type name."
+        }
+
+    # --- Normalize properties with detailed error handling ---
+    properties, props_error = normalize_properties(properties)
+    if props_error:
+        return {"success": False, "message": props_error}
+
+    # --- Validate value parameter for serialization issues ---
+    if value is not None and isinstance(value, str) and value in ("[object Object]", "undefined"):
+        return {"success": False, "message": f"value received invalid input: '{value}'. Expected an actual value."}
+
+    try:
+        params = {
+            "action": action,
+            "target": target,
+            "componentType": component_type,
+        }
+
+        if search_method:
+            params["searchMethod"] = search_method
+
+        if action == "set_property":
+            if property and value is not None:
+                params["property"] = property
+                params["value"] = value
+            if properties:
+                params["properties"] = properties
+
+        if action == "add" and properties:
+            params["properties"] = properties
+
+        response = await send_with_unity_instance(
+            async_send_command_with_retry,
+            unity_instance,
+            "manage_components",
+            params,
+        )
+
+        if isinstance(response, dict) and response.get("success"):
+            return {
+                "success": True,
+                "message": response.get("message", f"Component {action} 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"Error managing component: {e!s}"}

services/tools/manage_editor.py

@@ -0,0 +1,64 @@
+from typing import Annotated, Any, Literal
+
+from fastmcp import Context
+from mcp.types import ToolAnnotations
+
+from services.registry import mcp_for_unity_tool
+from core.telemetry import is_telemetry_enabled, record_tool_usage
+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="Controls and queries the Unity editor's state and settings. Tip: pass booleans as true/false; if your client only sends strings, 'true'/'false' are accepted. Read-only actions: telemetry_status, telemetry_ping. Modifying actions: play, pause, stop, set_active_tool, add_tag, remove_tag, add_layer, remove_layer.",
+    annotations=ToolAnnotations(
+        title="Manage Editor",
+    ),
+)
+async def manage_editor(
+    ctx: Context,
+    action: Annotated[Literal["telemetry_status", "telemetry_ping", "play", "pause", "stop", "set_active_tool", "add_tag", "remove_tag", "add_layer", "remove_layer"], "Get and update the Unity Editor state."],
+    wait_for_completion: Annotated[bool | str,
+                                   "Optional. If True, waits for certain actions (accepts true/false or 'true'/'false')"] | None = None,
+    tool_name: Annotated[str,
+                         "Tool name when setting active tool"] | None = None,
+    tag_name: Annotated[str,
+                        "Tag name when adding and removing tags"] | None = None,
+    layer_name: Annotated[str,
+                          "Layer name when adding and removing layers"] | None = None,
+) -> dict[str, Any]:
+    # Get active instance from request state (injected by middleware)
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    wait_for_completion = coerce_bool(wait_for_completion)
+
+    try:
+        # Diagnostics: quick telemetry checks
+        if action == "telemetry_status":
+            return {"success": True, "telemetry_enabled": is_telemetry_enabled()}
+
+        if action == "telemetry_ping":
+            record_tool_usage("diagnostic_ping", True, 1.0, None)
+            return {"success": True, "message": "telemetry ping queued"}
+        # Prepare parameters, removing None values
+        params = {
+            "action": action,
+            "waitForCompletion": wait_for_completion,
+            "toolName": tool_name,
+            "tagName": tag_name,
+            "layerName": layer_name,
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+
+        # Send command using centralized retry helper with instance routing
+        response = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "manage_editor", 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", "Editor 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 editor: {str(e)}"}

services/tools/manage_gameobject.py

@@ -0,0 +1,260 @@
+import json
+from typing import Annotated, Any, Literal
+
+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
+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, coerce_int, normalize_vector3
+from services.tools.preflight import preflight
+
+
+def _normalize_component_properties(value: Any) -> tuple[dict[str, dict[str, Any]] | None, str | None]:
+    """
+    Robustly normalize component_properties to a dict.
+    Returns (parsed_dict, error_message). If error_message is set, parsed_dict is None.
+    """
+    if value is None:
+        return None, None
+
+    # Already a dict - validate structure
+    if isinstance(value, dict):
+        return value, None
+
+    # Try parsing as JSON string
+    if isinstance(value, str):
+        # Check for obviously invalid values
+        if value in ("[object Object]", "undefined", "null", ""):
+            return None, f"component_properties received invalid value: '{value}'. Expected a JSON object like {{\"ComponentName\": {{\"property\": value}}}}"
+
+        parsed = parse_json_payload(value)
+        if isinstance(parsed, dict):
+            return parsed, None
+
+        return None, f"component_properties must be a JSON object (dict), got string that parsed to {type(parsed).__name__}"
+
+    return None, f"component_properties must be a dict or JSON string, got {type(value).__name__}"
+
+
+@mcp_for_unity_tool(
+    description="Performs CRUD operations on GameObjects. Actions: create, modify, delete, duplicate, move_relative. For finding GameObjects use find_gameobjects tool. For component operations use manage_components tool.",
+    annotations=ToolAnnotations(
+        title="Manage GameObject",
+        destructiveHint=True,
+    ),
+)
+async def manage_gameobject(
+    ctx: Context,
+    action: Annotated[Literal["create", "modify", "delete", "duplicate",
+                              "move_relative"], "Action to perform on GameObject."] | 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[list[float] | dict[str, float] | str,
+                        "Position as [x, y, z] array, {x, y, z} object, or JSON string"] | None = None,
+    rotation: Annotated[list[float] | dict[str, float] | str,
+                        "Rotation as [x, y, z] euler angles array, {x, y, z} object, or JSON string"] | None = None,
+    scale: Annotated[list[float] | dict[str, float] | str,
+                     "Scale as [x, y, z] array, {x, y, z} object, or JSON string"] | 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[dict[str, dict[str, Any]],
+                                    """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,
+    # --- Paging/safety for get_components ---
+    page_size: Annotated[int | str,
+                         "Page size for get_components paging."] | None = None,
+    cursor: Annotated[int | str,
+                      "Opaque cursor for get_components paging (offset)."] | None = None,
+    max_components: Annotated[int | str,
+                              "Hard cap on returned components per request (safety)."] | None = None,
+    include_properties: Annotated[bool | str,
+                                  "If true, include serialized component properties (bounded)."] | None = None,
+    # --- Parameters for 'duplicate' ---
+    new_name: Annotated[str,
+                        "New name for the duplicated object (default: SourceName_Copy)"] | 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,
+    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)
+
+    gate = await preflight(ctx, wait_for_no_compile=True, refresh_if_dirty=True)
+    if gate is not None:
+        return gate.model_dump()
+
+    if action is None:
+        return {
+            "success": False,
+            "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 with detailed error handling ---
+    position, position_error = normalize_vector3(position, "position")
+    if position_error:
+        return {"success": False, "message": position_error}
+    rotation, rotation_error = normalize_vector3(rotation, "rotation")
+    if rotation_error:
+        return {"success": False, "message": rotation_error}
+    scale, scale_error = normalize_vector3(scale, "scale")
+    if scale_error:
+        return {"success": False, "message": scale_error}
+    offset, offset_error = normalize_vector3(offset, "offset")
+    if offset_error:
+        return {"success": False, "message": offset_error}
+
+    # --- Normalize boolean parameters ---
+    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)
+    include_properties = coerce_bool(include_properties)
+    world_space = coerce_bool(world_space, default=True)
+
+    # --- Normalize integer parameters ---
+    page_size = coerce_int(page_size, default=None)
+    cursor = coerce_int(cursor, default=None)
+    max_components = coerce_int(max_components, default=None)
+
+    # --- Normalize component_properties with detailed error handling ---
+    component_properties, comp_props_error = _normalize_component_properties(
+        component_properties)
+    if comp_props_error:
+        return {"success": False, "message": comp_props_error}
+
+    try:
+        # Validate parameter usage to prevent silent failures
+        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,
+            "pageSize": page_size,
+            "cursor": cursor,
+            "maxComponents": max_components,
+            "includeProperties": include_properties,
+            # 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,111 @@
+"""
+Defines the manage_material tool for interacting with Unity materials.
+"""
+import json
+from typing import Annotated, Any, Literal
+
+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
+from services.tools.utils import parse_json_payload, coerce_int, normalize_properties, normalize_color
+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). Read-only actions: ping, get_material_info. Modifying actions: create, set_material_shader_property, set_material_color, assign_material_to_renderer, set_renderer_color.",
+    annotations=ToolAnnotations(
+        title="Manage Material",
+        destructiveHint=True,
+    ),
+)
+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[dict[str, Any],
+                          "Initial properties to set as {name: value} dict."] | None = None,
+
+    # set_material_shader_property
+    value: Annotated[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[list[float] | dict[str, float] | str,
+                     "Color as [r, g, b] or [r, g, b, a] array, {r, g, b, a} object, or JSON string."] | 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, "Material slot index (0-based)"] | 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)
+
+    # --- Normalize color with validation ---
+    color, color_error = normalize_color(color, output_range="float")
+    if color_error:
+        return {"success": False, "message": color_error}
+
+    # --- Normalize properties with validation ---
+    properties, props_error = normalize_properties(properties)
+    if props_error:
+        return {"success": False, "message": props_error}
+
+    # --- Normalize value (parse JSON if string) ---
+    value = parse_json_payload(value)
+    if isinstance(value, str) and value in ("[object Object]", "undefined"):
+        return {"success": False, "message": f"value received invalid input: '{value}'"}
+
+    # --- Normalize slot to int ---
+    slot = coerce_int(slot)
+
+    # 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)}