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

main.py

@@ -391,6 +391,22 @@ Examples:
         help="HTTP server port (overrides URL port). "
              "Overrides UNITY_MCP_HTTP_PORT environment variable."
     )
+    parser.add_argument(
+        "--unity-instance-token",
+        type=str,
+        default=None,
+        metavar="TOKEN",
+        help="Optional per-launch token set by Unity for deterministic lifecycle management. "
+             "Used by Unity to validate it is stopping the correct process."
+    )
+    parser.add_argument(
+        "--pidfile",
+        type=str,
+        default=None,
+        metavar="PATH",
+        help="Optional path where the server will write its PID on startup. "
+             "Used by Unity to stop the exact process it launched when running in a terminal."
+    )
 
     args = parser.parse_args()
 
@@ -418,6 +434,20 @@ Examples:
     os.environ["UNITY_MCP_HTTP_HOST"] = http_host
     os.environ["UNITY_MCP_HTTP_PORT"] = str(http_port)
 
+    # Optional lifecycle handshake for Unity-managed terminal launches
+    if args.unity_instance_token:
+        os.environ["UNITY_MCP_INSTANCE_TOKEN"] = args.unity_instance_token
+    if args.pidfile:
+        try:
+            pid_dir = os.path.dirname(args.pidfile)
+            if pid_dir:
+                os.makedirs(pid_dir, exist_ok=True)
+            with open(args.pidfile, "w", encoding="ascii") as f:
+                f.write(str(os.getpid()))
+        except Exception as exc:
+            logger.warning(
+                "Failed to write pidfile '%s': %s", args.pidfile, exc)
+
     if args.http_url != "http://localhost:8080":
         logger.info(f"HTTP URL set to: {http_url}")
     if args.http_host:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpforunityserver
