mcpforunityserver 9.4.0b20260203025228__py3-none-any.whl

services/resources/tests.py

@@ -0,0 +1,88 @@
+from typing import Annotated, Literal, Optional
+from pydantic import BaseModel, 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 TestItem(BaseModel):
+    name: Annotated[str, Field(description="The name of the test.")]
+    full_name: Annotated[str, Field(description="The full name of the test.")]
+    mode: Annotated[Literal["EditMode", "PlayMode"],
+                    Field(description="The mode the test is for.")]
+
+
+class PaginatedTestsData(BaseModel):
+    """Paginated test results."""
+    items: list[TestItem] = Field(description="Tests on current page")
+    cursor: int = Field(description="Current page cursor (0-based)")
+    nextCursor: Optional[int] = Field(None, description="Next page cursor, null if last page")
+    totalCount: int = Field(description="Total number of tests across all pages")
+    pageSize: int = Field(description="Number of items per page")
+    hasMore: bool = Field(description="Whether there are more items after this page")
+
+
+class GetTestsResponse(MCPResponse):
+    """Response containing paginated test data."""
+    data: PaginatedTestsData = Field(description="Paginated test data")
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://tests",
+    name="get_tests",
+    description="Provides the first page of Unity tests (default 50 items). "
+                "For filtering or pagination, use the run_tests tool instead.\n\nURI: mcpforunity://tests"
+)
+async def get_tests(ctx: Context) -> GetTestsResponse | MCPResponse:
+    """Provides a paginated list of all Unity tests.
+
+    Returns the first page of tests using Unity's default pagination (50 items).
+    For advanced filtering or pagination control, use the run_tests tool which
+    accepts mode, filter, page_size, and cursor parameters.
+    """
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_tests",
+        {},
+    )
+    return parse_resource_response(response, GetTestsResponse)
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://tests/{mode}",
+    name="get_tests_for_mode",
+    description="Provides the first page of tests for a specific mode (EditMode or PlayMode). "
+                "For filtering or pagination, use the run_tests tool instead.\n\nURI: mcpforunity://tests/{mode}"
+)
+async def get_tests_for_mode(
+    ctx: Context,
+    mode: Annotated[Literal["EditMode", "PlayMode"], Field(
+        description="The mode to filter tests by (EditMode or PlayMode)."
+    )],
+) -> GetTestsResponse | MCPResponse:
+    """Provides the first page of tests for a specific mode.
+
+    Args:
+        mode: The test mode to filter by (EditMode or PlayMode)
+
+    Returns the first page of tests using Unity's default pagination (50 items).
+    For advanced filtering or pagination control, use the run_tests tool.
+    """
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_tests_for_mode",
+        {"mode": mode},
+    )
+    return parse_resource_response(response, GetTestsResponse)

services/resources/unity_instances.py

