feat: honour UNITY_MCP_SERVER_PATH — launch a given server binary, skip download + version match

[IvanMurzak]

Summary

• Adds UNITY_MCP_SERVER_PATH. When it resolves to a file that exists, that file is the
  binary the Editor launches, and both the GitHub-release download and the pinned-version match are
  skipped. When it is unset — or set to a path that does not exist — nothing changes: the plugin
  keeps using Library/mcp-server/<rid>/ and the release pinned by ServerVersion (9.2.5, which
  this PR does not touch). Same rule as Unreal-MCP's UNREAL_MCP_SERVER_PATH, fall-through
  included.
• Resolved through the existing DevControlEnv.Resolve layer (process env →
  <projectRoot>/.env → unset) rather than a bare Environment.GetEnvironmentVariable, so an
  Editor launched from the GUI or an IDE — which inherits no shell exports — can still pick the
  override up from a .env at the Unity project root.
• The override splits the two tiers that used to be one: the launch target follows it, the
  download cache never does. Everything that describes or verifies a download reads the cache
  tier explicitly, so a manual Download Binaries run still verifies and reports the file it
  actually wrote.
• Scope: one product file, one new EditMode test file, one docs subsection.
  git diff --stat origin/main -- Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor lists
  only Scripts/McpServerManager.cs; git diff --stat origin/main -- .github is empty.

What the override changes, member by member

