mcpforunityserver 8.7.1__py3-none-any.whl → 9.0.1__py3-none-any.whl

services/resources/gameobject.py

@@ -0,0 +1,243 @@
+"""
+MCP Resources for reading GameObject data from Unity scenes.
+
+These resources provide read-only access to:
+- Single GameObject data (mcpforunity://scene/gameobject/{id})
+- All components on a GameObject (mcpforunity://scene/gameobject/{id}/components)
+- Single component on a GameObject (mcpforunity://scene/gameobject/{id}/component/{name})
+"""
+from typing import Any
+from pydantic import BaseModel
+from fastmcp import Context
+
+from models import MCPResponse
+from services.registry import mcp_for_unity_resource
+from services.tools import get_unity_instance_from_context
+from transport.unity_transport import send_with_unity_instance
+from transport.legacy.unity_connection import async_send_command_with_retry
+
+
+def _normalize_response(response: dict | Any) -> MCPResponse:
+    """Normalize Unity transport response to MCPResponse."""
+    if isinstance(response, dict):
+        return MCPResponse(**response)
+    return response
+
+
+def _validate_instance_id(instance_id: str) -> tuple[int | None, MCPResponse | None]:
+    """
+    Validate and convert instance_id string to int.
+    Returns (id_int, None) on success or (None, error_response) on failure.
+    """
+    try:
+        return int(instance_id), None
+    except ValueError:
+        return None, MCPResponse(success=False, error=f"Invalid instance ID: {instance_id}")
+
+
+# =============================================================================
+# Static Helper Resource (shows in UI)
+# =============================================================================
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://scene/gameobject-api",
+    name="gameobject_api",
+    description="Documentation for GameObject resources. Use find_gameobjects tool to get instance IDs, then access resources below."
+)
+async def get_gameobject_api_docs(_ctx: Context) -> MCPResponse:
+    """
+    Returns documentation for the GameObject resource API.
+
+    This is a helper resource that explains how to use the parameterized
+    GameObject resources which require an instance ID.
+    """
+    docs = {
+        "overview": "GameObject resources provide read-only access to Unity scene objects.",
+        "workflow": [
+            "1. Use find_gameobjects tool to search for GameObjects and get instance IDs",
+            "2. Use the instance ID to access detailed data via resources below"
+        ],
+        "best_practices": [
+            "⚡ Use batch_execute for multiple operations: Combine create/modify/component calls into one batch_execute call for 10-100x better performance",
+            "Example: Creating 5 cubes → 1 batch_execute with 5 manage_gameobject commands instead of 5 separate calls",
+            "Example: Adding components to 3 objects → 1 batch_execute with 3 manage_components commands"
+        ],
+        "resources": {
+            "mcpforunity://scene/gameobject/{instance_id}": {
+                "description": "Get basic GameObject data (name, tag, layer, transform, component type list)",
+                "example": "mcpforunity://scene/gameobject/-81840",
+                "returns": ["instanceID", "name", "tag", "layer", "transform", "componentTypes", "path", "parent", "children"]
+            },
+            "mcpforunity://scene/gameobject/{instance_id}/components": {
+                "description": "Get all components with full property serialization (paginated)",
+                "example": "mcpforunity://scene/gameobject/-81840/components",
+                "parameters": {
+                    "page_size": "Number of components per page (default: 25)",
+                    "cursor": "Pagination offset (default: 0)",
+                    "include_properties": "Include full property data (default: true)"
+                }
+            },
+            "mcpforunity://scene/gameobject/{instance_id}/component/{component_name}": {
+                "description": "Get a single component by type name with full properties",
+                "example": "mcpforunity://scene/gameobject/-81840/component/Camera",
+                "note": "Use the component type name (e.g., 'Camera', 'Rigidbody', 'Transform')"
+            }
+        },
+        "related_tools": {
+            "find_gameobjects": "Search for GameObjects by name, tag, layer, component, or path",
+            "manage_components": "Add, remove, or modify components on GameObjects",
+            "manage_gameobject": "Create, modify, or delete GameObjects"
+        }
+    }
+    return MCPResponse(success=True, data=docs)
+
+
+class TransformData(BaseModel):
+    """Transform component data."""
+    position: dict[str, float] = {"x": 0.0, "y": 0.0, "z": 0.0}
+    localPosition: dict[str, float] = {"x": 0.0, "y": 0.0, "z": 0.0}
+    rotation: dict[str, float] = {"x": 0.0, "y": 0.0, "z": 0.0}
+    localRotation: dict[str, float] = {"x": 0.0, "y": 0.0, "z": 0.0}
+    scale: dict[str, float] = {"x": 1.0, "y": 1.0, "z": 1.0}
+    lossyScale: dict[str, float] = {"x": 1.0, "y": 1.0, "z": 1.0}
+
+
+class GameObjectData(BaseModel):
+    """Data for a single GameObject (without full component serialization)."""
+    instanceID: int
+    name: str
+    tag: str = "Untagged"
+    layer: int = 0
+    layerName: str = "Default"
+    active: bool = True
+    activeInHierarchy: bool = True
+    isStatic: bool = False
+    transform: TransformData = TransformData()
+    parent: int | None = None
+    children: list[int] = []
+    componentTypes: list[str] = []
+    path: str = ""
+
+
+# TODO: Use these typed response classes for better type safety once
+# we update the endpoints to validate response structure more strictly.
+class GameObjectResponse(MCPResponse):
+    """Response containing GameObject data."""
+    data: GameObjectData | None = None
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://scene/gameobject/{instance_id}",
+    name="gameobject",
+    description="Get detailed information about a single GameObject by instance ID. Returns name, tag, layer, active state, transform data, parent/children IDs, and component type list (no full component properties)."
+)
+async def get_gameobject(ctx: Context, instance_id: str) -> MCPResponse:
+    """Get GameObject data by instance ID."""
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    id_int, error = _validate_instance_id(instance_id)
+    if error:
+        return error
+
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_gameobject",
+        {"instanceID": id_int}
+    )
+
+    return _normalize_response(response)
+
+
+class ComponentsData(BaseModel):
+    """Data for components on a GameObject."""
+    gameObjectID: int
+    gameObjectName: str
+    components: list[Any] = []
+    cursor: int = 0
+    pageSize: int = 25
+    nextCursor: int | None = None
+    totalCount: int = 0
+    hasMore: bool = False
+    includeProperties: bool = True
+
+
+class ComponentsResponse(MCPResponse):
+    """Response containing components data."""
+    data: ComponentsData | None = None
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://scene/gameobject/{instance_id}/components",
+    name="gameobject_components",
+    description="Get all components on a GameObject with full property serialization. Supports pagination with pageSize and cursor parameters."
+)
+async def get_gameobject_components(
+    ctx: Context,
+    instance_id: str,
+    page_size: int = 25,
+    cursor: int = 0,
+    include_properties: bool = True
+) -> MCPResponse:
+    """Get all components on a GameObject."""
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    id_int, error = _validate_instance_id(instance_id)
+    if error:
+        return error
+
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_gameobject_components",
+        {
+            "instanceID": id_int,
+            "pageSize": page_size,
+            "cursor": cursor,
+            "includeProperties": include_properties
+        }
+    )
+
+    return _normalize_response(response)
+
+
+class SingleComponentData(BaseModel):
+    """Data for a single component."""
+    gameObjectID: int
+    gameObjectName: str
+    component: Any = None
+
+
+class SingleComponentResponse(MCPResponse):
+    """Response containing single component data."""
+    data: SingleComponentData | None = None
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://scene/gameobject/{instance_id}/component/{component_name}",
+    name="gameobject_component",
+    description="Get a specific component on a GameObject by type name. Returns the fully serialized component with all properties."
+)
+async def get_gameobject_component(
+    ctx: Context,
+    instance_id: str,
+    component_name: str
+) -> MCPResponse:
+    """Get a specific component on a GameObject."""
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    id_int, error = _validate_instance_id(instance_id)
+    if error:
+        return error
+
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_gameobject_component",
+        {
+            "instanceID": id_int,
+            "componentName": component_name
+        }
+    )
+
+    return _normalize_response(response)

