fix: add recovery guidance when no Unity session is available (#1265)

Server/src/transport/plugin_hub.py

@@ -846,6 +846,13 @@ def _unavailable_retry_response(reason: str = "no_unity_session") -> dict[str, A
         return MCPResponse(
             success=False,
             error="Unity session not available; please retry",
+            message=(
+                "The MCP server is reachable, but the requested Unity session is unavailable. "
+                "Open Unity and start its MCP session. If the editor is already open, "
+                "bring it to the foreground and check for pending dialogs, then retry."
+                if reason == "no_unity_session"
+                else None
+            ),
             hint="retry",
             data={"reason": reason, "retry_after_ms": 250},
         ).model_dump()

website/docs/guides/troubleshooting.md

@@ -216,6 +216,21 @@ If restarting doesn't fix it:
 
 ---
 
+## HTTP server responds, but the Unity session is unavailable
+
+If a tool returns `Unity session not available; please retry` with
+`data.reason: no_unity_session`, the MCP server has handled the request, but the
+requested Unity bridge session is unavailable. Its message includes recovery
+steps; the machine-readable `hint: retry` and retry interval remain unchanged.
+
+- If Unity is compiling or reloading, allow it to finish before retrying.
+- Open Unity and confirm that its MCP for Unity session is started.
+- If the editor is already open in the background, bring it to the foreground
+  and check for pending dialogs before retrying.
+- Read `mcpforunity://instances` again to confirm that the editor has registered.
+
+---
+
 ## Unity takes focus while tests are running
 
 The server may briefly focus Unity when a running test has not reported progress,