mcpforunityserver 9.4.0b20260203025228__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.\n\nURI: mcpforunity://scene/gameobject-api"
+)
+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).\n\nURI: mcpforunity://scene/gameobject/{instance_id}"
+)
+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.\n\nURI: mcpforunity://scene/gameobject/{instance_id}/components"
+)
+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.\n\nURI: mcpforunity://scene/gameobject/{instance_id}/component/{component_name}"
+)
+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

@@ -0,0 +1,30 @@
+from fastmcp import Context
+
+from models import MCPResponse
+from models.unity_response import parse_resource_response
+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
+
+
+class LayersResponse(MCPResponse):
+    """Dictionary of layer indices to layer names."""
+    data: dict[int, str] = {}
+
+
+@mcp_for_unity_resource(
+    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.\n\nURI: mcpforunity://project/layers"
+)
+async def get_layers(ctx: Context) -> LayersResponse | MCPResponse:
+    """Get all project layers with their indices."""
+    unity_instance = get_unity_instance_from_context(ctx)
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_layers",
+        {}
+    )
+    return parse_resource_response(response, LayersResponse)

services/resources/menu_items.py

@@ -0,0 +1,35 @@
+from fastmcp import Context
+
+from models import MCPResponse
+from models.unity_response import parse_resource_response
+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
+
+
+class GetMenuItemsResponse(MCPResponse):
+    data: list[str] = []
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://menu-items",
+    name="menu_items",
+    description="Provides a list of all menu items.\n\nURI: mcpforunity://menu-items"
+)
+async def get_menu_items(ctx: Context) -> GetMenuItemsResponse | MCPResponse:
+    """Provides a list of all menu items.
+    """
+    unity_instance = get_unity_instance_from_context(ctx)
+    params = {
+        "refresh": True,
+        "search": "",
+    }
+
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_menu_items",
+        params,
+    )
+    return parse_resource_response(response, GetMenuItemsResponse)

services/resources/prefab.py

