mcpforunityserver 8.2.3__py3-none-any.whl

services/custom_tool_service.py

@@ -0,0 +1,339 @@
+import asyncio
+import logging
+import time
+from hashlib import sha256
+from typing import Optional
+
+from fastmcp import FastMCP
+from pydantic import BaseModel, Field, ValidationError
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from models.models import MCPResponse, ToolDefinitionModel, ToolParameterModel
+from transport.unity_transport import send_with_unity_instance
+from transport.legacy.unity_connection import (
+    async_send_command_with_retry,
+    get_unity_connection_pool,
+)
+from transport.plugin_hub import PluginHub
+
+logger = logging.getLogger("mcp-for-unity-server")
+
+_DEFAULT_POLL_INTERVAL = 1.0
+_MAX_POLL_SECONDS = 600
+
+
+class RegisterToolsPayload(BaseModel):
+    project_id: str
+    project_hash: str | None = None
+    tools: list[ToolDefinitionModel]
+
+
+class ToolRegistrationResponse(BaseModel):
+    success: bool
+    registered: list[str]
+    replaced: list[str]
+    message: str
+
+
+class CustomToolService:
+    _instance: "CustomToolService | None" = None
+
+    def __init__(self, mcp: FastMCP):
+        CustomToolService._instance = self
+        self._mcp = mcp
+        self._project_tools: dict[str, dict[str, ToolDefinitionModel]] = {}
+        self._hash_to_project: dict[str, str] = {}
+        self._register_http_routes()
+
+    @classmethod
+    def get_instance(cls) -> "CustomToolService":
+        if cls._instance is None:
+            raise RuntimeError("CustomToolService has not been initialized")
+        return cls._instance
+
+    # --- HTTP Routes -----------------------------------------------------
+    def _register_http_routes(self) -> None:
+        @self._mcp.custom_route("/register-tools", methods=["POST"])
+        async def register_tools(request: Request) -> JSONResponse:
+            try:
+                payload = RegisterToolsPayload.model_validate(await request.json())
+            except ValidationError as exc:
+                return JSONResponse({"success": False, "error": exc.errors()}, status_code=400)
+
+            registered: list[str] = []
+            replaced: list[str] = []
+            for tool in payload.tools:
+                if self._is_registered(payload.project_id, tool.name):
+                    replaced.append(tool.name)
+                self._register_tool(payload.project_id, tool)
+                registered.append(tool.name)
+
+            if payload.project_hash:
+                self._hash_to_project[payload.project_hash.lower(
+                )] = payload.project_id
+
+            message = f"Registered {len(registered)} tool(s)"
+            if replaced:
+                message += f" (replaced: {', '.join(replaced)})"
+
+            response = ToolRegistrationResponse(
+                success=True,
+                registered=registered,
+                replaced=replaced,
+                message=message,
+            )
+            return JSONResponse(response.model_dump())
+
+    # --- Public API for MCP tools ---------------------------------------
+    async def list_registered_tools(self, project_id: str) -> list[ToolDefinitionModel]:
+        legacy = list(self._project_tools.get(project_id, {}).values())
+        hub_tools = await PluginHub.get_tools_for_project(project_id)
+        return legacy + hub_tools
+
+    async def get_tool_definition(self, project_id: str, tool_name: str) -> ToolDefinitionModel | None:
+        tool = self._project_tools.get(project_id, {}).get(tool_name)
+        if tool:
+            return tool
+        return await PluginHub.get_tool_definition(project_id, tool_name)
+
+    async def execute_tool(
+        self,
+        project_id: str,
+        tool_name: str,
+        unity_instance: str | None,
+        params: dict[str, object] | None = None,
+    ) -> MCPResponse:
+        params = params or {}
+        logger.info(
+            f"Executing tool '{tool_name}' for project '{project_id}' (instance={unity_instance}) with params: {params}"
+        )
+
+        definition = await self.get_tool_definition(project_id, tool_name)
+        if definition is None:
+            return MCPResponse(
+                success=False,
+                message=f"Tool '{tool_name}' not found for project {project_id}",
+            )
+
+        response = await send_with_unity_instance(
+            async_send_command_with_retry,
+            unity_instance,
+            tool_name,
+            params,
+        )
+
+        if not definition.requires_polling:
+            result = self._normalize_response(response)
+            logger.info(f"Tool '{tool_name}' immediate response: {result}")
+            return result
+
+        result = await self._poll_until_complete(
+            tool_name,
+            unity_instance,
+            params,
+            response,
+            definition.poll_action or "status",
+        )
+        logger.info(f"Tool '{tool_name}' polled response: {result}")
+        return result
+
+    # --- Internal helpers ------------------------------------------------
+    def _is_registered(self, project_id: str, tool_name: str) -> bool:
+        return tool_name in self._project_tools.get(project_id, {})
+
+    def _register_tool(self, project_id: str, definition: ToolDefinitionModel) -> None:
+        self._project_tools.setdefault(project_id, {})[
+            definition.name] = definition
+
+    def get_project_id_for_hash(self, project_hash: str | None) -> str | None:
+        if not project_hash:
+            return None
+        return self._hash_to_project.get(project_hash.lower())
+
+    async def _poll_until_complete(
+        self,
+        tool_name: str,
+        unity_instance,
+        initial_params: dict[str, object],
+        initial_response,
+        poll_action: str,
+    ) -> MCPResponse:
+        poll_params = dict(initial_params)
+        poll_params["action"] = poll_action or "status"
+
+        deadline = time.time() + _MAX_POLL_SECONDS
+        response = initial_response
+
+        while True:
+            status, poll_interval = self._interpret_status(response)
+
+            if status in ("complete", "error", "final"):
+                return self._normalize_response(response)
+
+            if time.time() > deadline:
+                return MCPResponse(
+                    success=False,
+                    message=f"Timeout waiting for {tool_name} to complete",
+                    data=self._safe_response(response),
+                )
+
+            await asyncio.sleep(poll_interval)
+
+            try:
+                response = await send_with_unity_instance(
+                    async_send_command_with_retry, unity_instance, tool_name, poll_params
+                )
+            except Exception as exc:  # pragma: no cover - network/domain reload variability
+                logger.debug(f"Polling {tool_name} failed, will retry: {exc}")
+                # Back off modestly but stay responsive.
+                response = {
+                    "_mcp_status": "pending",
+                    "_mcp_poll_interval": min(max(poll_interval * 2, _DEFAULT_POLL_INTERVAL), 5.0),
+                    "message": f"Retrying after transient error: {exc}",
+                }
+
+    def _interpret_status(self, response) -> tuple[str, float]:
+        if response is None:
+            return "pending", _DEFAULT_POLL_INTERVAL
+
+        if not isinstance(response, dict):
+            return "final", _DEFAULT_POLL_INTERVAL
+
+        status = response.get("_mcp_status")
+        if status is None:
+            if len(response.keys()) == 0:
+                return "pending", _DEFAULT_POLL_INTERVAL
+            return "final", _DEFAULT_POLL_INTERVAL
+
+        if status == "pending":
+            interval_raw = response.get(
+                "_mcp_poll_interval", _DEFAULT_POLL_INTERVAL)
+            try:
+                interval = float(interval_raw)
+            except (TypeError, ValueError):
+                interval = _DEFAULT_POLL_INTERVAL
+
+            interval = max(0.1, min(interval, 5.0))
+            return "pending", interval
+
+        if status == "complete":
+            return "complete", _DEFAULT_POLL_INTERVAL
+
+        if status == "error":
+            return "error", _DEFAULT_POLL_INTERVAL
+
+        return "final", _DEFAULT_POLL_INTERVAL
+
+    def _normalize_response(self, response) -> MCPResponse:
+        if isinstance(response, MCPResponse):
+            return response
+        if isinstance(response, dict):
+            return MCPResponse(
+                success=response.get("success", True),
+                message=response.get("message"),
+                error=response.get("error"),
+                data=response.get(
+                    "data", response) if "data" not in response else response["data"],
+            )
+
+        success = True
+        message = None
+        error = None
+        data = None
+
+        if isinstance(response, dict):
+            success = response.get("success", True)
+            if "_mcp_status" in response and response["_mcp_status"] == "error":
+                success = False
+            message = str(response.get("message")) if response.get(
+                "message") else None
+            error = str(response.get("error")) if response.get(
+                "error") else None
+            data = response.get("data")
+            if "success" not in response and "_mcp_status" not in response:
+                data = response
+        else:
+            success = False
+            message = str(response)
+
+        return MCPResponse(success=success, message=message, error=error, data=data)
+
+    def _safe_response(self, response):
+        if isinstance(response, dict):
+            return response
+        if response is None:
+            return None
+        return {"message": str(response)}
+
+    def _safe_response(self, response):
+        if isinstance(response, dict):
+            return response
+        if response is None:
+            return None
+        return {"message": str(response)}
+
+
+def compute_project_id(project_name: str, project_path: str) -> str:
+    combined = f"{project_name}:{project_path}"
+    return sha256(combined.encode("utf-8")).hexdigest().upper()[:16]
+
+
+def resolve_project_id_for_unity_instance(unity_instance: str | None) -> str | None:
+    if unity_instance is None:
+        return None
+
+    # stdio transport: resolve via discovered instances with name+path
+    try:
+        pool = get_unity_connection_pool()
+        instances = pool.discover_all_instances()
+        target = None
+        if "@" in unity_instance:
+            name_part, _, hash_hint = unity_instance.partition("@")
+            target = next(
+                (
+                    inst for inst in instances
+                    if inst.name == name_part and inst.hash.startswith(hash_hint)
+                ),
+                None,
+            )
+        else:
+            target = next(
+                (
+                    inst for inst in instances
+                    if inst.id == unity_instance or inst.hash.startswith(unity_instance)
+                ),
+                None,
+            )
+
+        if target:
+            return compute_project_id(target.name, target.path)
+    except Exception:
+        logger.debug(
+            f"Failed to resolve project id via connection pool for {unity_instance}")
+
+    # HTTP/WebSocket transport: resolve via PluginHub using project_hash
+    try:
+        hash_part: Optional[str] = None
+        if "@" in unity_instance:
+            _, _, suffix = unity_instance.partition("@")
+            hash_part = suffix or None
+        else:
+            hash_part = unity_instance
+
+        if hash_part:
+            lowered = hash_part.lower()
+            mapped: Optional[str] = None
+            try:
+                service = CustomToolService.get_instance()
+                mapped = service.get_project_id_for_hash(lowered)
+            except RuntimeError:
+                mapped = None
+            if mapped:
+                return mapped
+            return lowered
+    except Exception:
+        logger.debug(
+            f"Failed to resolve project id via plugin hub for {unity_instance}")
+
+    return None

