mcpforunityserver 9.3.0b20260128055651__py3-none-any.whl → 9.3.0b20260129121506__py3-none-any.whl

core/telemetry.py

@@ -249,6 +249,7 @@ class TelemetryCollector:
         self._lock: threading.Lock = threading.Lock()
         # Bounded queue with single background worker (records only; no context propagation)
         self._queue: "queue.Queue[TelemetryRecord]" = queue.Queue(maxsize=1000)
+        self._shutdown: bool = False
         # Load persistent data before starting worker so first events have UUID
         self._load_persistent_data()
         self._worker: threading.Thread = threading.Thread(
@@ -349,8 +350,11 @@ class TelemetryCollector:
 
     def _worker_loop(self):
         """Background worker that serializes telemetry sends."""
-        while True:
-            rec = self._queue.get()
+        while not self._shutdown:
+            try:
+                rec = self._queue.get(timeout=0.5)
+            except queue.Empty:
+                continue
             try:
                 # Run sender directly; do not reuse caller context/thread-locals
                 self._send_telemetry(rec)
@@ -360,6 +364,12 @@ class TelemetryCollector:
                 with contextlib.suppress(Exception):
                     self._queue.task_done()
 
+    def shutdown(self):
+        """Shutdown the telemetry collector and worker thread."""
+        self._shutdown = True
+        if self._worker and self._worker.is_alive():
+            self._worker.join(timeout=2.0)
+
     def _send_telemetry(self, record: TelemetryRecord):
         """Send telemetry data to endpoint"""
         try:
@@ -440,6 +450,14 @@ def get_telemetry() -> TelemetryCollector:
     return _telemetry_collector
 
 
+def reset_telemetry():
+    """Reset the global telemetry collector. For testing only."""
+    global _telemetry_collector
+    if _telemetry_collector is not None:
+        _telemetry_collector.shutdown()
+        _telemetry_collector = None
+
+
 def record_telemetry(record_type: RecordType,
                      data: dict[str, Any],
                      milestone: MilestoneType | None = None):

{mcpforunityserver-9.3.0b20260128055651.dist-info → mcpforunityserver-9.3.0b20260129121506.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpforunityserver
-Version: 9.3.0b20260128055651
+Version: 9.3.0b20260129121506
 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
@@ -163,6 +163,26 @@ The server connects to Unity Editor automatically when both are running. No addi
 
 ---
 
+## MCP Resources
+
+The server provides read-only MCP resources for querying Unity Editor state. Resources provide up-to-date information about your Unity project without modifying it.
+
+**Accessing Resources:**
+
+Resources are accessed by their URI (not their name). Always use `ListMcpResources` to get the correct URI format.
+
+**Example URIs:**
+- `mcpforunity://editor/state` - Editor readiness snapshot
+- `mcpforunity://project/tags` - All project tags
+- `mcpforunity://scene/gameobject/{instance_id}` - GameObject details by ID
+- `mcpforunity://prefab/{encoded_path}` - Prefab info by asset path
+
+**Important:** Resource names use underscores (e.g., `editor_state`) but URIs use slashes/hyphens (e.g., `mcpforunity://editor/state`). Always use the URI from `ListMcpResources()` when reading resources.
+
+**All resource descriptions now include their URI** for easy reference. List available resources to see the complete catalog with URIs.
+
+---
+
 ## Example Prompts
 
 Once connected, try these commands in your AI assistant:

mcpforunityserver-9.3.0b20260129121506.dist-info/RECORD

@@ -0,0 +1,103 @@
+main.py,sha256=EoHA0upWjtQzuoOgN5BfNmGL6bIVnFQjRW5PHO5EmjY,29265
+cli/__init__.py,sha256=f2HjXqR9d8Uhibru211t9HPpdrb_1vdDC2v_NwF_eqA,63
+cli/main.py,sha256=V_VFa8tA-CDHNv9J5NzNSLxRuEGjRVZWDe4xn6rYdog,8457
+cli/commands/__init__.py,sha256=xQHf6o0afDV2HsU9gwSxjcrzS41cMCSGZyWYWxblPIk,69
+cli/commands/animation.py,sha256=a7ZqTkP7CRou9wL7MB8b3TSB7v0PFG_1LcjdxW5_zQ0,2388
+cli/commands/asset.py,sha256=Cm18PFLGLisTLRhycTbxaGT8XU3WnJWcPOwsWiB5E2s,7164
+cli/commands/audio.py,sha256=gTW4F6uutgQezAwDqL6_-i8vM588V-AVwxAaJ4LzGN8,3088
+cli/commands/batch.py,sha256=eo2DD62FzRPDk0mQ5WhFVAXS0qXf8_znT_5kdN0BoG4,5388
+cli/commands/code.py,sha256=N6MaBjH7QkYjjCP4wEhAoAQSwvboh2ub3rrI6qYv8AM,5226
+cli/commands/component.py,sha256=OqjuNOyA2n5UOy-0-vMeiIRCQHOq_OnhVqW4ZzMgqrE,5736
+cli/commands/editor.py,sha256=F_KOfQiE-uuwGHXZQ9o9BF5nURG1nKcWuiL-9hjAFHc,12704
+cli/commands/gameobject.py,sha256=D4h8xuMHjOoc_mdyZToNSzYCGrJKjeOpwrMWCXR0OCU,12881
+cli/commands/instance.py,sha256=5qYJtptOFGCzfhXEMIPoEYcJtpkKlfM76dq36i_ZK5s,2780
+cli/commands/lighting.py,sha256=4OpbzPvR8pesTTUVYmKV554SwbTyCVBRwDwTGlnmh2w,3558
+cli/commands/material.py,sha256=_9atAdD0Wo_mEpZ2FP9Opl54ZBi2ak96euydHD_xGa4,6999
+cli/commands/prefab.py,sha256=ef8mFF5pcBDH8X3zWANuD4Hq23sT3gK1mAXsHSbP1iM,7480
+cli/commands/scene.py,sha256=HRDOcOUMpS6RhqL3FNF4JphjseCZFhTuDrJ0l-MOSRc,5652
+cli/commands/script.py,sha256=70i3I6IuKWq5f49QvHIpTzC9fafYmJrWfynJl4ZAAMU,5966
+cli/commands/shader.py,sha256=w_n8g6GJcFmqqZMulPdJGbvWWOirbfzHr6_vUx_2nVE,5985
+cli/commands/texture.py,sha256=lLiPNMfcWNNcfHbyeNA1ZN16tKv1ljHkzhmr7SM5e50,18595
+cli/commands/tool.py,sha256=A-jC9qFAs-LkWY0rav-vrye0yytgfKxQ7y2FraIAzZ4,1605
+cli/commands/ui.py,sha256=u9rpeF_eT7qxdlYmaA2G4ARSe3a16Y4yt-3if7CKmxY,7225
+cli/commands/vfx.py,sha256=gdx5a_N7Ulu960xjaJIV0E_1Ii422C211KaipoRO6nQ,14453
+cli/utils/__init__.py,sha256=Gbm9hYC7UqwloFwdirXgo6z1iBktR9Y96o3bQcrYudc,613
+cli/utils/config.py,sha256=_k3XAFmXG22sv8tYIb5JmO46kNl3T1sGqFptySAayfc,1550
+cli/utils/confirmation.py,sha256=7NGu0I5ogowpdWRTUndn3g5nmWmJM9mV3e0wWMLJwA8,1234
+cli/utils/connection.py,sha256=RBSOK7WotKgokj-wewsqnKT5rwS0_DhsqXqZrFZWUXo,8534
+cli/utils/constants.py,sha256=xCyRMY1L3cc-sbCyl-TGyqkY5hMCOl5tU6L4ZVbN9w4,1046
+cli/utils/output.py,sha256=96daU55ta_hl7UeOhNh5Iy7OJ4psbdR9Nfx1-q2k3xA,6370
+cli/utils/parsers.py,sha256=mnpH2bhZn3L3Lyl8e7Sh7Zr2UW9Xzu3aUuCaLxpV2pk,3430
+cli/utils/suggestions.py,sha256=n6KG3Mrvub28X9rPFYFLRTtZ6HePp3PhhAeojG2WOJw,929
+core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+core/config.py,sha256=kE7yg_89QQck3zScWNjvrq7CnfYt6uLS0VdxK7AJ70o,1453
+core/logging_decorator.py,sha256=D9CD7rFvQz-MBG-G4inizQj0Ivr6dfc9RBmTrw7q8mI,1383
+core/telemetry.py,sha256=zIjmQKUNW0S822SSlkXyjjCIuX0ZpSTaZP4pAU0rCjw,20426
+core/telemetry_decorator.py,sha256=ycSTrzVNCDQHSd-xmIWOpVfKFURPxpiZe_XkOQAGDAo,6705
+mcpforunityserver-9.3.0b20260129121506.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
+services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+services/custom_tool_service.py,sha256=WJxljL-hdJE5GMlAhVimHVhQwwnWHCd0StgWhWEFgaI,18592
+services/registry/__init__.py,sha256=QCwcYThvGF0kBt3WR6DBskdyxkegJC7NymEChgJA-YM,470
+services/registry/resource_registry.py,sha256=T_Kznqgvt5kKgV7mU85nb0LlFuB4rg-Tm4Cjhxt-IcI,1467
+services/registry/tool_registry.py,sha256=9tMwOP07JE92QFYUS4KvoysO0qC9pkBD5B79kjRsSPw,1304
+services/resources/__init__.py,sha256=G8uSEYJtiyX3yg0QsfoeGdDXOdbU89l5m0B5Anay1Fc,3054
+services/resources/active_tool.py,sha256=6m65iPCD1Iqmp4xqpDKvPErfOJg7Gl3XU5vMyAVcdj8,1521
+services/resources/custom_tools.py,sha256=uujlJEuqv5svCvSZLILgiY6hiiWZqWHVzTBJpTTL3as,1751
+services/resources/editor_state.py,sha256=LZLmljdHQC7nQcA-YYtoRnpy1xDiiAzo4_iU69TgsH8,10858
+services/resources/gameobject.py,sha256=cviektt_GHmwgria5pkvNrzvD5-6hzBi64Ogm0YGIv8,9356
+services/resources/layers.py,sha256=e3bDhfJ0ZjtUagHhraI35GrzrDnzXrRHnDeobmnbniw,1123
+services/resources/menu_items.py,sha256=01LIVHA96bswYGXyLZzGFw3suDqftsBanhy_lkUB2H0,1054
+services/resources/prefab.py,sha256=4TLEBsrlnQdi5FOKWZZ9eesiUCG5Ryxh7FZvd02FcTc,7434
+services/resources/prefab_stage.py,sha256=YALZrfZh4zpV_tEfQI7sUR6ETLnz8qeTN--gwYxk_y8,1430
+services/resources/project_info.py,sha256=NaHb9v5n-2vi3woMxioMXbgpy1tBcmh2bh0RZOTxtC4,1364
+services/resources/selection.py,sha256=HxmpN0RAb6Op0r4kqqRsizahP5L3Hj8V1baRa3uaKpU,1884
+services/resources/tags.py,sha256=f50DzILLNQsUJ44ooomwIGasrcntbKJgT7boqrU4b5s,1090
+services/resources/tests.py,sha256=KOm1vFcDPAXi21rDRQ1hQmifs1T9Xnd0zUp-BcBrBxo,3458
+services/resources/unity_instances.py,sha256=8vLA5oR2VpeLRjuxHk-_J3eopLhuNpGEoJyCvyUAOXg,4386
+services/resources/windows.py,sha256=inD7zMB3R4Tip_92pCDtKGD7clzsGKOGkdmv4rKmygA,1470
+services/state/external_changes_scanner.py,sha256=ZiXu8ZcK5B-hv7CaJLmnEIa9JxzgOBpdmrsRDY2eK5I,9052
+services/tools/__init__.py,sha256=J-woLzm3aLF0uPC1-VroqG7QV9xLXHDmVYee2ZXuCgk,2746
+services/tools/batch_execute.py,sha256=hjh67kgWvQDHyGd2N-Tfezv9WAj5x_pWTt_Vybmmq7s,3501
+services/tools/debug_request_context.py,sha256=Duq5xiuSmRO5GdvWAlZhCfOfmrwvK7gGkRC4wYnXmXk,2907
+services/tools/execute_custom_tool.py,sha256=hiZbm2A9t84f92jitzvkE2G4CMOIUiDVm7u5B8K-RbU,1527
+services/tools/execute_menu_item.py,sha256=k4J89LlXmEGyo9z3NK8Q0vREIzr11ucF_9tN_JeQq9M,1248
+services/tools/find_gameobjects.py,sha256=Qyls8HxBgXjA5OtdJfXuIX0qNGMleQSt3NOvQwjP25E,3963
+services/tools/find_in_file.py,sha256=SxhMeo8lRrt0OiGApGZSFUnq671bxVfK8qgAsHxLua8,6493
+services/tools/manage_asset.py,sha256=St_iWQWg9icztnRthU78t6JNhJN0AlC6ELiZhn-SNZU,5990
+services/tools/manage_components.py,sha256=2_nKPk9iPAf5VyYiXuRxSkN8U76VNQbMtE68UTPngrw,5061
+services/tools/manage_editor.py,sha256=ShvlSBQRfoNQ0DvqBWak_Hi3MB7tv2WkMKEhrKQipk0,3279
+services/tools/manage_gameobject.py,sha256=SP-y3_7Ckw12JO6bLJy01Jrx303JXF-7RMROaQuA1kU,14154
+services/tools/manage_material.py,sha256=LSn9Kp-cSMZ5caU6Ux0M_OSMghCtZgOKkmvwf0xLTFE,4311
+services/tools/manage_prefabs.py,sha256=7K-6kTavqu2-oxbA49Ug-vTh1Jt39ua02lWcijwM1DI,10163
+services/tools/manage_scene.py,sha256=-ARtRuj7ZNk_14lmMSORnQs0qTAYKBTPtUfk0sNDo6A,5370
+services/tools/manage_script.py,sha256=tT8JmhTtAYgW8CQla71cfn6IjiUw-tiPjBWVd4ipuCE,28551
+services/tools/manage_scriptable_object.py,sha256=tezG_mbGzPLNpL3F7l5JJLyyjJN3rJi1thGMU8cpOC4,3659
+services/tools/manage_shader.py,sha256=bucRKzQww7opy6DK5nf6isVaEECWWqJ-DVkFulp8CV8,3185
+services/tools/manage_texture.py,sha256=uUicuxKl_uSnP2jBrMbYAhAEWnh7RETusgJfnBI1P8c,22538
+services/tools/manage_vfx.py,sha256=7KFbRohF8EzaD0m7vVIEwjUz-QwC7NEXS5cVcU6Die0,4710
+services/tools/preflight.py,sha256=0nvo0BmZMdIGop1Ha_vypkjn2VLiRvskF0uxh_SlZgE,4162
+services/tools/read_console.py,sha256=ps23debJcQkj3Ap-MqTYVhopYnKGspJs9QHLJHZAAkE,6826
+services/tools/refresh_unity.py,sha256=KrRA8bmLkDLFO1XBv2NmagQAp1dmyaXdUAap567Hcv4,7100
+services/tools/run_tests.py,sha256=Wd7hNZqy-OOZ9ZedonxUJ5bVlhta_aOEmD-2uxmrmyM,11743
+services/tools/script_apply_edits.py,sha256=0f-SaP5NUYGuivl4CWHjR8F-CXUpt3-5qkHpf_edn1U,47677
+services/tools/set_active_instance.py,sha256=pdmC1SxFijyzzjeEyC2N1bXk-GNMu_iXsbCieIpa-R4,4242
+services/tools/utils.py,sha256=ETCiNnWdMZEtnJcDD-CtPsCJ7TBp5x5sPsYuhufkxac,13962
+transport/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+transport/models.py,sha256=2tnK0Wc-IzvlOS0a04VB3WtuSlAAHeLVFfOnNFHGnhw,1311
+transport/plugin_hub.py,sha256=Kykqnydk_KkCSICaJGE8XQulr7sZeNcIgPOHjtdbjHM,23783
+transport/plugin_registry.py,sha256=L6xl7Ok9rtSW9xwSSKTFjWS7Duu1g4c-qfgfnn6y-sQ,4528
+transport/unity_instance_middleware.py,sha256=DD8gs-peMRmRJz9CYwaHEh4m75LTYPDjVuKuw9sArBw,10438
+transport/unity_transport.py,sha256=RKMH0NYPqTU3rpjXUPUkzZsdWhJqyVaHmkLswab4bGg,2135
+transport/legacy/port_discovery.py,sha256=JDSCqXLodfTT7fOsE0DFC1jJ3QsU6hVaYQb7x7FgdxY,12728
+transport/legacy/stdio_port_registry.py,sha256=j4iARuP6wetppNDG8qKeuvo1bJKcSlgEhZvSyl_uf0A,2313
+transport/legacy/unity_connection.py,sha256=FE9ZQfYMhHvIxBycr_DjI3BKvuEdORXuABnCE5Q2tjQ,36733
+utils/focus_nudge.py,sha256=0MCOms-SxUW7sN2hT3syy1epMdli2zc-6UHBICAfBSM,21330
+utils/module_discovery.py,sha256=My48ofB1BUqxiBoAZAGbEaLQYdsrDhMm8MayBP_bUSQ,2005
+mcpforunityserver-9.3.0b20260129121506.dist-info/METADATA,sha256=NhUC2AYe0dyaYPjuAkHQN1wksQiDGTHHM_8k8IvcEw4,6750
+mcpforunityserver-9.3.0b20260129121506.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mcpforunityserver-9.3.0b20260129121506.dist-info/entry_points.txt,sha256=pPm70RXQvkt3uBhPOtViDa47ZTA03RaQ6rwXvyi8oiI,70
+mcpforunityserver-9.3.0b20260129121506.dist-info/top_level.txt,sha256=3-A65WsmBO6UZYH8O5mINdyhhZ63SDssr8LncRd1PSQ,46
+mcpforunityserver-9.3.0b20260129121506.dist-info/RECORD,,

services/resources/active_tool.py

@@ -33,7 +33,7 @@ class ActiveToolResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://editor/active-tool",
     name="editor_active_tool",
-    description="Currently active editor tool (Move, Rotate, Scale, etc.) and transform handle settings."
+    description="Currently active editor tool (Move, Rotate, Scale, etc.) and transform handle settings.\n\nURI: mcpforunity://editor/active-tool"
 )
 async def get_active_tool(ctx: Context) -> ActiveToolResponse | MCPResponse:
     """Get active editor tool information."""

services/resources/custom_tools.py

@@ -24,7 +24,7 @@ class CustomToolsResourceResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://custom-tools",
     name="custom_tools",
-    description="Lists custom tools available for the active Unity project.",
+    description="Lists custom tools available for the active Unity project.\n\nURI: mcpforunity://custom-tools",
 )
 async def get_custom_tools(ctx: Context) -> CustomToolsResourceResponse | MCPResponse:
     unity_instance = get_unity_instance_from_context(ctx)

