mcpforunityserver 9.4.0b20260203025228__py3-none-any.whl

services/tools/manage_vfx.py

@@ -0,0 +1,120 @@
+from typing import Annotated, Any, Literal
+
+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
+
+# All possible actions grouped by component type
+PARTICLE_ACTIONS = [
+    "particle_get_info", "particle_set_main", "particle_set_emission", "particle_set_shape",
+    "particle_set_color_over_lifetime", "particle_set_size_over_lifetime",
+    "particle_set_velocity_over_lifetime", "particle_set_noise", "particle_set_renderer",
+    "particle_enable_module", "particle_play", "particle_stop", "particle_pause",
+    "particle_restart", "particle_clear", "particle_add_burst", "particle_clear_bursts"
+]
+
+VFX_ACTIONS = [
+    # Asset management
+    "vfx_create_asset", "vfx_assign_asset", "vfx_list_templates", "vfx_list_assets",
+    # Runtime control
+    "vfx_get_info", "vfx_set_float", "vfx_set_int", "vfx_set_bool",
+    "vfx_set_vector2", "vfx_set_vector3", "vfx_set_vector4", "vfx_set_color",
+    "vfx_set_gradient", "vfx_set_texture", "vfx_set_mesh", "vfx_set_curve",
+    "vfx_send_event", "vfx_play", "vfx_stop", "vfx_pause", "vfx_reinit",
+    "vfx_set_playback_speed", "vfx_set_seed"
+]
+
+LINE_ACTIONS = [
+    "line_get_info", "line_set_positions", "line_add_position", "line_set_position",
+    "line_set_width", "line_set_color", "line_set_material", "line_set_properties",
+    "line_clear", "line_create_line", "line_create_circle", "line_create_arc", "line_create_bezier"
+]
+
+TRAIL_ACTIONS = [
+    "trail_get_info", "trail_set_time", "trail_set_width", "trail_set_color",
+    "trail_set_material", "trail_set_properties", "trail_clear", "trail_emit"
+]
+
+ALL_ACTIONS = ["ping"] + PARTICLE_ACTIONS + VFX_ACTIONS + LINE_ACTIONS + TRAIL_ACTIONS
+
+
+@mcp_for_unity_tool(
+    description=(
+        "Manage Unity VFX components (ParticleSystem, VisualEffect, LineRenderer, TrailRenderer). "
+        "Action prefixes: particle_*, vfx_*, line_*, trail_*. "
+        "Action-specific parameters go in `properties` (keys match ManageVFX.cs)."
+    ),
+    annotations=ToolAnnotations(
+        title="Manage VFX",
+        destructiveHint=True,
+    ),
+)
+async def manage_vfx(
+    ctx: Context,
+    action: Annotated[str, "Action to perform (prefix: particle_, vfx_, line_, trail_)."],
+    target: Annotated[str | None, "Target GameObject (name/path/id)."] = None,
+    search_method: Annotated[
+        Literal["by_id", "by_name", "by_path", "by_tag", "by_layer"] | None,
+        "How to find the target GameObject.",
+    ] = None,
+    properties: Annotated[
+        dict[str, Any] | str | None,
+        "Action-specific parameters (dict or JSON string).",
+    ] = None,
+) -> dict[str, Any]:
+    """Unified VFX management tool."""
+
+    # Normalize action to lowercase to match Unity-side behavior
+    action_normalized = action.lower()
+
+    # Validate action against known actions using normalized value
+    if action_normalized not in ALL_ACTIONS:
+        # Provide helpful error with closest matches by prefix
+        prefix = action_normalized.split(
+            "_")[0] + "_" if "_" in action_normalized else ""
+        available_by_prefix = {
+            "particle_": PARTICLE_ACTIONS,
+            "vfx_": VFX_ACTIONS,
+            "line_": LINE_ACTIONS,
+            "trail_": TRAIL_ACTIONS,
+        }
+        suggestions = available_by_prefix.get(prefix, [])
+        if suggestions:
+            return {
+                "success": False,
+                "message": f"Unknown action '{action}'. Available {prefix}* actions: {', '.join(suggestions)}",
+            }
+        else:
+            return {
+                "success": False,
+                "message": (
+                    f"Unknown action '{action}'. Use prefixes: "
+                    "particle_*, vfx_*, line_*, trail_*. Run with action='ping' to test connection."
+                ),
+            }
+
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    params_dict: dict[str, Any] = {"action": action_normalized}
+    if properties is not None:
+        params_dict["properties"] = properties
+    if target is not None:
+        params_dict["target"] = target
+    if search_method is not None:
+        params_dict["searchMethod"] = search_method
+
+    params_dict = {k: v for k, v in params_dict.items() if v is not None}
+
+    # Send to Unity
+    result = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "manage_vfx",
+        params_dict,
+    )
+
+    return result if isinstance(result, dict) else {"success": False, "message": str(result)}

