mcpforunityserver 8.2.3__py3-none-any.whl

services/resources/layers.py

@@ -0,0 +1,29 @@
+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
+
+
+class LayersResponse(MCPResponse):
+    """Dictionary of layer indices to layer names."""
+    data: dict[int, str] = {}
+
+
+@mcp_for_unity_resource(
+    uri="unity://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."
+)
+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 LayersResponse(**response) if isinstance(response, dict) else response

services/resources/menu_items.py

@@ -0,0 +1,34 @@
+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
+
+
+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."
+)
+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 GetMenuItemsResponse(**response) if isinstance(response, dict) else response

services/resources/prefab_stage.py

@@ -0,0 +1,39 @@
+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
+
+
+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="unity://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."
+)
+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 PrefabStageResponse(**response) if isinstance(response, dict) else response

services/resources/project_info.py

@@ -0,0 +1,39 @@
+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
+
+
+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="unity://project/info",
+    name="project_info",
+    description="Static project information including root path, Unity version, and platform. This data rarely changes."
+)
+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 ProjectInfoResponse(**response) if isinstance(response, dict) else response

services/resources/selection.py

@@ -0,0 +1,55 @@
+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
+
+
+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="unity://editor/selection",
+    name="editor_selection",
+    description="Detailed information about currently selected objects in the editor, including GameObjects, assets, and their properties."
+)
+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 SelectionResponse(**response) if isinstance(response, dict) else response

services/resources/tags.py

@@ -0,0 +1,30 @@
+from pydantic import Field
+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
+
+
+class TagsResponse(MCPResponse):
+    """List of all tags in the project."""
+    data: list[str] = Field(default_factory=list)
+
+
+@mcp_for_unity_resource(
+    uri="unity://project/tags",
+    name="project_tags",
+    description="All tags defined in the project's TagManager. Read this before using add_tag or remove_tag tools."
+)
+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 TagsResponse(**response) if isinstance(response, dict) else response

services/resources/tests.py

@@ -0,0 +1,55 @@
+from typing import Annotated, Literal
+from pydantic import BaseModel, Field
+
+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
+
+
+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 GetTestsResponse(MCPResponse):
+    data: list[TestItem] = []
+
+
+@mcp_for_unity_resource(uri="mcpforunity://tests", name="get_tests", description="Provides a list of all tests.")
+async def get_tests(ctx: Context) -> GetTestsResponse | MCPResponse:
+    """Provides a list of all tests.
+    """
+    unity_instance = get_unity_instance_from_context(ctx)
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_tests",
+        {},
+    )
+    return GetTestsResponse(**response) if isinstance(response, dict) else response
+
+
+@mcp_for_unity_resource(uri="mcpforunity://tests/{mode}", name="get_tests_for_mode", description="Provides a list of tests for a specific mode.")
+async def get_tests_for_mode(
+    ctx: Context,
+    mode: Annotated[Literal["EditMode", "PlayMode"], Field(description="The mode to filter tests by.")],
+) -> GetTestsResponse | MCPResponse:
+    """Provides a list of tests for a specific mode.
+
+    Args:
+        mode: The test mode to filter by (EditMode or PlayMode).
+    """
+    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 GetTestsResponse(**response) if isinstance(response, dict) else response

services/resources/unity_instances.py

@@ -0,0 +1,122 @@
+"""
+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 transport.unity_transport import _current_transport
+
+
+@mcp_for_unity_resource(
+    uri="unity://instances",
+    name="unity_instances",
+    description="Lists all running Unity Editor instances with their details."
+)
+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 = _current_transport()
+        if transport == "http":
+            # HTTP/WebSocket transport: query PluginHub
+            sessions_data = await PluginHub.get_sessions()
+            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,47 @@
+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
+
+
+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="unity://editor/windows",
+    name="editor_windows",
+    description="All currently open editor windows with their titles, types, positions, and focus state."
+)
+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 WindowsResponse(**response) if isinstance(response, dict) else response

services/tools/__init__.py

@@ -0,0 +1,76 @@
+"""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):
+    """
+    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']
+
+        # Apply the @mcp.tool decorator, telemetry, and logging
+        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,78 @@
+"""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 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=(
+        "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."
+    ),
+)
+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,
+    )

services/tools/debug_request_context.py

@@ -0,0 +1,71 @@
+from typing import Any
+
+from fastmcp import Context
+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)."
+)
+def debug_request_context(ctx: Context) -> dict[str, Any]:
+    # Check request_context properties
+    rc = getattr(ctx, "request_context", None)
+    rc_client_id = getattr(rc, "client_id", None)
+    rc_session_id = getattr(rc, "session_id", None)
+    meta = getattr(rc, "meta", None)
+
+    # Check direct ctx properties (per latest FastMCP docs)
+    ctx_session_id = getattr(ctx, "session_id", None)
+    ctx_client_id = getattr(ctx, "client_id", None)
+
+    meta_dump = None
+    if meta is not None:
+        try:
+            dump_fn = getattr(meta, "model_dump", None)
+            if callable(dump_fn):
+                meta_dump = dump_fn(exclude_none=False)
+            elif isinstance(meta, dict):
+                meta_dump = dict(meta)
+        except Exception as e:
+            meta_dump = {"_error": str(e)}
+
+    # List all ctx attributes for debugging
+    ctx_attrs = [attr for attr in dir(ctx) if not attr.startswith("_")]
+
+    # Get session state info via middleware
+    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:
+        all_keys = list(middleware._active_by_key.keys())
+
+    # Debugging PluginHub state
+    plugin_hub_configured = PluginHub.is_configured()
+
+    return {
+        "success": True,
+        "data": {
+            "request_context": {
+                "client_id": rc_client_id,
+                "session_id": rc_session_id,
+                "meta": meta_dump,
+            },
+            "direct_properties": {
+                "session_id": ctx_session_id,
+                "client_id": ctx_client_id,
+            },
+            "session_state": {
+                "derived_key": derived_key,
+                "active_instance": active_instance,
+                "all_keys_in_store": all_keys,
+                "plugin_hub_configured": plugin_hub_configured,
+                "middleware_id": id(middleware),
+            },
+            "available_attributes": ctx_attrs,
+        },
+    }