services/resources/layers.py

@@ -13,7 +13,7 @@ class LayersResponse(MCPResponse):
 
 
 @mcp_for_unity_resource(
-    uri="unity://project/layers",
+    uri="mcpforunity://project/layers",
     name="project_layers",
     description="All layers defined in the project's TagManager with their indices (0-31). Read this before using add_layer or remove_layer tools."
 )

services/resources/prefab_stage.py

@@ -23,7 +23,7 @@ class PrefabStageResponse(MCPResponse):
 
 
 @mcp_for_unity_resource(
-    uri="unity://editor/prefab-stage",
+    uri="mcpforunity://editor/prefab-stage",
     name="editor_prefab_stage",
     description="Current prefab editing context if a prefab is open in isolation mode. Returns isOpen=false if no prefab is being edited."
 )

services/resources/project_info.py

@@ -23,7 +23,7 @@ class ProjectInfoResponse(MCPResponse):
 
 
 @mcp_for_unity_resource(
-    uri="unity://project/info",
+    uri="mcpforunity://project/info",
     name="project_info",
     description="Static project information including root path, Unity version, and platform. This data rarely changes."
 )

services/resources/selection.py

@@ -39,7 +39,7 @@ class SelectionResponse(MCPResponse):
 
 
 @mcp_for_unity_resource(
-    uri="unity://editor/selection",
+    uri="mcpforunity://editor/selection",
     name="editor_selection",
     description="Detailed information about currently selected objects in the editor, including GameObjects, assets, and their properties."
 )

services/resources/tags.py

@@ -14,7 +14,7 @@ class TagsResponse(MCPResponse):
 
 
 @mcp_for_unity_resource(
-    uri="unity://project/tags",
+    uri="mcpforunity://project/tags",
     name="project_tags",
     description="All tags defined in the project's TagManager. Read this before using add_tag or remove_tag tools."
 )

