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

[haranishi]

Description

When the HTTP server was running but no Unity session could be found, the response contained only retry information and no verification steps. Adds guidance to the no_unity_session response that tells users to launch Unity, start an MCP session, and bring the window to the foreground to check for dialogs.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Test update

Changes Made

• Adds human-readable recovery steps to the no_unity_session response in PluginHub. Explains that the server is responding and the requested Unity session is unavailable.
• Preserves the existing error, hint: retry, data.reason, and retry_after_ms: 250. Places the guidance in the existing message field and leaves the stale_connection response unchanged.
• Adds steps to the troubleshooting guide: confirm that reloading has completed, start a session, bring Unity from the background to the foreground, and recheck instance registration.

Compatibility / Package Source

• Unity version(s) tested: Not applicable (changes to the Python server and documentation).
• Package source used (#beta, #main, tag, branch, or file:): Source branched from 142ea0a on beta.
• Resolved commit hash from Packages/packages-lock.json (if using a Git package URL): Not applicable.

Testing/Screenshots/Recordings

• Python tests (cd Server && uv run pytest tests/ -v): 1,575 passed, 18 skipped.
• Unity EditMode tests
• Unity PlayMode tests
• Package import/compile check
• Not applicable (explain why in Additional Notes)

Started an isolated localhost HTTP server and used the real FastMCP SDK to initialize it, read mcpforunity://instances, and call 2 tools. The server was healthy, with 0 Unity registrations, and before the fix, both read_console and refresh_unity(wait_for_ready=false) returned message: null.

After the fix, received recovery guidance from both tools and verified that the existing error and retry information was unchanged. Also verified that the endpoint stopped responding after the verification server was shut down. Verification used an empty registration state without mocking requests to Unity or session resolution.

The generated-docs consistency check and site build succeeded. Also ran the prescribed multi-version Unity check, but all 4 specified versions were skipped because they were not installed.

Also ran the same coverage-enabled test run as CI, locally on Python 3.10.20, with 1,575 passed and 18 skipped. tools/tests had 205 passed, and the generated-docs check and tool count comparison also succeeded.

Documentation Updates

• I have added/removed/modified tools or resources
• If yes, I have updated all documentation files using:
  • The LLM prompt at tools/UPDATE_DOCS_PROMPT.md (recommended)
  • Manual review of the generated changes

There are no changes to tool definitions, arguments, or counts. Adds the guidance to the troubleshooting documentation.

Related Issues

Relates to #1265

Additional Notes

Addresses the request for diagnostic guidance in #1265. Session loss while Unity is in the background and stalled compilation remain open issues. Since the changes affect only the Python server and documentation, Unity EditMode, PlayMode, and package compile verification are not applicable.

Fork CI verification

Checked the GitHub Actions results for the same commit 9fcf0416c77b854afe6c4ab0c291f5f3a79923f5. The Python tests succeeded, as did the harness tests that run without Unity.

The docs build succeeded.

The upstream GitHub Actions are waiting for a maintainer to approve the run for the current commit. The CI successes above are results from runs on the fork that verified the same commit.

Summary by CodeRabbit

• Bug Fixes

  • Responses caused by an unavailable Unity session now include an actionable message. Other retry responses remain unchanged.

• Documentation

  • Added troubleshooting guidance for unavailable Unity sessions, including checks for editor reloads, session startup, pending dialogs, and instance registration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 86277d5d-f9ac-4f4f-bfc8-db2397a1335e

📥 Commits

Reviewing files that changed from the base of the PR and between 142ea0a and 9fcf041.

📒 Files selected for processing (2)

• Server/src/transport/plugin_hub.py
• website/docs/guides/troubleshooting.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review.

📝 Walkthrough

The unavailable-session retry response now includes a user-facing message for no_unity_session. The troubleshooting guide explains the response and lists checks for Unity session availability.

Changes: Unity Session Retry Guidance

Layer / File(s)	Summary
Retry message and troubleshooting guidance Server/src/transport/plugin_hub.py, website/docs/guides/troubleshooting.md	For no_unity_session, the retry response now includes a message directing users to start Unity or address pending dialogs. The guide describes the response and lists checks for Unity state and editor registration.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: scriptwonder

Merge Risk: ⚪ Minimal · up to 9fcf0

No material merge-blocking risk remains; the recovery guidance is available on the HTTP MCP response path it changes.

Pre-merge checks · 4 · 1

Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 1 files. (1 skipped: 1 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks (4 passed)

Check name	Status	Explanation
Description check		The description follows the repository template. It includes the change summary, change type, detailed changes, compatibility information, testing results, documentation notes, related issue, and addi…
Title check		The title clearly and concisely describes the primary change: adding recovery guidance when no Unity session is available.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 1 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[haranishi]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.