mcpforunityserver 8.7.0__py3-none-any.whl → 9.1.0__py3-none-any.whl

services/custom_tool_service.py

@@ -1,21 +1,26 @@
 import asyncio
+import inspect
 import logging
 import time
 from hashlib import sha256
 from typing import Optional
 
-from fastmcp import FastMCP
+from fastmcp import Context, 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 core.logging_decorator import log_execution
+from core.telemetry_decorator import telemetry_tool
 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
+from services.tools import get_unity_instance_from_context
+from services.registry import get_registered_tools
 
 logger = logging.getLogger("mcp-for-unity-server")
 
@@ -39,11 +44,13 @@ class ToolRegistrationResponse(BaseModel):
 class CustomToolService:
     _instance: "CustomToolService | None" = None
 
-    def __init__(self, mcp: FastMCP):
+    def __init__(self, mcp: FastMCP, project_scoped_tools: bool = True):
         CustomToolService._instance = self
         self._mcp = mcp
+        self._project_scoped_tools = project_scoped_tools
         self._project_tools: dict[str, dict[str, ToolDefinitionModel]] = {}
         self._hash_to_project: dict[str, str] = {}
+        self._global_tools: dict[str, ToolDefinitionModel] = {}
         self._register_http_routes()
 
     @classmethod
@@ -61,17 +68,8 @@ class CustomToolService:
             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
+            registered, replaced = self._register_project_tools(
+                payload.project_id, payload.tools, project_hash=payload.project_hash)
 
             message = f"Registered {len(registered)} tool(s)"
             if replaced:
@@ -266,15 +264,171 @@ class CustomToolService:
             return None
         return {"message": str(response)}
 
-    def _safe_response(self, response):
-        if isinstance(response, dict):
-            return response
-        if response is None:
+    def _register_project_tools(
+        self,
+        project_id: str,
+        tools: list[ToolDefinitionModel],
+        project_hash: str | None = None,
+    ) -> tuple[list[str], list[str]]:
+        registered: list[str] = []
+        replaced: list[str] = []
+        for tool in tools:
+            if self._is_registered(project_id, tool.name):
+                replaced.append(tool.name)
+            self._register_tool(project_id, tool)
+            registered.append(tool.name)
+            if not self._project_scoped_tools:
+                self._register_global_tool(tool)
+
+        if project_hash:
+            self._hash_to_project[project_hash.lower()] = project_id
+
+        return registered, replaced
+
+    def register_global_tools(self, tools: list[ToolDefinitionModel]) -> None:
+        if self._project_scoped_tools:
+            return
+        builtin_names = self._get_builtin_tool_names()
+        for tool in tools:
+            if tool.name in builtin_names:
+                logger.info(
+                    "Skipping global custom tool registration for built-in tool '%s'",
+                    tool.name,
+                )
+                continue
+            self._register_global_tool(tool)
+
+    def _get_builtin_tool_names(self) -> set[str]:
+        return {tool["name"] for tool in get_registered_tools()}
+
+    def _register_global_tool(self, definition: ToolDefinitionModel) -> None:
+        existing = self._global_tools.get(definition.name)
+        if existing:
+            if existing.model_dump() != definition.model_dump():
+                logger.warning(
+                    "Custom tool '%s' already registered with a different schema; keeping existing definition.",
+                    definition.name,
+                )
+            return
+
+        handler = self._build_global_tool_handler(definition)
+        wrapped = log_execution(definition.name, "Tool")(handler)
+        wrapped = telemetry_tool(definition.name)(wrapped)
+
+        try:
+            wrapped = self._mcp.tool(
+                name=definition.name,
+                description=definition.description,
+            )(wrapped)
+        except Exception as exc:  # pragma: no cover - defensive against tool conflicts
+            logger.warning(
+                "Failed to register custom tool '%s' globally: %s",
+                definition.name,
+                exc,
+            )
+            return
+
+        self._global_tools[definition.name] = definition
+
+    def _build_global_tool_handler(self, definition: ToolDefinitionModel):
+        async def _handler(ctx: Context, **kwargs) -> 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 mcpforunity://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.",
+                )
+
+            params = {k: v for k, v in kwargs.items() if v is not None}
+            service = CustomToolService.get_instance()
+            return await service.execute_tool(project_id, definition.name, unity_instance, params)
+
+        _handler.__name__ = f"custom_tool_{definition.name}"
+        _handler.__doc__ = definition.description or ""
+        _handler.__signature__ = self._build_signature(definition)
+        _handler.__annotations__ = self._build_annotations(definition)
+        return _handler
+
+    def _build_signature(self, definition: ToolDefinitionModel) -> inspect.Signature:
+        params: list[inspect.Parameter] = [
+            inspect.Parameter(
+                "ctx",
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                annotation=Context,
+            )
+        ]
+        for param in definition.parameters:
+            if not param.name.isidentifier():
+                logger.warning(
+                    "Custom tool '%s' has non-identifier parameter '%s'; exposing via kwargs only.",
+                    definition.name,
+                    param.name,
+                )
+                continue
+            default = inspect._empty if param.required else self._coerce_default(
+                param.default_value, param.type)
+            params.append(
+                inspect.Parameter(
+                    param.name,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    default=default,
+                    annotation=self._map_param_type(param),
+                )
+            )
+        return inspect.Signature(parameters=params)
+
+    def _build_annotations(self, definition: ToolDefinitionModel) -> dict[str, object]:
+        annotations: dict[str, object] = {"ctx": Context}
+        for param in definition.parameters:
+            if not param.name.isidentifier():
+                continue
+            annotations[param.name] = self._map_param_type(param)
+        return annotations
+
+    def _map_param_type(self, param: ToolParameterModel):
+        ptype = (param.type or "string").lower()
+        if ptype in ("integer", "int"):
+            return int
+        if ptype in ("number", "float", "double"):
+            return float
+        if ptype in ("bool", "boolean"):
+            return bool
+        if ptype in ("array", "list"):
+            return list
+        if ptype in ("object", "dict"):
+            return dict
+        return str
+
+    def _coerce_default(self, value: str | None, param_type: str | None):
+        if value is None:
             return None