Member	Override inactive (unset, or set-but-missing)	Override active
ResolveServerPathOverride()	null	the full path
ExecutableFullPath	Library/mcp-server/<rid>/gamedev-mcp-server(.exe)	the override
ExecutableFolderPath (StartServer's WorkingDirectory)	Library/mcp-server/<rid>/	the override's directory
VersionFullPath	Library/mcp-server/<rid>/version	<override dir>/version
IsVersionMatches()	reads the version marker and compares to ServerVersion	true (there is no marker beside a workspace-built binary)
CachedExecutableFolderPath	Library/mcp-server/<rid>/	Library/mcp-server/<rid>/ — never redirected
CachedExecutableFullPath	Library/mcp-server/<rid>/gamedev-mcp-server(.exe)	unchanged — never redirected
GetCachedBinaryVersion()	Library/mcp-server/<rid>/version	unchanged — never redirected

IsBinaryReadyToStart(), the DownloadServerBinaryIfNeeded gate and the editor-startup /
package-update paths all short-circuit off IsBinaryExists() && IsVersionMatches(), so under an
override DownloadAndUnpackBinary is never entered from either automatic path.

The manual menu item is the one download path that stays live under an override, and the bottom
three rows of that table are what keep it honest. MenuItems.DownloadServer calls
DownloadAndUnpackBinary directly, bypassing that gate, so with an override set it still runs —
and every member that describes the launch target is, by construction, true about the developer's
own binary. So the download path publishes to CachedExecutableFolderPath, verifies
CachedExecutableFullPath + GetCachedBinaryVersion(), and reports the same, rather than
ExecutableFullPath / IsBinaryExists() / IsVersionMatches() / GetBinaryVersion(). Had it kept
reading the launch tier, Download Binaries would have reported success however the publish went
(the override file exists because the resolver only returns it after File.Exists passed, and
IsVersionMatches() short-circuits to true), logged the override path as the download
destination, and shown a blank Version: in the result popup. This is the same reasoning that moved
PublishStagedBinary off ExecutableFolderPath: without it, a manual download would have deleted
and replaced the developer's own override directory, and the documented sentence "downloads into
Library/ regardless of the override; the override still wins at launch" would have been false.

Evidence

1. Behavioural proof against the real launch path

Unity 2022.3.62f3, this repo's own Unity-MCP-Plugin project in a fresh worktree whose
Library/ did not exist. Override target: a locally published server —
dotnet publish shared/GameDev-MCP-Server/com.IvanMurzak.GameDev.MCP.Server.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true → ProductVersion 9.2.6+62a6b7d1,
i.e. deliberately not the pinned 9.2.5, at a path outside Library/.

Half 1 — UNITY_MCP_SERVER_PATH set (Editor.log, verbatim, colour tags stripped):

info: [13:53:11:2855] [AI] McpServerManager UNITY_MCP_SERVER_PATH override active: launching
  ...\.agent-scratch\chain-server\gamedev-mcp-server.exe — server download and version check are skipped.
info: [13:53:15:0678] [AI] McpServerManager Starting MCP server:
  ...\.agent-scratch\chain-server\gamedev-mcp-server.exe port=5780 plugin-timeout=1800000
  client-transport=streamableHttp auth=none

• grep -c 'Downloaded and unpacked' Editor.log → 0
• grep -c 'Deleted existing MCP server folder' Editor.log → 0
• Unity-MCP-Plugin/Library/mcp-server → does not exist
• live process: gamedev-mcp-server.exe ExecutablePath = ...\.agent-scratch\chain-server\gamedev-mcp-server.exe
• the plugin reached READY through it (wait-for-ready exit 0, SignalR negotiate returned 200 with a connectionId).

Half 2 — the plant the brief asks for: same Editor, variable unset.

info: [13:54:39:7257] [AI] McpServerManager Starting MCP server:
  ...\Unity-MCP-Plugin\Library\mcp-server\win-x64\gamedev-mcp-server.exe port=5780 ...
Downloaded and unpacked GameDev-MCP-Server binary to:
  ...\Unity-MCP-Plugin\Library\mcp-server\win-x64\gamedev-mcp-server.exe

Library/mcp-server/win-x64/ now exists with a version marker reading 9.2.5, and the
override active line is absent from that run. So the launch target moved with the variable in
both directions, and the download only happened when the override was gone.

2. Plant rounds — six plants, each RED attributed from its own run

Applied with the Edit tool, each confirmed live in git diff before the run and reverted after;
assets-refresh between every plant and its run. Every round ran
tests-run --input {"testMode":"EditMode","testClass":"McpServerPathOverrideTests",...} and the
verdict is read per test from the run's own JSON — unity-mcp-cli exits 0 even when tests
fail, so an exit status could not have told these apart.

Plant	Mutation	Result
baseline	none	7 passed / 0 failed
P1	delete the IsVersionMatches() override short-circuit	3 failed: Override_ExistingFile_IsWhatGetsLaunched ("the override must skip the pinned-release version match"), Override_SkipsVersionMatch_EvenWithAMismatchedVersionMarkerBesideIt, Override_ResolvesFromProjectDotEnv_WhenTheProcessEnvIsUnset
P2	delete the File.Exists(raw) check in ResolveServerPathOverride	1 failed: Override_SetButMissingFile_FallsThroughToThePinnedRelease ("a set-but-missing override must not resolve (the Unreal rule)")
P3	ExecutableFolderRootPath literal "mcp-server" → "mcp-server-planted"	3 failed: NoOverride_KeepsThePinnedLibraryCache_AndTheVersionMarkerCheck, the pinned-cache assertion in Override_SetButMissingFile_FallsThroughToThePinnedRelease, and the cache assertion in Override_ExistingFile_IsWhatGetsLaunched
P4	DevControlEnv.Resolve(...) → Environment.GetEnvironmentVariable(...)	2 failed: Override_ResolvesFromProjectDotEnv_WhenTheProcessEnvIsUnset and ResolveServerPathOverride_ReadsTheDotEnvOfTheGivenProjectRoot (both But was: null)
P5	make CachedExecutableFolderPath follow the override	2 failed: "an active override must NOT move the download cache" and "the download-cache version read must NOT follow the override" — while the no-override test stays green, which is what proves the mutation bites only under an override
P6	GetCachedBinaryVersion() reads VersionFullPath instead of <cache>/version	1 failed: "the download-cache version read must NOT follow the override" (But was: "0.0.0-not-the-pinned-version")
final	all plants reverted, no residue	7 passed / 0 failed, Logs: []

P1 and P2 are the two the brief mandates. P3 and P4 exist because two other claims would otherwise
have been unfalsifiable: P3 proves the no-override test really pins Library/mcp-server/<rid>/
rather than comparing a value with itself, and P4 proves the .env layer is load-bearing rather
than incidental. P5 and P6 cover the download/launch tier split — they are the plants for behaviour
this PR changed in production code, derived from the change rather than from an existing test.

P5 and P6 attack one claim at two sites and share a red with identical text. Both redden
"the download-cache version read must NOT follow the override" verbatim. They are told apart by
their failure SET, not by that line: P5 additionally reddens the cache-folder assertion in
Override_ExistingFile_IsWhatGetsLaunched; P6 reddens the version assertion alone. Stated rather
than papered over, because a future red on that marker alone means P6's site, not P5's.

What makes each assertion able to fail (stated because a check that cannot fail scores green
with the feature deleted):

• The override fixture directory contains no version marker, and the test asserts that
  (Assert.IsFalse(File.Exists(VersionFullPath)), Assert.IsNull(GetBinaryVersion())) before
  asserting IsVersionMatches() is true — so that true can only come from the short-circuit.
  A sibling test goes further and puts a marker reading 0.0.0-not-the-pinned-version beside the
  override, asserts the marker is readable and disagrees with ServerVersion, and still requires
  IsVersionMatches() to be true. That same fixture is what makes P6 discriminate: with the
  mismatched marker beside the override, a cache read that followed the override returns it.
• The fall-through test captures the genuinely-unset baseline first ([SetUp] neutralises both
  sources — the process env var and <projectRoot>/.env — and [TearDown] restores them), then
  asserts equality with it and equality with an independently re-derived
  Library/mcp-server/<rid>/gamedev-mcp-server.exe, so "unchanged" cannot be satisfied by nothing
  having been read at all.
• The .env tests assert the process env var is empty and that nothing resolves before the file
  is written, so neither can pass on a process-env read.

Environment-conditional assertions — four of them, not one. Corrected here after the review
pass measured it; the earlier revision of this section understated the count.

Assertion	Discriminates on a clean CI runner (no Library/ cache)	Discriminates on a box holding the pinned release
NoOverride…: IsVersionMatches() == (marker == ServerVersion)	yes (no marker ⇒ false == false, and an unconditional true reddens)	no (both sides true)
SetButMissing…: IsBinaryExists() unchanged	no	yes
SetButMissing…: IsVersionMatches() unchanged	yes	no
SetButMissing…: IsBinaryReadyToStart() unchanged	no	yes

The suite is sound regardless, because the path equalities in those same tests — and the
cache-folder assertions P3 and P5 redden — discriminate in every environment. No assertion is
relied on where it cannot fail, and the two assertions that could not discriminate anywhere
(GetBinaryVersion() re-derived from its own body, and IsBinaryReadyToStart() restated as
IsBinaryExists() && IsVersionMatches()) were removed rather than left reading as coverage.

3. Local suites

• Suite 1 — Unity EditMode, full chunked run against Unity-MCP-Plugin (2022.3.62f3): see the
  "Suites" line below.
• Suite 2 — PlayMode: not applicable. The diff touches only Editor/ (Editor-only assembly)
  and docs/; nothing is compiled into a player.
• Suite 3 — CLI: not applicable. No file under cli/ changed.
• Suite 4 — CI surface: not applicable (no .github/** change), but
  python .github/scripts/check_nuget_gate.py was run anyway and exits 0:
  NuGet gate OK: 15 pins, generation UNITY_MCP_DEPS_3, propagation consistent.

Review pass (/code-review + /simplify)

Three report-only reviewers over the full diff, plus an in-context pass. Everything below was
verified from source before it was applied; findings whose prescription was wrong are recorded as
such rather than followed.

Applied — three real defects, all on the manual-download path, all invisible unless the override
is active (detailed in the member table above): the post-publish verification was vacuous, the
success log named the override instead of the download destination, and the result popup read the
version marker from the override's directory. Plus one consistency fix: StartServer now derives
WorkingDirectory from the executablePath local instead of re-resolving ExecutableFolderPath,
so FileName and WorkingDirectory cannot describe different binaries.

Applied — test hardening. [SetUp] used to File.Delete the real <projectRoot>/.env with the
only copy in a managed field. That file is gitignored, user-owned config that this feature's own
docs tell developers to create, so git holds no copy and a run killed before [TearDown] — a
domain reload, a cancelled run, an editor crash — would have destroyed it. It is now moved aside
to a sibling path and moved back, [SetUp] recovers a file left parked by an earlier killed run,
and a failed restore is a Debug.LogError (which fails the test) instead of a silent
catch { /* best effort */ }.

Applied — one new test. ResolveServerPathOverride(string? projectRootPath) is public and
documented as the unit-test seam, and no test used it. It has one now, reading an arbitrary root's
.env from a temp directory — which also pins that the root is an argument rather than the live
project.

Not applied, recorded instead:

• Moving the override resolution beside DevControlEnv, where the two sibling dev-only vars and
  their resolvers live. Genuinely the better home; out of bounds, since the brief fixes
  McpServerManager.cs as the only product file.
• Rewriting the .env tests to use the seam against a temp root instead of the real project root.
  That would drop the end-to-end coverage of ExecutableFullPath following <projectRoot>/.env,
  which is exactly what the brief asks the .env case to prove. The seam got its own test instead.
• Logging a warning when UNITY_MCP_SERVER_PATH is set but the file is missing. The silent
  fall-through is the ruled Unreal semantics; a new unverified log line late in review is not worth
  it. The docs now point at the Starting MCP server: <path> line as the reliable confirmation
  instead — which is also why the override active notice is no longer described as authoritative:
  it is emitted once per domain load, so it is absent if you write the .env afterwards even though
  the override still applies.
• Caching the resolution per domain load. It would break the tests and change behaviour; no caller
  is on a per-frame path (checked: no EditorApplication.update subscriber reads these members
  without self-unsubscribing, no OnGUI, no schedule.Execute loop).

Not done, on purpose

• ServerVersion (McpServerManager.cs) is unchanged.
• MenuItems.DownloadServer still downloads into Library/, which is documented.
• Editor/DependencyResolver/**, NuGetConfig.cs, the Assets/Plugins/NuGet drops, cli/**,
  Runtime/**, UpdateChecker and every UI file are untouched.
• No version field in any package.json was bumped.
• DownloadAndUnpackBinary's own body has no EditMode coverage — it downloads — so the
  post-publish fix is verified through the members it now reads (CachedExecutableFolderPath,
  GetCachedBinaryVersion(), planted P5/P6) rather than by exercising the download itself.

Test plan

• EditMode suite McpServerPathOverrideTests — 7 tests, 0 failures, Logs: [].
• Six plant rounds, each RED attributed per test from its own run log; all reverted; residue-checked; final run green.
• Behavioural proof on the real launch path, both directions.
• check_nuget_gate.py exit 0.
• Target-specific local tests passed (see profile test.md).

CI

• Authoritative CI run for this PR's current head (test-pull-request) on
  05be00d2f137907414582d362e9836f8322e5dcc: id 33815830447 —
  https://github.com/IvanMurzak/Unity-MCP/actions/runs/33815830447 — 17/17 checks green:
  nuget gate, test-cli (20), test-cli (22), the twelve licensed test-unity-* legs
  (2022.3.62f3 / 2023.2.22f1 / 6000.3.1f1 x editmode/standalone x base/windows-mono),
  Test Results and save-event-file. SHA-tied: that run's headSha equals this PR's
  current headRefOid, so it covers the refine commit as well as the implement commit.
• SUPERSEDED — PR run on the pre-refine head 80143639: id 33807352185 —
  https://github.com/IvanMurzak/Unity-MCP/actions/runs/33807352185 — all 17 checks green
  (SHA-tied: 801436398b953ad345e454b3f719fdc5b96a65c9). Retained for history only; it does
  NOT cover the refine commit. The authoritative run above is the one this PR is gated on.
  This is a same-repository branch, so the twelve licensed test-unity-* legs
  receive the repository secrets (the late-August red runs on this repo were fork PRs, per docs(ci): the red test-unity legs are fork PRs with no secrets, not a regression #974).