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

services/tools/manage_material.py

@@ -2,18 +2,57 @@
 Defines the manage_material tool for interacting with Unity materials.
 """
 import json
-from typing import Annotated, Any, Literal, Union
+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
+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
 
 
+def _normalize_color(value: Any) -> tuple[list[float] | None, str | None]:
+    """
+    Normalize color parameter to [r, g, b] or [r, g, b, a] format.
+    Returns (parsed_color, error_message).
+    """
+    if value is None:
+        return None, None
+
+    # Already a list - validate
+    if isinstance(value, (list, tuple)):
+        if len(value) in (3, 4):
+            try:
+                return [float(c) for c in value], None
+            except (ValueError, TypeError):
+                return None, f"color values must be numbers, got {value}"
+        return None, f"color must have 3 or 4 components, got {len(value)}"
+
+    # Try parsing as string
+    if isinstance(value, str):
+        if value in ("[object Object]", "undefined", "null", ""):
+            return None, f"color received invalid value: '{value}'. Expected [r, g, b] or [r, g, b, a]"
+
+        parsed = parse_json_payload(value)
+        if isinstance(parsed, (list, tuple)) and len(parsed) in (3, 4):
+            try:
+                return [float(c) for c in parsed], None
+            except (ValueError, TypeError):
+                return None, f"color values must be numbers, got {parsed}"
+        return None, f"Failed to parse color string: {value}"
+
+    return None, f"color must be a list or JSON string, got {type(value).__name__}"
+
+
 @mcp_for_unity_tool(
-    description="Manages Unity materials (set properties, colors, shaders, etc)."
+    description="Manages Unity materials (set properties, colors, shaders, etc). Read-only actions: ping, get_material_info. Modifying actions: create, set_material_shader_property, set_material_color, assign_material_to_renderer, set_renderer_color.",
+    annotations=ToolAnnotations(
+        title="Manage Material",
+        destructiveHint=True,
+    ),
 )
 async def manage_material(
     ctx: Context,
@@ -26,45 +65,55 @@ async def manage_material(
         "set_renderer_color",
         "get_material_info"
     ], "Action to perform."],
-    
+
     # Common / Shared
-    material_path: Annotated[str, "Path to material asset (Assets/...)"] | None = None,
-    property: Annotated[str, "Shader property name (e.g., _BaseColor, _MainTex)"] | None = None,
+    material_path: Annotated[str,
+                             "Path to material asset (Assets/...)"] | None = None,
+    property: Annotated[str,
+                        "Shader property name (e.g., _BaseColor, _MainTex)"] | None = None,
 
     # create
     shader: Annotated[str, "Shader name (default: Standard)"] | None = None,
-    properties: Annotated[Union[dict[str, Any], str], "Initial properties to set {name: value}."] | None = None,
-    
+    properties: Annotated[dict[str, Any],
+                          "Initial properties to set as {name: value} dict."] | None = None,
+
     # set_material_shader_property
-    value: Annotated[Union[list, float, int, str, bool, None], "Value to set (color array, float, texture path/instruction)"] | None = None,
-    
+    value: Annotated[list | float | int | str | bool | None,
+                     "Value to set (color array, float, texture path/instruction)"] | None = None,
+
     # set_material_color / set_renderer_color
-    color: Annotated[Union[list[float], list[int], str], "Color as [r,g,b] or [r,g,b,a]."] | None = None,
-    
+    color: Annotated[list[float],
+                     "Color as [r, g, b] or [r, g, b, a] array."] | None = None,
+
     # assign_material_to_renderer / set_renderer_color
-    target: Annotated[str, "Target GameObject (name, path, or find instruction)"] | None = None,
-    search_method: Annotated[Literal["by_name", "by_path", "by_tag", "by_layer", "by_component"], "Search method for target"] | None = None,
-    slot: Annotated[int | str, "Material slot index"] | None = None,
-    mode: Annotated[Literal["shared", "instance", "property_block"], "Assignment/modification mode"] | None = None,
-    
+    target: Annotated[str,
+                      "Target GameObject (name, path, or find instruction)"] | None = None,
+    search_method: Annotated[Literal["by_name", "by_path", "by_tag",
+                                     "by_layer", "by_component"], "Search method for target"] | None = None,
+    slot: Annotated[int, "Material slot index (0-based)"] | None = None,
+    mode: Annotated[Literal["shared", "instance", "property_block"],
+                    "Assignment/modification mode"] | None = None,
+
 ) -> dict[str, Any]:
     unity_instance = get_unity_instance_from_context(ctx)
 
-    # Parse inputs that might be stringified JSON
-    color = parse_json_payload(color)
-    properties = parse_json_payload(properties)
+    # --- Normalize color with validation ---
+    color, color_error = _normalize_color(color)
+    if color_error:
+        return {"success": False, "message": color_error}
+
+    # --- Normalize properties with validation ---
+    properties, props_error = normalize_properties(properties)
+    if props_error:
+        return {"success": False, "message": props_error}
+
+    # --- Normalize value (parse JSON if string) ---
     value = parse_json_payload(value)
+    if isinstance(value, str) and value in ("[object Object]", "undefined"):
+        return {"success": False, "message": f"value received invalid input: '{value}'"}
 
-    # Coerce slot to int if it's a string
-    if slot is not None:
-        if isinstance(slot, str):
-            try:
-                slot = int(slot)
-            except ValueError:
-                return {
-                    "success": False,
-                    "message": f"Invalid slot value: '{slot}' must be a valid integer"
-                }
+    # --- Normalize slot to int ---
+    slot = coerce_int(slot)
 
     # Prepare parameters for the C# handler
     params_dict = {
@@ -91,5 +140,5 @@ async def manage_material(
         "manage_material",
         params_dict,
     )
-    
+
     return result if isinstance(result, dict) else {"success": False, "message": str(result)}

services/tools/manage_prefabs.py

@@ -1,6 +1,8 @@
 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
@@ -9,7 +11,11 @@ from services.tools.utils import coerce_bool
 
 
 @mcp_for_unity_tool(
-    description="Performs prefab operations (open_stage, close_stage, save_open_stage, create_from_gameobject)."
+    description="Performs prefab operations (open_stage, close_stage, save_open_stage, create_from_gameobject).",
+    annotations=ToolAnnotations(
+        title="Manage Prefabs",
+        destructiveHint=True,
+    ),
 )
 async def manage_prefabs(
     ctx: Context,

services/tools/manage_scene.py

@@ -1,6 +1,8 @@
 from typing import Annotated, Literal, Any
 
 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
@@ -10,7 +12,11 @@ from services.tools.preflight import preflight
 
 
 @mcp_for_unity_tool(
-    description="Performs CRUD operations on Unity scenes."
+    description="Performs CRUD operations on Unity scenes. Read-only actions: get_hierarchy, get_active, get_build_settings, screenshot. Modifying actions: create, load, save.",
+    annotations=ToolAnnotations(
+        title="Manage Scene",
+        destructiveHint=True,
+    ),
 )
 async def manage_scene(
     ctx: Context,
@@ -27,16 +33,25 @@ async def manage_scene(
     path: Annotated[str, "Scene path."] | None = None,
     build_index: Annotated[int | str,
                            "Unity build index (quote as string, e.g., '0')."] | None = None,
-    screenshot_file_name: Annotated[str, "Screenshot file name (optional). Defaults to timestamp when omitted."] | None = None,
-    screenshot_super_size: Annotated[int | str, "Screenshot supersize multiplier (integer ≥1). Optional." ] | None = None,
+    screenshot_file_name: Annotated[str,
+                                    "Screenshot file name (optional). Defaults to timestamp when omitted."] | None = None,
+    screenshot_super_size: Annotated[int | str,
+                                     "Screenshot supersize multiplier (integer ≥1). Optional."] | None = None,
     # --- get_hierarchy paging/safety ---
-    parent: Annotated[str | int, "Optional parent GameObject reference (name/path/instanceID) to list direct children."] | None = None,
-    page_size: Annotated[int | str, "Page size for get_hierarchy paging."] | None = None,
-    cursor: Annotated[int | str, "Opaque cursor for paging (offset)."] | None = None,
-    max_nodes: Annotated[int | str, "Hard cap on returned nodes per request (safety)."] | None = None,
-    max_depth: Annotated[int | str, "Accepted for forward-compatibility; current paging returns a single level."] | None = None,
-    max_children_per_node: Annotated[int | str, "Child paging hint (safety)."] | None = None,
-    include_transform: Annotated[bool | str, "If true, include local transform in node summaries."] | None = None,
+    parent: Annotated[str | int,
+                      "Optional parent GameObject reference (name/path/instanceID) to list direct children."] | None = None,
+    page_size: Annotated[int | str,
+                         "Page size for get_hierarchy paging."] | None = None,
+    cursor: Annotated[int | str,
+                      "Opaque cursor for paging (offset)."] | None = None,
+    max_nodes: Annotated[int | str,
+                         "Hard cap on returned nodes per request (safety)."] | None = None,
+    max_depth: Annotated[int | str,
+                         "Accepted for forward-compatibility; current paging returns a single level."] | None = None,
+    max_children_per_node: Annotated[int | str,
+                                     "Child paging hint (safety)."] | None = None,
+    include_transform: Annotated[bool | str,
+                                 "If true, include local transform in node summaries."] | None = None,
 ) -> dict[str, Any]:
     # Get active instance from session state
     # Removed session_state import
@@ -51,8 +66,10 @@ async def manage_scene(
         coerced_cursor = coerce_int(cursor, default=None)
         coerced_max_nodes = coerce_int(max_nodes, default=None)
         coerced_max_depth = coerce_int(max_depth, default=None)
-        coerced_max_children_per_node = coerce_int(max_children_per_node, default=None)
-        coerced_include_transform = coerce_bool(include_transform, default=None)
+        coerced_max_children_per_node = coerce_int(
+            max_children_per_node, default=None)
+        coerced_include_transform = coerce_bool(
+            include_transform, default=None)
 
         params: dict[str, Any] = {"action": action}
         if name:
@@ -65,7 +82,7 @@ async def manage_scene(
             params["fileName"] = screenshot_file_name
         if coerced_super_size is not None:
             params["superSize"] = coerced_super_size
-        
+
         # get_hierarchy paging/safety params (optional)
         if parent is not None:
             params["parent"] = parent

services/tools/manage_script.py

@@ -4,6 +4,7 @@ from typing import Annotated, Any, Literal
 from urllib.parse import urlparse, unquote
 
 from fastmcp import FastMCP, Context
+from mcp.types import ToolAnnotations
 
 from services.registry import mcp_for_unity_tool
 from services.tools import get_unity_instance_from_context
@@ -15,7 +16,7 @@ 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)
+    - 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.
@@ -23,8 +24,8 @@ def _split_uri(uri: str) -> tuple[str, str]:
         return relative to 'Assets'.
     """
     raw_path: str