services/resources/unity_instances.py

@@ -11,7 +11,7 @@ from transport.unity_transport import _current_transport
 
 
 @mcp_for_unity_resource(
-    uri="unity://instances",
+    uri="mcpforunity://instances",
     name="unity_instances",
     description="Lists all running Unity Editor instances with their details."
 )

services/resources/windows.py

@@ -31,7 +31,7 @@ class WindowsResponse(MCPResponse):
 
 
 @mcp_for_unity_resource(
-    uri="unity://editor/windows",
+    uri="mcpforunity://editor/windows",
     name="editor_windows",
     description="All currently open editor windows with their titles, types, positions, and focus state."
 )

services/state/external_changes_scanner.py

@@ -116,7 +116,8 @@ class ExternalChangesScanner:
             st.manifest_last_mtime_ns = None
             return []
 
-        mtime_ns = getattr(stat, "st_mtime_ns", int(stat.st_mtime * 1_000_000_000))
+        mtime_ns = getattr(stat, "st_mtime_ns", int(
+            stat.st_mtime * 1_000_000_000))
         if st.extra_roots is not None and st.manifest_last_mtime_ns == mtime_ns:
             return [Path(p) for p in st.extra_roots if p]
 
@@ -143,7 +144,7 @@ class ExternalChangesScanner:
             v = ver.strip()
             if not v.startswith("file:"):
                 continue
-            suffix = v[len("file:") :].strip()
+            suffix = v[len("file:"):].strip()
             # Handle file:///abs/path or file:/abs/path
             if suffix.startswith("///"):
                 candidate = Path("/" + suffix.lstrip("/"))
@@ -242,5 +243,3 @@ class ExternalChangesScanner:
 
 # Global singleton (simple, process-local)
 external_changes_scanner = ExternalChangesScanner()
-
-

services/tools/batch_execute.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 from typing import Annotated, Any
 
 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,22 +17,33 @@ MAX_COMMANDS_PER_BATCH = 25
 @mcp_for_unity_tool(
     name="batch_execute",
     description=(
-        "Runs a list of MCP tool calls as one batch. Use it to send a full sequence of commands, "
-        "inspect the results, then submit the next batch for the following step."
+        "Executes multiple MCP commands in a single batch for dramatically better performance. "
+        "STRONGLY RECOMMENDED when creating/modifying multiple objects, adding components to multiple targets, "
+        "or performing any repetitive operations. Reduces latency and token costs by 10-100x compared to "
+        "sequential tool calls. Supports up to 25 commands per batch. "
+        "Example: creating 5 cubes → use 1 batch_execute with 5 create commands instead of 5 separate calls."
+    ),
+    annotations=ToolAnnotations(
+        title="Batch Execute",
+        destructiveHint=True,
     ),
 )
 async def batch_execute(
     ctx: Context,
     commands: Annotated[list[dict[str, Any]], "List of commands with 'tool' and 'params' keys."],
-    parallel: Annotated[bool | None, "Attempt to run read-only commands in parallel"] = None,
-    fail_fast: Annotated[bool | None, "Stop processing after the first failure"] = None,
-    max_parallelism: Annotated[int | None, "Hint for the maximum number of parallel workers"] = None,
+    parallel: Annotated[bool | None,
+                        "Attempt to run read-only commands in parallel"] = None,
+    fail_fast: Annotated[bool | None,
+                         "Stop processing after the first failure"] = None,
+    max_parallelism: Annotated[int | None,
+                               "Hint for the maximum number of parallel workers"] = None,
 ) -> dict[str, Any]:
     """Proxy the batch_execute tool to the Unity Editor transporter."""
     unity_instance = get_unity_instance_from_context(ctx)
 
     if not isinstance(commands, list) or not commands:
-        raise ValueError("'commands' must be a non-empty list of command specifications")
+        raise ValueError(
+            "'commands' must be a non-empty list of command specifications")
 
     if len(commands) > MAX_COMMANDS_PER_BATCH:
         raise ValueError(
@@ -41,18 +53,21 @@ async def batch_execute(
     normalized_commands: list[dict[str, Any]] = []
     for index, command in enumerate(commands):
         if not isinstance(command, dict):
-            raise ValueError(f"Command at index {index} must be an object with 'tool' and 'params' keys")
+            raise ValueError(
+                f"Command at index {index} must be an object with 'tool' and 'params' keys")
 
         tool_name = command.get("tool")
         params = command.get("params", {})
 
         if not tool_name or not isinstance(tool_name, str):
-            raise ValueError(f"Command at index {index} is missing a valid 'tool' name")
+            raise ValueError(
+                f"Command at index {index} is missing a valid 'tool' name")
 
         if params is None:
             params = {}
         if not isinstance(params, dict):
-            raise ValueError(f"Command '{tool_name}' must specify parameters as an object/dict")
+            raise ValueError(
+                f"Command '{tool_name}' must specify parameters as an object/dict")
 
         normalized_commands.append({
             "tool": tool_name,

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}"}