mcpforunityserver 9.4.0b20260203025228__py3-none-any.whl

services/tools/debug_request_context.py

@@ -0,0 +1,86 @@
+from typing import Any
+import os
+import sys
+
+from core.telemetry import get_package_version
+
+from fastmcp import Context
+from mcp.types import ToolAnnotations
+
+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).",
+    annotations=ToolAnnotations(
+        title="Debug Request Context",
+        readOnlyHint=True,
+    ),
+)
+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": {
+            "server": {
+                "version": get_package_version(),
+                "cwd": os.getcwd(),
+                "argv": list(sys.argv),
+            },
+            "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,
+        },
+    }

services/tools/execute_custom_tool.py

@@ -0,0 +1,43 @@
+from fastmcp import Context
+from mcp.types import ToolAnnotations
+from models.models import MCPResponse
+
+from services.custom_tool_service import (
+    CustomToolService,
+    resolve_project_id_for_unity_instance,
+)
+from services.registry import mcp_for_unity_tool
+from services.tools import get_unity_instance_from_context
+
+
+@mcp_for_unity_tool(
+    name="execute_custom_tool",
+    description="Execute a project-scoped custom tool registered by Unity.",
+    annotations=ToolAnnotations(
+        title="Execute Custom Tool",
+        destructiveHint=True,
+    ),
+)
+async def execute_custom_tool(ctx: Context, tool_name: str, parameters: dict | None = None) -> 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.",
+        )
+
+    if not isinstance(parameters, dict):
+        return MCPResponse(
+            success=False,
+            message="parameters must be an object/dictionary",
+        )
+
+    service = CustomToolService.get_instance()
+    return await service.execute_tool(project_id, tool_name, unity_instance, parameters)

services/tools/execute_menu_item.py

@@ -0,0 +1,32 @@
+"""
+Defines the execute_menu_item tool for executing and reading Unity Editor menu items.
+"""
+from typing import Annotated, Any
+
+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
+from transport.unity_transport import send_with_unity_instance
+from transport.legacy.unity_connection import async_send_command_with_retry
+
+
+@mcp_for_unity_tool(
+    description="Execute a Unity menu item by path.",
+    annotations=ToolAnnotations(
+        title="Execute Menu Item",
+        destructiveHint=True,
+    ),
+)
+async def execute_menu_item(
+    ctx: Context,
+    menu_path: Annotated[str,
+                         "Menu path for 'execute' or 'exists' (e.g., 'File/Save Project')"] | None = None,
+) -> MCPResponse:
+    unity_instance = get_unity_instance_from_context(ctx)
+    params_dict: dict[str, Any] = {"menuPath": menu_path}
+    params_dict = {k: v for k, v in params_dict.items() if v is not None}
+    result = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "execute_menu_item", params_dict)
+    return MCPResponse(**result) if isinstance(result, dict) else result

services/tools/find_gameobjects.py

