mcpforunityserver 8.2.3__py3-none-any.whl

services/tools/execute_custom_tool.py

@@ -0,0 +1,38 @@
+from fastmcp import Context
+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.",
+)
+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 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.",
+        )
+
+    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,29 @@
+"""
+Defines the execute_menu_item tool for executing and reading Unity Editor menu items.
+"""
+from typing import Annotated, Any
+
+from fastmcp import Context
+
+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."
+)
+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:
+    # Get active instance from session state
+    # Removed session_state import
+    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_in_file.py

@@ -0,0 +1,174 @@
+import base64
+import os
+import re
+from typing import Annotated, Any
+from urllib.parse import unquote, urlparse
+
+from fastmcp import Context
+
+from services.registry import mcp_for_unity_tool
+from services.tools import get_unity_instance_from_context
+from transport.unity_transport import send_with_unity_instance
+from transport.legacy.unity_connection import async_send_command_with_retry
+
+
+def _split_uri(uri: str) -> tuple[str, str]:
+    """Split an incoming URI or path into (name, directory) suitable for Unity.
+
+    Rules:
+    - unity://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("unity://path/"):
+        raw_path = uri[len("unity://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.")
+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,129 @@
+"""
+Defines the manage_asset tool for interacting with Unity assets.
+"""
+import ast
+import asyncio
+import json
+from typing import Annotated, Any, Literal
+
+from fastmcp import Context
+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
+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="Performs asset operations (import, create, modify, delete, etc.) in Unity."
+)
+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."],
+    asset_type: Annotated[str,
+                          "Asset type (e.g., 'Material', 'Folder') - required for 'create'."] | None = None,
+    properties: Annotated[dict[str, Any] | str,
+                          "Dictionary (or JSON string) of properties for 'create'/'modify'."] | 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."] = False,
+    search_pattern: Annotated[str,
+                              "Search pattern (e.g., '*.prefab')."] | 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"] | None = None,
+    page_number: Annotated[int | float | str,
+                           "Page number for pagination"] | None = None,
+) -> dict[str, Any]:
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    def _parse_properties_string(raw: str) -> tuple[dict[str, Any] | None, str | None]:
+        try:
+            parsed = json.loads(raw)
+            if not isinstance(parsed, dict):
+                return None, f"manage_asset: properties JSON must decode to a dictionary; received {type(parsed)}"
+            return parsed, "JSON"
+        except json.JSONDecodeError as json_err:
+            try:
+                parsed = ast.literal_eval(raw)
+                if not isinstance(parsed, dict):
+                    return None, f"manage_asset: properties string must evaluate to a dictionary; received {type(parsed)}"
+                return parsed, "Python literal"
+            except (ValueError, SyntaxError) as literal_err:
+                return None, f"manage_asset: failed to parse properties string. JSON error: {json_err}; literal_eval error: {literal_err}"
+
+    async def _normalize_properties(raw: dict[str, Any] | str | None) -> tuple[dict[str, Any] | None, str | None]:
+        if raw is None:
+            return {}, None
+        if isinstance(raw, dict):
+            await ctx.info(f"manage_asset: received properties as dict with keys: {list(raw.keys())}")
+            return raw, None
+        if isinstance(raw, str):
+            await ctx.info(f"manage_asset: received properties as string (first 100 chars): {raw[:100]}")
+            # Try our robust centralized parser first, then fallback to ast.literal_eval specific to manage_asset if needed
+            parsed = parse_json_payload(raw)
+            if isinstance(parsed, dict):
+                 await ctx.info("manage_asset: coerced properties using centralized parser")
+                 return parsed, None
+
+            # Fallback to original logic for ast.literal_eval which parse_json_payload avoids for safety/simplicity
+            parsed, source = _parse_properties_string(raw)
+            if parsed is None:
+                return None, source
+            await ctx.info(f"manage_asset: coerced properties from {source} string to dict")
+            return parsed, None
+        return None, f"manage_asset: properties must be a dict or JSON string; received {type(raw)}"
+
+    properties, parse_error = await _normalize_properties(properties)
+    if parse_error:
+        await ctx.error(parse_error)
+        return {"success": False, "message": parse_error}
+
+    # Coerce numeric inputs defensively
+    def _coerce_int(value, default=None):
+        if value is None:
+            return default
+        try:
+            if isinstance(value, bool):
+                return default
+            if isinstance(value, int):
+                return int(value)
+            s = str(value).strip()
+            if s.lower() in ("", "none", "null"):
+                return default
+            return int(float(s))
+        except Exception:
+            return default
+
+    page_size = _coerce_int(page_size)
+    page_number = _coerce_int(page_number)
+
+    # 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)}

services/tools/manage_editor.py

@@ -0,0 +1,63 @@
+from typing import Annotated, Any, Literal
+
+from fastmcp import Context
+from services.registry import mcp_for_unity_tool
+from core.telemetry import is_telemetry_enabled, record_tool_usage
+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
+
+
+@mcp_for_unity_tool(
+    description="Controls and queries the Unity editor's state and settings. Tip: pass booleans as true/false; if your client only sends strings, 'true'/'false' are accepted."
+)
+async def manage_editor(
+    ctx: Context,
+    action: Annotated[Literal["telemetry_status", "telemetry_ping", "play", "pause", "stop", "set_active_tool", "add_tag", "remove_tag", "add_layer", "remove_layer"], "Get and update the Unity Editor state."],
+    wait_for_completion: Annotated[bool | str,
+                                   "Optional. If True, waits for certain actions (accepts true/false or 'true'/'false')"] | None = None,
+    tool_name: Annotated[str,
+                         "Tool name when setting active tool"] | None = None,
+    tag_name: Annotated[str,
+                        "Tag name when adding and removing tags"] | None = None,
+    layer_name: Annotated[str,
+                          "Layer name when adding and removing layers"] | None = None,
+) -> dict[str, Any]:
+    # Get active instance from request state (injected by middleware)
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    wait_for_completion = coerce_bool(wait_for_completion)
+
+    try:
+        # Diagnostics: quick telemetry checks
+        if action == "telemetry_status":
+            return {"success": True, "telemetry_enabled": is_telemetry_enabled()}
+
+        if action == "telemetry_ping":
+            record_tool_usage("diagnostic_ping", True, 1.0, None)
+            return {"success": True, "message": "telemetry ping queued"}
+        # Prepare parameters, removing None values
+        params = {
+            "action": action,
+            "waitForCompletion": wait_for_completion,
+            "toolName": tool_name,  # Corrected parameter name to match C#
+            "tagName": tag_name,   # Pass tag name
+            "layerName": layer_name,  # Pass layer name
+            # Add other parameters based on the action being performed
+            # "width": width,
+            # "height": height,
+            # etc.
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+
+        # Send command using centralized retry helper with instance routing
+        response = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "manage_editor", params)
+
+        # Preserve structured failure data; unwrap success into a friendlier shape
+        if isinstance(response, dict) and response.get("success"):
+            return {"success": True, "message": response.get("message", "Editor operation successful."), "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"Python error managing editor: {str(e)}"}