services/resources/editor_state.py

@@ -214,7 +214,7 @@ def _enrich_advice_and_staleness(state_v2: dict[str, Any]) -> dict[str, Any]:
 @mcp_for_unity_resource(
     uri="mcpforunity://editor/state",
     name="editor_state",
-    description="Canonical editor readiness snapshot. Includes advice and server-computed staleness.",
+    description="Canonical editor readiness snapshot. Includes advice and server-computed staleness.\n\nURI: mcpforunity://editor/state",
 )
 async def get_editor_state(ctx: Context) -> MCPResponse:
     unity_instance = get_unity_instance_from_context(ctx)

services/resources/gameobject.py

@@ -42,7 +42,7 @@ def _validate_instance_id(instance_id: str) -> tuple[int | None, MCPResponse | N
 @mcp_for_unity_resource(
     uri="mcpforunity://scene/gameobject-api",
     name="gameobject_api",
-    description="Documentation for GameObject resources. Use find_gameobjects tool to get instance IDs, then access resources below."
+    description="Documentation for GameObject resources. Use find_gameobjects tool to get instance IDs, then access resources below.\n\nURI: mcpforunity://scene/gameobject-api"
 )
 async def get_gameobject_api_docs(_ctx: Context) -> MCPResponse:
     """
@@ -129,7 +129,7 @@ class GameObjectResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://scene/gameobject/{instance_id}",
     name="gameobject",
-    description="Get detailed information about a single GameObject by instance ID. Returns name, tag, layer, active state, transform data, parent/children IDs, and component type list (no full component properties)."
+    description="Get detailed information about a single GameObject by instance ID. Returns name, tag, layer, active state, transform data, parent/children IDs, and component type list (no full component properties).\n\nURI: mcpforunity://scene/gameobject/{instance_id}"
 )
 async def get_gameobject(ctx: Context, instance_id: str) -> MCPResponse:
     """Get GameObject data by instance ID."""
@@ -170,7 +170,7 @@ class ComponentsResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://scene/gameobject/{instance_id}/components",
     name="gameobject_components",
-    description="Get all components on a GameObject with full property serialization. Supports pagination with pageSize and cursor parameters."
+    description="Get all components on a GameObject with full property serialization. Supports pagination with pageSize and cursor parameters.\n\nURI: mcpforunity://scene/gameobject/{instance_id}/components"
 )
 async def get_gameobject_components(
     ctx: Context,
@@ -216,7 +216,7 @@ class SingleComponentResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://scene/gameobject/{instance_id}/component/{component_name}",
     name="gameobject_component",
-    description="Get a specific component on a GameObject by type name. Returns the fully serialized component with all properties."
+    description="Get a specific component on a GameObject by type name. Returns the fully serialized component with all properties.\n\nURI: mcpforunity://scene/gameobject/{instance_id}/component/{component_name}"
 )
 async def get_gameobject_component(
     ctx: Context,

services/resources/layers.py

@@ -15,7 +15,7 @@ class LayersResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://project/layers",
     name="project_layers",
-    description="All layers defined in the project's TagManager with their indices (0-31). Read this before using add_layer or remove_layer tools."
+    description="All layers defined in the project's TagManager with their indices (0-31). Read this before using add_layer or remove_layer tools.\n\nURI: mcpforunity://project/layers"
 )
 async def get_layers(ctx: Context) -> LayersResponse | MCPResponse:
     """Get all project layers with their indices."""

services/resources/menu_items.py

@@ -14,7 +14,7 @@ class GetMenuItemsResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://menu-items",
     name="menu_items",
-    description="Provides a list of all menu items."
+    description="Provides a list of all menu items.\n\nURI: mcpforunity://menu-items"
 )
 async def get_menu_items(ctx: Context) -> GetMenuItemsResponse | MCPResponse:
     """Provides a list of all menu items.

services/resources/prefab.py

@@ -43,7 +43,7 @@ def _decode_prefab_path(encoded_path: str) -> str:
 @mcp_for_unity_resource(
     uri="mcpforunity://prefab-api",
     name="prefab_api",
-    description="Documentation for Prefab resources. Use manage_asset action=search filterType=Prefab to find prefabs, then access resources below."
+    description="Documentation for Prefab resources. Use manage_asset action=search filterType=Prefab to find prefabs, then access resources below.\n\nURI: mcpforunity://prefab-api"
 )
 async def get_prefab_api_docs(_ctx: Context) -> MCPResponse:
     """
@@ -117,7 +117,7 @@ class PrefabInfoResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://prefab/{encoded_path}",
     name="prefab_info",
-    description="Get detailed information about a prefab asset by URL-encoded path. Returns prefab type, root object name, component types, child count, and variant info."
+    description="Get detailed information about a prefab asset by URL-encoded path. Returns prefab type, root object name, component types, child count, and variant info.\n\nURI: mcpforunity://prefab/{encoded_path}"
 )
 async def get_prefab_info(ctx: Context, encoded_path: str) -> MCPResponse:
     """Get prefab asset info by path."""
@@ -169,7 +169,7 @@ class PrefabHierarchyResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://prefab/{encoded_path}/hierarchy",
     name="prefab_hierarchy",
-    description="Get the full hierarchy of a prefab with nested prefab information. Returns all GameObjects with their components and nesting depth."
+    description="Get the full hierarchy of a prefab with nested prefab information. Returns all GameObjects with their components and nesting depth.\n\nURI: mcpforunity://prefab/{encoded_path}/hierarchy"
 )
 async def get_prefab_hierarchy(ctx: Context, encoded_path: str) -> MCPResponse:
     """Get prefab hierarchy by path."""

services/resources/prefab_stage.py

@@ -25,7 +25,7 @@ class PrefabStageResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://editor/prefab-stage",
     name="editor_prefab_stage",
-    description="Current prefab editing context if a prefab is open in isolation mode. Returns isOpen=false if no prefab is being edited."
+    description="Current prefab editing context if a prefab is open in isolation mode. Returns isOpen=false if no prefab is being edited.\n\nURI: mcpforunity://editor/prefab-stage"
 )
 async def get_prefab_stage(ctx: Context) -> PrefabStageResponse | MCPResponse:
     """Get current prefab stage information."""

services/resources/project_info.py

@@ -25,7 +25,7 @@ class ProjectInfoResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://project/info",
     name="project_info",
-    description="Static project information including root path, Unity version, and platform. This data rarely changes."
+    description="Static project information including root path, Unity version, and platform. This data rarely changes.\n\nURI: mcpforunity://project/info"
 )
 async def get_project_info(ctx: Context) -> ProjectInfoResponse | MCPResponse:
     """Get static project configuration information."""

services/resources/selection.py

@@ -41,7 +41,7 @@ class SelectionResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://editor/selection",
     name="editor_selection",
-    description="Detailed information about currently selected objects in the editor, including GameObjects, assets, and their properties."
+    description="Detailed information about currently selected objects in the editor, including GameObjects, assets, and their properties.\n\nURI: mcpforunity://editor/selection"
 )
 async def get_selection(ctx: Context) -> SelectionResponse | MCPResponse:
     """Get detailed editor selection information."""

services/resources/tags.py

@@ -16,7 +16,7 @@ class TagsResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://project/tags",
     name="project_tags",
-    description="All tags defined in the project's TagManager. Read this before using add_tag or remove_tag tools."
+    description="All tags defined in the project's TagManager. Read this before using add_tag or remove_tag tools.\n\nURI: mcpforunity://project/tags"
 )
 async def get_tags(ctx: Context) -> TagsResponse | MCPResponse:
     """Get all project tags."""

services/resources/tests.py

@@ -1,4 +1,4 @@
-from typing import Annotated, Literal
+from typing import Annotated, Literal, Optional
 from pydantic import BaseModel, Field
 
 from fastmcp import Context
@@ -17,15 +17,36 @@ class TestItem(BaseModel):
                     Field(description="The mode the test is for.")]
 
 
+class PaginatedTestsData(BaseModel):
+    """Paginated test results."""
+    items: list[TestItem] = Field(description="Tests on current page")
+    cursor: int = Field(description="Current page cursor (0-based)")
+    nextCursor: Optional[int] = Field(None, description="Next page cursor, null if last page")
+    totalCount: int = Field(description="Total number of tests across all pages")
+    pageSize: int = Field(description="Number of items per page")
+    hasMore: bool = Field(description="Whether there are more items after this page")
+
+
 class GetTestsResponse(MCPResponse):
-    data: list[TestItem] = []
+    """Response containing paginated test data."""
+    data: PaginatedTestsData = Field(description="Paginated test data")
 
 
-@mcp_for_unity_resource(uri="mcpforunity://tests", name="get_tests", description="Provides a list of all tests.")
+@mcp_for_unity_resource(
+    uri="mcpforunity://tests",
+    name="get_tests",
+    description="Provides the first page of Unity tests (default 50 items). "
+                "For filtering or pagination, use the run_tests tool instead.\n\nURI: mcpforunity://tests"
+)
 async def get_tests(ctx: Context) -> GetTestsResponse | MCPResponse:
-    """Provides a list of all tests.
+    """Provides a paginated list of all Unity tests.
+
+    Returns the first page of tests using Unity's default pagination (50 items).
+    For advanced filtering or pagination control, use the run_tests tool which
+    accepts mode, filter, page_size, and cursor parameters.
     """
     unity_instance = get_unity_instance_from_context(ctx)
+
     response = await send_with_unity_instance(
         async_send_command_with_retry,
         unity_instance,
@@ -35,17 +56,28 @@ async def get_tests(ctx: Context) -> GetTestsResponse | MCPResponse:
     return GetTestsResponse(**response) if isinstance(response, dict) else response
 
 
-@mcp_for_unity_resource(uri="mcpforunity://tests/{mode}", name="get_tests_for_mode", description="Provides a list of tests for a specific mode.")
+@mcp_for_unity_resource(
+    uri="mcpforunity://tests/{mode}",
+    name="get_tests_for_mode",
+    description="Provides the first page of tests for a specific mode (EditMode or PlayMode). "
+                "For filtering or pagination, use the run_tests tool instead.\n\nURI: mcpforunity://tests/{mode}"
+)
 async def get_tests_for_mode(
     ctx: Context,
-    mode: Annotated[Literal["EditMode", "PlayMode"], Field(description="The mode to filter tests by.")],
+    mode: Annotated[Literal["EditMode", "PlayMode"], Field(
+        description="The mode to filter tests by (EditMode or PlayMode)."
+    )],
 ) -> GetTestsResponse | MCPResponse:
-    """Provides a list of tests for a specific mode.
+    """Provides the first page of tests for a specific mode.
 
     Args:
-        mode: The test mode to filter by (EditMode or PlayMode).
+        mode: The test mode to filter by (EditMode or PlayMode)
+
+    Returns the first page of tests using Unity's default pagination (50 items).
+    For advanced filtering or pagination control, use the run_tests tool.
     """
     unity_instance = get_unity_instance_from_context(ctx)
+
     response = await send_with_unity_instance(
         async_send_command_with_retry,
         unity_instance,

services/resources/unity_instances.py

@@ -13,7 +13,7 @@ from transport.unity_transport import _current_transport
 @mcp_for_unity_resource(
     uri="mcpforunity://instances",
     name="unity_instances",
-    description="Lists all running Unity Editor instances with their details."
+    description="Lists all running Unity Editor instances with their details.\n\nURI: mcpforunity://instances"
 )
 async def unity_instances(ctx: Context) -> dict[str, Any]:
     """

services/resources/windows.py

@@ -33,7 +33,7 @@ class WindowsResponse(MCPResponse):
 @mcp_for_unity_resource(
     uri="mcpforunity://editor/windows",
     name="editor_windows",
-    description="All currently open editor windows with their titles, types, positions, and focus state."
+    description="All currently open editor windows with their titles, types, positions, and focus state.\n\nURI: mcpforunity://editor/windows"
 )
 async def get_windows(ctx: Context) -> WindowsResponse | MCPResponse:
     """Get all open editor windows."""

services/tools/__init__.py

@@ -51,7 +51,9 @@ def register_all_tools(mcp: FastMCP, *, project_scoped_tools: bool = True):
                 "Skipping execute_custom_tool registration (project-scoped tools disabled)")
             continue
 
-        # Apply the @mcp.tool decorator, telemetry, and logging
+        # Apply decorators: logging -> telemetry -> mcp.tool
+        # Note: Parameter normalization (camelCase -> snake_case) is handled by
+        # ParamNormalizerMiddleware before FastMCP validation
         wrapped = log_execution(tool_name, "Tool")(func)
         wrapped = telemetry_tool(tool_name)(wrapped)
         wrapped = mcp.tool(

services/tools/find_gameobjects.py

@@ -5,6 +5,7 @@ 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
@@ -14,22 +15,42 @@ from services.tools.preflight import preflight
 
 
 @mcp_for_unity_tool(
-    description="Search for GameObjects in the scene. Returns instance IDs only (paginated) for efficient lookups. Use mcpforunity://scene/gameobject/{id} resource to get full GameObject data."
+    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, "The value to search for (name, tag, layer name, component type, or path)"],
+    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"],
-        "How to search for GameObjects"
+        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,
-                                "Include inactive GameObjects in search"] | None = None,
-    page_size: Annotated[int | str,
-                         "Number of results per page (default: 50, max: 500)"] | None = None,
-    cursor: Annotated[int | str,
-                      "Pagination cursor (offset for next page)"] | None = None,
+    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.

services/tools/manage_gameobject.py

@@ -1,5 +1,4 @@
 import json
-import math
 from typing import Annotated, Any, Literal
 
 from fastmcp import Context
@@ -9,64 +8,10 @@ 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, coerce_int
+from services.tools.utils import coerce_bool, parse_json_payload, coerce_int, normalize_vector3
 from services.tools.preflight import preflight
 
 
-def _normalize_vector(value: Any, param_name: str = "vector") -> tuple[list[float] | None, str | None]:
-    """
-    Robustly normalize a vector parameter to [x, y, z] format.
-    Handles: list, tuple, JSON string, comma-separated string.
-    Returns (parsed_vector, error_message). If error_message is set, parsed_vector is None.
-    """
-    if value is None:
-        return None, None
-
-    # If already a list/tuple with 3 elements, convert to floats
-    if isinstance(value, (list, tuple)) and len(value) == 3:
-        try:
-            vec = [float(value[0]), float(value[1]), float(value[2])]
-            if all(math.isfinite(n) for n in vec):
-                return vec, None
-            return None, f"{param_name} values must be finite numbers, got {value}"
-        except (ValueError, TypeError):
-            return None, f"{param_name} values must be numbers, got {value}"
-
-    # Try parsing as JSON string
-    if isinstance(value, str):
-        # Check for obviously invalid values
-        if value in ("[object Object]", "undefined", "null", ""):
-            return None, f"{param_name} received invalid value: '{value}'. Expected [x, y, z] array (list or JSON string)"
-
-        parsed = parse_json_payload(value)
-        if isinstance(parsed, list) and len(parsed) == 3:
-            try:
-                vec = [float(parsed[0]), float(parsed[1]), float(parsed[2])]
-                if all(math.isfinite(n) for n in vec):
-                    return vec, None
-                return None, f"{param_name} values must be finite numbers, got {parsed}"
-            except (ValueError, TypeError):
-                return None, f"{param_name} values must be numbers, got {parsed}"
-
-        # Handle legacy comma-separated strings "1,2,3" or "[1,2,3]"
-        s = value.strip()
-        if s.startswith("[") and s.endswith("]"):
-            s = s[1:-1]
-        parts = [p.strip() for p in (s.split(",") if "," in s else s.split())]
-        if len(parts) == 3:
-            try:
-                vec = [float(parts[0]), float(parts[1]), float(parts[2])]
-                if all(math.isfinite(n) for n in vec):
-                    return vec, None
-                return None, f"{param_name} values must be finite numbers, got {value}"
-            except (ValueError, TypeError):
-                return None, f"{param_name} values must be numbers, got {value}"
-
-        return None, f"{param_name} must be a [x, y, z] array (list or JSON string), got: {value}"
-
-    return None, f"{param_name} must be a list or JSON string, got {type(value).__name__}"
-
-
 def _normalize_component_properties(value: Any) -> tuple[dict[str, dict[str, Any]] | None, str | None]:
     """
     Robustly normalize component_properties to a dict.
@@ -115,12 +60,12 @@ async def manage_gameobject(
                    "Tag name - used for both 'create' (initial tag) and 'modify' (change tag)"] | None = None,
     parent: Annotated[str,
                       "Parent GameObject reference - used for both 'create' (initial parent) and 'modify' (change parent)"] | None = None,
-    position: Annotated[list[float] | str,
-                        "Position as [x, y, z] array (list or JSON string)"] | None = None,
-    rotation: Annotated[list[float] | str,
-                        "Rotation as [x, y, z] euler angles array (list or JSON string)"] | None = None,
-    scale: Annotated[list[float] | str,
-                     "Scale as [x, y, z] array (list or JSON string)"] | None = None,
+    position: Annotated[list[float] | dict[str, float] | str,
+                        "Position as [x, y, z] array, {x, y, z} object, or JSON string"] | None = None,
+    rotation: Annotated[list[float] | dict[str, float] | str,
+                        "Rotation as [x, y, z] euler angles array, {x, y, z} object, or JSON string"] | None = None,
+    scale: Annotated[list[float] | dict[str, float] | str,
+                     "Scale as [x, y, z] array, {x, y, z} object, or JSON string"] | None = None,
     components_to_add: Annotated[list[str],
                                  "List of component names to add"] | None = None,
     primitive_type: Annotated[str,
@@ -196,16 +141,16 @@ async def manage_gameobject(
         }
 
     # --- Normalize vector parameters with detailed error handling ---
-    position, position_error = _normalize_vector(position, "position")
+    position, position_error = normalize_vector3(position, "position")
     if position_error:
         return {"success": False, "message": position_error}
-    rotation, rotation_error = _normalize_vector(rotation, "rotation")
+    rotation, rotation_error = normalize_vector3(rotation, "rotation")
     if rotation_error:
         return {"success": False, "message": rotation_error}
-    scale, scale_error = _normalize_vector(scale, "scale")
+    scale, scale_error = normalize_vector3(scale, "scale")
     if scale_error:
         return {"success": False, "message": scale_error}
-    offset, offset_error = _normalize_vector(offset, "offset")
+    offset, offset_error = normalize_vector3(offset, "offset")
     if offset_error:
         return {"success": False, "message": offset_error}