v1.5.0 — Performance Snapshot Tool

What's new

A new MCP tool — capture_performance_snapshot — that lets your AI assistant get a quick, structured read on Unity performance without you having to open the Profiler.

Why it's useful

Before: "the scene feels laggy" was a subjective handoff. You'd open the Profiler, eyeball the graph, screenshot it, paste numbers into chat.

Now: one tool call returns hard data — "max frame time 106ms vs 16.6ms target, 174 samples over 3s". Your AI agent can act on facts instead of guesses, and even close the loop: change code → re-snapshot → compare.

What it captures

• In Play Mode: frame timing (avg/min/max ms + fps) sampled every frame after a configurable warmup, plus memory (Profiler.GetTotalReservedMemoryLong, Mono heap/used).
• In Edit Mode: memory only, with an honest warning. The tool refuses to fake frame timing from editor repaints — those numbers would be meaningless.
• Warnings: fires when any frame exceeds the targetFpsThreshold budget, or when memory counters come back empty.

Parameters

Param	Default	Notes
durationSeconds	5	Post-warmup sampling window
warmupSeconds	1	Frames during warmup are discarded
targetFpsThreshold	60	Used for the over-budget warning
includeMemory	true	Skip if you only want frame stats

Duration is auto-clamped to fit inside RequestTimeoutSeconds - 5s and hard-capped at 20s, so MCP calls never hang.

Example prompts

• "Capture a 5 second performance snapshot while the game is running."
• "Take a memory snapshot of the editor right now."
• "Sample frames for 10 seconds at 30fps target and tell me if we miss budget."

Notes for upgraders

• No breaking changes. New tool only.
• Locale-safe text output (1.0s, 56.2 fps) regardless of system locale.
• 12 new tests (7 NUnit + 5 Jest), all green; full Node suite at 190/190.

Out of scope (planned for later)

• start_performance_capture / stop_performance_capture for sessions longer than 20s
• ProfilerRecorder-based counters (render thread, GC alloc, physics)
• Memory Profiler .snap integration

v1.4.0

First release after the upstream-1.3.0 baseline that adds standalone dirty-scene tools and meaningfully reduces native Unity modal interference in MCP workflows.

New tools

• discard_open_scene_changes — reload dirty open scenes from disk silently (no Scene(s) Have Been Modified modal). Useful before quit / scene switch / run_tests when a scene was unintentionally dirtied — e.g. an [ExecuteAlways] MonoBehaviour spawning children after a domain reload. Optional scope parameter (loaded default, active alt). Refuses with cannot_discard_unsaved_scene if any loaded scene has no asset path. — d4d0241
• save_open_scenes — save every dirty open scene to disk silently. No parameters. Refuses with cannot_save_unsaved_scene if any dirty scene has no asset path. — d4d0241

Both wrap the same DirtyScenePreflightService already used by run_tests / enter_play_mode preflight, so error contracts (dirty_scene_preflight_refused, cannot_*_unsaved_scene) and the preflight payload are identical across all four entry points.

Bug fixes

• dirtyScenePolicy='discard' no longer raises the native save-changes modal on Unity 6.2. Both EditorSceneManager.OpenScene and RestoreSceneManagerSetup prompt on dirty scenes despite documentation suggesting otherwise — empirically verified. The service now clears the dirty flag via reflection on internal EditorSceneManager.ClearSceneDirtiness(Scene) before the reload call. Wrapped in try/catch so a future Unity API rename degrades gracefully to the prompting fallback rather than crashing the preflight. — 7d1d73a

• Supervisor restart spam eliminated when two Unity Editors are open. Previously the editor that lost the race for port 8090 logged Supervisor detected server is down + Port 8090 is already in use every ~5s indefinitely. McpUnityServer.StartServer now does a TcpListener bind-probe (with ExclusiveAddressUse=true) before constructing the WebSocketServer, and the supervisor skips restart attempts entirely while the port is occupied. State-transition logging only: single warning on entering blocked state, single info when the port becomes free. — cd9a220

Internal / docs

• AGENTS.md release checklist extended to include Server~/src/index.ts and Editor/UnityBridge/McpUnitySettings.cs — both surface the version string (to MCP clients and to the Editor's Server Window respectively) and were being missed in prior releases.
• McpUnitySettings.ServerVersion const caught up from 1.2.0 (last bumped in v1.2.0; missed in v1.3.0 and v1.3.1).

Verification

• TypeScript build clean, Jest 185/185 passing (16 suites, includes 9 new tests for the two new MCP tool wrappers).
• Unity 6.2 EditMode tests 156/156 passing: 151 prior baseline + 5 new port-probe (McpUnityServerPortProbeTests). Includes regression coverage on the existing 16 DirtyScenePreflightServiceTests after the ClearSceneDirtiness refactor.
• End-to-end MCP → Node → WebSocket → Unity smoke verified on both new tools.

Known limitations

• The reflection-based modal suppression only covers the initial reload in discard / save_open_scenes paths. Downstream Unity-internal operations (TestRunner harness-scene swap, Play Mode entry, editor quit) can still raise the modal if a scene re-dirties immediately after reload — e.g. when an [ExecuteAlways] MonoBehaviour mutates the hierarchy in OnEnable. Tracked in #5 as a modal-watchdog follow-up that does not block this release.

Consumer pin update

- "com.gamelovers.mcp-unity": "https://github.com/st-VALVe/mcp-unity.git#v1.3.1",
+ "com.gamelovers.mcp-unity": "https://github.com/st-VALVe/mcp-unity.git#v1.4.0",

Full changelog

v1.3.1...v1.4.0