mcpforunityserver 8.5.0__py3-none-any.whl → 9.1.0__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

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+import os
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+
+def _now_unix_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _in_pytest() -> bool:
+    # Keep scanner inert during the Python integration suite unless explicitly invoked.
+    return bool(os.environ.get("PYTEST_CURRENT_TEST"))
+
+
+@dataclass
+class ExternalChangesState:
+    project_root: str | None = None
+    last_scan_unix_ms: int | None = None
+    last_seen_mtime_ns: int | None = None
+    dirty: bool = False
+    dirty_since_unix_ms: int | None = None
+    external_changes_last_seen_unix_ms: int | None = None
+    last_cleared_unix_ms: int | None = None
+    # Cached package roots referenced by Packages/manifest.json "file:" dependencies
+    extra_roots: list[str] | None = None
+    manifest_last_mtime_ns: int | None = None
+
+
+class ExternalChangesScanner:
+    """
+    Lightweight external-changes detector using recursive max-mtime scan.
+
+    This is intentionally conservative:
+    - It only marks dirty when it sees a strictly newer mtime than the baseline.
+    - It scans at most once per scan_interval_ms per instance to keep overhead bounded.
+    """
+
+    def __init__(self, *, scan_interval_ms: int = 1500, max_entries: int = 20000):
+        self._states: dict[str, ExternalChangesState] = {}
+        self._scan_interval_ms = int(scan_interval_ms)
+        self._max_entries = int(max_entries)
+
+    def _get_state(self, instance_id: str) -> ExternalChangesState:
+        return self._states.setdefault(instance_id, ExternalChangesState())
+
+    def set_project_root(self, instance_id: str, project_root: str | None) -> None:
+        st = self._get_state(instance_id)
+        if project_root:
+            st.project_root = project_root
+
+    def clear_dirty(self, instance_id: str) -> None:
+        st = self._get_state(instance_id)
+        st.dirty = False
+        st.dirty_since_unix_ms = None
+        st.last_cleared_unix_ms = _now_unix_ms()
+        # Reset baseline to “now” on next scan.
+        st.last_seen_mtime_ns = None
+
+    def _scan_paths_max_mtime_ns(self, roots: Iterable[Path]) -> int | None:
+        newest: int | None = None
+        entries = 0
+
+        for root in roots:
+            if not root.exists():
+                continue
+
+            # Walk the tree; skip common massive/irrelevant dirs (Library/Temp/Logs).
+            for dirpath, dirnames, filenames in os.walk(str(root)):
+                entries += 1
+                if entries > self._max_entries:
+                    return newest
+
+                dp = Path(dirpath)
+                name = dp.name.lower()
+                if name in {"library", "temp", "logs", "obj", ".git", "node_modules"}:
+                    dirnames[:] = []
+                    continue
+
+                # Allow skipping hidden directories quickly
+                dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+
+                for fn in filenames:
+                    if fn.startswith("."):
+                        continue
+                    entries += 1
+                    if entries > self._max_entries:
+                        return newest
+                    p = dp / fn
+                    try:
+                        stat = p.stat()
+                    except OSError:
+                        continue
+                    m = getattr(stat, "st_mtime_ns", None)
+                    if m is None:
+                        # Fallback when st_mtime_ns is unavailable
+                        m = int(stat.st_mtime * 1_000_000_000)
+                    newest = m if newest is None else max(newest, int(m))
+
+        return newest
+
+    def _resolve_manifest_extra_roots(self, project_root: Path, st: ExternalChangesState) -> list[Path]:
+        """
+        Parse Packages/manifest.json for local file: dependencies and resolve them to absolute paths.
+        Returns a list of Paths that exist and are directories.
+        """
+        manifest_path = project_root / "Packages" / "manifest.json"
+        try:
+            stat = manifest_path.stat()
+        except OSError:
+            st.extra_roots = []
+            st.manifest_last_mtime_ns = None
+            return []
+
+        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]
+
+        try:
+            raw = manifest_path.read_text(encoding="utf-8")
+            doc = json.loads(raw)
+        except Exception:
+            st.extra_roots = []
+            st.manifest_last_mtime_ns = mtime_ns
+            return []
+
+        deps = doc.get("dependencies") if isinstance(doc, dict) else None
+        if not isinstance(deps, dict):
+            st.extra_roots = []
+            st.manifest_last_mtime_ns = mtime_ns
+            return []
+
+        roots: list[str] = []
+        base_dir = manifest_path.parent
+
+        for _, ver in deps.items():
+            if not isinstance(ver, str):
+                continue
+            v = ver.strip()
+            if not v.startswith("file:"):
+                continue
+            suffix = v[len("file:"):].strip()
+            # Handle file:///abs/path or file:/abs/path
+            if suffix.startswith("///"):
+                candidate = Path("/" + suffix.lstrip("/"))
+            elif suffix.startswith("/"):
+                candidate = Path(suffix)
+            else:
+                candidate = (base_dir / suffix).resolve()
+            try:
+                if candidate.exists() and candidate.is_dir():
+                    roots.append(str(candidate))
+            except OSError:
+                continue
+
+        # De-dupe, preserve order
+        deduped: list[str] = []
+        seen = set()
+        for r in roots:
+            if r not in seen:
+                seen.add(r)
+                deduped.append(r)
+
+        st.extra_roots = deduped
+        st.manifest_last_mtime_ns = mtime_ns
+        return [Path(p) for p in deduped if p]
+
+    def update_and_get(self, instance_id: str) -> dict[str, int | bool | None]:
+        """
+        Returns a small dict suitable for embedding in editor_state_v2.assets:
+          - external_changes_dirty
+          - external_changes_last_seen_unix_ms
+          - dirty_since_unix_ms
+          - last_cleared_unix_ms
+        """
+        st = self._get_state(instance_id)
+
+        if _in_pytest():
+            return {
+                "external_changes_dirty": st.dirty,
+                "external_changes_last_seen_unix_ms": st.external_changes_last_seen_unix_ms,
+                "dirty_since_unix_ms": st.dirty_since_unix_ms,
+                "last_cleared_unix_ms": st.last_cleared_unix_ms,
+            }
+
+        now = _now_unix_ms()
+        if st.last_scan_unix_ms is not None and (now - st.last_scan_unix_ms) < self._scan_interval_ms:
+            return {
+                "external_changes_dirty": st.dirty,
+                "external_changes_last_seen_unix_ms": st.external_changes_last_seen_unix_ms,
+                "dirty_since_unix_ms": st.dirty_since_unix_ms,
+                "last_cleared_unix_ms": st.last_cleared_unix_ms,
+            }
+
+        st.last_scan_unix_ms = now
+
+        project_root = st.project_root
+        if not project_root:
+            return {
+                "external_changes_dirty": st.dirty,
+                "external_changes_last_seen_unix_ms": st.external_changes_last_seen_unix_ms,
+                "dirty_since_unix_ms": st.dirty_since_unix_ms,
+                "last_cleared_unix_ms": st.last_cleared_unix_ms,
+            }
+
+        root = Path(project_root)
+        paths = [root / "Assets", root / "ProjectSettings", root / "Packages"]
+        # Include any local package roots referenced by file: deps in Packages/manifest.json
+        try:
+            paths.extend(self._resolve_manifest_extra_roots(root, st))
+        except Exception:
+            pass
+        newest = self._scan_paths_max_mtime_ns(paths)
+        if newest is None:
+            return {
+                "external_changes_dirty": st.dirty,
+                "external_changes_last_seen_unix_ms": st.external_changes_last_seen_unix_ms,
+                "dirty_since_unix_ms": st.dirty_since_unix_ms,
+                "last_cleared_unix_ms": st.last_cleared_unix_ms,
+            }
+
+        if st.last_seen_mtime_ns is None:
+            st.last_seen_mtime_ns = newest
+        elif newest > st.last_seen_mtime_ns:
+            st.last_seen_mtime_ns = newest
+            st.external_changes_last_seen_unix_ms = now
+            if not st.dirty:
+                st.dirty = True
+                st.dirty_since_unix_ms = now
+
+        return {
+            "external_changes_dirty": st.dirty,
+            "external_changes_last_seen_unix_ms": st.external_changes_last_seen_unix_ms,
+            "dirty_since_unix_ms": st.dirty_since_unix_ms,
+            "last_cleared_unix_ms": st.last_cleared_unix_ms,
+        }
+
+
+# Global singleton (simple, process-local)
+external_changes_scanner = ExternalChangesScanner()

services/tools/__init__.py

@@ -20,7 +20,7 @@ __all__ = [
 ]
 
 
-def register_all_tools(mcp: FastMCP):
+def register_all_tools(mcp: FastMCP, *, project_scoped_tools: bool = True):
     """
     Auto-discover and register all tools in the tools/ directory.
 
@@ -46,6 +46,11 @@ def register_all_tools(mcp: FastMCP):
         description = tool_info['description']
         kwargs = tool_info['kwargs']
 
+        if not project_scoped_tools and tool_name == "execute_custom_tool":
+            logger.info(
+                "Skipping execute_custom_tool registration (project-scoped tools disabled)")
+            continue
+
         # Apply the @mcp.tool decorator, telemetry, and logging
         wrapped = log_execution(tool_name, "Tool")(func)
         wrapped = telemetry_tool(tool_name)(wrapped)

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,