-    if uri.startswith("unity://path/"):
-        raw_path = uri[len("unity://path/"):]
+    if uri.startswith("mcpforunity://path/"):
+        raw_path = uri[len("mcpforunity://path/"):]
     elif uri.startswith("file://"):
         parsed = urlparse(uri)
         host = (parsed.netloc or "").strip()
@@ -63,8 +64,9 @@ def _split_uri(uri: str) -> tuple[str, str]:
     return name, directory
 
 
-@mcp_for_unity_tool(description=(
-    """Apply small text edits to a C# script identified by URI.
+@mcp_for_unity_tool(
+    description=(
+        """Apply small text edits to a C# script identified by URI.
     IMPORTANT: This tool replaces EXACT character positions. Always verify content at target lines/columns BEFORE editing!
     RECOMMENDED WORKFLOW:
         1. First call resources/read with start_line/line_count to verify exact content
@@ -76,10 +78,15 @@ def _split_uri(uri: str) -> tuple[str, str]:
         - For pattern-based replacements, consider anchor operations in script_apply_edits
         - Lines, columns are 1-indexed
         - Tabs count as 1 column"""
-))
+    ),
+    annotations=ToolAnnotations(
+        title="Apply Text Edits",
+        destructiveHint=True,
+    ),
+)
 async def apply_text_edits(
     ctx: Context,
-    uri: Annotated[str, "URI of the script to edit under Assets/ directory, unity://path/Assets/... or file://... or Assets/..."],
+    uri: Annotated[str, "URI of the script to edit under Assets/ directory, mcpforunity://path/Assets/... or file://... or Assets/..."],
     edits: Annotated[list[dict[str, Any]], "List of edits to apply to the script, i.e. a list of {startLine,startCol,endLine,endCol,newText} (1-indexed!)"],
     precondition_sha256: Annotated[str,
                                    "Optional SHA256 of the script to edit, used to prevent concurrent edits"] | None = None,
@@ -367,7 +374,13 @@ async def apply_text_edits(
     return {"success": False, "message": str(resp)}
 
 
-@mcp_for_unity_tool(description=("Create a new C# script at the given project path."))
+@mcp_for_unity_tool(
+    description="Create a new C# script at the given project path.",
+    annotations=ToolAnnotations(
+        title="Create Script",
+        destructiveHint=True,
+    ),
+)
 async def create_script(
     ctx: Context,
     path: Annotated[str, "Path under Assets/ to create the script at, e.g., 'Assets/Scripts/My.cs'"],
@@ -412,10 +425,16 @@ async def create_script(
     return resp if isinstance(resp, dict) else {"success": False, "message": str(resp)}
 
 
-@mcp_for_unity_tool(description=("Delete a C# script by URI or Assets-relative path."))
+@mcp_for_unity_tool(
+    description="Delete a C# script by URI or Assets-relative path.",
+    annotations=ToolAnnotations(
+        title="Delete Script",
+        destructiveHint=True,
+    ),
+)
 async def delete_script(
     ctx: Context,
-    uri: Annotated[str, "URI of the script to delete under Assets/ directory, unity://path/Assets/... or file://... or Assets/..."],
+    uri: Annotated[str, "URI of the script to delete under Assets/ directory, mcpforunity://path/Assets/... or file://... or Assets/..."],
 ) -> dict[str, Any]:
     """Delete a C# script by URI."""
     unity_instance = get_unity_instance_from_context(ctx)
@@ -434,10 +453,16 @@ async def delete_script(
     return resp if isinstance(resp, dict) else {"success": False, "message": str(resp)}
 
 
-@mcp_for_unity_tool(description=("Validate a C# script and return diagnostics."))
+@mcp_for_unity_tool(
+    description="Validate a C# script and return diagnostics.",
+    annotations=ToolAnnotations(
+        title="Validate Script",
+        readOnlyHint=True,
+    ),
+)
 async def validate_script(
     ctx: Context,
-    uri: Annotated[str, "URI of the script to validate under Assets/ directory, unity://path/Assets/... or file://... or Assets/..."],
+    uri: Annotated[str, "URI of the script to validate under Assets/ directory, mcpforunity://path/Assets/... or file://... or Assets/..."],
     level: Annotated[Literal['basic', 'standard'],
                      "Validation level"] = "basic",
     include_diagnostics: Annotated[bool,
@@ -475,14 +500,20 @@ async def validate_script(
     return resp if isinstance(resp, dict) else {"success": False, "message": str(resp)}
 
 
-@mcp_for_unity_tool(description=("Compatibility router for legacy script operations. Prefer apply_text_edits (ranges) or script_apply_edits (structured) for edits."))
+@mcp_for_unity_tool(
+    description="Compatibility router for legacy script operations. Prefer apply_text_edits (ranges) or script_apply_edits (structured) for edits. Read-only action: read. Modifying actions: create, delete.",
+    annotations=ToolAnnotations(
+        title="Manage Script",
+        destructiveHint=True,
+    ),
+)
 async def manage_script(
     ctx: Context,
     action: Annotated[Literal['create', 'read', 'delete'], "Perform CRUD operations on C# scripts."],
     name: Annotated[str, "Script name (no .cs extension)", "Name of the script to create"],
     path: Annotated[str, "Asset path (default: 'Assets/')", "Path under Assets/ to create the script at, e.g., 'Assets/Scripts/My.cs'"],
     contents: Annotated[str, "Contents of the script to create",
-                        "C# code for 'create'/'update'"] | None = None,
+                        "C# code for 'create' action"] | None = None,
     script_type: Annotated[str, "Script type (e.g., 'C#')",
                            "Type hint (e.g., 'MonoBehaviour')"] | None = None,
     namespace: Annotated[str, "Namespace for the script"] | None = None,
@@ -543,14 +574,20 @@ async def manage_script(
         }
 
 
-@mcp_for_unity_tool(description=(
-    """Get manage_script capabilities (supported ops, limits, and guards).
+@mcp_for_unity_tool(
+    description=(
+        """Get manage_script capabilities (supported ops, limits, and guards).
     Returns:
         - ops: list of supported structured ops
         - text_ops: list of supported text ops
         - max_edit_payload_bytes: server edit payload cap
         - guards: header/using guard enabled flag"""
-))
+    ),
+    annotations=ToolAnnotations(
+        title="Manage Script Capabilities",
+        readOnlyHint=True,
+    ),
+)
 async def manage_script_capabilities(ctx: Context) -> dict[str, Any]:
     await ctx.info("Processing manage_script_capabilities")
     try:
@@ -575,10 +612,16 @@ async def manage_script_capabilities(ctx: Context) -> dict[str, Any]:
         return {"success": False, "error": f"capabilities error: {e}"}
 
 
-@mcp_for_unity_tool(description="Get SHA256 and basic metadata for a Unity C# script without returning file contents")
+@mcp_for_unity_tool(
+    description="Get SHA256 and basic metadata for a Unity C# script without returning file contents",
+    annotations=ToolAnnotations(
+        title="Get SHA",
+        readOnlyHint=True,
+    ),
+)
 async def get_sha(
     ctx: Context,
-    uri: Annotated[str, "URI of the script to edit under Assets/ directory, unity://path/Assets/... or file://... or Assets/..."],
+    uri: Annotated[str, "URI of the script to edit under Assets/ directory, mcpforunity://path/Assets/... or file://... or Assets/..."],
 ) -> dict[str, Any]:
     unity_instance = get_unity_instance_from_context(ctx)
     await ctx.info(

services/tools/manage_scriptable_object.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 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
@@ -22,20 +23,33 @@ from transport.legacy.unity_connection import async_send_command_with_retry
 
 
 @mcp_for_unity_tool(
-    description="Creates and modifies ScriptableObject assets using Unity SerializedObject property paths."
+    description="Creates and modifies ScriptableObject assets using Unity SerializedObject property paths.",
+    annotations=ToolAnnotations(
+        title="Manage Scriptable Object",
+        destructiveHint=True,
+    ),
 )
 async def manage_scriptable_object(
     ctx: Context,
     action: Annotated[Literal["create", "modify"], "Action to perform: create or modify."],
     # --- create params ---
-    type_name: Annotated[str | None, "Namespace-qualified ScriptableObject type name (for create)."] = None,
-    folder_path: Annotated[str | None, "Target folder under Assets/... (for create)."] = None,
-    asset_name: Annotated[str | None, "Asset file name without extension (for create)."] = None,
-    overwrite: Annotated[bool | str | None, "If true, overwrite existing asset at same path (for create)."] = None,
+    type_name: Annotated[str | None,
+                         "Namespace-qualified ScriptableObject type name (for create)."] = None,
+    folder_path: Annotated[str | None,
+                           "Target folder under Assets/... (for create)."] = None,
+    asset_name: Annotated[str | None,
+                          "Asset file name without extension (for create)."] = None,
+    overwrite: Annotated[bool | str | None,
+                         "If true, overwrite existing asset at same path (for create)."] = None,
     # --- modify params ---
-    target: Annotated[dict[str, Any] | str | None, "Target asset reference {guid|path} (for modify)."] = None,
+    target: Annotated[dict[str, Any] | str | None,
+                      "Target asset reference {guid|path} (for modify)."] = None,
     # --- shared ---
-    patches: Annotated[list[dict[str, Any]] | str | None, "Patch list (or JSON string) to apply."] = None,
+    patches: Annotated[list[dict[str, Any]] | str | None,
+                       "Patch list (or JSON string) to apply."] = None,
+    # --- validation ---
+    dry_run: Annotated[bool | str | None,
+                       "If true, validate patches without applying (modify only)."] = None,
 ) -> dict[str, Any]:
     unity_instance = get_unity_instance_from_context(ctx)
 
@@ -57,6 +71,7 @@ async def manage_scriptable_object(
         "overwrite": coerce_bool(overwrite, default=None),
         "target": parsed_target,
         "patches": parsed_patches,
+        "dryRun": coerce_bool(dry_run, default=None),
     }
 
     # Remove None values to keep Unity handler simpler
@@ -70,6 +85,3 @@ async def manage_scriptable_object(
     )
     await ctx.info(f"Response {response}")
     return response if isinstance(response, dict) else {"success": False, "message": "Unexpected response from Unity."}
-
-
-

services/tools/manage_shader.py

@@ -2,6 +2,8 @@ import base64
 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
@@ -9,7 +11,12 @@ from transport.legacy.unity_connection import async_send_command_with_retry
 
 
 @mcp_for_unity_tool(
-    description="Manages shader scripts in Unity (create, read, update, delete)."
+    description="Manages shader scripts in Unity (create, read, update, delete). Read-only action: read. Modifying actions: create, update, delete.",
+    annotations=ToolAnnotations(
+        title="Manage Shader",
+        # Note: 'read' action is non-destructive; 'create', 'update', 'delete' are destructive
+        destructiveHint=True,
+    ),
 )
 async def manage_shader(
     ctx: Context,