@@ -0,0 +1,110 @@
+"""
+Tool for searching GameObjects in Unity scenes.
+Returns only instance IDs with pagination support for efficient searches.
+"""
+from typing import Annotated, Any, Literal
+
+from fastmcp import Context
+from pydantic import Field
+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
+from services.tools.utils import coerce_bool, coerce_int
+from services.tools.preflight import preflight
+
+
+@mcp_for_unity_tool(
+    description="Search for GameObjects in the scene. Requires search_term (name, tag, layer name, component type, or path). Returns instance IDs only (paginated). Use mcpforunity://scene/gameobject/{id} resource to get full GameObject data."
+)
+async def find_gameobjects(
+    ctx: Context,
+    search_term: Annotated[
+        str,
+        Field(description="The value to search for (name, tag, layer name, component type, or path)")
+    ],
+    search_method: Annotated[
+        Literal["by_name", "by_tag", "by_layer", "by_component", "by_path", "by_id"],
+        Field(
+            default="by_name",
+            description="How to search for GameObjects"
+        )
+    ] = "by_name",
+    include_inactive: Annotated[
+        bool | str | None,
+        Field(
+            default=None,
+            description="Include inactive GameObjects in search"
+        )
+    ] = None,
+    page_size: Annotated[
+        int | str | None,
+        Field(
+            default=None,
+            description="Number of results per page (default: 50, max: 500)"
+        )
+    ] = None,
+    cursor: Annotated[
+        int | str | None,
+        Field(
+            default=None,
+            description="Pagination cursor (offset for next page)"
+        )
+    ] = None,
+) -> dict[str, Any]:
+    """
+    Search for GameObjects and return their instance IDs.
+
+    This is a focused search tool optimized for finding GameObjects efficiently.
+    It returns only instance IDs to minimize payload size.
+
+    For detailed GameObject information, use the returned IDs with:
+    - mcpforunity://scene/gameobject/{id} - Get full GameObject data
+    - mcpforunity://scene/gameobject/{id}/components - Get all components
+    - mcpforunity://scene/gameobject/{id}/component/{name} - Get specific component
+    """
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    # Validate required parameters before preflight I/O
+    if not search_term:
+        return {
+            "success": False,
+            "message": "Missing required parameter 'search_term'. Specify what to search for."
+        }
+
+    gate = await preflight(ctx, wait_for_no_compile=True, refresh_if_dirty=True)
+    if gate is not None:
+        return gate.model_dump()
+
+    # Coerce parameters
+    include_inactive = coerce_bool(include_inactive, default=False)
+    page_size = coerce_int(page_size, default=50)
+    cursor = coerce_int(cursor, default=0)
+
+    try:
+        params = {
+            "searchMethod": search_method,
+            "searchTerm": search_term,
+            "includeInactive": include_inactive,
+            "pageSize": page_size,
+            "cursor": cursor,
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+
+        response = await send_with_unity_instance(
+            async_send_command_with_retry,
+            unity_instance,
+            "find_gameobjects",
+            params,
+        )
+
+        if isinstance(response, dict) and response.get("success"):
+            return {
+                "success": True,
+                "message": response.get("message", "Search completed."),
+                "data": response.get("data")
+            }
+        return response if isinstance(response, dict) else {"success": False, "message": str(response)}
+
+    except Exception as e:
+        return {"success": False, "message": f"Error searching GameObjects: {e!s}"}

services/tools/find_in_file.py

@@ -0,0 +1,181 @@
+import base64
+import os
+import re
+from typing import Annotated, Any
+from urllib.parse import unquote, urlparse
+
+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
+
+
+def _split_uri(uri: str) -> tuple[str, str]:
+    """Split an incoming URI or path into (name, directory) suitable for Unity.
+
+    Rules:
+    - mcpforunity://path/Assets/... → keep as Assets-relative (after decode/normalize)
+    - file://... → percent-decode, normalize, strip host and leading slashes,
+        then, if any 'Assets' segment exists, return path relative to that 'Assets' root.
+        Otherwise, fall back to original name/dir behavior.
+    - plain paths → decode/normalize separators; if they contain an 'Assets' segment,
+        return relative to 'Assets'.
+    """
+    raw_path: str
+    if uri.startswith("mcpforunity://path/"):
+        raw_path = uri[len("mcpforunity://path/"):]
+    elif uri.startswith("file://"):
+        parsed = urlparse(uri)
+        host = (parsed.netloc or "").strip()
+        p = parsed.path or ""
+        # UNC: file://server/share/... -> //server/share/...
+        if host and host.lower() != "localhost":
+            p = f"//{host}{p}"
+        # Use percent-decoded path, preserving leading slashes
+        raw_path = unquote(p)
+    else:
+        raw_path = uri
+
+    # Percent-decode any residual encodings and normalize separators
+    raw_path = unquote(raw_path).replace("\\", "/")
+    # Strip leading slash only for Windows drive-letter forms like "/C:/..."
+    if os.name == "nt" and len(raw_path) >= 3 and raw_path[0] == "/" and raw_path[2] == ":":
+        raw_path = raw_path[1:]
+
+    # Normalize path (collapse ../, ./)
+    norm = os.path.normpath(raw_path).replace("\\", "/")
+
+    # If an 'Assets' segment exists, compute path relative to it (case-insensitive)
+    parts = [p for p in norm.split("/") if p not in ("", ".")]
+    idx = next((i for i, seg in enumerate(parts)
+                if seg.lower() == "assets"), None)
+    assets_rel = "/".join(parts[idx:]) if idx is not None else None
+
+    effective_path = assets_rel if assets_rel else norm
+    # For POSIX absolute paths outside Assets, drop the leading '/'
+    # to return a clean relative-like directory (e.g., '/tmp' -> 'tmp').
+    if effective_path.startswith("/"):
+        effective_path = effective_path[1:]
+
+    name = os.path.splitext(os.path.basename(effective_path))[0]
+    directory = os.path.dirname(effective_path)
+    return name, directory
+
+
+@mcp_for_unity_tool(
+    description="Searches a file with a regex pattern and returns line numbers and excerpts.",
+    annotations=ToolAnnotations(
+        title="Find in File",
+        readOnlyHint=True,
+    ),
+)
+async def find_in_file(
+    ctx: Context,
+    uri: Annotated[str, "The resource URI to search under Assets/ or file path form supported by read_resource"],
+    pattern: Annotated[str, "The regex pattern to search for"],
+    project_root: Annotated[str | None, "Optional project root path"] = None,
+    max_results: Annotated[int, "Cap results to avoid huge payloads"] = 200,
+    ignore_case: Annotated[bool | str | None,
+                           "Case insensitive search"] = True,
+) -> dict[str, Any]:
+    # project_root is currently unused but kept for interface consistency
+    unity_instance = get_unity_instance_from_context(ctx)
+    await ctx.info(
+        f"Processing find_in_file: {uri} (unity_instance={unity_instance or 'default'})")
+
+    name, directory = _split_uri(uri)
+
+    # 1. Read file content via Unity
+    read_resp = await send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "manage_script",
+        {
+            "action": "read",
+            "name": name,
+            "path": directory,
+        },
+    )
+
+    if not isinstance(read_resp, dict) or not read_resp.get("success"):
+        return read_resp if isinstance(read_resp, dict) else {"success": False, "message": str(read_resp)}
+
+    data = read_resp.get("data", {})
+    contents = data.get("contents")
+    if not contents and data.get("contentsEncoded") and data.get("encodedContents"):
+        try:
+            contents = base64.b64decode(data.get("encodedContents", "").encode(
+                "utf-8")).decode("utf-8", "replace")
+        except (ValueError, TypeError, base64.binascii.Error):
+            contents = contents or ""
+
+    if contents is None:
+        return {"success": False, "message": "Could not read file content."}
+
+    # 2. Perform regex search
+    flags = re.MULTILINE
+    # Handle ignore_case which can be boolean or string from some clients
+    ic = ignore_case
+    if isinstance(ic, str):
+        ic = ic.lower() in ("true", "1", "yes")
+    if ic:
+        flags |= re.IGNORECASE
+
+    try:
+        regex = re.compile(pattern, flags)
+    except re.error as e:
+        return {"success": False, "message": f"Invalid regex pattern: {e}"}
+
+    # If the regex is not multiline specific (doesn't contain \n literal match logic),
+    # we could iterate lines. But users might use multiline regexes.
+    # Let's search the whole content and map back to lines.
+
+    found = list(regex.finditer(contents))
+
+    results = []
+    count = 0
+
+    for m in found:
+        if count >= max_results:
+            break
+
+        start_idx = m.start()
+        end_idx = m.end()
+
+        # Calculate line number
+        # Count newlines up to start_idx
+        line_num = contents.count('\n', 0, start_idx) + 1
+
+        # Get line content for excerpt
+        # Find start of line
+        line_start = contents.rfind('\n', 0, start_idx) + 1
+        # Find end of line
+        line_end = contents.find('\n', start_idx)
+        if line_end == -1:
+            line_end = len(contents)
+
+        line_content = contents[line_start:line_end]
+
+        # Create excerpt
+        # We can just return the line content as excerpt
+
+        results.append({
+            "line": line_num,
+            "content": line_content.strip(),  # detailed match info?
+            "match": m.group(0),
+            "start": start_idx,
+            "end": end_idx
+        })
+        count += 1
+
+    return {
+        "success": True,
+        "data": {
+            "matches": results,
+            "count": len(results),
+            "total_matches": len(found)
+        }
+    }