services/registry/__init__.py

@@ -0,0 +1,22 @@
+"""
+Registry package for MCP tool auto-discovery.
+"""
+from .tool_registry import (
+    mcp_for_unity_tool,
+    get_registered_tools,
+    clear_tool_registry,
+)
+from .resource_registry import (
+    mcp_for_unity_resource,
+    get_registered_resources,
+    clear_resource_registry,
+)
+
+__all__ = [
+    'mcp_for_unity_tool',
+    'get_registered_tools',
+    'clear_tool_registry',
+    'mcp_for_unity_resource',
+    'get_registered_resources',
+    'clear_resource_registry'
+]

services/registry/resource_registry.py

@@ -0,0 +1,53 @@
+"""
+Resource registry for auto-discovery of MCP resources.
+"""
+from typing import Callable, Any
+
+# Global registry to collect decorated resources
+_resource_registry: list[dict[str, Any]] = []
+
+
+def mcp_for_unity_resource(
+    uri: str,
+    name: str | None = None,
+    description: str | None = None,
+    **kwargs
+) -> Callable:
+    """
+    Decorator for registering MCP resources in the server's resources directory.
+
+    Resources are registered in the global resource registry.
+
+    Args:
+        name: Resource name (defaults to function name)
+        description: Resource description
+        **kwargs: Additional arguments passed to @mcp.resource()
+
+    Example:
+        @mcp_for_unity_resource("mcpforunity://resource", description="Gets something interesting")
+        async def my_custom_resource(ctx: Context, ...):
+            pass
+    """
+    def decorator(func: Callable) -> Callable:
+        resource_name = name if name is not None else func.__name__
+        _resource_registry.append({
+            'func': func,
+            'uri': uri,
+            'name': resource_name,
+            'description': description,
+            'kwargs': kwargs
+        })
+
+        return func
+
+    return decorator
+
+
+def get_registered_resources() -> list[dict[str, Any]]:
+    """Get all registered resources"""
+    return _resource_registry.copy()
+
+
+def clear_resource_registry():
+    """Clear the resource registry (useful for testing)"""
+    _resource_registry.clear()