-Version: 8.5.0
+Version: 8.6.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
@@ -108,7 +108,7 @@ Use this to run the latest released version from the repository. Change the vers
       "command": "uvx",
       "args": [
         "--from",
-        "git+https://github.com/CoplayDev/unity-mcp@v8.5.0#subdirectory=Server",
+        "git+https://github.com/CoplayDev/unity-mcp@v8.6.0#subdirectory=Server",
         "mcp-for-unity",
         "--transport",
         "stdio"

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

@@ -1,11 +1,11 @@
 __init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-main.py,sha256=OH_Ux5Aj43q1lXPu4AS8zafRnFHZWFYCDZbswReQOac,18011
+main.py,sha256=ITxelXUAmr9BoasG0knZifXKp3lWJyml_RLaIwvEyVs,19184
 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.5.0.dist-info/licenses/LICENSE,sha256=bv5lDJZQEqxBgjjc1rkRbkEwpSIHF-8N-1Od0VnEJFw,1066
+mcpforunityserver-8.6.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
@@ -18,7 +18,7 @@ services/registry/tool_registry.py,sha256=9tMwOP07JE92QFYUS4KvoysO0qC9pkBD5B79kj
 services/resources/__init__.py,sha256=O5heeMcgCswnQX1qG2nNtMeAZIaLut734qD7t5UsA0k,2801
 services/resources/active_tool.py,sha256=YTbsiy_hmnKH2q7IoM7oYD7pJkoveZTszRiL1PlhO9M,1474
 services/resources/custom_tools.py,sha256=8lyryGhN3vD2LwMt6ZyKIp5ONtxdI1nfcCAlYjlfQnQ,1704
-services/resources/editor_state.py,sha256=acrSyMfdulRgYQIn7wKHqKqyw4uED_oUf9GU-4o4GAg,1497
+services/resources/editor_state.py,sha256=8hrNnskSFdsvdKagAYEeZGJ0Oz9QRlkWJjpM4q0XeNo,2013
 services/resources/layers.py,sha256=q4UQ5PUVUVhmM5l3oXID1wa_wOWAS8l5BGXadBgFuwY,1080
 services/resources/menu_items.py,sha256=9SNycjwTXoeS1ZHra0Y1fTyCjSEdPCo34JyxtuqauG8,1021
 services/resources/prefab_stage.py,sha256=C3mn3UapKYVOA8QUNmLsYreG5YiXdlvGm9ypHQeKBeQ,1382
@@ -43,24 +43,24 @@ services/tools/manage_scene.py,sha256=3BhIsbbtGiMNqBMQMqEsB4ajYmtx-VwWl-krOkFR_B
 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=gZWEf0Ru0hvN9oJUZqZ4w-mMBBLm5Z5KAUPv282XbYQ,4091
-services/tools/run_tests.py,sha256=LBVwGasLvmF4k1FiX3DdBQ8udh89WZJFiVHfJRWGvOs,3313
+services/tools/read_console.py,sha256=MdQcrnVXra9PLu5AFkmARjriObT0miExtQKkFaANznU,4662
+services/tools/run_tests.py,sha256=eeHwFmBxbKHaL_RMxoDN6qKsmBp2qTrnG7FxnRQR5mQ,3709
 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=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
+transport/plugin_hub.py,sha256=g_DOhCThgJ9Oco_z3m2qpwDeUcFvvt7Z47xMS0diihw,21497
 transport/plugin_registry.py,sha256=nW-7O7PN0QUgSWivZTkpAVKKq9ZOe2b2yeIdpaNt_3I,4359
-transport/unity_instance_middleware.py,sha256=a-ULWU9b86w0CbYN3meyLxWGxTBXL5CQmBKZmmQ0xZQ,6197
-transport/unity_transport.py,sha256=dvwCjo2jRvnFXd8ruOL36C8W4P1VIQ91qreS2750lPM,3307
+transport/unity_instance_middleware.py,sha256=kf1QeA138r7PaC98dcMDYtUPGWZ4EUmZGESc2DdiWQs,10429
+transport/unity_transport.py,sha256=_cFVgD3pzFZRcDXANq4oPFYSoI6jntSGaN22dJC8LRU,3880
 transport/legacy/port_discovery.py,sha256=qM_mtndbYjAj4qPSZEWVeXFOt5_nKczG9pQqORXTBJ0,12768
 transport/legacy/stdio_port_registry.py,sha256=j4iARuP6wetppNDG8qKeuvo1bJKcSlgEhZvSyl_uf0A,2313
 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.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,,
+mcpforunityserver-8.6.0.dist-info/METADATA,sha256=mhrVzwZHOC4hsY1aNMsgBK3wLZuFNyE05hJ0xN94k18,5712
+mcpforunityserver-8.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mcpforunityserver-8.6.0.dist-info/entry_points.txt,sha256=vCtkqw-J9t4pj7JwUZcB54_keVx7DpAR3fYzK6i-s6g,44
+mcpforunityserver-8.6.0.dist-info/top_level.txt,sha256=YKU5e5dREMfCnoVpmlsTm9bku7oqnrzSZ9FeTgjoxJw,58
+mcpforunityserver-8.6.0.dist-info/RECORD,,

services/resources/editor_state.py

@@ -39,4 +39,13 @@ async def get_editor_state(ctx: Context) -> EditorStateResponse | MCPResponse:
         "get_editor_state",
         {}
     )
-    return EditorStateResponse(**response) if isinstance(response, dict) else response
+    # When Unity is reloading/unresponsive (often when unfocused), transports may return
+    # a retryable MCPResponse payload with success=false and no data. Do not attempt to
+    # coerce that into EditorStateResponse (it would fail validation); return it as-is.
+    if isinstance(response, dict):
+        if not response.get("success", True):
+            return MCPResponse(**response)
+        if response.get("data") is None:
+            return MCPResponse(success=False, error="Editor state missing 'data' payload", data=response)
+        return EditorStateResponse(**response)
+    return response

services/tools/read_console.py

