docs: Streamline README for faster onboarding #583
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Major restructuring to reduce README from ~500 lines to ~200 lines while preserving all essential information. Changes: - Add prominent "Quick Start" section at top with prerequisites and 5-step setup - Highlight Git package URL with GitHub TIP admonition for visibility - Collapse detailed content into expandable sections: - Features & Tools - Manual Configuration (with nested stdio legacy config) - Multiple Unity Instances - Roslyn Script Validation - Troubleshooting - Contributing - Telemetry & Privacy - Keep Star History and Coplay sections always visible - Condense tools/resources from verbose lists to compact bullet format - Add step 5 for client connection (toggle for Cursor/Windsurf/Antigravity) The goal is 1-2 screens of visible content for new users to get started quickly, with all details accessible via dropdowns for those who need them.
Contributor
Reviewer's GuideREADME.md is heavily restructured to prioritize a top-of-page Quick Start flow, collapse advanced/reference content, and streamline wording while preserving key setup, configuration, and reference details. Flow diagram for new Quick Start setup pathflowchart TD
A[Open README on GitHub] --> B[Scan logo badges summary GIF]
B --> C[Review Quick_Start prerequisites]
C --> D[Install Unity package via Git Git_URL from TIP box]
D --> E[Optionally use Asset Store or OpenUPM instead]
D --> F[Open Unity Window MCP_for_Unity]
F --> G[Click Start_Server - HTTP localhost:8080]
G --> H[Select MCP client in Unity window]
H --> I[Click Configure]
I --> J{Client connected?}
J -->|Yes| K[Send first prompt in MCP client]
J -->|No| L[Open Manual_Configuration collapsed section]
L --> M[Update MCP client JSON config]
M --> I
K --> N[Optionally open collapsed sections for Features Tools Multiple_Instances Roslyn Troubleshooting]
N --> O[Iterate on Unity project with LLM]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Contributor
📝 WalkthroughWalkthroughThe README was rewritten and reorganized: intro tightened to emphasize Model Context Protocol (MCP), content restructured into user-facing sections (Quick Start, Key Features, Available Tools, Resources, How It Works, Installation, Troubleshooting, Telemetry & Privacy, Contributing, License), and many long sections collapsed into terse details/summary blocks. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
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. Comment |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The new Quick Start is much clearer, but consider keeping a short explicit note near the server section that the HTTP URL must include the
/mcpsuffix, since that was previously called out and is easy to miss for manual config users. - In the Roslyn Script Validation section, you removed the manual DLL installation path—if that’s still supported, it might be worth linking to a separate doc or briefly mentioning that an advanced manual option exists for teams that can’t use NuGetForUnity.
- You’ve collapsed a lot of detailed troubleshooting and platform-specific paths into a single Troubleshooting section; consider preserving at least the per‑OS default server install paths (Windows/macOS/Linux) in that section so users can still quickly verify their config without digging through history.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The new Quick Start is much clearer, but consider keeping a short explicit note near the server section that the HTTP URL must include the `/mcp` suffix, since that was previously called out and is easy to miss for manual config users.
- In the Roslyn Script Validation section, you removed the manual DLL installation path—if that’s still supported, it might be worth linking to a separate doc or briefly mentioning that an advanced manual option exists for teams that can’t use NuGetForUnity.
- You’ve collapsed a lot of detailed troubleshooting and platform-specific paths into a single Troubleshooting section; consider preserving at least the per‑OS default server install paths (Windows/macOS/Linux) in that section so users can still quickly verify their config without digging through history.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@README.md`:
- Around line 34-42: Add a language identifier (e.g., text) to the fenced code
blocks that contain the Git URLs in README.md so markdown linters render them
correctly; update the two fenced blocks surrounding the URL strings
"https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity" and
"https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v9.0.3" to use
```text instead of ``` (ensure both opening triple-backtick lines are changed).
🧹 Nitpick comments (1)
README.md (1)
63-63: Clarify client connection instructions.The distinction between clients that require manual toggle vs. auto-connect is somewhat unclear. Consider reorganizing this into clearer categories or providing a brief table/list for each connection method.
📋 Suggested restructure
5. **Connect your client:** - **Cursor, Windsurf, Antigravity:** Enable the MCP toggle in settings - **Claude Desktop, Claude Code:** Auto-connect once configured in the Unity MCP windowOr alternatively, keep it as a single sentence but clarify the logic:
5. **Connect your client:** Some clients (Cursor, Windsurf, Antigravity) require enabling an MCP toggle in settings, while others (Claude Desktop, Claude Code) auto-connect after configuration.
- Add `text` language identifier to Git URL code blocks for linter compliance - Clarify step 5 client connection instructions with clearer categorization - Add nested dropdown for manual Roslyn DLL installation option
vbucc
added a commit
to Studio-Pronto/unity-mcp
that referenced
this pull request
Jan 19, 2026
Upstream changes (v9.0.7 → v9.0.8): - fix: UIDocument serialization to prevent infinite loops (CoplayDev#586) - fix: Filter isCompiling false positives in Play mode (CoplayDev#582) - fix: search inactive objects when setActive=true (CoplayDev#581) - fix: Add Prefab Stage support for GameObject lookup (CoplayDev#573) - fix: Prevent infinite compilation loop in Unity 6 (CoplayDev#559) - fix: parse and validate read_console types (CoplayDev#565) - fix: Local HTTP server UI check (CoplayDev#556) - fix: Claude Code HTTP Remote UV path override detection - fix: ULF detection in Claude licensing (CoplayDev#569) - chore: Replace asmdef GUID references (CoplayDev#564) - docs: Streamline README for faster onboarding (CoplayDev#583) - Many new client configurators (VSCode, Cursor, Windsurf, etc.) Fork enhancements preserved: - "find" instruction handler in UnityTypeConverters.cs - MarkSceneOrPrefabDirty() helper for proper Prefab Stage support - IsInPrefabStage() and GetPrefabStageRoot() helpers - #main URL reference (no version tags) - TestProjects excluded Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
4 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Major README restructuring to improve first-time user experience:
Before vs After
What's Visible Above the Fold
What's Collapsed (but accessible)
Test plan
Summary by Sourcery
Restructure and condense the README to emphasize a quick-start path and simplify onboarding for new users.
Documentation:
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.