services/registry/tool_registry.py

@@ -0,0 +1,51 @@
+"""
+Tool registry for auto-discovery of MCP tools.
+"""
+from typing import Callable, Any
+
+# Global registry to collect decorated tools
+_tool_registry: list[dict[str, Any]] = []
+
+
+def mcp_for_unity_tool(
+    name: str | None = None,
+    description: str | None = None,
+    **kwargs
+) -> Callable:
+    """
+    Decorator for registering MCP tools in the server's tools directory.
+
+    Tools are registered in the global tool registry.
+
+    Args:
+        name: Tool name (defaults to function name)
+        description: Tool description
+        **kwargs: Additional arguments passed to @mcp.tool()
+
+    Example:
+        @mcp_for_unity_tool(description="Does something cool")
+        async def my_custom_tool(ctx: Context, ...):
+            pass
+    """
+    def decorator(func: Callable) -> Callable:
+        tool_name = name if name is not None else func.__name__
+        _tool_registry.append({
+            'func': func,
+            'name': tool_name,
+            'description': description,
+            'kwargs': kwargs
+        })
+
+        return func
+
+    return decorator
+
+
+def get_registered_tools() -> list[dict[str, Any]]:
+    """Get all registered tools"""
+    return _tool_registry.copy()
+
+
+def clear_tool_registry():
+    """Clear the tool registry (useful for testing)"""
+    _tool_registry.clear()

