CodeRabbit + Copilot review fixes that don't touch the generated tool
reference. Generator change + regenerated pages come in a follow-up
commit.
docs:
- guides/uv-setup.md: Python requirement was wrongly 3.12+; the server
pyproject declares >=3.10. Verify command + body updated to 3.10+.
Homebrew tip retains 3.12 as a reasonable default.
- getting-started/index.md: drop "(coming soon)" placeholders for
Your First Prompt and Choosing an MCP Client — both pages exist
in this PR. Setup Wizard remains "coming soon" (not in this PR).
- .github/ISSUE_TEMPLATE/bug_report.yml: troubleshooting link pointed
at /guides/cursor (deleted earlier in this branch); now points at
/guides/troubleshooting which is where that content lives.
components:
- CopyButton: track setTimeout in a useRef, clear it on unmount and
before scheduling a new one. Prevents React "setState on unmounted
component" warnings and stops timer-stacking on rapid clicks.
- HomeArchitecture diagram <div>: now role="img" with a descriptive
aria-label that explains the layer flow, so assistive tech actually
announces the diagram instead of skipping it.
workflows (security):
- docs-deploy.yml, docs-generate.yml: add `persist-credentials: false`
on actions/checkout — these jobs never push, so the token shouldn't
linger in the checked-out worktree (zizmor `artipacked` warning).
- sync-releases.yml:
- Workflow-level permissions narrowed to `contents: read`; the
`sync` job opts into `contents: write` itself. `drift-check`
stays read-only.
- drift-check job: was gated on `pull_request` but the workflow had
no pull_request trigger — unreachable code. Added a paths-scoped
pull_request trigger so PRs touching the sync script or the synced
docs run the check.
- `sync` job retains `persist-credentials: true` (it pushes back).
- drift-check checkout gets `persist-credentials: false`.
CodeRabbit comments NOT addressed in this PR and why:
- execute_menu_item 'exists' mode, script_apply_edits malformed JSON,
find_gameobjects empty param descriptions: all live in the Python
tool's source description string under Server/src/services/tools/.
Fixing upstream is a separate code PR; the generator faithfully
renders whatever source provides.
- React 18.3.1 / Docusaurus 3.10.1 bump: out of scope for this docs
PR; the lockfile already permits the latest 18.x, and a Docusaurus
minor bump is a separate dependency PR.
- robots.txt sitemap 404 check: will resolve as soon as Pages serves
the site on the canonical URL. Not a real bug.
- sidebars.js duplicate roadmap: /architecture/roadmap is the 2026
feature deep-research; /architecture/project-roadmap is the wiki
living roadmap. Two distinct docs, intentional.
- scripting_ext group blurb: comes from the registry TOOL_GROUPS map;
wording tweak not worth touching in a docs PR.
- docusaurus.config.js: count *.Configurator.cs files in
MCPForUnity/Editor/Clients/Configurators/ at build time, expose
via siteConfig.customFields.supportedClientCount. No hand-maintained
constant to forget — the homepage stats row stays accurate forever.
Current count: 21.
- HomeStats: reads the count via useDocusaurusContext. Replaces the
"12+" hardcode with the real number.
- HomeHero tagline + README intro + Overview doc intro: replace
"Claude, Claude Code, Cursor, VS Code, Windsurf" with the more
representative "Claude, Codex, VS Code, local LLMs, and more" —
reflects the actual client lineup that matters today.
Verified live: stats row reads "21 MCP clients supported"; hero
tagline reads "Claude, Codex, VS Code, local LLMs, and more".
Custom React landing page replaces the markdown-doc-as-homepage.
Refined CSS for a calmer, more spacious feel. Navbar gets icon
links for GitHub/Discord and a Reference + Releases quick-jump.
What lands:
- src/pages/index.js + 3 components (HomeHero, HomeStats, HomeFeatures):
hero with eyebrow, large headline, install one-liner, dual CTA;
4-cell stats row (43 tools, 25 resources, 12+ clients, Unity 2021.3+
through 6.x); 6-card feature grid linking to the most important
docs (tools, multi-instance, transports, tool-groups, docs-workflow,
custom-tools).
- getting-started/index.md slug moved from / to /getting-started so
the custom landing can claim the root. Title harmonized with
sidebar label ("Overview"); body H1 + intro updated to match.
- docusaurus.config.js navbar:
- Added Reference and Releases as left items (quick access to the
two most-trafficked pages)
- GitHub + Discord text labels replaced with icon links via
.header-icon-link CSS class + inline SVG backgrounds. Dark-mode
invert via CSS variable.
- src/css/custom.css:
- 16px base, 1.7 line-height, generous heading spacing
- Tighter heading letter-spacing (-0.012 to -0.022em)
- Subtle code-block borders, no garish shadow
- Cleaner tables (rounded, single border, no internal grid)
- Sidebar font 0.92rem, calmer hover/active states
- Navbar: no shadow, subtle bottom border, tighter height
- --ifm-toc-border-color set transparent for cleaner right rail
- Dark mode background tuned to near-black
Verified: npm run build clean. Smoke test: / returns custom hero,
/getting-started returns the doc, /guides/uv-setup renders new
wiki content, /guides/cursor correctly 404s.
9 hand-written pages flagged NEW in the locked IA. All wired into
sidebars.js and verified by `npm run build`.
Getting Started:
- first-prompt.md: end-to-end "build a red cube" walkthrough with the
exact MCP tool chain the assistant should call, common failure modes,
and escalating prompts that exercise other groups.
- clients.md: capability matrix across all 12 supported MCP clients
(transport, auto-config, streaming, free tier, per-client toggles).
Guides:
- multi-instance.md: set_active_instance semantics — Name@hash, hash
prefix, port shorthand; HTTP vs stdio isolation; per-call unity_instance
routing for cross-project prompts.
- tool-groups.md: the 9 groups, how manage_tools(activate/deactivate/
list_groups/sync/reset) works, why per-session visibility exists
(prompt economy, routing clarity, package hygiene), server vs session
state reconciliation.
Architecture:
- transports.md: HTTP vs stdio decision matrix, the architecture of each,
what instance routing semantics each gives you, network security guards
(loopback by default, LAN/remote opt-in).
- python-layers.md: the three Python surfaces (MCP tools, CLI commands,
resources), why they're hand-maintained instead of auto-generated,
domain symmetry rule.
- unity-compat.md: the four active shims, when to add a new shim, what
doesn't belong in a shim, static-dispatch vs reflection patterns,
link to the canonical UnityCompatShims.cs marker class.
Contributing:
- testing.md: Python pytest, Unity EditMode/PlayMode, multi-version
compile matrix, pre-push/pre-commit hooks, stress scripts, CI surface.
- docs.md: hand-written vs auto-generated split, examples block
preservation rule, slug discipline (brand-neutral), redirect protocol
for slug renames, CommonMark vs MDX.
sidebars.js: uncommented the NEW entries; left reference/cli and
reference/manifest TODOs in place for a follow-up.
Verified:
- npm run build succeeds (Client 2.4s, Server 1.1s) with no errors
Typography upgrade matching modern AI-product docs sites (e.g. benchflow):
- Satoshi (Fontshare, weights 300/400/500/700/900) for body and headings
- JetBrains Mono (Google Fonts, 400/500/700) for monospace
- Loaded via stylesheet links + preconnect hints in docusaurus.config.js
- custom.css updates: --ifm-font-family-base, --ifm-font-family-monospace,
tighter heading letter-spacing, slightly bumped line-height for Satoshi,
brand color shifted to indigo (#4f46e5) to pair with the new sans
- Inline code nudged 0.88em to sit on Satoshi's baseline
Emojis removed across all in-house content for a cleaner, professional
tone:
- generator banner: dropped the gear glyph
- generator parameter table: required column is now "yes" / "—" instead
of an emoji checkbox (regenerated all 43 tool pages)
- install.md: status-text instead of green-dot emoji
- SECURITY.md: Yes / No instead of check/cross
- ISSUE_TEMPLATE/config.yml: plain link labels, no leading emoji
Verified:
- npm run build succeeds (5.7s client, 4.5s server)
- generator --check exits 0 (deterministic regeneration)
- HTML head includes both font stylesheets + preconnect hints
- CSS bundle resolves Satoshi and JetBrains Mono font-family stacks
Two M1 follow-ups uncovered by the first local `npm run build`:
1. MDX 3 was treating `{name: value}`, `{r, g, b, a}`, `<T>` and the
multi-line JSON examples in tool descriptions as JS expressions /
JSX tags. All 7 generated reference pages failed to compile.
Fix: markdown.format = 'detect' — .md uses CommonMark (no expression
parsing), .mdx keeps full MDX for future interactive components.
2. Visiting localhost:3000/unity-mcp/ landed on an empty docs index.
Fix: getting-started/index.md slug '/getting-started' → '/'. Now
the site root IS the Overview page; install stays at
/getting-started/install/. Footer link updated to match.
Also nests onBrokenMarkdownLinks under markdown.hooks (the deprecated
top-level option is removed in Docusaurus v4).
15 existing markdown files moved with git mv (history preserved), wired
into the Docusaurus sidebar across Guides, Architecture, Contributing,
and Migrations categories. Images that the migration docs reference
copied into website/static/img/ and refs rewritten to /img/...
Brand-neutral URL strategy holds: every slug omits "mcp-for-unity" /
"unity-mcp" — e.g. /guides/cli, /architecture/remote-auth,
/migrations/v8. A future rename touches docusaurus.config.js, not URLs.
Deferred to a follow-up:
- docs/development/README-DEV-zh.md (Chinese dev guide)
- docs/i18n/README-zh.md (Chinese overview)
These need Docusaurus i18n config (defaultLocale + zh in locales) and
a full translation pass before they make sense on the site.
Minor edits limited to making files build-clean (M2 plan: no content
rewrites):
- Front-matter added to cli-examples.md and cursor.md (no top-level H1)
- v8.md's [CUSTOM_TOOLS.md] link repointed at /guides/custom-tools
- dev-setup.md's broken language switcher repointed at GitHub source
- install.md's M2 forward-reference link now goes to /guides/client-configurators
Root README still points at docs/images/ for its hero gif — that path
keeps working because the images remain in docs/images/ for now and
will move only when README is slimmed in M5.
Stand up /website with Docusaurus 3.x, hand-written so the scaffold ships
exactly what we need (no default blog, no tutorial-basics clutter).
What lands in M1:
- /website/ structure: package.json, docusaurus.config.js, sidebars.js,
src/css/custom.css, static/{logo,favicon,social-card,.nojekyll}
- Getting Started: Overview + Install pages (extracted from README §1-2)
- .github/workflows/docs-deploy.yml: builds on PR, deploys to
https://coplaydev.github.io/unity-mcp/ on push to beta
- @easyops-cn/docusaurus-search-local for day-1 search (Algolia DocSearch
application is M5)
URL strategy is brand-neutral: slugs like /getting-started/ and (later)
/reference/tools/manage-script — never /mcp-for-unity/... — so a future
product rename touches docusaurus.config.js, not URLs.
Subsequent milestones:
- M2: migrate /docs/* into /website/docs/ per locked IA
- M3: tools/generate_docs_reference.py + auto-generated tool catalog
- M4: net-new content pages (First Prompt, Multi-Instance, etc.)
- M5: slim root README to a landing card + governance files
See /Users/scriptwonder/.claude/plans/as-unity-mcp-coming-close-indexed-karp.md
for the full plan.
Shutong Wu