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

services/tools/debug_request_context.py

@@ -5,13 +5,19 @@ import sys
 from core.telemetry import get_package_version
 
 from fastmcp import Context
+from mcp.types import ToolAnnotations
+
 from services.registry import mcp_for_unity_tool
 from transport.unity_instance_middleware import get_unity_instance_middleware
 from transport.plugin_hub import PluginHub
 
 
 @mcp_for_unity_tool(
-    description="Return the current FastMCP request context details (client_id, session_id, and meta dump)."
+    description="Return the current FastMCP request context details (client_id, session_id, and meta dump).",
+    annotations=ToolAnnotations(
+        title="Debug Request Context",
+        readOnlyHint=True,
+    ),
 )
 def debug_request_context(ctx: Context) -> dict[str, Any]:
     # Check request_context properties
@@ -42,7 +48,7 @@ def debug_request_context(ctx: Context) -> dict[str, Any]:
     middleware = get_unity_instance_middleware()
     derived_key = middleware.get_session_key(ctx)
     active_instance = middleware.get_active_instance(ctx)
-    
+
     # Debugging middleware internals
     # NOTE: These fields expose internal implementation details and may change between versions.
     with middleware._lock:

services/tools/execute_custom_tool.py

@@ -1,4 +1,5 @@
 from fastmcp import Context
+from mcp.types import ToolAnnotations
 from models.models import MCPResponse
 
 from services.custom_tool_service import (
@@ -12,13 +13,17 @@ from services.tools import get_unity_instance_from_context
 @mcp_for_unity_tool(
     name="execute_custom_tool",
     description="Execute a project-scoped custom tool registered by Unity.",
+    annotations=ToolAnnotations(
+        title="Execute Custom Tool",
+        destructiveHint=True,
+    ),
 )
 async def execute_custom_tool(ctx: Context, tool_name: str, parameters: dict | None = None) -> MCPResponse:
     unity_instance = get_unity_instance_from_context(ctx)
     if not unity_instance:
         return MCPResponse(
             success=False,
-            message="No active Unity instance. Call set_active_instance with Name@hash from unity://instances.",
+            message="No active Unity instance. Call set_active_instance with Name@hash from mcpforunity://instances.",
         )
 
     project_id = resolve_project_id_for_unity_instance(unity_instance)

services/tools/execute_menu_item.py

@@ -4,6 +4,7 @@ Defines the execute_menu_item tool for executing and reading Unity Editor menu i
 from typing import Annotated, Any
 
 from fastmcp import Context
+from mcp.types import ToolAnnotations
 
 from models import MCPResponse
 from services.registry import mcp_for_unity_tool
@@ -13,15 +14,17 @@ from transport.legacy.unity_connection import async_send_command_with_retry
 
 
 @mcp_for_unity_tool(
-    description="Execute a Unity menu item by path."
+    description="Execute a Unity menu item by path.",
+    annotations=ToolAnnotations(
+        title="Execute Menu Item",
+        destructiveHint=True,
+    ),
 )
 async def execute_menu_item(
     ctx: Context,
     menu_path: Annotated[str,
                          "Menu path for 'execute' or 'exists' (e.g., 'File/Save Project')"] | None = None,
 ) -> MCPResponse:
-    # Get active instance from session state
-    # Removed session_state import
     unity_instance = get_unity_instance_from_context(ctx)
     params_dict: dict[str, Any] = {"menuPath": menu_path}
     params_dict = {k: v for k, v in params_dict.items() if v is not None}

services/tools/find_gameobjects.py

@@ -0,0 +1,89 @@
+"""
+Tool for searching GameObjects in Unity scenes.
+Returns only instance IDs with pagination support for efficient searches.
+"""
+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, coerce_int
+from services.tools.preflight import preflight
+
+
+@mcp_for_unity_tool(
+    description="Search for GameObjects in the scene. Returns instance IDs only (paginated) for efficient lookups. Use mcpforunity://scene/gameobject/{id} resource to get full GameObject data."
+)
+async def find_gameobjects(
+    ctx: Context,
+    search_term: Annotated[str, "The value to search for (name, tag, layer name, component type, or path)"],
+    search_method: Annotated[
+        Literal["by_name", "by_tag", "by_layer",
+                "by_component", "by_path", "by_id"],
+        "How to search for GameObjects"
+    ] = "by_name",
+    include_inactive: Annotated[bool | str,
+                                "Include inactive GameObjects in search"] | None = None,
+    page_size: Annotated[int | str,
+                         "Number of results per page (default: 50, max: 500)"] | None = None,
+    cursor: Annotated[int | str,
+                      "Pagination cursor (offset for next page)"] | None = None,
+) -> dict[str, Any]:
+    """
+    Search for GameObjects and return their instance IDs.
+
+    This is a focused search tool optimized for finding GameObjects efficiently.
+    It returns only instance IDs to minimize payload size.
+
+    For detailed GameObject information, use the returned IDs with:
+    - mcpforunity://scene/gameobject/{id} - Get full GameObject data
+    - mcpforunity://scene/gameobject/{id}/components - Get all components
+    - mcpforunity://scene/gameobject/{id}/component/{name} - Get specific component
+    """
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    # Validate required parameters before preflight I/O
+    if not search_term:
+        return {
+            "success": False,
+            "message": "Missing required parameter 'search_term'. Specify what to search for."
+        }
+
+    gate = await preflight(ctx, wait_for_no_compile=True, refresh_if_dirty=True)
+    if gate is not None:
+        return gate.model_dump()
+
+    # Coerce parameters
+    include_inactive = coerce_bool(include_inactive, default=False)
+    page_size = coerce_int(page_size, default=50)
+    cursor = coerce_int(cursor, default=0)
+
+    try:
+        params = {
+            "searchMethod": search_method,
+            "searchTerm": search_term,
+            "includeInactive": include_inactive,
+            "pageSize": page_size,
+            "cursor": cursor,
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+
+        response = await send_with_unity_instance(
+            async_send_command_with_retry,
+            unity_instance,
+            "find_gameobjects",
+            params,
+        )
+
+        if isinstance(response, dict) and response.get("success"):
+            return {
+                "success": True,
+                "message": response.get("message", "Search completed."),
+                "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 searching GameObjects: {e!s}"}

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,17 +1,19 @@
 """
 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
 
 
 @mcp_for_unity_tool(
@@ -19,7 +21,11 @@ from transport.legacy.unity_connection import async_send_command_with_retry
         "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,
@@ -27,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,
@@ -47,46 +53,16 @@ async def manage_asset(
 ) -> dict[str, Any]:
     unity_instance = get_unity_instance_from_context(ctx)
 
-    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)}"
+    # Best-effort guard: if Unity is compiling/reloading or known external changes are pending,
+    # wait/refresh to avoid stale reads and flaky timeouts.
+    gate = await preflight(ctx, wait_for_no_compile=True, refresh_if_dirty=True)
+    if gate is not None:
+        return gate.model_dump()
 
-    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}