services/resources/__init__.py

@@ -0,0 +1,81 @@
+"""
+MCP Resources package - Auto-discovers and registers all resources in this directory.
+"""
+import inspect
+import logging
+from pathlib import Path
+
+from fastmcp import FastMCP
+from core.telemetry_decorator import telemetry_resource
+from core.logging_decorator import log_execution
+
+from services.registry import get_registered_resources
+from utils.module_discovery import discover_modules
+
+logger = logging.getLogger("mcp-for-unity-server")
+
+# Export decorator for easy imports within tools
+__all__ = ['register_all_resources']
+
+
+def register_all_resources(mcp: FastMCP):
+    """
+    Auto-discover and register all resources in the resources/ directory.
+
+    Any .py file in this directory or subdirectories with @mcp_for_unity_resource decorated
+    functions will be automatically registered.
+    """
+    logger.info("Auto-discovering MCP for Unity Server resources...")
+    # Dynamic import of all modules in this directory
+    resources_dir = Path(__file__).parent
+
+    # Discover and import all modules
+    list(discover_modules(resources_dir, __package__))
+
+    resources = get_registered_resources()
+
+    if not resources:
+        logger.warning("No MCP resources registered!")
+        return
+
+    registered_count = 0
+    for resource_info in resources:
+        func = resource_info['func']
+        uri = resource_info['uri']
+        resource_name = resource_info['name']
+        description = resource_info['description']
+        kwargs = resource_info['kwargs']
+
+        # Check if URI contains query parameters (e.g., {?unity_instance})
+        has_query_params = '{?' in uri
+
+        if has_query_params:
+            wrapped_template = log_execution(resource_name, "Resource")(func)
+            wrapped_template = telemetry_resource(
+                resource_name)(wrapped_template)
+            wrapped_template = mcp.resource(
+                uri=uri,
+                name=resource_name,
+                description=description,
+                **kwargs,
+            )(wrapped_template)
+            logger.debug(
+                f"Registered resource template: {resource_name} - {uri}")
+            registered_count += 1
+            resource_info['func'] = wrapped_template
+        else:
+            wrapped = log_execution(resource_name, "Resource")(func)
+            wrapped = telemetry_resource(resource_name)(wrapped)
+            wrapped = mcp.resource(
+                uri=uri,
+                name=resource_name,
+                description=description,
+                **kwargs,
+            )(wrapped)
+            resource_info['func'] = wrapped
+            logger.debug(
+                f"Registered resource: {resource_name} - {description}")
+            registered_count += 1
+
+    logger.info(
+        f"Registered {registered_count} MCP resources ({len(resources)} unique)")