@@ -0,0 +1,191 @@
+"""
+MCP Resources for reading Prefab data from Unity.
+
+These resources provide read-only access to:
+- Prefab info by asset path (mcpforunity://prefab/{path})
+- Prefab hierarchy by asset path (mcpforunity://prefab/{path}/hierarchy)
+- Currently open prefab stage (mcpforunity://editor/prefab-stage - see prefab_stage.py)
+"""
+from typing import Any
+from urllib.parse import unquote
+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 | MCPResponse | Any) -> MCPResponse:
+    """Normalize Unity transport response to MCPResponse."""
+    if isinstance(response, dict):
+        return MCPResponse(**response)
+    if isinstance(response, MCPResponse):
+        return response
+    # Fallback: wrap unexpected types in an error response
+    return MCPResponse(success=False, error=f"Unexpected response type: {type(response).__name__}")
+
+
+def _decode_prefab_path(encoded_path: str) -> str:
+    """
+    Decode a URL-encoded prefab path.
+    Handles paths like 'Assets%2FPrefabs%2FMyPrefab.prefab' -> 'Assets/Prefabs/MyPrefab.prefab'
+    """
+    return unquote(encoded_path)
+
+
+# =============================================================================
+# Static Helper Resource (shows in UI)
+# =============================================================================
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://prefab-api",
+    name="prefab_api",
+    description="Documentation for Prefab resources. Use manage_asset action=search filterType=Prefab to find prefabs, then access resources below.\n\nURI: mcpforunity://prefab-api"
+)
+async def get_prefab_api_docs(_ctx: Context) -> MCPResponse:
+    """
+    Returns documentation for the Prefab resource API.
+
+    This is a helper resource that explains how to use the parameterized
+    Prefab resources which require an asset path.
+    """
+    docs = {
+        "overview": "Prefab resources provide read-only access to Unity prefab assets.",
+        "workflow": [
+            "1. Use manage_asset action=search filterType=Prefab to find prefabs",
+            "2. Use the asset path to access detailed data via resources below",
+            "3. Use manage_prefabs tool for prefab stage operations (open, save, close)"
+        ],
+        "path_encoding": {
+            "note": "Prefab paths must be URL-encoded when used in resource URIs",
+            "example": "Assets/Prefabs/MyPrefab.prefab -> Assets%2FPrefabs%2FMyPrefab.prefab"
+        },
+        "resources": {
+            "mcpforunity://prefab/{encoded_path}": {
+                "description": "Get prefab asset info (type, root name, components, variant info)",
+                "example": "mcpforunity://prefab/Assets%2FPrefabs%2FPlayer.prefab",
+                "returns": ["assetPath", "guid", "prefabType", "rootObjectName", "rootComponentTypes", "childCount", "isVariant", "parentPrefab"]
+            },
+            "mcpforunity://prefab/{encoded_path}/hierarchy": {
+                "description": "Get full prefab hierarchy with nested prefab information",
+                "example": "mcpforunity://prefab/Assets%2FPrefabs%2FPlayer.prefab/hierarchy",
+                "returns": ["prefabPath", "total", "items (with name, instanceId, path, componentTypes, prefab nesting info)"]
+            },
+            "mcpforunity://editor/prefab-stage": {
+                "description": "Get info about the currently open prefab stage (if any)",
+                "returns": ["isOpen", "assetPath", "prefabRootName", "mode", "isDirty"]
+            }
+        },
+        "related_tools": {
+            "manage_prefabs": "Open/close prefab stages, save changes, create prefabs from GameObjects",
+            "manage_asset": "Search for prefab assets, get asset info",
+            "manage_gameobject": "Modify GameObjects in open prefab stage",
+            "manage_components": "Add/remove/modify components on prefab GameObjects"
+        }
+    }
+    return MCPResponse(success=True, data=docs)
+
+
+# =============================================================================
+# Prefab Info Resource
+# =============================================================================
+
+# TODO: Use these typed response classes for better type safety once
+# we update the endpoints to validate response structure more strictly.
+
+
+class PrefabInfoData(BaseModel):
+    """Data for a prefab asset."""
+    assetPath: str
+    guid: str = ""
+    prefabType: str = "Regular"
+    rootObjectName: str = ""
+    rootComponentTypes: list[str] = []
+    childCount: int = 0
+    isVariant: bool = False
+    parentPrefab: str | None = None
+
+
+class PrefabInfoResponse(MCPResponse):
+    """Response containing prefab info data."""
+    data: PrefabInfoData | None = None
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://prefab/{encoded_path}",
+    name="prefab_info",
+    description="Get detailed information about a prefab asset by URL-encoded path. Returns prefab type, root object name, component types, child count, and variant info.\n\nURI: mcpforunity://prefab/{encoded_path}"
+)
+async def get_prefab_info(ctx: Context, encoded_path: str) -> MCPResponse:
+    """Get prefab asset info by path."""
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    # Decode the URL-encoded path
+    decoded_path = _decode_prefab_path(encoded_path)
+
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "manage_prefabs",
+        {
+            "action": "get_info",
+            "prefabPath": decoded_path
+        }
+    )
+
+    return _normalize_response(response)
+
+
+# =============================================================================
+# Prefab Hierarchy Resource
+# =============================================================================
+
+class PrefabHierarchyItem(BaseModel):
+    """Single item in prefab hierarchy."""
+    name: str
+    instanceId: int
+    path: str
+    activeSelf: bool = True
+    childCount: int = 0
+    componentTypes: list[str] = []
+    prefab: dict[str, Any] = {}
+
+
+class PrefabHierarchyData(BaseModel):
+    """Data for prefab hierarchy."""
+    prefabPath: str
+    total: int = 0
+    items: list[PrefabHierarchyItem] = []
+
+
+class PrefabHierarchyResponse(MCPResponse):
+    """Response containing prefab hierarchy data."""
+    data: PrefabHierarchyData | None = None
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://prefab/{encoded_path}/hierarchy",
+    name="prefab_hierarchy",
+    description="Get the full hierarchy of a prefab with nested prefab information. Returns all GameObjects with their components and nesting depth.\n\nURI: mcpforunity://prefab/{encoded_path}/hierarchy"
+)
+async def get_prefab_hierarchy(ctx: Context, encoded_path: str) -> MCPResponse:
+    """Get prefab hierarchy by path."""
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    # Decode the URL-encoded path
+    decoded_path = _decode_prefab_path(encoded_path)
+
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "manage_prefabs",
+        {
+            "action": "get_hierarchy",
+            "prefabPath": decoded_path
+        }
+    )
+
+    return _normalize_response(response)

services/resources/prefab_stage.py

