Measured four concurrent agents against one Editor over the HTTP
transport (527 client calls, 1498 commands through the bridge at
97.9% success). The Editor stayed healthy throughout, so the notes
below are about degradation modes, not failure.
Guide gains a section on running several agents at once: a single
Editor executes one command at a time, so reads stretched from ~5s
to ~17s behind another agent's writes and batching bought nothing
(~2-3s per call regardless of batch size). Also documents that
'Available: none' is a transient reconnect artifact rather than an
absent Editor, and tabulates when a failed call is safe to retry.
Architecture doc records two gaps found while measuring. Instance
resolution runs before dispatch and hard-fails while the registry
is briefly empty during a domain reload, which was roughly seven in
ten client-visible errors. And a timed-out command is not cancelled
in Unity: send_command pops the pending future, so a command already
executing runs to completion and its result is discarded, reporting
failure for an effect that landed. Commands still queued when the
socket drops are lost cleanly instead.
Also corrects the claim that throughput had not been measured; the
numbers support the existing no-broker decision, since serialization
comes from Unity's single-threaded main loop rather than the layer a
broker would occupy.
A resource's name and its URI are deliberately different (`editor_state` vs
`mcpforunity://editor/state`), and the URI scheme is not derivable from the
name -- most resources are `category/thing` but several are flat
(`mcpforunity://instances`, `mcpforunity://menu-items`, `mcpforunity://tests`).
Several agent-facing strings still named resources without their URI, so an
agent following them built `mcpforunity://editor_state` and got a 404:
- server instructions listed resources by bare name and told the reader to
"poll the `editor_state` resource's `isCompiling` field" (that field path is
also wrong -- payloads are wrapped, so it is `data.compilation.is_compiling`)
- `refresh_unity`'s `wait_for_ready` parameter description referred to
`editor_state.advice.ready_for_tools`
- the hint Unity returns in the `refresh_unity` result said "poll editor_state
until ready_for_tools is true"
#1244 added a warning that names and URIs are not interchangeable, but left the
strings that trigger the mistake unchanged. Spell every resource reference as a
full URI instead, and correct the field paths while here.
Adds a regression test asserting that no agent-facing prose -- server
instructions, resource descriptions, tool and parameter descriptions, and
multi-word string literals under MCPForUnity/Editor -- mentions a resource by
its snake_case name without also giving that resource's URI.
Fixes#1297. At action:"create", component_properties was accepted and
coerced by the C# dispatcher (ManageGameObject.cs) but only ever consumed
by the "modify" handler, so it silently did nothing. Meanwhile the shape
"create" already reads directly out of each componentsToAdd entry
({typeName, properties}) was rejected before it reached Unity, because the
Python schema typed components_to_add as list[str].
- GameObjectComponentHelpers.cs: factor the componentProperties loop +
error aggregation out of GameObjectModify.cs into a shared
ApplyComponentProperties helper, so both actions apply it identically.
- GameObjectCreate.cs: call the new helper after components are added,
destroying the partially-created object and returning the error if any
property fails to set (matching how component-add failures are handled).
- GameObjectModify.cs: switch to the shared helper (behavior-preserving
refactor, no functional change on the modify path).
- manage_gameobject.py: widen components_to_add to accept
{"typeName": ..., "properties": {...}} objects alongside plain strings,
matching what GameObjectCreate.cs already reads.
- Regenerated website/docs/reference/tools/core/manage_gameobject.md via
tools/generate_docs_reference.py for the updated parameter docs.
Tested: Server/tests/test_manage_gameobject.py exercises the Python
contract end-to-end, including a real fastmcp/pydantic schema validation
run of the issue's exact repro payloads (confirmed the pre-fix
ValidationError reproduces on the unmodified file, and is gone after).
Added TestProjects/UnityMCPTests/Assets/Tests/EditMode/Tools/
ManageGameObjectCreateTests.cs coverage for the C# side, but this was not
run against a live Editor.
Generated by tools/generate_docs_reference.py; the "Check docs reference is
fresh" CI job flagged testing/run_tests.md as stale after clear_stuck was added.
- McpToolsSection: add the asset_gen -> "Asset Gen" group display name so
the tool-group tab no longer falls back to the raw "Asset_gen".
- Update the asset_gen group blurb (registry + CLI) to include audio gen.
- Regenerate the tool reference docs from the Python registry: add the
missing generate_audio.md and refresh the asset_gen landscape/index.
Claude-Session: https://claude.ai/code/session_015KYy51gwBuhDuLZXXoqc98
CodeRabbit follow-up on #1262: the API-level default is omitting the
parameter (nothing crosses the wire); passing 'none' explicitly maps to
the same no-rig import. Say "omitted or 'none'" instead of calling
'none' the default, and regenerate the reference page.
Claude-Session: https://claude.ai/code/session_01Cya1SZmg7CJgJS61nhjLH4
Review responses (CodeRabbit + Copilot):
- Document the 'legacy' animation_type value in the C# XML summary, MCP tool
description, param help, and CLI help (Copilot x4).
- SKILL.md: drop multi-material zones as a GLB-only trigger (both formats keep
slots), define out_glb in the glTF branch example, document the full
animation_type contract, probe both Principled emission socket names
('Emission Color' 4.x / 'Emission' 3.x), keep use_active_scene=True in the
Notes GLB example, and distinguish FBX vertex-color data transfer from URP
Lit shader display.
- bridge-fidelity.md: make export_apply conditional (static-only; skinned/
shape-key meshes need False) and document export_animations' active/NLA-
stashed semantics.
Regenerate website/docs/reference for the updated tool description — fixes the
"Check docs reference is fresh" CI failure ("differs: asset_gen/import_model_file.md").
Claude-Session: https://claude.ai/code/session_01Cya1SZmg7CJgJS61nhjLH4
- favicon now rasterized from the full logo-mark.svg (was the simplified
favicon-safe mini, which dropped the inner edges, 3rd rung, and node dots);
remove the now-unused logo-mark-mini.svg
- add docs/images/connector.svg (blue node — cyan bridge — teal node, echoing the
split-cube 'two things connected') and use it between English/中文 and Discord/Wiki
- bump the Recent Updates summary to an <h3> (one size up)
Claude-Session: https://claude.ai/code/session_01XFiuAUxNS9riUJFFBEHvui
- docs-deploy.yml: map GOATCOUNTER_CODE into the Build env so the cookieless
beacon actually activates when the maintainer sets the variable (was a
producer-without-consumer gap that silently disabled docs traffic)
- MAINTAINER_ACTIONS.md: rewrite the stats section to match the shipped private
design (drop the stale 'grant Actions write + commit data.json' over-priv item,
add the required STATS_GITHUB_TOKEN PAT, fix the social-preview note)
- docusaurus.config.js: wire favicon-32.png (was an orphaned generated asset)
- lowercase 3 stray 'MCP For Unity' refs in roslyn.md / migrations/v6.md
- remove internal docs/superpowers/ spec+plan scratch from the PR (contradicted
the shipped Ocean/private design); gitignore superpowers artifacts
Whole-branch review: 6/6 Critical/Important confirmed, 0 refuted, all docs/config
hygiene — build/tests/security/correctness all clean. These are the fixes.
Claude-Session: https://claude.ai/code/session_01XFiuAUxNS9riUJFFBEHvui
Adds GitHub real-account signals to the private maintainer summary and reorders
it honest-first:
- In-product DAU/WAU flagged as the true active-user metric (pending Coplay read API)
- Unique repo cloners/viewers (14d) via GitHub traffic API (needs STATS_GITHUB_TOKEN
PAT with Administration: read; default token 401s)
- GitHub stars/forks (public, real accounts)
- PyPI downloads kept but explicitly labeled inflated install events, not users
All fetches graceful on failure; 6 unit tests; build green.
Claude-Session: https://claude.ai/code/session_01XFiuAUxNS9riUJFFBEHvui
Per request, stop publishing adoption numbers to outsiders:
- remove the public /stats page + public data.json + navbar link
- workflow now posts a unified PyPI+traffic table to $GITHUB_STEP_SUMMARY
(visible only to repo collaborators); drops to contents: read, no commits
- fetch-stats emits Markdown (renderSummary, +2 tests) instead of a public JSON
- public side keeps only the README downloads badge (PyPI counts are public anyway)
Claude-Session: https://claude.ai/code/session_01XFiuAUxNS9riUJFFBEHvui
Single ProductInfo.{ProductName,MenuRoot} const; routes all user-facing
'MCP For Unity' (capital F) display strings to it. Internal identifiers,
namespaces, and manifest.json 'Unity MCP' unchanged.
Claude-Session: https://claude.ai/code/session_01XFiuAUxNS9riUJFFBEHvui
A one-command, no-API-key end-to-end gate for the Python<->Unity bridge,
runnable locally and in CI.
- tools/local_harness.py: boots a headless Hub-licensed Editor (or attaches
with --reuse) and runs smoke + EditMode + PlayMode legs over the bridge,
aggregating JUnit; exit codes 0-5 (pass / regression / unreachable /
no-compile / no-license / no-editor)
- Server/tests/e2e/bridge_smoke.py: deterministic no-LLM contract driver over
the real wire path; the no-LLM counterpart to claude-nl-suite.yml
- .github/workflows/e2e-bridge.yml: PR gate booting headless Unity in CI;
self-skips (warns) when Unity license secrets are absent
- .github/workflows/python-tests.yml: run the hermetic harness unit tests and
add tools/** to the path triggers
- tools/tests/test_local_harness.py: 69 hermetic unit tests for the harness's
Unity-free decision logic (discovery, version resolution, exit-code mapping)
- Document the harness in CLAUDE.md and the contributor docs
PR #1157 review surfaced that the drift-check job was failing on
outsider PRs that touched README.md for unrelated reasons (citation
tweaks, link fixes). The path filter caught any README edit even when
the recent-updates block wasn't touched, and the failure couldn't be
fixed by the PR author since they didn't have push access to commit
a regen.
Real-world reasoning: release notes can only legitimately go stale
when a release event occurs. PRs cannot introduce drift the workflow
needs to "catch" — and a drift-check that an outsider can't fix is
hostile to contributions.
Changes:
- Drop the `pull_request` trigger entirely (was only there to feed the
now-removed drift-check job).
- Drop the daily `schedule` cron. UI edits to release bodies are
caught by the `release.edited` event already; falling back to a
cron added mystery commits unattached to a release.
- Drop the `drift-check` job. Nothing left needs to gate on PRs.
- Keep `release.{published,edited,unpublished,deleted}` as the
canonical trigger, and `workflow_dispatch` as the manual hatch.
- Updated /contributing/docs page to match, with an explicit
paragraph on why PRs are NOT a trigger here.
PR #1157 review (Copilot + CodeRabbit) flagged that several tool pages
had truncated frontmatter, e.g. manage_asset rendering as:
description: "Performs asset operations (import, create, modify, delete, etc"
Root cause: the generator used `description.split(".")[0]` to derive the
frontmatter blurb. That cuts at the FIRST period — including periods
inside abbreviations and parenthesized lists ("etc.) in Unity."), so
the rendered description stopped mid-clause.
Fix: introduce `_first_sentence()` that splits on real sentence
boundaries — `.` / `!` / `?` followed by whitespace + capital, or a
paragraph break — and falls back to the whole string if no boundary
exists. Also caps absurdly long single-sentence descriptions at ~240
chars to keep frontmatter compact.
All three call sites that used the old split:
- frontmatter `description:` in render_tool_page
- group-index bullets in render_group_index
- catalog-index bullets in render_catalog_index
Regenerated all 43 tool pages + 9 group landings + catalog index +
resources catalog. Verified `--check` passes round-trip and full
website build is clean.
manage_asset now reads: "Performs asset operations (import, create,
modify, delete, etc.) in Unity."
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.
Pages is now enabled on CoplayDev/unity-mcp, so the canonical preview
URL is back to https://coplaydev.github.io/unity-mcp/.
- docusaurus.config.js: url + organizationName back to CoplayDev
- docs-deploy.yml: deploy condition narrowed back to push-to-beta only
(drops the temporary docs/v2-wiki-refresh trigger)
- README.md, website/README.md, website/static/robots.txt,
website/docs/contributing/docs.md: hardcoded scriptwonder URLs swept
back to coplaydev, and the temporary "Scriptwonder fork preview" /
"flips back to coplaydev" prose removed
Next deploy of the live site happens when this lands on upstream/beta
(via PR merge) and triggers the existing workflow.
Citation: trimmed to bibtex only — the paper info paragraph and APA
plain-text citation were nice-to-have but added vertical noise. The
bibtex carries enough metadata for both code search and academic use.
Hosting move (Scriptwonder fork preview):
- docusaurus.config.js: url + organizationName flipped to Scriptwonder
- docs-deploy.yml: deploy on push to `docs/v2-wiki-refresh` OR `beta`
(Setup Pages, Upload artifact, Deploy job conditions all updated).
Lets the live preview at scriptwonder.github.io/unity-mcp update as
we iterate, without waiting for an upstream maintainer to enable
Pages on CoplayDev/unity-mcp.
- Hardcoded URLs in README.md, website/README.md, website/static/
robots.txt swapped from coplaydev.github.io/unity-mcp to
scriptwonder.github.io/unity-mcp via a one-shot sed.
- docs.md + website/README.md retain a one-line note about flipping
back to coplaydev once upstream Pages is enabled.
After push, to make the preview actually serve:
- Settings → Pages → Source → "GitHub Actions"
on https://github.com/Scriptwonder/unity-mcp/settings/pages
The deploy job in the next push will then provision Pages on first run.
Hand-written examples on five high-traffic tool pages (preserved across
regeneration by the generator) and a proper nested Tools sidebar so
groups are collapsible categories instead of a flat list.
Examples (in <!-- examples:start --><!-- examples:end --> blocks):
- manage_gameobject: create primitives, modify (move + reparent),
delete by tag, duplicate, multi-instance routing
- manage_scene: load, paged get_hierarchy, save, create from template,
additive multi-scene editing
- manage_material: create, assign to renderer, set_material_shader_property,
tint via MaterialPropertyBlock (mode: property_block) for batching
- manage_script: REWRITTEN to match the tool's actual surface
(create / read / delete only). The previous draft conflated it with
script_apply_edits / validate_script — those examples moved to:
- script_apply_edits: replace_method, insert_method (with position
anchor), delete_method, anchor_insert (regex anchor), multi-op
atomic transaction
- batch_execute: 9-op spawn-three-colored-cubes payload, parallel/
fail_fast semantics, batch-size limits
Generator fixes (tools/generate_docs_reference.py):
- Examples-preservation regex now requires markers at line boundaries
(re.MULTILINE + ^/$ anchors). Previously the generator's own warning
banner referenced the literal `<!-- examples:start --><!-- examples:end -->`
strings and the lazy regex matched THOSE first — capturing empty
content and overwriting real examples with the placeholder
- --check mode now reads existing examples from the committed location
(passes `examples_source=TOOLS_OUT`) instead of the empty tempdir,
so CI drift detection no longer false-positives every run
- Emits `_category_.json` per group dir + a sidebar_class_name on the
catalog index — Docusaurus then renders Tools → group → tool as a
proper nested tree, with the duplicate catalog-as-child entry
CSS-hidden via .sidebar-hidden
Sidebar (sidebars.js):
- Reference > Tools is now a single category, link points to the
catalog index, items autogenerate from website/docs/reference/tools/
using the new `_category_.json` metadata for nesting
Verified: build clean, generator --check exits 0, examples survive
end-to-end regeneration round-trip.
Reworks the homepage and shared chrome into a "terminal meets blueprint"
aesthetic — mono microcopy as a deliberate signal, hairline borders,
dot-grid backdrop, no rounded blobs.
Landing components (new + reworked):
- HomeHero: status-pill eyebrow (live OPERATIONAL · v9.7.0 with a
pulsing green dot), confident "Run the Unity Editor with your AI
assistant." headline with an indigo marker-highlight on
"AI assistant", terminal-style install block with STABLE + BETA
channels and per-channel Copy buttons, refined demo frame
- HomeStats: spec-sheet treatment (// SPEC at a glance) with mono
numbers and labels in a hairline grid. 21 clients (dynamic count)
- HomeArchitecture (NEW): three-stage flow MCP client → Python server
→ Unity Editor with mono edge labels (`stdio · HTTP /mcp`,
`WebSocket · /hub/plugin`) and a filled-vs-outlined legend
- HomeFeatures: numbered index cards (01 CONTROL, 02 ROUTING, …) with
hairline borders only and mono kicker labels
- HomeCloser (NEW): closing CTA strip + uncollapsed research citation
block with full bibtex
- CopyButton (NEW): reusable clipboard component with check-feedback,
used by the install block
Asset pipeline:
- building_scene.gif (2.1 MB) → MP4 (274 KB) + WebM (290 KB), wrapped
in <video autoplay loop muted playsInline> with format fallback
- logo-mark.svg + logo-mark-dark.svg: minimal "bridge" mark (filled
node → line → outlined node), tight 40×16 viewBox so it fills the
navbar height crisply at any DPI
- social-card.png: regenerated 1200×630 (52 KB) via headless Chrome
from a Satoshi/JetBrains-Mono HTML template — corner crosshairs,
status pill, headline, spec line, URL
Navbar polish (docusaurus.config.js + custom.css):
- GitHub + Discord become icon-only links via mask-image +
background-color: currentColor (no filter-blur artifacts, theme-
aware). Reference + Releases promoted to left items
- Day/night toggle + GitHub + Discord all share 40×40 box and 0.2rem
margin so the right cluster sits on an even rhythm
- Search bar absolute-positioned to the centre of the navbar with
refined ⌘K kbd pill hints (system font for crisp ⌘ glyph, 22px
tall, 2px bottom border for Linear/Vercel-style physicality, fades
on focus)
Theme contrast hardening (custom.css):
- Pinned --ifm-heading-color (was 'inherit') and --ifm-background-color
(was '#0000' — transparent — in light mode). Buttons and link colors
that resolved through these vars were rendering invisible
- Architecture filled stages softened from solid heading-black to
emphasis-200 cards with hairline borders
- Cmd+K hint kbds switched from JetBrains Mono (fuzzy ⌘ glyph) to
system font, with refined Linear-style chrome
- dot-grid backdrop helper on the hero + closer sections
Footer: dropped the Asset Store link (lived in the More column),
kept GitHub + PyPI.
- 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".
Problem: website/docs/releases.md and the README's "Recent Updates"
block had drifted badly. README claimed v9.6.3 was the latest; the
actual latest is v9.7.0 (and there are 60 releases on record going
back to v4.0.0).
Solution:
- tools/sync_release_notes.py: pulls every non-draft release from the
GitHub Releases API and renders both files. Uses `gh api` when
available (handles auth + TLS cleanly), falls back to urllib +
certifi when not. Supports --check for CI drift detection.
- README.md: gets a sentinel-bracketed `<!-- recent-updates:start -->
... <!-- recent-updates:end -->` block the script regenerates
surgically — never touches the surrounding content. Latest 5
releases with tag, date, link.
- website/docs/releases.md: full 60-release history, grouped by minor
version, each release body inside a collapsible `<details>` block.
Now shows the real v9.7.0 → v4.0.0 span.
- .github/workflows/sync-releases.yml: triggers the sync on every
release event (published/edited/unpublished/deleted), daily at
11:00 UTC (catches out-of-band edits), and on workflow_dispatch.
Commits directly to beta with [skip ci]. PRs run --check only.
- /contributing/docs page: new "Release notes sync" section
documenting the do-not-edit contract for releases.md and the
recent-updates block, plus the manual sync commands.
Verified: sync ran end-to-end via `gh api`, renders 60 releases into
1304 lines of releases.md + 5 entries in the README block. npm run
build passes.
Second iteration after user feedback. GitHub + Discord icons are now
visually prominent without dominating the navbar. Search verified
working in the production build (1.6 MB lunr index, /search page
returns 200, queries for 'manage_material' and 'roslyn' both hit).
- HomeHero: building_scene.gif rendered below the install block in a
bordered, rounded frame with a one-line caption. lazy-loaded, sized
1200x675 to avoid layout shift. Asset copied from docs/images/ into
website/static/img/ so the docs site is self-contained.
- /reference/cli: new page documenting the mcp-for-unity CLI —
invocation (uvx and uv run), how it talks to Unity over HTTP,
global flags table, command-group → MCP-tool mapping (29 groups
cross-linked to their generated tool reference pages), Click
--help discovery, source pointers.
- /reference/manifest: new page documenting manifest.json — its
relationship to package.json (UPM) and pyproject.toml (PyPI),
per-field reference (top-level, server, tools), MCPB bundle
generation path.
- sidebars.js: uncommented both reference items.
Verified: build clean. Smoke test: / renders gif, /reference/cli +
/reference/manifest both 200, gif fetch returns 2.2 MB.
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.
Replaces AI-skeleton content with the actual CoplayDev/unity-mcp.wiki
pages so the docs site has the real install/repair/troubleshooting
material people have been linking to.
Wiki pages absorbed:
- 1.-Fix-Unity-MCP-and-Cursor,-VSCode,-Windsurf,-Rider → new
/guides/uv-setup page. Covers Python 3.12+ install, uv install on
macOS/Linux/Windows, common uv locations, the MCP for Unity window's
"Choose UV Install Location" + "Repair Python Env" buttons, where
the server lives per OS, macOS PATH gotchas. Replaces the shallow
/guides/cursor page (deleted) — the cursor-specific Windows uv path
fix moved into the new troubleshooting FAQ.
- 2.-Fix-Unity-MCP-and-Claude-Code → new /guides/claude-code-cli page.
Native installer + NVM + Homebrew Node paths, macOS PATH workaround.
- 3.-Common-Setup-Problems → new /guides/troubleshooting page. macOS
dyld ICU error, WSL2-to-Windows bridging (@aollivier82 contribution
with port-proxy + firewall + WSL host IP discovery), Unity AI
Assistant DLL conflict (@rkroska report), Claude Code / VS Code /
Cursor FAQs.
- Project-Roadmap (wiki) → new /architecture/project-roadmap page.
Distinct from the existing /architecture/roadmap (2026 deep-research
feature plan). This is the living high-level roadmap with Current
Focus / Mid-Term / Long-Term / Icebox / Recently Completed sections
the wiki maintains.
Sidebar reorganized: Guides now leads with the install/setup pages
(uv-setup, claude-code-cli, client-configurators), then capability
(multi-instance, tool-groups, cli, cli-examples), then advanced
(custom-tools, remote-server-auth, roslyn), then troubleshooting last.
Verified: npm run build clean. One broken-anchor fix landed for the
em-dash heading "FAQ — Claude Code" which slugifies to faq--claude-code
(double dash).
- docs-deploy.yml: actions/checkout with fetch-depth: 0 so Docusaurus's
showLastUpdateTime / showLastUpdateAuthor resolves real per-file
commit metadata. Shallow clones make every page report the latest
build commit, which is useless to readers.
- website/static/robots.txt: allow-all crawlers + sitemap reference.
Required by Algolia DocSearch's crawler when the application gets
approved; harmless before then.
- /contributing/docs page: new sections covering first-time GitHub
Pages enablement (Settings → Pages → Source: GitHub Actions) and
the custom-domain CNAME path. Maintainers reading this would
otherwise hit a 404 on first deploy and not know why.
Verified:
- npm run build succeeds (Server 935ms, Client 1.8s)
- sitemap.xml lists all 80+ URLs
- robots.txt copies to build/ correctly
Brings the root README in line with the live docs site. Everything
optional or reference-y now lives in docs; the README is the landing
card a 10K-star repo deserves.
What survives in README (118 lines, ~120 target):
- Logo + language selector
- Aura sponsorship (unchanged)
- Badges row, now with a Docs badge as first item
- Tagline + hero gif
- Big "Read the Docs" CTA after the gif (per discussion)
- One-liner install (git URL only — Asset Store/OpenUPM moved to docs)
- "Try it" example with one prompt + link to First Prompt walkthrough
- Collapsed Recent Updates (last 4 entries only)
- Community block (Discord/Issues/Discussions/SECURITY.md)
- Contributing pointer (CONTRIBUTING.md + dev-setup docs)
- Advanced block with links to Multi-Instance, Tool Groups, Roslyn,
Remote Server Auth
- License, Star History, Citation, Aura Tools block, Disclaimer
What moved to docs:
- Prerequisites + Asset Store/OpenUPM install paths → /getting-started/install
- Setup wizard walkthrough → /getting-started/install
- Per-client gotchas → /getting-started/install + /getting-started/clients
- Manual Configuration JSON snippets → /getting-started/install
- Multiple Unity Instances → /guides/multi-instance
- Roslyn Script Validation → new /guides/roslyn page (NEW)
- Troubleshooting → /guides/cursor + GitHub Wiki link
- Telemetry + Security → SECURITY.md + /architecture/telemetry
- Full release history → new /releases page (NEW), seeded from the
current Recent Updates section
Also: emoji removal pass on README (Godot AI line).
Verified:
- README is 118 lines (vs target ~120)
- npm run build succeeds
- All links resolve (no onBrokenLinks throws)
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
Generated by the first successful `npm install` in /website/. Required
by `npm ci` in .github/workflows/docs-deploy.yml so the CI build pins
exact dependency versions and doesn't surprise us on a fresh tree.
Shutong Wu