-        return {"message": str(response)}
+        try:
+            ptype = (param_type or "string").lower()
+            if ptype in ("integer", "int"):
+                return int(value)
+            if ptype in ("number", "float", "double"):
+                return float(value)
+            if ptype in ("bool", "boolean"):
+                return str(value).lower() in ("1", "true", "yes", "on")
+            return value
+        except Exception:
+            return value
 
 
 def compute_project_id(project_name: str, project_path: str) -> str:
+    """
+    DEPRECATED: Computes a SHA256-based project ID.
+    This function is no longer used as of the multi-session fix.
+    Unity instances now use their native project_hash (SHA1-based) for consistency
+    across stdio and WebSocket transports.
+    """
     combined = f"{project_name}:{project_path}"
     return sha256(combined.encode("utf-8")).hexdigest().upper()[:16]
 
@@ -307,7 +461,13 @@ def resolve_project_id_for_unity_instance(unity_instance: str | None) -> str | N
             )
 
         if target:
-            return compute_project_id(target.name, target.path)
+            # Return the project_hash from Unity (not a computed SHA256 hash).
+            # This matches the hash Unity uses when registering tools via WebSocket.
+            if target.hash:
+                return target.hash
+            logger.warning(
+                f"Unity instance {target.id} has empty hash; cannot resolve project ID")
+            return None
     except Exception:
         logger.debug(
             f"Failed to resolve project id via connection pool for {unity_instance}")

services/resources/__init__.py

@@ -18,7 +18,7 @@ logger = logging.getLogger("mcp-for-unity-server")
 __all__ = ['register_all_resources']
 
 