services/tools/preflight.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import Any
+
+from models import MCPResponse
+
+
+def _in_pytest() -> bool:
+    # Integration tests in this repo stub transports and do not run against a live Unity editor.
+    # Preflight must be a no-op in that environment to avoid breaking the existing test suite.
+    return bool(os.environ.get("PYTEST_CURRENT_TEST"))
+
+
+def _busy(reason: str, retry_after_ms: int) -> MCPResponse:
+    return MCPResponse(
+        success=False,
+        error="busy",
+        message=reason,
+        hint="retry",
+        data={"reason": reason, "retry_after_ms": int(retry_after_ms)},
+    )
+
+
+async def preflight(
+    ctx,
+    *,
+    requires_no_tests: bool = False,
+    wait_for_no_compile: bool = False,
+    refresh_if_dirty: bool = False,
+    max_wait_s: float = 30.0,
+) -> MCPResponse | None:
+    """
+    Server-side preflight guard used by tools so they behave safely even if the client never reads resources.
+
+    Returns:
+      - MCPResponse busy/retry payload when the tool should not proceed right now
+      - None when the tool should proceed normally
+    """
+    if _in_pytest():
+        return None
+
+    # Load canonical editor state (server enriches advice + staleness).
+    try:
+        from services.resources.editor_state import get_editor_state
+        state_resp = await get_editor_state(ctx)
+        state = state_resp.model_dump() if hasattr(
+            state_resp, "model_dump") else state_resp
+    except Exception:
+        # If we cannot determine readiness, fall back to proceeding (tools already contain retry logic).
+        return None
+
+    if not isinstance(state, dict) or not state.get("success", False):
+        # Unknown state; proceed rather than blocking (avoids false positives when Unity is reachable but status isn't).
+        return None
+
+    data = state.get("data")
+    if not isinstance(data, dict):
+        return None
+
+    # Optional refresh-if-dirty
+    if refresh_if_dirty:
+        assets = data.get("assets")
+        if isinstance(assets, dict) and assets.get("external_changes_dirty") is True:
+            try:
+                from services.tools.refresh_unity import refresh_unity
+                await refresh_unity(ctx, mode="if_dirty", scope="all", compile="request", wait_for_ready=True)
+            except Exception:
+                # Best-effort only; fall through to normal tool dispatch.
+                pass
+
+    # Tests running: fail fast for tools that require exclusivity.
+    if requires_no_tests:
+        tests = data.get("tests")
+        if isinstance(tests, dict) and tests.get("is_running") is True:
+            return _busy("tests_running", 5000)
+
+    # Compilation: optionally wait for a bounded time.
+    if wait_for_no_compile:
+        deadline = time.monotonic() + float(max_wait_s)
+        while True:
+            compilation = data.get("compilation") if isinstance(
+                data, dict) else None
+            is_compiling = isinstance(compilation, dict) and compilation.get(
+                "is_compiling") is True
+            is_domain_reload_pending = isinstance(compilation, dict) and compilation.get(
+                "is_domain_reload_pending") is True
+            if not is_compiling and not is_domain_reload_pending:
+                break
+            if time.monotonic() >= deadline:
+                return _busy("compiling", 500)
+            await asyncio.sleep(0.25)
+
+            # Refresh state for the next loop iteration.
+            try:
+                from services.resources.editor_state import get_editor_state
+                state_resp = await get_editor_state(ctx)
+                state = state_resp.model_dump() if hasattr(
+                    state_resp, "model_dump") else state_resp
+                data = state.get("data") if isinstance(state, dict) else None
+                if not isinstance(data, dict):
+                    return None
+            except Exception:
+                return None
+
+    # Staleness: if the snapshot is stale, proceed (tools will still run), but callers that read resources can back off.
+    # In future we may make this strict for some tools.
+    return None