@@ -0,0 +1,40 @@
+from pydantic import BaseModel
+from fastmcp import Context
+
+from models import MCPResponse
+from models.unity_response import parse_resource_response
+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
+
+
+class PrefabStageData(BaseModel):
+    """Prefab stage data fields."""
+    isOpen: bool = False
+    assetPath: str | None = None
+    prefabRootName: str | None = None
+    mode: str | None = None
+    isDirty: bool = False
+
+
+class PrefabStageResponse(MCPResponse):
+    """Information about the current prefab editing context."""
+    data: PrefabStageData = PrefabStageData()
+
+
+@mcp_for_unity_resource(
+    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.\n\nURI: mcpforunity://editor/prefab-stage"
+)
+async def get_prefab_stage(ctx: Context) -> PrefabStageResponse | MCPResponse:
+    """Get current prefab stage information."""
+    unity_instance = get_unity_instance_from_context(ctx)
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_prefab_stage",
+        {}
+    )
+    return parse_resource_response(response, PrefabStageResponse)

services/resources/project_info.py

@@ -0,0 +1,40 @@
+from pydantic import BaseModel
+from fastmcp import Context
+
+from models import MCPResponse
+from models.unity_response import parse_resource_response
+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
+
+
+class ProjectInfoData(BaseModel):
+    """Project info data fields."""
+    projectRoot: str = ""
+    projectName: str = ""
+    unityVersion: str = ""
+    platform: str = ""
+    assetsPath: str = ""
+
+
+class ProjectInfoResponse(MCPResponse):
+    """Static project configuration information."""
+    data: ProjectInfoData = ProjectInfoData()
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://project/info",
+    name="project_info",
+    description="Static project information including root path, Unity version, and platform. This data rarely changes.\n\nURI: mcpforunity://project/info"
+)
+async def get_project_info(ctx: Context) -> ProjectInfoResponse | MCPResponse:
+    """Get static project configuration information."""
+    unity_instance = get_unity_instance_from_context(ctx)
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_project_info",
+        {}
+    )
+    return parse_resource_response(response, ProjectInfoResponse)

services/resources/selection.py

@@ -0,0 +1,56 @@
+from pydantic import BaseModel
+from fastmcp import Context
+
+from models import MCPResponse
+from models.unity_response import parse_resource_response
+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
+
+
+class SelectionObjectInfo(BaseModel):
+    """Information about a selected object."""
+    name: str | None = None
+    type: str | None = None
+    instanceID: int | None = None
+
+
+class SelectionGameObjectInfo(BaseModel):
+    """Information about a selected GameObject."""
+    name: str | None = None
+    instanceID: int | None = None
+
+
+class SelectionData(BaseModel):
+    """Selection data fields."""
+    activeObject: str | None = None
+    activeGameObject: str | None = None
+    activeTransform: str | None = None
+    activeInstanceID: int = 0
+    count: int = 0
+    objects: list[SelectionObjectInfo] = []
+    gameObjects: list[SelectionGameObjectInfo] = []
+    assetGUIDs: list[str] = []
+
+
+class SelectionResponse(MCPResponse):
+    """Detailed information about the current editor selection."""
+    data: SelectionData = SelectionData()
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://editor/selection",
+    name="editor_selection",
+    description="Detailed information about currently selected objects in the editor, including GameObjects, assets, and their properties.\n\nURI: mcpforunity://editor/selection"
+)
+async def get_selection(ctx: Context) -> SelectionResponse | MCPResponse:
+    """Get detailed editor selection information."""
+    unity_instance = get_unity_instance_from_context(ctx)
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_selection",
+        {}
+    )
+    return parse_resource_response(response, SelectionResponse)

services/resources/tags.py

@@ -0,0 +1,31 @@
+from pydantic import Field
+from fastmcp import Context
+
+from models import MCPResponse
+from models.unity_response import parse_resource_response
+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
+
+
+class TagsResponse(MCPResponse):
+    """List of all tags in the project."""
+    data: list[str] = Field(default_factory=list)
+
+
+@mcp_for_unity_resource(
+    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.\n\nURI: mcpforunity://project/tags"
+)
+async def get_tags(ctx: Context) -> TagsResponse | MCPResponse:
+    """Get all project tags."""
+    unity_instance = get_unity_instance_from_context(ctx)
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_tags",
+        {}
+    )
+    return parse_resource_response(response, TagsResponse)