-def register_all_resources(mcp: FastMCP):
+def register_all_resources(mcp: FastMCP, *, project_scoped_tools: bool = True):
     """
     Auto-discover and register all resources in the resources/ directory.
 
@@ -46,6 +46,11 @@ def register_all_resources(mcp: FastMCP):
         description = resource_info['description']
         kwargs = resource_info['kwargs']
 
+        if not project_scoped_tools and resource_name == "custom_tools":
+            logger.info(
+                "Skipping custom_tools resource registration (project-scoped tools disabled)")
+            continue
+
         # Check if URI contains query parameters (e.g., {?unity_instance})
         has_query_params = '{?' in uri
 

services/resources/active_tool.py

@@ -31,7 +31,7 @@ class ActiveToolResponse(MCPResponse):
 
 
 @mcp_for_unity_resource(
-    uri="unity://editor/active-tool",
+    uri="mcpforunity://editor/active-tool",
     name="editor_active_tool",
     description="Currently active editor tool (Move, Rotate, Scale, etc.) and transform handle settings."
 )

services/resources/custom_tools.py

@@ -22,7 +22,7 @@ class CustomToolsResourceResponse(MCPResponse):
 
 
 @mcp_for_unity_resource(
-    uri="unity://custom-tools",
+    uri="mcpforunity://custom-tools",
     name="custom_tools",
     description="Lists custom tools available for the active Unity project.",
 )
@@ -31,7 +31,7 @@ async def get_custom_tools(ctx: Context) -> CustomToolsResourceResponse | MCPRes
     if not unity_instance:
         return MCPResponse(
             success=False,
-            message="No active Unity instance. Call set_active_instance with Name@hash from unity://instances.",
+            message="No active Unity instance. Call set_active_instance with Name@hash from mcpforunity://instances.",
         )
 
     project_id = resolve_project_id_for_unity_instance(unity_instance)

services/resources/editor_state.py

@@ -1,51 +1,304 @@
-from pydantic import BaseModel
+import os
+import time
+from typing import Any
+
 from fastmcp import Context
+from pydantic import BaseModel
 
 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 services.state.external_changes_scanner import external_changes_scanner
+import transport.unity_transport as unity_transport
 from transport.legacy.unity_connection import async_send_command_with_retry
 
 
+class EditorStateUnity(BaseModel):
+    instance_id: str | None = None
+    unity_version: str | None = None
+    project_id: str | None = None
+    platform: str | None = None
+    is_batch_mode: bool | None = None
+
+
+class EditorStatePlayMode(BaseModel):
+    is_playing: bool | None = None
+    is_paused: bool | None = None
+    is_changing: bool | None = None
+
+
+class EditorStateActiveScene(BaseModel):
+    path: str | None = None
+    guid: str | None = None
+    name: str | None = None
+
+
+class EditorStateEditor(BaseModel):
+    is_focused: bool | None = None
+    play_mode: EditorStatePlayMode | None = None
+    active_scene: EditorStateActiveScene | None = None
+
+
+class EditorStateActivity(BaseModel):
+    phase: str | None = None
+    since_unix_ms: int | None = None
+    reasons: list[str] | None = None
+
+
+class EditorStateCompilation(BaseModel):
+    is_compiling: bool | None = None
+    is_domain_reload_pending: bool | None = None
+    last_compile_started_unix_ms: int | None = None
+    last_compile_finished_unix_ms: int | None = None
+    last_domain_reload_before_unix_ms: int | None = None
+    last_domain_reload_after_unix_ms: int | None = None
+
+
+class EditorStateRefresh(BaseModel):
+    is_refresh_in_progress: bool | None = None
+    last_refresh_requested_unix_ms: int | None = None
+    last_refresh_finished_unix_ms: int | None = None
+
+
+class EditorStateAssets(BaseModel):
+    is_updating: bool | None = None
+    external_changes_dirty: bool | None = None
+    external_changes_last_seen_unix_ms: int | None = None
+    external_changes_dirty_since_unix_ms: int | None = None
+    external_changes_last_cleared_unix_ms: int | None = None
+    refresh: EditorStateRefresh | None = None
+
+
+class EditorStateLastRun(BaseModel):
+    finished_unix_ms: int | None = None
+    result: str | None = None
+    counts: Any | None = None
+
+
+class EditorStateTests(BaseModel):
+    is_running: bool | None = None
+    mode: str | None = None
+    current_job_id: str | None = None
+    started_unix_ms: int | None = None
+    started_by: str | None = None
+    last_run: EditorStateLastRun | None = None
+
+
+class EditorStateTransport(BaseModel):
+    unity_bridge_connected: bool | None = None
+    last_message_unix_ms: int | None = None
+
+
+class EditorStateAdvice(BaseModel):
+    ready_for_tools: bool | None = None
+    blocking_reasons: list[str] | None = None
+    recommended_retry_after_ms: int | None = None
+    recommended_next_action: str | None = None
+
+
+class EditorStateStaleness(BaseModel):
+    age_ms: int | None = None
+    is_stale: bool | None = None
+
+
 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
+    schema_version: str
+    observed_at_unix_ms: int
+    sequence: int
+    unity: EditorStateUnity | None = None
+    editor: EditorStateEditor | None = None
+    activity: EditorStateActivity | None = None
+    compilation: EditorStateCompilation | None = None
+    assets: EditorStateAssets | None = None
+    tests: EditorStateTests | None = None
+    transport: EditorStateTransport | None = None
+    advice: EditorStateAdvice | None = None
+    staleness: EditorStateStaleness | None = None
+
+
+def _now_unix_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _in_pytest() -> bool:
+    # Avoid instance-discovery side effects during the Python integration test suite.
+    return bool(os.environ.get("PYTEST_CURRENT_TEST"))
+
+
+async def infer_single_instance_id(ctx: Context) -> str | None:
+    """
+    Best-effort: if exactly one Unity instance is connected, return its Name@hash id.
+    This makes editor_state outputs self-describing even when no explicit active instance is set.
+    """
+    await ctx.info("If exactly one Unity instance is connected, return its Name@hash id.")
+
+    try:
+        transport = unity_transport._current_transport()
+    except Exception:
+        transport = None
+
+    if transport == "http":
+        # HTTP/WebSocket transport: derive from PluginHub sessions.
+        try:
+            from transport.plugin_hub import PluginHub
+
+            sessions_data = await PluginHub.get_sessions()
+            sessions = sessions_data.sessions if hasattr(
+                sessions_data, "sessions") else {}
+            if isinstance(sessions, dict) and len(sessions) == 1:
+                session = next(iter(sessions.values()))
+                project = getattr(session, "project", None)
+                project_hash = getattr(session, "hash", None)
+                if project and project_hash:
+                    return f"{project}@{project_hash}"
+        except Exception:
+            return None
+        return None
+
+    # Stdio/TCP transport: derive from connection pool discovery.
+    try:
+        from transport.legacy.unity_connection import get_unity_connection_pool
+
+        pool = get_unity_connection_pool()
+        instances = pool.discover_all_instances(force_refresh=False)
+        if isinstance(instances, list) and len(instances) == 1:
+            inst = instances[0]
+            inst_id = getattr(inst, "id", None)
+            return str(inst_id) if inst_id else None
+    except Exception:
+        return None
+    return None
+
+
+def _enrich_advice_and_staleness(state_v2: dict[str, Any]) -> dict[str, Any]:
+    now_ms = _now_unix_ms()
+    observed = state_v2.get("observed_at_unix_ms")
+    try:
+        observed_ms = int(observed)
+    except Exception:
+        observed_ms = now_ms
 
+    age_ms = max(0, now_ms - observed_ms)
+    # Conservative default: treat >2s as stale (covers common unfocused-editor throttling).
+    is_stale = age_ms > 2000
 
-class EditorStateResponse(MCPResponse):
-    """Dynamic editor state information that changes frequently."""
-    data: EditorStateData = EditorStateData()
+    compilation = state_v2.get("compilation") or {}
+    tests = state_v2.get("tests") or {}
+    assets = state_v2.get("assets") or {}
+    refresh = (assets.get("refresh") or {}) if isinstance(assets, dict) else {}
+
+    blocking: list[str] = []
+    if compilation.get("is_compiling") is True:
+        blocking.append("compiling")
+    if compilation.get("is_domain_reload_pending") is True:
+        blocking.append("domain_reload")
+    if tests.get("is_running") is True:
+        blocking.append("running_tests")
+    if refresh.get("is_refresh_in_progress") is True:
+        blocking.append("asset_refresh")
+    if is_stale:
+        blocking.append("stale_status")
+
+    ready_for_tools = len(blocking) == 0
+
+    state_v2["advice"] = {
+        "ready_for_tools": ready_for_tools,
+        "blocking_reasons": blocking,
+        "recommended_retry_after_ms": 0 if ready_for_tools else 500,
+        "recommended_next_action": "none" if ready_for_tools else "retry_later",
+    }
+    state_v2["staleness"] = {"age_ms": age_ms, "is_stale": is_stale}
+    return state_v2
 
 
 @mcp_for_unity_resource(
-    uri="unity://editor/state",
+    uri="mcpforunity://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."
+    description="Canonical editor readiness snapshot. Includes advice and server-computed staleness.",
 )
-async def get_editor_state(ctx: Context) -> EditorStateResponse | MCPResponse:
-    """Get current editor runtime state."""
+async def get_editor_state(ctx: Context) -> MCPResponse:
     unity_instance = get_unity_instance_from_context(ctx)
-    response = await send_with_unity_instance(
+
+    response = await unity_transport.send_with_unity_instance(
         async_send_command_with_retry,
         unity_instance,
         "get_editor_state",
-        {}
+        {},
     )
-    # When Unity is reloading/unresponsive (often when unfocused), transports may return
-    # a retryable MCPResponse payload with success=false and no data. Do not attempt to
-    # coerce that into EditorStateResponse (it would fail validation); return it as-is.
-    if isinstance(response, dict):
-        if not response.get("success", True):
-            return MCPResponse(**response)
-        if response.get("data") is None:
-            return MCPResponse(success=False, error="Editor state missing 'data' payload", data=response)
-        return EditorStateResponse(**response)
-    return response
+
+    # If Unity returns a structured retry hint or error, surface it directly.
+    if isinstance(response, dict) and not response.get("success", True):
+        return MCPResponse(**response)
+
+    state_v2 = response.get("data") if isinstance(
+        response, dict) and isinstance(response.get("data"), dict) else {}
+    state_v2.setdefault("schema_version", "unity-mcp/editor_state@2")
+    state_v2.setdefault("observed_at_unix_ms", _now_unix_ms())
+    state_v2.setdefault("sequence", 0)
+
+    # Ensure the returned snapshot is clearly associated with the targeted instance.
+    unity_section = state_v2.get("unity")
+    if not isinstance(unity_section, dict):
+        unity_section = {}
+        state_v2["unity"] = unity_section
+    current_instance_id = unity_section.get("instance_id")
+    if current_instance_id in (None, ""):
+        if unity_instance:
+            unity_section["instance_id"] = unity_instance
+        else:
+            inferred = await infer_single_instance_id(ctx)
+            if inferred:
+                unity_section["instance_id"] = inferred
+
+    # External change detection (server-side): compute per instance based on project root path.
+    try:
+        instance_id = unity_section.get("instance_id")
+        if isinstance(instance_id, str) and instance_id.strip():
+            from services.resources.project_info import get_project_info
+
+            proj_resp = await get_project_info(ctx)
+            proj = proj_resp.model_dump() if hasattr(
+                proj_resp, "model_dump") else proj_resp
+            proj_data = proj.get("data") if isinstance(proj, dict) else None
+            project_root = proj_data.get("projectRoot") if isinstance(
+                proj_data, dict) else None
+            if isinstance(project_root, str) and project_root.strip():
+                external_changes_scanner.set_project_root(
+                    instance_id, project_root)
+
+            ext = external_changes_scanner.update_and_get(instance_id)
+
+            assets = state_v2.get("assets")
+            if not isinstance(assets, dict):
+                assets = {}
+                state_v2["assets"] = assets
+            assets["external_changes_dirty"] = bool(
+                ext.get("external_changes_dirty", False))
+            assets["external_changes_last_seen_unix_ms"] = ext.get(
+                "external_changes_last_seen_unix_ms")
+            assets["external_changes_dirty_since_unix_ms"] = ext.get(
+                "dirty_since_unix_ms")
+            assets["external_changes_last_cleared_unix_ms"] = ext.get(
+                "last_cleared_unix_ms")
+    except Exception:
+        pass
+
+    state_v2 = _enrich_advice_and_staleness(state_v2)
+
+    try:
+        if hasattr(EditorStateData, "model_validate"):
+            validated = EditorStateData.model_validate(state_v2)
+        else:
+            validated = EditorStateData.parse_obj(
+                state_v2)  # type: ignore[attr-defined]
+        data = validated.model_dump() if hasattr(
+            validated, "model_dump") else validated.dict()
+    except Exception as e:
+        return MCPResponse(
+            success=False,
+            error="invalid_editor_state",
+            message=f"Editor state payload failed validation: {e}",
+            data={"raw": state_v2},
+        )
+
+    return MCPResponse(success=True, message="Retrieved editor state.", data=data)