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

services/tools/find_in_file.py

@@ -5,6 +5,7 @@ from typing import Annotated, Any
 from urllib.parse import unquote, urlparse
 
 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
@@ -16,7 +17,7 @@ def _split_uri(uri: str) -> tuple[str, str]:
     """Split an incoming URI or path into (name, directory) suitable for Unity.
 
     Rules:
-    - unity://path/Assets/... → keep as Assets-relative (after decode/normalize)
+    - mcpforunity://path/Assets/... → keep as Assets-relative (after decode/normalize)
     - file://... → percent-decode, normalize, strip host and leading slashes,
         then, if any 'Assets' segment exists, return path relative to that 'Assets' root.
         Otherwise, fall back to original name/dir behavior.
@@ -24,8 +25,8 @@ def _split_uri(uri: str) -> tuple[str, str]:
         return relative to 'Assets'.
     """
     raw_path: str
-    if uri.startswith("unity://path/"):
-        raw_path = uri[len("unity://path/"):]
+    if uri.startswith("mcpforunity://path/"):
+        raw_path = uri[len("mcpforunity://path/"):]
     elif uri.startswith("file://"):
         parsed = urlparse(uri)
         host = (parsed.netloc or "").strip()
@@ -64,14 +65,21 @@ def _split_uri(uri: str) -> tuple[str, str]:
     return name, directory
 
 
-@mcp_for_unity_tool(description="Searches a file with a regex pattern and returns line numbers and excerpts.")
+@mcp_for_unity_tool(
+    description="Searches a file with a regex pattern and returns line numbers and excerpts.",
+    annotations=ToolAnnotations(
+        title="Find in File",
+        readOnlyHint=True,
+    ),
+)
 async def find_in_file(
     ctx: Context,
     uri: Annotated[str, "The resource URI to search under Assets/ or file path form supported by read_resource"],
     pattern: Annotated[str, "The regex pattern to search for"],
     project_root: Annotated[str | None, "Optional project root path"] = None,
     max_results: Annotated[int, "Cap results to avoid huge payloads"] = 200,
-    ignore_case: Annotated[bool | str | None, "Case insensitive search"] = True,
+    ignore_case: Annotated[bool | str | None,
+                           "Case insensitive search"] = True,
 ) -> dict[str, Any]:
     # project_root is currently unused but kept for interface consistency
     unity_instance = get_unity_instance_from_context(ctx)
@@ -79,7 +87,7 @@ async def find_in_file(
         f"Processing find_in_file: {uri} (unity_instance={unity_instance or 'default'})")
 
     name, directory = _split_uri(uri)
-    
+
     # 1. Read file content via Unity
     read_resp = await send_with_unity_instance(
         async_send_command_with_retry,
@@ -103,7 +111,7 @@ async def find_in_file(
                 "utf-8")).decode("utf-8", "replace")
         except (ValueError, TypeError, base64.binascii.Error):
             contents = contents or ""
-    
+
     if contents is None:
         return {"success": False, "message": "Could not read file content."}
 