services/tools/read_console.py

@@ -0,0 +1,151 @@
+"""
+Defines the read_console tool for accessing Unity Editor console messages.
+"""
+from typing import Annotated, Any, Literal
+
+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 services.tools.utils import coerce_int, coerce_bool, parse_json_payload
+from transport.unity_transport import send_with_unity_instance
+from transport.legacy.unity_connection import async_send_command_with_retry
+
+
+def _strip_stacktrace_from_list(items: list) -> None:
+    """Remove stacktrace fields from a list of log entries."""
+    for item in items:
+        if isinstance(item, dict) and "stacktrace" in item:
+            item.pop("stacktrace", None)
+
+
+@mcp_for_unity_tool(
+    description="Gets messages from or clears the Unity Editor console. Defaults to 10 most recent entries. Use page_size/cursor for paging. Note: For maximum client compatibility, pass count as a quoted string (e.g., '5'). The 'get' action is read-only; 'clear' modifies ephemeral UI state (not project data).",
+    annotations=ToolAnnotations(
+        title="Read Console",
+    ),
+)
+async def read_console(
+    ctx: Context,
+    action: Annotated[Literal['get', 'clear'],
+                      "Get or clear the Unity Editor console. Defaults to 'get' if omitted."] | None = None,
+    types: Annotated[list[Literal['error', 'warning',
+                                  'log', 'all']] | str,
+                     "Message types to get (accepts list or JSON string)"] | None = None,
+    count: Annotated[int | str,
+                     "Max messages to return in non-paging mode (accepts int or string, e.g., 5 or '5'). Ignored when paging with page_size/cursor."] | None = None,
+    filter_text: Annotated[str, "Text filter for messages"] | None = None,
+    since_timestamp: Annotated[str,
+                               "Get messages after this timestamp (ISO 8601)"] | None = None,
+    page_size: Annotated[int | str,
+                         "Page size for paginated console reads. Defaults to 50 when omitted."] | None = None,
+    cursor: Annotated[int | str,
+                      "Opaque cursor for paging (0-based offset). Defaults to 0."] | None = None,
+    format: Annotated[Literal['plain', 'detailed',
+                              'json'], "Output format"] | None = None,
+    include_stacktrace: Annotated[bool | str,
+                                  "Include stack traces in output (accepts true/false or 'true'/'false')"] | None = None,
+) -> dict[str, Any]:
+    # Get active instance from session state
+    # Removed session_state import
+    unity_instance = get_unity_instance_from_context(ctx)
+    # Set defaults if values are None
+    action = action if action is not None else 'get'
+    
+    # Parse types if it's a JSON string (handles client compatibility issue #561)
+    if isinstance(types, str):
+        types = parse_json_payload(types)
+    # Validate types is a list after parsing
+    if types is not None and not isinstance(types, list):
+        return {
+            "success": False,
+            "message": (
+                f"types must be a list, got {type(types).__name__}. "
+                "If passing as JSON string, use format: '[\"error\", \"warning\"]'"
+            )
+        }
+    if types is not None:
+        allowed_types = {"error", "warning", "log", "all"}
+        normalized_types = []
+        for entry in types:
+            if not isinstance(entry, str):
+                return {
+                    "success": False,
+                    "message": f"types entries must be strings, got {type(entry).__name__}"
+                }
+            normalized = entry.strip().lower()
+            if normalized not in allowed_types:
+                return {
+                    "success": False,
+                    "message": (
+                        f"invalid types entry '{entry}'. "
+                        f"Allowed values: {sorted(allowed_types)}"
+                    )
+                }
+            normalized_types.append(normalized)
+        types = normalized_types
+    else:
+        types = ['error', 'warning', 'log']
+    
+    format = format if format is not None else 'plain'
+    # Coerce booleans defensively (strings like 'true'/'false')
+
+    include_stacktrace = coerce_bool(include_stacktrace, default=False)
+    coerced_page_size = coerce_int(page_size, default=None)
+    coerced_cursor = coerce_int(cursor, default=None)
+
+    # Normalize action if it's a string
+    if isinstance(action, str):
+        action = action.lower()
+
+    # Coerce count defensively (string/float -> int).
+    # Important: leaving count unset previously meant "return all console entries", which can be extremely slow
+    # (and can exceed the plugin command timeout when Unity has a large console).
+    # To keep the tool responsive by default, we cap the default to a reasonable number of most-recent entries.
+    # If a client truly wants everything, it can pass count="all" (or count="*") explicitly.
+    if isinstance(count, str) and count.strip().lower() in ("all", "*"):
+        count = None
+    else:
+        count = coerce_int(count)
+
+    if action == "get" and count is None:
+        count = 10
+
+    # Prepare parameters for the C# handler
+    params_dict = {
+        "action": action,
+        "types": types,
+        "count": count,
+        "filterText": filter_text,
+        "sinceTimestamp": since_timestamp,
+        "pageSize": coerced_page_size,
+        "cursor": coerced_cursor,
+        "format": format.lower() if isinstance(format, str) else format,
+        "includeStacktrace": include_stacktrace
+    }
+
+    # Remove None values unless it's 'count' (as None might mean 'all')
+    params_dict = {k: v for k, v in params_dict.items()
+                   if v is not None or k == 'count'}
+
+    # Add count back if it was None, explicitly sending null might be important for C# logic
+    if 'count' not in params_dict:
+        params_dict['count'] = None
+
+    # Use centralized retry helper with instance routing
+    resp = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "read_console", params_dict)
+    if isinstance(resp, dict) and resp.get("success") and not include_stacktrace:
+        # Strip stacktrace fields from returned lines if present
+        try:
+            data = resp.get("data")
+            if isinstance(data, dict):
+                for key in ("lines", "items"):
+                    if key in data and isinstance(data[key], list):
+                        _strip_stacktrace_from_list(data[key])
+                        break
+            elif isinstance(data, list):
+                _strip_stacktrace_from_list(data)
+        except Exception:
+            pass
+    return resp if isinstance(resp, dict) else {"success": False, "message": str(resp)}