@@ -0,0 +1,125 @@
+"""
+Resource to list all available Unity Editor instances.
+"""
+from typing import Any
+
+from fastmcp import Context
+from services.registry import mcp_for_unity_resource
+from transport.legacy.unity_connection import get_unity_connection_pool
+from transport.plugin_hub import PluginHub
+from core.config import config
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://instances",
+    name="unity_instances",
+    description="Lists all running Unity Editor instances with their details.\n\nURI: mcpforunity://instances"
+)
+async def unity_instances(ctx: Context) -> dict[str, Any]:
+    """
+    List all available Unity Editor instances.
+
+    Returns information about each instance including:
+    - id: Unique identifier (ProjectName@hash)
+    - name: Project name
+    - path: Full project path (stdio only)
+    - hash: 8-character hash of project path
+    - port: TCP port number (stdio only)
+    - status: Current status (running, reloading, etc.) (stdio only)
+    - last_heartbeat: Last heartbeat timestamp (stdio only)
+    - unity_version: Unity version (if available)
+    - connected_at: Connection timestamp (HTTP only)
+
+    Returns:
+        Dictionary containing list of instances and metadata
+    """
+    await ctx.info("Listing Unity instances")
+
+    try:
+        transport = (config.transport_mode or "stdio").lower()
+        if transport == "http":
+            # HTTP/WebSocket transport: query PluginHub
+            # In remote-hosted mode, filter sessions by user_id
+            user_id = ctx.get_state(
+                "user_id") if config.http_remote_hosted else None
+            sessions_data = await PluginHub.get_sessions(user_id=user_id)
+            sessions = sessions_data.sessions
+
+            instances = []
+            for session_id, session_info in sessions.items():
+                project = session_info.project
+                project_hash = session_info.hash
+
+                if not project or not project_hash:
+                    raise ValueError(
+                        "PluginHub session missing required 'project' or 'hash' fields."
+                    )
+
+                instances.append({
+                    "id": f"{project}@{project_hash}",
+                    "name": project,
+                    "hash": project_hash,
+                    "unity_version": session_info.unity_version,
+                    "connected_at": session_info.connected_at,
+                    "session_id": session_id,
+                })
+
+            # Check for duplicate project names
+            name_counts = {}
+            for inst in instances:
+                name_counts[inst["name"]] = name_counts.get(
+                    inst["name"], 0) + 1
+
+            duplicates = [name for name,
+                          count in name_counts.items() if count > 1]
+
+            result = {
+                "success": True,
+                "transport": transport,
+                "instance_count": len(instances),
+                "instances": instances,
+            }
+
+            if duplicates:
+                result["warning"] = (
+                    f"Multiple instances found with duplicate project names: {duplicates}. "
+                    f"Use full format (e.g., 'ProjectName@hash') to specify which instance."
+                )
+
+            return result
+        else:
+            # Stdio/TCP transport: query connection pool
+            pool = get_unity_connection_pool()
+            instances = pool.discover_all_instances(force_refresh=False)
+
+            # Check for duplicate project names
+            name_counts = {}
+            for inst in instances:
+                name_counts[inst.name] = name_counts.get(inst.name, 0) + 1
+
+            duplicates = [name for name,
+                          count in name_counts.items() if count > 1]
+
+            result = {
+                "success": True,
+                "transport": transport,
+                "instance_count": len(instances),
+                "instances": [inst.to_dict() for inst in instances],
+            }
+
+            if duplicates:
+                result["warning"] = (
+                    f"Multiple instances found with duplicate project names: {duplicates}. "
+                    f"Use full format (e.g., 'ProjectName@hash') to specify which instance."
+                )
+
+            return result
+
+    except Exception as e:
+        await ctx.error(f"Error listing Unity instances: {e}")
+        return {
+            "success": False,
+            "error": f"Failed to list Unity instances: {str(e)}",
+            "instance_count": 0,
+            "instances": []
+        }

services/resources/windows.py

@@ -0,0 +1,48 @@
+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 WindowPosition(BaseModel):
+    """Window position and size."""
+    x: float = 0.0
+    y: float = 0.0
+    width: float = 0.0
+    height: float = 0.0
+
+
+class WindowInfo(BaseModel):
+    """Information about an editor window."""
+    title: str = ""
+    typeName: str = ""
+    isFocused: bool = False
+    position: WindowPosition = WindowPosition()
+    instanceID: int = 0
+
+
+class WindowsResponse(MCPResponse):
+    """List of all open editor windows."""
+    data: list[WindowInfo] = []
+
+
+@mcp_for_unity_resource(
+    uri="mcpforunity://editor/windows",
+    name="editor_windows",
+    description="All currently open editor windows with their titles, types, positions, and focus state.\n\nURI: mcpforunity://editor/windows"
+)
+async def get_windows(ctx: Context) -> WindowsResponse | MCPResponse:
+    """Get all open editor windows."""
+    unity_instance = get_unity_instance_from_context(ctx)
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_windows",
+        {}
+    )
+    return parse_resource_response(response, WindowsResponse)

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