services/tools/manage_asset.py

@@ -0,0 +1,119 @@
+"""
+Defines the manage_asset tool for interacting with Unity assets.
+"""
+import asyncio
+import json
+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 parse_json_payload, coerce_int, normalize_properties
+from transport.unity_transport import send_with_unity_instance
+from transport.legacy.unity_connection import async_send_command_with_retry
+from services.tools.preflight import preflight
+
+
+@mcp_for_unity_tool(
+    description=(
+        "Performs asset operations (import, create, modify, delete, etc.) in Unity.\n\n"
+        "Tip (payload safety): for `action=\"search\"`, prefer paging (`page_size`, `page_number`) and keep "
+        "`generate_preview=false` (previews can add large base64 blobs)."
+    ),
+    annotations=ToolAnnotations(
+        title="Manage Asset",
+        destructiveHint=True,
+    ),
+)
+async def manage_asset(
+    ctx: Context,
+    action: Annotated[Literal["import", "create", "modify", "delete", "duplicate", "move", "rename", "search", "get_info", "create_folder", "get_components"], "Perform CRUD operations on assets."],
+    path: Annotated[str, "Asset path (e.g., 'Materials/MyMaterial.mat') or search scope (e.g., 'Assets')."],
+    asset_type: Annotated[str,
+                          "Asset type (e.g., 'Material', 'Folder') - required for 'create'. Note: For ScriptableObjects, use manage_scriptable_object."] | None = None,
+    properties: Annotated[dict[str, Any],
+                          "Dictionary of properties for 'create'/'modify'. Keys are property names, values are property values."] | None = None,
+    destination: Annotated[str,
+                           "Target path for 'duplicate'/'move'."] | None = None,
+    generate_preview: Annotated[bool,
+                                "Generate a preview/thumbnail for the asset when supported. "
+                                "Warning: previews may include large base64 payloads; keep false unless needed."] = False,
+    search_pattern: Annotated[str,
+                              "Search pattern (e.g., '*.prefab' or AssetDatabase filters like 't:MonoScript'). "
+                              "Recommended: put queries like 't:MonoScript' here and set path='Assets'."] | None = None,
+    filter_type: Annotated[str, "Filter type for search"] | None = None,
+    filter_date_after: Annotated[str,
+                                 "Date after which to filter"] | None = None,
+    page_size: Annotated[int | float | str,
+                         "Page size for pagination. Recommended: 25 (smaller for LLM-friendly responses)."] | None = None,
+    page_number: Annotated[int | float | str,
+                           "Page number for pagination (1-based)."] | None = None,
+) -> dict[str, Any]:
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    # Best-effort guard: if Unity is compiling/reloading or known external changes are pending,
+    # wait/refresh to avoid stale reads and flaky timeouts.
+    gate = await preflight(ctx, wait_for_no_compile=True, refresh_if_dirty=True)
+    if gate is not None:
+        return gate.model_dump()
+
+    # --- Normalize properties using robust module-level helper ---
+    properties, parse_error = normalize_properties(properties)
+    if parse_error:
+        await ctx.error(f"manage_asset: {parse_error}")
+        return {"success": False, "message": parse_error}
+
+    page_size = coerce_int(page_size)
+    page_number = coerce_int(page_number)
+
+    # --- Payload-safe normalization for common LLM mistakes (search) ---
+    # Unity's C# handler treats `path` as a folder scope. If a model mistakenly puts a query like
+    # "t:MonoScript" into `path`, Unity will consider it an invalid folder and fall back to searching
+    # the entire project, which is token-heavy. Normalize such cases into search_pattern + Assets scope.
+    action_l = (action or "").lower()
+    if action_l == "search":
+        try:
+            raw_path = (path or "").strip()
+        except (AttributeError, TypeError):
+            # Handle case where path is not a string despite type annotation
+            raw_path = ""
+
+        # If the caller put an AssetDatabase query into `path`, treat it as `search_pattern`.
+        if (not search_pattern) and raw_path.startswith("t:"):
+            search_pattern = raw_path
+            path = "Assets"
+            await ctx.info("manage_asset(search): normalized query from `path` into `search_pattern` and set path='Assets'")
+
+        # If the caller used `asset_type` to mean a search filter, map it to filter_type.
+        # (In Unity, filterType becomes `t:<filterType>`.)
+        if (not filter_type) and asset_type and isinstance(asset_type, str):
+            filter_type = asset_type
+            await ctx.info("manage_asset(search): mapped `asset_type` into `filter_type` for safer server-side filtering")
+
+    # Prepare parameters for the C# handler
+    params_dict = {
+        "action": action.lower(),
+        "path": path,
+        "assetType": asset_type,
+        "properties": properties,
+        "destination": destination,
+        "generatePreview": generate_preview,
+        "searchPattern": search_pattern,
+        "filterType": filter_type,
+        "filterDateAfter": filter_date_after,
+        "pageSize": page_size,
+        "pageNumber": page_number
+    }
+
+    # Remove None values to avoid sending unnecessary nulls
+    params_dict = {k: v for k, v in params_dict.items() if v is not None}
+
+    # Get the current asyncio event loop
+    loop = asyncio.get_running_loop()
+
+    # Use centralized async retry helper with instance routing
+    result = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "manage_asset", params_dict, loop=loop)
+    # Return the result obtained from Unity
+    return result if isinstance(result, dict) else {"success": False, "message": str(result)}