services/tools/refresh_unity.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Annotated, Any, Literal
+
+from fastmcp import Context
+from mcp.types import ToolAnnotations
+
+from models import MCPResponse
+from services.registry import mcp_for_unity_tool
+from services.tools import get_unity_instance_from_context
+import transport.unity_transport as unity_transport
+from transport.legacy.unity_connection import async_send_command_with_retry, _extract_response_reason
+from services.state.external_changes_scanner import external_changes_scanner
+import services.resources.editor_state as editor_state
+
+logger = logging.getLogger(__name__)
+
+
+@mcp_for_unity_tool(
+    description="Request a Unity asset database refresh and optionally a script compilation. Can optionally wait for readiness.",
+    annotations=ToolAnnotations(
+        title="Refresh Unity",
+        destructiveHint=True,
+    ),
+)
+async def refresh_unity(
+    ctx: Context,
+    mode: Annotated[Literal["if_dirty", "force"], "Refresh mode"] = "if_dirty",
+    scope: Annotated[Literal["assets", "scripts", "all"],
+                     "Refresh scope"] = "all",
+    compile: Annotated[Literal["none", "request"],
+                       "Whether to request compilation"] = "none",
+    wait_for_ready: Annotated[bool,
+                              "If true, wait until editor_state.advice.ready_for_tools is true"] = True,
+) -> MCPResponse | dict[str, Any]:
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    params: dict[str, Any] = {
+        "mode": mode,
+        "scope": scope,
+        "compile": compile,
+        "wait_for_ready": bool(wait_for_ready),
+    }
+
+    recovered_from_disconnect = False
+    # Don't retry on reload - refresh_unity triggers compilation/reload,
+    # so retrying would cause multiple reloads (issue #577)
+    response = await unity_transport.send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "refresh_unity",
+        params,
+        retry_on_reload=False,
+    )
+
+    # Handle connection errors during refresh/compile gracefully.
+    # Unity disconnects during domain reload, which is expected behavior - not a failure.
+    # If we sent the command and connection closed, the refresh was likely triggered successfully.
+    # Convert MCPResponse to dict if needed
+    response_dict = response if isinstance(response, dict) else (response.model_dump() if hasattr(response, "model_dump") else response.__dict__)
+    if not response_dict.get("success", True):
+        hint = response_dict.get("hint")
+        err = (response_dict.get("error") or response_dict.get("message") or "").lower()
+        reason = _extract_response_reason(response_dict)
+
+        # Connection closed/timeout during compile = refresh was triggered, Unity is reloading
+        # This is SUCCESS, not failure - don't return error to prevent Claude Code from retrying
+        is_connection_lost = (
+            "connection closed" in err
+            or "disconnected" in err
+            or "aborted" in err  # WinError 10053: connection aborted
+            or "timeout" in err
+            or reason == "reloading"
+        )
+
+        if is_connection_lost and compile == "request":
+            # EXPECTED BEHAVIOR: When compile="request", Unity triggers domain reload which
+            # causes connection to close mid-command. This is NOT a failure - the refresh
+            # was successfully triggered. Treating this as success prevents Claude Code from
+            # retrying unnecessarily (which would cause multiple domain reloads - issue #577).
+            # The subsequent wait_for_ready loop (below) will verify Unity becomes ready.
+            logger.info("refresh_unity: Connection lost during compile (expected - domain reload triggered)")
+            recovered_from_disconnect = True
+        elif hint == "retry" or "could not connect" in err:
+            # Retryable error - proceed to wait loop if wait_for_ready
+            if not wait_for_ready:
+                return MCPResponse(**response_dict)
+            recovered_from_disconnect = True
+        else:
+            # Non-recoverable error - connection issue unrelated to domain reload
+            logger.warning(f"refresh_unity: Non-recoverable error (compile={compile}): {err[:100]}")
+            return MCPResponse(**response_dict)
+
+    # Optional server-side wait loop (defensive): if Unity tool doesn't wait or returns quickly,
+    # poll the canonical editor_state resource until ready or timeout.
+    ready_confirmed = False
+    if wait_for_ready:
+        timeout_s = 60.0
+        start = time.monotonic()
+
+        # Blocking reasons that indicate Unity is actually busy (not just stale status)
+        # Must match activityPhase values from EditorStateCache.cs
+        real_blocking_reasons = {"compiling", "domain_reload", "running_tests", "asset_import"}
+
+        while time.monotonic() - start < timeout_s:
+            state_resp = await editor_state.get_editor_state(ctx)
+            state = state_resp.model_dump() if hasattr(
+                state_resp, "model_dump") else state_resp
+            data = (state or {}).get("data") if isinstance(
+                state, dict) else None
+            advice = (data or {}).get(
+                "advice") if isinstance(data, dict) else None
+            if isinstance(advice, dict):
+                # Exit if ready_for_tools is True
+                if advice.get("ready_for_tools") is True:
+                    ready_confirmed = True
+                    break
+                # Also exit if the only blocking reason is "stale_status" (Unity in background)
+                # Staleness means we can't confirm status, not that Unity is actually busy
+                blocking = set(advice.get("blocking_reasons") or [])
+                if not (blocking & real_blocking_reasons):
+                    ready_confirmed = True  # No real blocking reasons, consider ready
+                    break
+            await asyncio.sleep(0.25)
+
+        # If we timed out without confirming readiness, log and return failure
+        if not ready_confirmed:
+            logger.warning(f"refresh_unity: Timed out after {timeout_s}s waiting for editor to become ready")
+            return MCPResponse(
+                success=False,
+                message=f"Refresh triggered but timed out after {timeout_s}s waiting for editor readiness.",
+                data={"timeout": True, "wait_seconds": timeout_s},
+            )
+
+    # After readiness is restored, clear any external-dirty flag for this instance so future tools can proceed cleanly.
+    try:
+        inst = unity_instance or await editor_state.infer_single_instance_id(ctx)
+        if inst:
+            external_changes_scanner.clear_dirty(inst)
+    except Exception:
+        pass
+
+    if recovered_from_disconnect:
+        return MCPResponse(
+            success=True,
+            message="Refresh recovered after Unity disconnect/retry; editor is ready.",
+            data={"recovered_from_disconnect": True},
+        )
+
+    return MCPResponse(**response_dict) if isinstance(response, dict) else response