@@ -0,0 +1,83 @@
+"""MCP tools package - auto-discovery and Unity routing helpers."""
+
+import logging
+import os
+from pathlib import Path
+from typing import TypeVar
+
+from fastmcp import Context, FastMCP
+from core.telemetry_decorator import telemetry_tool
+from core.logging_decorator import log_execution
+from utils.module_discovery import discover_modules
+from services.registry import get_registered_tools
+
+logger = logging.getLogger("mcp-for-unity-server")
+
+# Export decorator and helpers for easy imports within tools
+__all__ = [
+    "register_all_tools",
+    "get_unity_instance_from_context",
+]
+
+
+def register_all_tools(mcp: FastMCP, *, project_scoped_tools: bool = True):
+    """
+    Auto-discover and register all tools in the tools/ directory.
+
+    Any .py file in this directory or subdirectories with @mcp_for_unity_tool decorated
+    functions will be automatically registered.
+    """
+    logger.info("Auto-discovering MCP for Unity Server tools...")
+    # Dynamic import of all modules in this directory
+    tools_dir = Path(__file__).parent
+
+    # Discover and import all modules
+    list(discover_modules(tools_dir, __package__))
+
+    tools = get_registered_tools()
+
+    if not tools:
+        logger.warning("No MCP tools registered!")
+        return
+
+    for tool_info in tools:
+        func = tool_info['func']
+        tool_name = tool_info['name']
+        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 decorators: logging -> telemetry -> mcp.tool
+        # Note: Parameter normalization (camelCase -> snake_case) is handled by
+        # ParamNormalizerMiddleware before FastMCP validation
+        wrapped = log_execution(tool_name, "Tool")(func)
+        wrapped = telemetry_tool(tool_name)(wrapped)
+        wrapped = mcp.tool(
+            name=tool_name, description=description, **kwargs)(wrapped)
+        tool_info['func'] = wrapped
+        logger.debug(f"Registered tool: {tool_name} - {description}")
+
+    logger.info(f"Registered {len(tools)} MCP tools")
+
+
+def get_unity_instance_from_context(
+    ctx: Context,
+    key: str = "unity_instance",
+) -> str | None:
+    """Extract the unity_instance value from middleware state.
+
+    The instance is set via the set_active_instance tool and injected into
+    request state by UnityInstanceMiddleware.
+    """
+    get_state_fn = getattr(ctx, "get_state", None)
+    if callable(get_state_fn):
+        try:
+            return get_state_fn(key)
+        except Exception:  # pragma: no cover - defensive
+            pass
+
+    return None

services/tools/batch_execute.py

@@ -0,0 +1,93 @@
+"""Defines the batch_execute tool for orchestrating multiple Unity MCP commands."""
+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
+from transport.unity_transport import send_with_unity_instance
+from transport.legacy.unity_connection import async_send_command_with_retry
+
+MAX_COMMANDS_PER_BATCH = 25
+
+
+@mcp_for_unity_tool(
+    name="batch_execute",
+    description=(
+        "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,
+) -> 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")
+
+    if len(commands) > MAX_COMMANDS_PER_BATCH:
+        raise ValueError(
+            f"batch_execute currently supports up to {MAX_COMMANDS_PER_BATCH} commands; received {len(commands)}"
+        )
+
+    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")
+
+        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")
+
+        if params is None:
+            params = {}
+        if not isinstance(params, dict):
+            raise ValueError(
+                f"Command '{tool_name}' must specify parameters as an object/dict")
+
+        normalized_commands.append({
+            "tool": tool_name,
+            "params": params,
+        })
+
+    payload: dict[str, Any] = {
+        "commands": normalized_commands,
+    }
+
+    if parallel is not None:
+        payload["parallel"] = bool(parallel)
+    if fail_fast is not None:
+        payload["failFast"] = bool(fail_fast)
+    if max_parallelism is not None:
+        payload["maxParallelism"] = int(max_parallelism)
+
+    return await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "batch_execute",
+        payload,
+    )