mcpforunityserver 8.2.3__py3-none-any.whl → 8.5.0__py3-none-any.whl

main.py

@@ -8,6 +8,32 @@ import time
 from typing import AsyncIterator, Any
 from urllib.parse import urlparse
 
+# Workaround for environments where tool signature evaluation runs with a globals
+# dict that does not include common `typing` names (e.g. when annotations are strings
+# and evaluated via `eval()` during schema generation).
+# Making these names available in builtins avoids `NameError: Annotated/Literal/... is not defined`.
+try:  # pragma: no cover - startup safety guard
+    import builtins
+    import typing as _typing
+
+    _typing_names = (
+        "Annotated",
+        "Literal",
+        "Any",
+        "Union",
+        "Optional",
+        "Dict",
+        "List",
+        "Tuple",
+        "Set",
+        "FrozenSet",
+    )
+    for _name in _typing_names:
+        if not hasattr(builtins, _name) and hasattr(_typing, _name):
+            setattr(builtins, _name, getattr(_typing, _name))  # type: ignore[attr-defined]
+except Exception:
+    pass
+
 from fastmcp import FastMCP
 from logging.handlers import RotatingFileHandler
 from starlette.requests import Request
@@ -242,6 +268,18 @@ Console Monitoring:
 Menu Items:
 - Use `execute_menu_item` when you have read the menu items resource
 - This lets you interact with Unity's menu system and third-party tools