@@ -121,26 +129,26 @@ async def find_in_file(
     except re.error as e:
         return {"success": False, "message": f"Invalid regex pattern: {e}"}
 
-    # If the regex is not multiline specific (doesn't contain \n literal match logic), 
+    # If the regex is not multiline specific (doesn't contain \n literal match logic),
     # we could iterate lines. But users might use multiline regexes.
     # Let's search the whole content and map back to lines.
-    
+
     found = list(regex.finditer(contents))
-    
+
     results = []
     count = 0
-    
+
     for m in found:
         if count >= max_results:
             break
-        
+
         start_idx = m.start()
         end_idx = m.end()
-        
+
         # Calculate line number
         # Count newlines up to start_idx
         line_num = contents.count('\n', 0, start_idx) + 1
-        
+
         # Get line content for excerpt
         # Find start of line
         line_start = contents.rfind('\n', 0, start_idx) + 1
@@ -148,15 +156,15 @@ async def find_in_file(
         line_end = contents.find('\n', start_idx)
         if line_end == -1:
             line_end = len(contents)
-            
+
         line_content = contents[line_start:line_end]
-        
+
         # Create excerpt
         # We can just return the line content as excerpt
-        
+
         results.append({
             "line": line_num,
-            "content": line_content.strip(), # detailed match info?
+            "content": line_content.strip(),  # detailed match info?
             "match": m.group(0),
             "start": start_idx,
             "end": end_idx
@@ -171,4 +179,3 @@ async def find_in_file(
             "total_matches": len(found)
         }
     }
-

services/tools/manage_asset.py

@@ -1,15 +1,16 @@
 """
 Defines the manage_asset tool for interacting with Unity assets.
 """
-import ast
 import asyncio
 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
+from services.tools.utils import parse_json_payload, coerce_int, normalize_properties
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
 from services.tools.preflight import preflight
@@ -20,7 +21,11 @@ from services.tools.preflight import preflight
         "Performs asset operations (import, create, modify, delete, etc.) in Unity.\n\n"
         "Tip (payload safety): for `action=\"search\"`, prefer paging (`page_size`, `page_number`) and keep "
         "`generate_preview=false` (previews can add large base64 blobs)."
-    )
+    ),
+    annotations=ToolAnnotations(
+        title="Manage Asset",
+        destructiveHint=True,
+    ),
 )
 async def manage_asset(
     ctx: Context,
@@ -28,8 +33,8 @@ async def manage_asset(
     path: Annotated[str, "Asset path (e.g., 'Materials/MyMaterial.mat') or search scope (e.g., 'Assets')."],
     asset_type: Annotated[str,
                           "Asset type (e.g., 'Material', 'Folder') - required for 'create'. Note: For ScriptableObjects, use manage_scriptable_object."] | None = None,
-    properties: Annotated[dict[str, Any] | str,
-                          "Dictionary (or JSON string) of properties for 'create'/'modify'."] | None = None,
+    properties: Annotated[dict[str, Any],
+                          "Dictionary of properties for 'create'/'modify'. Keys are property names, values are property values."] | None = None,
     destination: Annotated[str,
                            "Target path for 'duplicate'/'move'."] | None = None,
     generate_preview: Annotated[bool,
@@ -54,46 +59,10 @@ async def manage_asset(
     if gate is not None:
         return gate.model_dump()
 
-    def _parse_properties_string(raw: str) -> tuple[dict[str, Any] | None, str | None]:
-        try:
-            parsed = json.loads(raw)
-            if not isinstance(parsed, dict):
-                return None, f"manage_asset: properties JSON must decode to a dictionary; received {type(parsed)}"
-            return parsed, "JSON"
-        except json.JSONDecodeError as json_err:
-            try:
-                parsed = ast.literal_eval(raw)
-                if not isinstance(parsed, dict):
-                    return None, f"manage_asset: properties string must evaluate to a dictionary; received {type(parsed)}"
-                return parsed, "Python literal"
-            except (ValueError, SyntaxError) as literal_err:
-                return None, f"manage_asset: failed to parse properties string. JSON error: {json_err}; literal_eval error: {literal_err}"
-
-    async def _normalize_properties(raw: dict[str, Any] | str | None) -> tuple[dict[str, Any] | None, str | None]:
-        if raw is None:
-            return {}, None
-        if isinstance(raw, dict):
-            await ctx.info(f"manage_asset: received properties as dict with keys: {list(raw.keys())}")
-            return raw, None
-        if isinstance(raw, str):
-            await ctx.info(f"manage_asset: received properties as string (first 100 chars): {raw[:100]}")
-            # Try our robust centralized parser first, then fallback to ast.literal_eval specific to manage_asset if needed
-            parsed = parse_json_payload(raw)
-            if isinstance(parsed, dict):
-                 await ctx.info("manage_asset: coerced properties using centralized parser")
-                 return parsed, None
-
-            # Fallback to original logic for ast.literal_eval which parse_json_payload avoids for safety/simplicity
-            parsed, source = _parse_properties_string(raw)
-            if parsed is None:
-                return None, source
-            await ctx.info(f"manage_asset: coerced properties from {source} string to dict")
-            return parsed, None
-        return None, f"manage_asset: properties must be a dict or JSON string; received {type(raw)}"
-
-    properties, parse_error = await _normalize_properties(properties)
+    # --- Normalize properties using robust module-level helper ---
+    properties, parse_error = normalize_properties(properties)
     if parse_error:
-        await ctx.error(parse_error)
+        await ctx.error(f"manage_asset: {parse_error}")
         return {"success": False, "message": parse_error}
 
     page_size = coerce_int(page_size)

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[Any,
+                     "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

@@ -1,6 +1,8 @@
 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
@@ -10,7 +12,10 @@ 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."
+    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,
@@ -41,13 +46,9 @@ async def manage_editor(
         params = {
             "action": action,
             "waitForCompletion": wait_for_completion,
-            "toolName": tool_name,  # Corrected parameter name to match C#
-            "tagName": tag_name,   # Pass tag name
-            "layerName": layer_name,  # Pass layer name
-            # Add other parameters based on the action being performed
-            # "width": width,
-            # "height": height,
-            # etc.
+            "toolName": tool_name,
+            "tagName": tag_name,
+            "layerName": layer_name,
         }
         params = {k: v for k, v in params.items() if v is not None}
 

services/tools/manage_gameobject.py

@@ -1,8 +1,10 @@
 import json
 import math
-from typing import Annotated, Any, Literal, Union
+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
@@ -11,12 +13,86 @@ 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:
+    """
+    Robustly normalize a vector parameter to [x, y, z] format.
+    Handles: list, tuple, JSON string, comma-separated string.
+    Returns None if parsing fails.
+    """
+    if value is None:
+        return default
+
+    # 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
+        except (ValueError, TypeError):
+            return default
+
+    # Try parsing as JSON string
+    if isinstance(value, str):
+        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
+            except (ValueError, TypeError):
+                pass
+
+        # Handle legacy comma-separated strings "1,2,3" or "[1,2,3]"
+        s = value.strip()
+        if 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])]
+                return vec if all(math.isfinite(n) for n in vec) else default
+            except (ValueError, TypeError):
+                pass
+
+    return default
+
+
+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 and components."
+    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", "find", "add_component", "remove_component", "set_component_property", "get_components", "get_component", "duplicate", "move_relative"], "Perform CRUD operations on GameObjects and components."] | None = None,
+    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"],
@@ -27,12 +103,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[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,
+    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,
     components_to_add: Annotated[list[str],
                                  "List of component names to add"] | None = None,
     primitive_type: Annotated[str,
@@ -48,7 +124,7 @@ async def manage_gameobject(
     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],
+    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
@@ -70,24 +146,28 @@ async def manage_gameobject(
     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,
+    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[Union[list[float], str],
-                      "Offset from original/reference position - [x,y,z] or string '[x,y,z]'"] | None = None,
+    offset: Annotated[list[float],
+                      "Offset from original/reference position as [x, y, z] array"] | None = None,
     # --- Parameters for 'move_relative' ---
     reference_object: Annotated[str,
-                               "Reference object for relative movement (required for move_relative)"] | None = None,
+                                "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,
+                         "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,
+                        "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,
+                           "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
@@ -100,44 +180,16 @@ async def manage_gameobject(
     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"
+            "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."
         }
 
-    # 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
+    # --- Normalize vector parameters using robust helper ---
+    position = _normalize_vector(position)
+    rotation = _normalize_vector(rotation)
+    scale = _normalize_vector(scale)
+    offset = _normalize_vector(offset)
 
-    position = _coerce_vec(position, default=position)
-    rotation = _coerce_vec(rotation, default=rotation)
-    scale = _coerce_vec(scale, default=scale)
-    offset = _coerce_vec(offset, default=offset)
+    # --- Normalize boolean parameters ---
     save_as_prefab = coerce_bool(save_as_prefab)
     set_active = coerce_bool(set_active)
     find_all = coerce_bool(find_all)
@@ -146,36 +198,20 @@ async def manage_gameobject(
     includeNonPublicSerialized = coerce_bool(includeNonPublicSerialized)
     include_properties = coerce_bool(include_properties)
     world_space = coerce_bool(world_space, default=True)
-    # If coercion fails, omit these fields (None) rather than preserving invalid input.
+
+    # --- 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)
 
-    # 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
+    # --- 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 == "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 {