services/resources/active_tool.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 Vector3(BaseModel):
+    """3D vector."""
+    x: float = 0.0
+    y: float = 0.0
+    z: float = 0.0
+
+
+class ActiveToolData(BaseModel):
+    """Active tool data fields."""
+    activeTool: str = ""
+    isCustom: bool = False
+    pivotMode: str = ""
+    pivotRotation: str = ""
+    handleRotation: Vector3 = Vector3()
+    handlePosition: Vector3 = Vector3()
+
+
+class ActiveToolResponse(MCPResponse):
+    """Information about the currently active editor tool."""
+    data: ActiveToolData = ActiveToolData()
+
+
+@mcp_for_unity_resource(
+    uri="unity://editor/active-tool",
+    name="editor_active_tool",
+    description="Currently active editor tool (Move, Rotate, Scale, etc.) and transform handle settings."
+)
+async def get_active_tool(ctx: Context) -> ActiveToolResponse | MCPResponse:
+    """Get active editor tool information."""
+    unity_instance = get_unity_instance_from_context(ctx)
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_active_tool",
+        {}
+    )
+    return ActiveToolResponse(**response) if isinstance(response, dict) else response

services/resources/custom_tools.py

@@ -0,0 +1,57 @@
+from fastmcp import Context
+from pydantic import BaseModel
+
+from models import MCPResponse
+from services.custom_tool_service import (
+    CustomToolService,
+    resolve_project_id_for_unity_instance,
+    ToolDefinitionModel,
+)
+from services.registry import mcp_for_unity_resource
+from services.tools import get_unity_instance_from_context
+
+
+class CustomToolsData(BaseModel):
+    project_id: str
+    tool_count: int
+    tools: list[ToolDefinitionModel]
+
+
+class CustomToolsResourceResponse(MCPResponse):
+    data: CustomToolsData | None = None
+
+
+@mcp_for_unity_resource(
+    uri="unity://custom-tools",
+    name="custom_tools",
+    description="Lists custom tools available for the active Unity project.",
+)
+async def get_custom_tools(ctx: Context) -> CustomToolsResourceResponse | MCPResponse:
+    unity_instance = get_unity_instance_from_context(ctx)
+    if not unity_instance:
+        return MCPResponse(
+            success=False,
+            message="No active Unity instance. Call set_active_instance with Name@hash from unity://instances.",
+        )
+
+    project_id = resolve_project_id_for_unity_instance(unity_instance)
+    if project_id is None:
+        return MCPResponse(
+            success=False,
+            message=f"Could not resolve project id for {unity_instance}. Ensure Unity is running and reachable.",
+        )
+
+    service = CustomToolService.get_instance()
+    tools = await service.list_registered_tools(project_id)
+
+    data = CustomToolsData(
+        project_id=project_id,
+        tool_count=len(tools),
+        tools=tools,
+    )
+
+    return CustomToolsResourceResponse(
+        success=True,
+        message="Custom tools retrieved successfully.",
+        data=data,
+    )

services/resources/editor_state.py

@@ -0,0 +1,42 @@
+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 EditorStateData(BaseModel):
+    """Editor state data fields."""
+    isPlaying: bool = False
+    isPaused: bool = False
+    isCompiling: bool = False
+    isUpdating: bool = False
+    timeSinceStartup: float = 0.0
+    activeSceneName: str = ""
+    selectionCount: int = 0
+    activeObjectName: str | None = None
+
+
+class EditorStateResponse(MCPResponse):
+    """Dynamic editor state information that changes frequently."""
+    data: EditorStateData = EditorStateData()
+
+
+@mcp_for_unity_resource(
+    uri="unity://editor/state",
+    name="editor_state",
+    description="Current editor runtime state including play mode, compilation status, active scene, and selection summary. Refresh frequently for up-to-date information."
+)
+async def get_editor_state(ctx: Context) -> EditorStateResponse | MCPResponse:
+    """Get current editor runtime state."""
+    unity_instance = get_unity_instance_from_context(ctx)
+    response = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "get_editor_state",
+        {}
+    )
+    return EditorStateResponse(**response) if isinstance(response, dict) else response