+
+Payload sizing & paging (important):
+- Many Unity queries can return very large JSON. Prefer **paged + summary-first** calls.
+- `manage_scene(action="get_hierarchy")`:
+  - Use `page_size` + `cursor` and follow `next_cursor` until null.
+  - `page_size` is **items per page**; recommended starting point: **50**.
+- `manage_gameobject(action="get_components")`:
+  - Start with `include_properties=false` (metadata-only) and small `page_size` (e.g. **10-25**).
+  - Only request `include_properties=true` when needed; keep `page_size` small (e.g. **3-10**) to bound payloads.
+- `manage_asset(action="search")`:
+  - Use paging (`page_size`, `page_number`) and keep `page_size` modest (e.g. **25-50**) to avoid token-heavy responses.
+  - Keep `generate_preview=false` unless you explicitly need thumbnails (previews may include large base64 payloads).
 """
 )
 

{mcpforunityserver-8.2.3.dist-info → mcpforunityserver-8.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpforunityserver
-Version: 8.2.3
+Version: 8.5.0
 Summary: MCP for Unity Server: A Unity package for Unity Editor integration via the Model Context Protocol (MCP).
 Author-email: Marcus Sanatan <msanatan@gmail.com>, David Sarno <david.sarno@gmail.com>, Wu Shutong <martinwfire@gmail.com>
 License-Expression: MIT
@@ -26,9 +26,9 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx>=0.27.2
-Requires-Dist: fastmcp<2.13.2,>=2.13.0
+Requires-Dist: fastmcp==2.14.1
 Requires-Dist: mcp>=1.16.0
-Requires-Dist: pydantic>=2.12.0
+Requires-Dist: pydantic>=2.12.5
 Requires-Dist: tomli>=2.3.0
 Requires-Dist: fastapi>=0.104.0
 Requires-Dist: uvicorn>=0.35.0
@@ -50,24 +50,20 @@ Model Context Protocol server for Unity Editor integration. Control Unity throug
 
 💬 **Join our community:** [Discord Server](https://discord.gg/y4p8KfzrN4)
 
-**Required:** Install the [Unity MCP Plugin](https://github.com/CoplayDev/unity-mcp?tab=readme-ov-file#-step-1-install-the-unity-package) to connect Unity Editor with this MCP server.
+**Required:** Install the [Unity MCP Plugin](https://github.com/CoplayDev/unity-mcp?tab=readme-ov-file#-step-1-install-the-unity-package) to connect Unity Editor with this MCP server. You also need `uvx` (requires [uv](https://docs.astral.sh/uv/)) to run the server.
 
 ---
 
 ## Installation
 
-### Option 1: Using uvx (Recommended)
+### Option 1: PyPI
 
-Run directly from GitHub without installation:
+Install and run directly from PyPI using `uvx`.
 
-```bash
-# HTTP (default)
-uvx --from git+https://github.com/CoplayDev/unity-mcp@v8.2.3#subdirectory=Server \
-    mcp-for-unity --transport http --http-url http://localhost:8080
+**Run Server (HTTP):**
 
-# Stdio
-uvx --from git+https://github.com/CoplayDev/unity-mcp@v8.2.3#subdirectory=Server \
-    mcp-for-unity --transport stdio
+```bash
+uvx --from mcpforunityserver mcp-for-unity --transport http --http-url http://localhost:8080
 ```
 
 **MCP Client Configuration (HTTP):**
@@ -91,55 +87,29 @@ uvx --from git+https://github.com/CoplayDev/unity-mcp@v8.2.3#subdirectory=Server
       "command": "uvx",
       "args": [
         "--from",
-        "git+https://github.com/CoplayDev/unity-mcp@v8.2.3#subdirectory=Server",
+        "mcpforunityserver",
         "mcp-for-unity",
         "--transport",
         "stdio"
-      ],
-      "type": "stdio"
+      ]
     }
   }
 }
 ```
 
-### Option 2: Using uv (Local Installation)
-
-For local development or custom installations:
-
-```bash
-# Clone the repository
-git clone https://github.com/CoplayDev/unity-mcp.git
-cd unity-mcp/Server
-
-# Run with uv (HTTP)
-uv run server.py --transport http --http-url http://localhost:8080
-
-# Run with uv (stdio)
-uv run server.py --transport stdio
-```
+### Option 2: From GitHub Source
 
-**MCP Client Configuration (HTTP):**
-```json
-{
-  "mcpServers": {
-    "UnityMCP": {
-      "url": "http://localhost:8080/mcp"
-    }
-  }
-}
-```
+Use this to run the latest released version from the repository. Change the version to `main` to run the latest unreleased changes from the repository.
 
-**MCP Client Configuration (stdio – Windows):**
 ```json
 {
   "mcpServers": {
     "UnityMCP": {
-      "command": "uv",
+      "command": "uvx",
       "args": [
-        "run",
-        "--directory",
-        "C:\\path\\to\\unity-mcp\\Server",
-        "server.py",
+        "--from",
+        "git+https://github.com/CoplayDev/unity-mcp@v8.5.0#subdirectory=Server",
+        "mcp-for-unity",
         "--transport",
         "stdio"
       ]
@@ -148,33 +118,35 @@ uv run server.py --transport stdio
 }
 ```
 
-**MCP Client Configuration (stdio – macOS/Linux):**
-```json
-{
-  "mcpServers": {
-    "UnityMCP": {
-      "command": "uv",
-      "args": [
-        "run",
-        "--directory",
-        "/path/to/unity-mcp/Server",
-        "server.py",
-        "--transport",
-        "stdio"
-      ]
-    }
-  }
-}
+### Option 3: Docker
+
+**Use Pre-built Image:**
+
+```bash
+docker run -p 8080:8080 msanatan/mcp-for-unity-server:latest --transport http --http-url http://0.0.0.0:8080
 ```
 
-### Option 3: Using Docker
+**Build Locally:**
 
 ```bash
 docker build -t unity-mcp-server .
 docker run -p 8080:8080 unity-mcp-server --transport http --http-url http://0.0.0.0:8080
 ```
 
-Configure your MCP client with `"url": "http://localhost:8080/mcp"`. For stdio-in-docker (rare), run the container with `--transport stdio` and use the same `command`/`args` pattern as the uv examples, wrapping it in `docker run -i ...` if needed.
+Configure your MCP client with `"url": "http://localhost:8080/mcp"`.
+
+### Option 4: Local Development
+
+For contributing or modifying the server code:
+
+```bash
+# Clone the repository
+git clone https://github.com/CoplayDev/unity-mcp.git
+cd unity-mcp/Server
+
+# Run with uv
+uv run src/main.py --transport stdio
+```
 
 ---
 

{mcpforunityserver-8.2.3.dist-info → mcpforunityserver-8.5.0.dist-info}/RECORD

@@ -1,11 +1,11 @@
 __init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-main.py,sha256=bjQfzp3c9rAe9TtDr1009ARZ6ULWBPxEBopCRmRyXc8,16316
+main.py,sha256=OH_Ux5Aj43q1lXPu4AS8zafRnFHZWFYCDZbswReQOac,18011
 core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 core/config.py,sha256=czkTtNji1crQcQbUvmdx4OL7f-RBqkVhj_PtHh-w7rs,1623
 core/logging_decorator.py,sha256=D9CD7rFvQz-MBG-G4inizQj0Ivr6dfc9RBmTrw7q8mI,1383
 core/telemetry.py,sha256=eHjYgzd8f7eTwSwF2Kbi8D4TtJIcdaDjKLeo1c-0hVA,19829
 core/telemetry_decorator.py,sha256=ycSTrzVNCDQHSd-xmIWOpVfKFURPxpiZe_XkOQAGDAo,6705
-mcpforunityserver-8.2.3.dist-info/licenses/LICENSE,sha256=bv5lDJZQEqxBgjjc1rkRbkEwpSIHF-8N-1Od0VnEJFw,1066
+mcpforunityserver-8.5.0.dist-info/licenses/LICENSE,sha256=bv5lDJZQEqxBgjjc1rkRbkEwpSIHF-8N-1Od0VnEJFw,1066
 models/__init__.py,sha256=JlscZkGWE9TRmSoBi99v_LSl8OAFNGmr8463PYkXin4,179
 models/models.py,sha256=heXuvdBtdats1SGwW8wKFFHM0qR4hA6A7qETn5s9BZ0,1827
 models/unity_response.py,sha256=oJ1PTsnNc5VBC-9OgM59C0C-R9N-GdmEdmz_yph4GSU,1454
@@ -30,23 +30,24 @@ services/resources/unity_instances.py,sha256=fR0cVopGQnmF41IFDycwlo2XniKstfJWLGo
 services/resources/windows.py,sha256=--QVsb0oyoBpSjK2D4kPcZFSe2zdR-t_KSHP-e2QNoY,1427
 services/tools/__init__.py,sha256=3Qav7fAowZ1_TbDRdZQQQES53gv2lTs-2D7PGECnlbM,2353
 services/tools/batch_execute.py,sha256=_ByjffeXQB9j64mcjaxJmrnbSJrMn0f9_6Zh9BBI_2c,2898
-services/tools/debug_request_context.py,sha256=pk02OGfa_yuc4SWxzTR6lEBo0R4ls2yFXp7sdIVshDM,2531
+services/tools/debug_request_context.py,sha256=WQBtQdXSH5stw2MAwIM32H6jGwUVQOgU2r35VUWLlYo,2765
 services/tools/execute_custom_tool.py,sha256=K2qaO4-FTPz0_3j53hhDP9idjC002ugc8C03FtHGTbY,1376
 services/tools/execute_menu_item.py,sha256=FAC-1v_TwOcy6GSxkogDsVxeRtdap0DsPlIngf8uJdU,1184
 services/tools/find_in_file.py,sha256=xp80lqRN2cdZc3XGJWlCpeQEy6WnwyKOj2l5WiHNx0Q,6379
-services/tools/manage_asset.py,sha256=wvzdqgSKC3dhdLcFOgQj9thNYp16y8RJQNWu3PluDpg,6021
+services/tools/manage_asset.py,sha256=Kpqr82cmXH7wxXub3O0D8whksORSqn9nDRjskDe_A_w,7534
 services/tools/manage_editor.py,sha256=_HZRT-_hBakH0g6p7BpxTv3gWpxsaV6KNGRol-qknwo,3243
-services/tools/manage_gameobject.py,sha256=wGJayE8giHwtOkeNBvjWaN8ecEnBDgGTraJKvVRHSgM,13257
+services/tools/manage_gameobject.py,sha256=kYIouvt-iNUEsY0VIWp4FqagLjo7Up2TwKDhB4Nfxmo,14213
 services/tools/manage_material.py,sha256=wZB2H4orhL6wG9TTnmnk-Lj2Gj_zvg7koxW3t319BLU,3545
 services/tools/manage_prefabs.py,sha256=73XzznjFNOm1SazW_Y7l6uGIE7wosMpAIVQs8xpvK9A,3037
-services/tools/manage_scene.py,sha256=dw2ZkbEKCkLVIMA_KqAJmHXcAc9LJeo83GhhvYJZ0DQ,3192
+services/tools/manage_scene.py,sha256=3BhIsbbtGiMNqBMQMqEsB4ajYmtx-VwWl-krOkFR_Bw,4648
 services/tools/manage_script.py,sha256=lPA5HcS4Al0RiQVz-S6qahFTcPqsk3GSLLXJWHri8P4,27557
+services/tools/manage_scriptable_object.py,sha256=Oi03CJLgepaWR59V-nJiAjnCC8at4YqFhRGpACruqgw,3150
 services/tools/manage_shader.py,sha256=HHnHKh7vLij3p8FAinNsPdZGEKivgwSUTxdgDydfmbs,2882
-services/tools/read_console.py,sha256=JSqi2jSgEB5JUZbVripEjXoeEZC-r8rbG8zBprsnxNQ,4895
-services/tools/run_tests.py,sha256=Aga_yubZUuB_YnJNqBYJEq3nIV5z1u3YoyH4YvXCbuc,3780
+services/tools/read_console.py,sha256=gZWEf0Ru0hvN9oJUZqZ4w-mMBBLm5Z5KAUPv282XbYQ,4091
+services/tools/run_tests.py,sha256=LBVwGasLvmF4k1FiX3DdBQ8udh89WZJFiVHfJRWGvOs,3313
 services/tools/script_apply_edits.py,sha256=qPm_PsmsK3mYXnziX_btyk8CaB66LTqpDFA2Y4ebZ4U,47504
 services/tools/set_active_instance.py,sha256=B18Y8Jga0pKsx9mFywXr1tWfy0cJVopIMXYO-UJ1jOU,4136
-services/tools/utils.py,sha256=ILZN7bYb5nZvS-60t6rdTsX6OwDu7mlIN3AXXQsJ8H4,1917
+services/tools/utils.py,sha256=4ZgfIu178eXZqRyzs8X77B5lKLP1f73OZoGBSDNokJ4,2409
 transport/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 transport/models.py,sha256=6wp7wsmSaeeJEvUGXPF1m6zuJnxJ1NJlCC4YZ9oQIq0,1226
 transport/plugin_hub.py,sha256=55R00ohrmUI0mk_smc_8BsYTvrQMPX4wwsvqXprj0Vk,15596
@@ -58,8 +59,8 @@ transport/legacy/stdio_port_registry.py,sha256=j4iARuP6wetppNDG8qKeuvo1bJKcSlgEh
 transport/legacy/unity_connection.py,sha256=ujUX9WX7Gb-fxQveHts3uiepTPzFq8i7-XG7u5gSPuM,32668
 utils/module_discovery.py,sha256=My48ofB1BUqxiBoAZAGbEaLQYdsrDhMm8MayBP_bUSQ,2005
 utils/reload_sentinel.py,sha256=s1xMWhl-r2XwN0OUbiUv_VGUy8TvLtV5bkql-5n2DT0,373
-mcpforunityserver-8.2.3.dist-info/METADATA,sha256=OgSQ7AOFOMi03YLWBKxF0jB-96_4RCTcegiXj23njII,6313
-mcpforunityserver-8.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mcpforunityserver-8.2.3.dist-info/entry_points.txt,sha256=vCtkqw-J9t4pj7JwUZcB54_keVx7DpAR3fYzK6i-s6g,44
-mcpforunityserver-8.2.3.dist-info/top_level.txt,sha256=YKU5e5dREMfCnoVpmlsTm9bku7oqnrzSZ9FeTgjoxJw,58
-mcpforunityserver-8.2.3.dist-info/RECORD,,
+mcpforunityserver-8.5.0.dist-info/METADATA,sha256=3YWJc7I-EKxcLzMgG0MweNSJm3QR_VYCNTTwwB45UNE,5712
+mcpforunityserver-8.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mcpforunityserver-8.5.0.dist-info/entry_points.txt,sha256=vCtkqw-J9t4pj7JwUZcB54_keVx7DpAR3fYzK6i-s6g,44
+mcpforunityserver-8.5.0.dist-info/top_level.txt,sha256=YKU5e5dREMfCnoVpmlsTm9bku7oqnrzSZ9FeTgjoxJw,58
+mcpforunityserver-8.5.0.dist-info/RECORD,,

services/tools/debug_request_context.py

@@ -1,4 +1,8 @@
 from typing import Any
+import os
+import sys
+
+from core.telemetry import get_package_version
 
 from fastmcp import Context
 from services.registry import mcp_for_unity_tool
@@ -50,6 +54,11 @@ def debug_request_context(ctx: Context) -> dict[str, Any]:
     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,

services/tools/manage_asset.py

@@ -9,35 +9,41 @@ 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 services.tools.utils import parse_json_payload, coerce_int
 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."
+    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)."
+    )
 )
 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."],
+    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'."] | None = None,
+                          "Asset type (e.g., 'Material', 'Folder') - required for 'create'. Note: For ScriptableObjects, use manage_scriptable_object."] | 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,
+                                "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')."] | None = None,
+                              "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"] | None = None,
+                         "Page size for pagination. Recommended: 25 (smaller for LLM-friendly responses)."] | None = None,
     page_number: Annotated[int | float | str,
-                           "Page number for pagination"] | None = None,
+                           "Page number for pagination (1-based)."] | None = None,
 ) -> dict[str, Any]:
     unity_instance = get_unity_instance_from_context(ctx)
 
@@ -83,24 +89,32 @@ async def manage_asset(
         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
+    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:
-            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
+            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'")
 
-    page_size = _coerce_int(page_size)
-    page_number = _coerce_int(page_number)
+        # 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 = {

services/tools/manage_gameobject.py

@@ -7,7 +7,7 @@ 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, parse_json_payload
+from services.tools.utils import coerce_bool, parse_json_payload, coerce_int
 
 
 @mcp_for_unity_tool(
@@ -68,6 +68,11 @@ async def manage_gameobject(
     # Controls whether serialization of private [SerializeField] fields is included
     includeNonPublicSerialized: Annotated[bool | str,
                                           "Controls whether serialization of private [SerializeField] fields is included (accepts true/false or 'true'/'false')"] | None = None,
+    # --- Paging/safety for get_components ---
+    page_size: Annotated[int | str, "Page size for get_components paging."] | None = None,
+    cursor: Annotated[int | str, "Opaque cursor for get_components paging (offset)."] | None = None,
+    max_components: Annotated[int | str, "Hard cap on returned components per request (safety)."] | None = None,
+    include_properties: Annotated[bool | str, "If true, include serialized component properties (bounded)."] | None = None,
     # --- Parameters for 'duplicate' ---
     new_name: Annotated[str,
                         "New name for the duplicated object (default: SourceName_Copy)"] | None = None,
@@ -134,7 +139,12 @@ async def manage_gameobject(
     search_in_children = coerce_bool(search_in_children)
     search_inactive = coerce_bool(search_inactive)
     includeNonPublicSerialized = coerce_bool(includeNonPublicSerialized)
+    include_properties = coerce_bool(include_properties)
     world_space = coerce_bool(world_space, default=True)
+    # If coercion fails, omit these fields (None) rather than preserving invalid input.
+    page_size = coerce_int(page_size, default=None)
+    cursor = coerce_int(cursor, default=None)
+    max_components = coerce_int(max_components, default=None)
 
     # Coerce 'component_properties' from JSON string to dict for client compatibility
     component_properties = parse_json_payload(component_properties)
@@ -194,6 +204,10 @@ async def manage_gameobject(
             "searchInactive": search_inactive,
             "componentName": component_name,
             "includeNonPublicSerialized": includeNonPublicSerialized,
+            "pageSize": page_size,
+            "cursor": cursor,
+            "maxComponents": max_components,
+            "includeProperties": include_properties,
             # Parameters for 'duplicate'
             "new_name": new_name,
             "offset": offset,

services/tools/manage_scene.py

@@ -3,6 +3,7 @@ from typing import Annotated, Literal, Any
 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 coerce_int, coerce_bool
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
 
@@ -27,29 +28,27 @@ async def manage_scene(
                            "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,
+    # --- 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,
 ) -> dict[str, Any]:
     # Get active instance from session state
     # Removed session_state import
     unity_instance = get_unity_instance_from_context(ctx)
     try:
-        # 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
-
-        coerced_build_index = _coerce_int(build_index, default=None)
-        coerced_super_size = _coerce_int(screenshot_super_size, default=None)
+        coerced_build_index = coerce_int(build_index, default=None)
+        coerced_super_size = coerce_int(screenshot_super_size, default=None)
+        coerced_page_size = coerce_int(page_size, default=None)
+        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)
 
         params: dict[str, Any] = {"action": action}
         if name:
@@ -62,6 +61,22 @@ 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
+        if coerced_page_size is not None:
+            params["pageSize"] = coerced_page_size
+        if coerced_cursor is not None:
+            params["cursor"] = coerced_cursor
+        if coerced_max_nodes is not None:
+            params["maxNodes"] = coerced_max_nodes
+        if coerced_max_depth is not None:
+            params["maxDepth"] = coerced_max_depth
+        if coerced_max_children_per_node is not None:
+            params["maxChildrenPerNode"] = coerced_max_children_per_node
+        if coerced_include_transform is not None:
+            params["includeTransform"] = coerced_include_transform
 
         # Use centralized retry helper with instance routing
         response = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "manage_scene", params)

services/tools/manage_scriptable_object.py

@@ -0,0 +1,75 @@
+"""
+Tool wrapper for managing ScriptableObject assets via Unity MCP.
+
+Unity-side handler: MCPForUnity.Editor.Tools.ManageScriptableObject
+Command name: "manage_scriptable_object"
+Actions:
+  - create: create an SO asset (optionally with patches)
+  - modify: apply serialized property patches to an existing SO asset
+"""
+
+from __future__ import annotations
+
+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 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
+
+
+@mcp_for_unity_tool(
+    description="Creates and modifies ScriptableObject assets using Unity SerializedObject property paths."
+)
+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,
+    # --- modify params ---
+    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,
+) -> dict[str, Any]:
+    unity_instance = get_unity_instance_from_context(ctx)
+
+    # Tolerate JSON-string payloads (LLMs sometimes stringify complex objects)
+    parsed_target = parse_json_payload(target)
+    parsed_patches = parse_json_payload(patches)
+
+    if parsed_target is not None and not isinstance(parsed_target, dict):
+        return {"success": False, "message": "manage_scriptable_object: 'target' must be an object {guid|path} (or JSON string of such)."}
+
+    if parsed_patches is not None and not isinstance(parsed_patches, list):
+        return {"success": False, "message": "manage_scriptable_object: 'patches' must be a list (or JSON string of a list)."}
+
+    params: dict[str, Any] = {
+        "action": action,
+        "typeName": type_name,
+        "folderPath": folder_path,
+        "assetName": asset_name,
+        "overwrite": coerce_bool(overwrite, default=None),
+        "target": parsed_target,
+        "patches": parsed_patches,
+    }
+
+    # Remove None values to keep Unity handler simpler
+    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,
+        "manage_scriptable_object",
+        params,
+    )
+    await ctx.info(f"Response {response}")
+    return response if isinstance(response, dict) else {"success": False, "message": "Unexpected response from Unity."}
+
+
+

services/tools/read_console.py

@@ -6,6 +6,7 @@ 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 coerce_int, coerce_bool
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
 
@@ -38,42 +39,14 @@ async def read_console(
     format = format if format is not None else 'detailed'
     # Coerce booleans defensively (strings like 'true'/'false')
 
-    def _coerce_bool(value, default=None):
-        if value is None:
-            return default
-        if isinstance(value, bool):
-            return value
-        if isinstance(value, str):
-            v = value.strip().lower()
-            if v in ("true", "1", "yes", "on"):
-                return True
-            if v in ("false", "0", "no", "off"):
-                return False
-        return bool(value)
-
-    include_stacktrace = _coerce_bool(include_stacktrace, True)
+    include_stacktrace = coerce_bool(include_stacktrace, default=True)
 
     # Normalize action if it's a string
     if isinstance(action, str):
         action = action.lower()
 
     # Coerce count defensively (string/float -> int)
-    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
-
-    count = _coerce_int(count)
+    count = coerce_int(count)
 
     # Prepare parameters for the C# handler
     params_dict = {

services/tools/run_tests.py

@@ -7,6 +7,7 @@ from pydantic import BaseModel, Field
 from models import MCPResponse
 from services.registry import mcp_for_unity_tool
 from services.tools import get_unity_instance_from_context
+from services.tools.utils import coerce_int
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
 
@@ -54,22 +55,6 @@ async def run_tests(
 ) -> RunTestsResponse:
     unity_instance = get_unity_instance_from_context(ctx)
 
-    # Coerce timeout defensively (string/float -> int)
-    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
-
     # Coerce string or list to list of strings
     def _coerce_string_list(value) -> list[str] | None:
         if value is None:
@@ -82,7 +67,7 @@ async def run_tests(
         return None
 
     params: dict[str, Any] = {"mode": mode}
-    ts = _coerce_int(timeout_seconds)
+    ts = coerce_int(timeout_seconds)
     if ts is not None:
         params["timeoutSeconds"] = ts
 

services/tools/utils.py

@@ -58,3 +58,20 @@ def parse_json_payload(value: Any) -> Any:
     except (json.JSONDecodeError, ValueError):
         # If parsing fails, assume it was meant to be a literal string
         return value
+
+
+def coerce_int(value: Any, default: int | None = None) -> int | None:
+    """Attempt to coerce a loosely-typed value to an integer."""
+    if value is None:
+        return default
+    try:
+        if isinstance(value, bool):
+            return default
+        if isinstance(value, int):
+            return value
+        s = str(value).strip()
+        if s.lower() in ("", "none", "null"):
+            return default
+        return int(float(s))
+    except Exception:
+        return default