@@ -45,8 +45,18 @@ async def read_console(
     if isinstance(action, str):
         action = action.lower()
 
-    # Coerce count defensively (string/float -> int)
-    count = coerce_int(count)
+    # Coerce count defensively (string/float -> int).
+    # Important: leaving count unset previously meant "return all console entries", which can be extremely slow
+    # (and can exceed the plugin command timeout when Unity has a large console).
+    # To keep the tool responsive by default, we cap the default to a reasonable number of most-recent entries.
+    # If a client truly wants everything, it can pass count="all" (or count="*") explicitly.
+    if isinstance(count, str) and count.strip().lower() in ("all", "*"):
+        count = None
+    else:
+        count = coerce_int(count)
+
+    if action == "get" and count is None:
+        count = 200
 
     # Prepare parameters for the C# handler
     params_dict = {

services/tools/run_tests.py

@@ -34,7 +34,7 @@ class RunTestsTestResult(BaseModel):
 class RunTestsResult(BaseModel):
     mode: str
     summary: RunTestsSummary
-    results: list[RunTestsTestResult]
+    results: list[RunTestsTestResult] | None = None
 
 
 class RunTestsResponse(MCPResponse):
@@ -52,6 +52,8 @@ async def run_tests(
     group_names: Annotated[list[str] | str, "Same as test_names, except it allows for Regex"] | None = None,
     category_names: Annotated[list[str] | str, "NUnit category names to filter by (tests marked with [Category] attribute)"] | None = None,
     assembly_names: Annotated[list[str] | str, "Assembly names to filter tests by"] | None = None,
+    include_failed_tests: Annotated[bool, "Include details for failed/skipped tests only (default: false)"] = False,
+    include_details: Annotated[bool, "Include details for all tests (default: false)"] = False,
 ) -> RunTestsResponse:
     unity_instance = get_unity_instance_from_context(ctx)
 
@@ -88,6 +90,12 @@ async def run_tests(
     if assembly_names_list:
         params["assemblyNames"] = assembly_names_list
 
+    # Add verbosity parameters
+    if include_failed_tests:
+        params["includeFailedTests"] = True
+    if include_details:
+        params["includeDetails"] = True
+
     response = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "run_tests", params)
     await ctx.info(f'Response {response}')
     return RunTestsResponse(**response) if isinstance(response, dict) else response

transport/plugin_hub.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import os
 import time
 import uuid
 from typing import Any
@@ -12,6 +13,7 @@ from starlette.endpoints import WebSocketEndpoint
 from starlette.websockets import WebSocket
 
 from core.config import config
+from models.models import MCPResponse
 from transport.plugin_registry import PluginRegistry
 from transport.models import (
     WelcomeMessage,
@@ -28,6 +30,10 @@ from transport.models import (
 logger = logging.getLogger("mcp-for-unity-server")
 
 
+class PluginDisconnectedError(RuntimeError):
+    """Raised when a plugin WebSocket disconnects while commands are in flight."""
+
+
 class PluginHub(WebSocketEndpoint):
     """Manages persistent WebSocket connections to Unity plugins."""
 
@@ -35,10 +41,15 @@ class PluginHub(WebSocketEndpoint):
     KEEP_ALIVE_INTERVAL = 15
     SERVER_TIMEOUT = 30
     COMMAND_TIMEOUT = 30
+    # Fast-path commands should never block the client for long; return a retry hint instead.
+    # This helps avoid the Cursor-side ~30s tool-call timeout when Unity is compiling/reloading
+    # or is throttled while unfocused.
+    _FAST_FAIL_COMMANDS: set[str] = {"read_console", "get_editor_state", "ping"}
 
     _registry: PluginRegistry | None = None
     _connections: dict[str, WebSocket] = {}
-    _pending: dict[str, asyncio.Future] = {}
+    # command_id -> {"future": Future, "session_id": str}
+    _pending: dict[str, dict[str, Any]] = {}
     _lock: asyncio.Lock | None = None
     _loop: asyncio.AbstractEventLoop | None = None
 
@@ -95,6 +106,21 @@ class PluginHub(WebSocketEndpoint):
                 (sid for sid, ws in cls._connections.items() if ws is websocket), None)
             if session_id:
                 cls._connections.pop(session_id, None)
+                # Fail-fast any in-flight commands for this session to avoid waiting for COMMAND_TIMEOUT.
+                pending_ids = [
+                    command_id
+                    for command_id, entry in cls._pending.items()
+                    if entry.get("session_id") == session_id
+                ]
+                for command_id in pending_ids:
+                    entry = cls._pending.get(command_id)
+                    future = entry.get("future") if isinstance(entry, dict) else None
+                    if future and not future.done():
+                        future.set_exception(
+                            PluginDisconnectedError(
+                                f"Unity plugin session {session_id} disconnected while awaiting command_result"
+                            )
+                        )
                 if cls._registry:
                     await cls._registry.unregister(session_id)
                 logger.info(
@@ -108,6 +134,39 @@ class PluginHub(WebSocketEndpoint):
         websocket = await cls._get_connection(session_id)
         command_id = str(uuid.uuid4())
         future: asyncio.Future = asyncio.get_running_loop().create_future()
+        # Compute a per-command timeout:
+        # - fast-path commands: short timeout (encourage retry)
+        # - long-running commands (e.g., run_tests): allow caller to request a longer timeout via params
+        unity_timeout_s = float(cls.COMMAND_TIMEOUT)
+        server_wait_s = float(cls.COMMAND_TIMEOUT)
+        if command_type in cls._FAST_FAIL_COMMANDS:
+            try:
+                fast_timeout = float(os.environ.get("UNITY_MCP_FAST_COMMAND_TIMEOUT", "3"))
+            except Exception:
+                fast_timeout = 3.0
+            unity_timeout_s = fast_timeout
+            server_wait_s = fast_timeout
+        else:
+            # Common tools pass a requested timeout in seconds (e.g., run_tests(timeout_seconds=900)).
+            requested = None
+            try:
+                if isinstance(params, dict):
+                    requested = params.get("timeout_seconds", None)
+                    if requested is None:
+                        requested = params.get("timeoutSeconds", None)
+            except Exception:
+                requested = None
+
+            if requested is not None:
+                try:
+                    requested_s = float(requested)
+                    # Clamp to a sane upper bound to avoid accidental infinite hangs.
+                    requested_s = max(1.0, min(requested_s, 60.0 * 60.0))
+                    unity_timeout_s = max(unity_timeout_s, requested_s)
+                    # Give the server a small cushion beyond the Unity-side timeout to account for transport overhead.
+                    server_wait_s = max(server_wait_s, requested_s + 5.0)
+                except Exception:
+                    pass
 
         lock = cls._lock
         if lock is None:
@@ -117,18 +176,35 @@ class PluginHub(WebSocketEndpoint):
             if command_id in cls._pending:
                 raise RuntimeError(
                     f"Duplicate command id generated: {command_id}")
-            cls._pending[command_id] = future
+            cls._pending[command_id] = {"future": future, "session_id": session_id}
 
         try:
             msg = ExecuteCommandMessage(
                 id=command_id,
                 name=command_type,
                 params=params,
-                timeout=cls.COMMAND_TIMEOUT,
+                timeout=unity_timeout_s,
             )
-            await websocket.send_json(msg.model_dump())
-            result = await asyncio.wait_for(future, timeout=cls.COMMAND_TIMEOUT)
-            return result
+            try:
+                await websocket.send_json(msg.model_dump())
+            except Exception as exc:
+                # If send fails (socket already closing), fail the future so callers don't hang.
+                if not future.done():
+                    future.set_exception(exc)
+                raise
+            try:
+                result = await asyncio.wait_for(future, timeout=server_wait_s)
+                return result
+            except PluginDisconnectedError as exc:
+                return MCPResponse(success=False, error=str(exc), hint="retry").model_dump()
+            except asyncio.TimeoutError:
+                if command_type in cls._FAST_FAIL_COMMANDS:
+                    return MCPResponse(
+                        success=False,
+                        error=f"Unity did not respond to '{command_type}' within {server_wait_s:.1f}s; please retry",
+                        hint="retry",
+                    ).model_dump()
+                raise
         finally:
             async with lock:
                 cls._pending.pop(command_id, None)
@@ -245,7 +321,8 @@ class PluginHub(WebSocketEndpoint):
             return
 
         async with lock:
-            future = cls._pending.get(command_id)
+            entry = cls._pending.get(command_id)
+        future = entry.get("future") if isinstance(entry, dict) else None
         if future and not future.done():
             future.set_result(result)
 
@@ -364,6 +441,40 @@ class PluginHub(WebSocketEndpoint):
         params: dict[str, Any],
     ) -> dict[str, Any]:
         session_id = await cls._resolve_session_id(unity_instance)
+
+        # During domain reload / immediate reconnect windows, the plugin may be connected but not yet
+        # ready to process execute commands on the Unity main thread (which can be further delayed when
+        # the Unity Editor is unfocused). For fast-path commands, we do a bounded readiness probe using
+        # a main-thread ping command (handled by TransportCommandDispatcher) rather than waiting on
+        # register_tools (which can be delayed by EditorApplication.delayCall).
+        if command_type in cls._FAST_FAIL_COMMANDS and command_type != "ping":
+            try:
+                max_wait_s = float(os.environ.get("UNITY_MCP_SESSION_READY_WAIT_SECONDS", "6"))
+            except Exception:
+                max_wait_s = 6.0
+            max_wait_s = max(0.0, min(max_wait_s, 30.0))
+            if max_wait_s > 0:
+                deadline = time.monotonic() + max_wait_s
+                while time.monotonic() < deadline:
+                    try:
+                        probe = await cls.send_command(session_id, "ping", {})
+                    except Exception:
+                        probe = None
+
+                    # The Unity-side dispatcher responds with {status:"success", result:{message:"pong"}}
+                    if isinstance(probe, dict) and probe.get("status") == "success":
+                        result = probe.get("result") if isinstance(probe.get("result"), dict) else {}
+                        if result.get("message") == "pong":
+                            break
+                    await asyncio.sleep(0.1)
+                else:
+                    # Not ready within the bounded window: return retry hint without sending.
+                    return MCPResponse(
+                        success=False,
+                        error=f"Unity session not ready for '{command_type}' (ping not answered); please retry",
+                        hint="retry",
+                    ).model_dump()
+
         return await cls.send_command(session_id, command_type, params)
 
     # ------------------------------------------------------------------

transport/unity_instance_middleware.py

@@ -83,11 +83,101 @@ class UnityInstanceMiddleware(Middleware):
         with self._lock:
             self._active_by_key.pop(key, None)
 
+    async def _maybe_autoselect_instance(self, ctx) -> str | None:
+        """
+        Auto-select the sole Unity instance when no active instance is set.
+
+        Note: This method both *discovers* and *persists* the selection via
+        `set_active_instance` as a side-effect, since callers expect the selection
+        to stick for subsequent tool/resource calls in the same session.
+        """
+        try:
+            # Import here to avoid circular dependencies / optional transport modules.
+            from transport.unity_transport import _current_transport
+
+            transport = _current_transport()
+            if PluginHub.is_configured():
+                try:
+                    sessions_data = await PluginHub.get_sessions()
+                    sessions = sessions_data.sessions or {}
+                    ids: list[str] = []
+                    for session_info in sessions.values():
+                        project = getattr(session_info, "project", None) or "Unknown"
+                        hash_value = getattr(session_info, "hash", None)
+                        if hash_value:
+                            ids.append(f"{project}@{hash_value}")
+                    if len(ids) == 1:
+                        chosen = ids[0]
+                        self.set_active_instance(ctx, chosen)
+                        logger.info(
+                            "Auto-selected sole Unity instance via PluginHub: %s",
+                            chosen,
+                        )
+                        return chosen
+                except (ConnectionError, ValueError, KeyError, TimeoutError, AttributeError) as exc:
+                    logger.debug(
+                        "PluginHub auto-select probe failed (%s); falling back to stdio",
+                        type(exc).__name__,
+                        exc_info=True,
+                    )
+                except Exception as exc:
+                    if isinstance(exc, (SystemExit, KeyboardInterrupt)):
+                        raise
+                    logger.debug(
+                        "PluginHub auto-select probe failed with unexpected error (%s); falling back to stdio",
+                        type(exc).__name__,
+                        exc_info=True,
+                    )
+
+            if transport != "http":
+                try:
+                    # Import here to avoid circular imports in legacy transport paths.
+                    from transport.legacy.unity_connection import get_unity_connection_pool
+
+                    pool = get_unity_connection_pool()
+                    instances = pool.discover_all_instances(force_refresh=True)
+                    ids = [getattr(inst, "id", None) for inst in instances]
+                    ids = [inst_id for inst_id in ids if inst_id]
+                    if len(ids) == 1:
+                        chosen = ids[0]
+                        self.set_active_instance(ctx, chosen)
+                        logger.info(
+                            "Auto-selected sole Unity instance via stdio discovery: %s",
+                            chosen,
+                        )
+                        return chosen
+                except (ConnectionError, ValueError, KeyError, TimeoutError, AttributeError) as exc:
+                    logger.debug(
+                        "Stdio auto-select probe failed (%s)",
+                        type(exc).__name__,
+                        exc_info=True,
+                    )
+                except Exception as exc:
+                    if isinstance(exc, (SystemExit, KeyboardInterrupt)):
+                        raise
+                    logger.debug(
+                        "Stdio auto-select probe failed with unexpected error (%s)",
+                        type(exc).__name__,
+                        exc_info=True,
+                    )
+        except Exception as exc:
+            if isinstance(exc, (SystemExit, KeyboardInterrupt)):
+                raise
+            logger.debug(
+                "Auto-select path encountered an unexpected error (%s)",
+                type(exc).__name__,
+                exc_info=True,
+            )
+
+        return None
+
     async def _inject_unity_instance(self, context: MiddlewareContext) -> None:
         """Inject active Unity instance into context if available."""
         ctx = context.fastmcp_context
 
         active_instance = self.get_active_instance(ctx)
+        if not active_instance:
+            active_instance = await self._maybe_autoselect_instance(ctx)
         if active_instance:
             # If using HTTP transport (PluginHub configured), validate session
             # But for stdio transport (no PluginHub needed or maybe partially configured),

transport/unity_transport.py

@@ -9,6 +9,7 @@ from typing import Awaitable, Callable, TypeVar
 from fastmcp import Context
 
 from transport.plugin_hub import PluginHub
+from models.models import MCPResponse
 from models.unity_response import normalize_unity_response
 from services.tools import get_unity_instance_from_context
 
@@ -91,12 +92,21 @@ async def send_with_unity_instance(
         if not isinstance(params, dict):
             raise TypeError(
                 "Command parameters must be a dict for HTTP transport")
-        raw = await PluginHub.send_command_for_instance(
-            unity_instance,
-            command_type,
-            params,
-        )
-        return normalize_unity_response(raw)
+        try:
+            raw = await PluginHub.send_command_for_instance(
+                unity_instance,
+                command_type,
+                params,
+            )
+            return normalize_unity_response(raw)
+        except Exception as exc:
+            # NOTE: asyncio.TimeoutError has an empty str() by default, which is confusing for clients.
+            err = str(exc) or f"{type(exc).__name__}"
+            # Fail fast with a retry hint instead of hanging for COMMAND_TIMEOUT.
+            # The client can decide whether retrying is appropriate for the command.
+            return normalize_unity_response(
+                MCPResponse(success=False, error=err, hint="retry").model_dump()
+            )
 
     if unity_instance:
         kwargs.setdefault("instance_id", unity_instance)