* fix: change vector/color parameter types to Any to allow string inputs
* fix: add type check in manage_component to pass cursor error
The Pydantic validation in FastMCP occurs before function execution,
causing validation errors when clients pass string values like '[2, 2, 2]'
for parameters typed as `list[float] | str`. Since the code already has
normalization functions (_normalize_vector, _normalize_color) that handle
string inputs, change the type annotations to `Any` to bypass Pydantic's
strict validation.
Affected parameters:
- manage_gameobject: position, rotation, scale, offset
- manage_material: color
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: improve vector parameter validation with clear error messages
- Change parameter types from `list[float]` to `list[float] | str` to accept
both list and JSON string inputs (consistent with read_console/run_tests)
- Modify _normalize_vector to return (value, error_message) tuple instead of
silently returning None on invalid input
- Add detailed error messages for invalid vector values
This fixes the Pydantic validation error when clients pass string values
like "[2, 2, 2]" for scale/position/rotation parameters.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Loosen the type to pass the cursor error
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Shutong Wu <51266340+Scriptwonder@users.noreply.github.com>
- Mark prefab stage scene as dirty when manage_components adds/removes/
modifies components, ensuring save_open_stage correctly detects changes
- When renaming the root GameObject of an open prefab stage, also rename
the prefab asset file to match, preventing Unity's "file name must
match" dialog from interrupting automated workflows
- Fix ManagePrefabsCrudTests cleanup order: delete NestedContainer.prefab
before ChildPrefab.prefab to avoid missing prefab reference errors
- Remove incorrect LogAssert.Expect that expected an error that doesn't
occur in the test scenario
- Add new prefab MCP resources for inspecting prefabs:
- mcpforunity://prefab-api: Documentation for prefab resources
- mcpforunity://prefab/{path}: Get prefab asset info
- mcpforunity://prefab/{path}/hierarchy: Get full prefab hierarchy
Addresses #97 (Prefab Editor Inspection & Modification Support)
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* feat: Add prefab read operations (get_info, get_hierarchy, list_prefabs)
- Add get_info: retrieve prefab metadata (GUID, type, components, child count, variant info)
- Add get_hierarchy: get prefab internal structure with pagination support
- Add list_prefabs: search prefabs in project with optional name filtering
- Extract PrefabUtilityHelper class for reusable prefab utility methods
- Update Python tool descriptions and parameter documentation
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: Use correct API to save prefab stage changes
Replace PrefabUtility.SaveAsPrefabAsset (for creating new prefabs) with
EditorSceneManager.SaveScene to properly save stage modifications.
This fixes the issue where component additions were lost after closing
the prefab stage.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* refactor: improve code quality and error handling
- Add pagination constants (DefaultPageSize, MaxPageSize)
- Extract SaveAndRefreshStage helper to reduce duplication
- Change all user-facing messages to English
- Add REQUIRED_PARAMS validation in Python
- Split path parameter into prefab_path and folder_path for clarity
- Improve error handling with specific exception types
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: Remove list_prefabs action and update related documentation
* feat: Enhance prefab management with detailed parameter descriptions and new unlinking option
* feat: Simplify prefab creation logic and unify logging for asset replacement
* feat: Update SaveStagePrefab method to use SetDirty and SaveAssets for prefab stage saving
* feat: Add PrefabUtilityHelper class with utility methods for prefab asset management
* feat: Refactor action constants and enhance parameter validation in prefab management
* feat: Update ValidateSourceObjectForPrefab method to remove replaceExisting parameter and simplify validation logic
* fix: Fix searchInactive parameter and improve prefab management
- Fix searchInactive not working correctly for child objects
- Improve error message accuracy for object not found
- Use Application.dataPath for reliable directory path resolution
* feat: Add path validation and security checks for prefab operations
* feat: Remove pagination from GetHierarchy method and simplify prefab retrieval
* feat: Remove mode parameter from prefab management functions to simplify usage
* fix: Improve path validation and replace logic in prefab management
* feat: Enhance prefab management by adding nesting depth and parent prefab path retrieval
* fix: resolve Unknown pseudo class last-child USS warnings
Unity UI Toolkit does not support the :last-child pseudo-class. Replace
it with a .section-last class that is applied programmatically to the
last section in each .section-stack container.
Also moves the Configure All Detected Clients button to the bottom
of the Client Configuration section and makes it auto-width.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: improve prefab stage save for automated workflows
- Add force parameter to save_open_stage for automated workflows
where isDirty may not be correctly set
- Use PrefabUtility.SaveAsPrefabAsset for dialog-free saving
- Mark prefab stage scene dirty when modifying GameObjects in prefab mode
- Skip save when no changes and force=false (prevents false dirty flag)
The force parameter ensures reliable saving in CI/automation scenarios
where Unity dirty tracking may be inconsistent with programmatic changes.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Update prefab.py
* refactor: remove unnecessary blank line before create function
* feat: add info and hierarchy commands to prefab CLI for enhanced prefab management
* feat: enhance prefab management with comprehensive CRUD tests and ensure dirty state tracking
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: David Sarno <david@lighthaus.us>
* Update for Texture2D/Sprite Generation
Given the choice to generate Texture2D based on patterns and color, also introduce pipeline to turn Texture2D direct to Sprite.
Update CLI command to include this too.
* Texture Size Set
Set texture size to 1024X1024 to avoid too large texture set
* Add image input
* Update to release direct error with large tex2d
* Fix for AI advice
* Update on action fetch line
* feat: Add CLI for Unity MCP server
- Add click-based CLI with 15+ command groups
- Commands: gameobject, component, scene, asset, script, editor, prefab, material, lighting, ui, audio, animation, code
- HTTP transport to communicate with Unity via MCP server
- Output formats: text, json, table
- Configuration via environment variables or CLI options
- Comprehensive usage guide and unit tests
* Update based on AI feedback
* Fixes main.py error
* Update for further error fix
* Update based on AI
* Update script.py
* Update with better coverage and Tool Readme
* Log a message with implicit URI changes
Small update for #542
* Minor fixes (#602)
* Log a message with implicit URI changes
Small update for #542
* Log a message with implicit URI changes
Small update for #542
* Add helper scripts to update forks
* fix: improve HTTP Local URL validation UX and styling specificity
- Rename CSS class from generic "error" to "http-local-url-error" for better specificity
- Rename "invalid-url" class to "http-local-invalid-url" for clarity
- Disable httpServerCommandField when URL is invalid or transport not HTTP Local
- Clear field value and tooltip when showing validation errors
- Ensure field is re-enabled when URL becomes valid
* Docker mcp gateway (#603)
* Log a message with implicit URI changes
Small update for #542
* Update docker container to default to stdio
Replaces #541
* fix: Rider config path and add MCP registry manifest (#604)
- Fix RiderConfigurator to use correct GitHub Copilot config path:
- Windows: %LOCALAPPDATA%\github-copilot\intellij\mcp.json
- macOS: ~/Library/Application Support/github-copilot/intellij/mcp.json
- Linux: ~/.config/github-copilot/intellij/mcp.json
- Add mcp.json for GitHub MCP Registry support:
- Enables users to install via coplaydev/unity-mcp
- Uses uvx with mcpforunityserver from PyPI
* Use click.echo instead of print statements
* Standardize whitespace
* Minor tweak in docs
* Use `wait` params
* Unrelated but project scoped tools should be off by default
* Update lock file
* Whitespace cleanup
* Update custom_tool_service.py to skip global registration for any tool name that already exists as a built‑in.
* Avoid silently falling back to the first Unity session when a specific unity_instance was requested but not found.
If a client passes a unity_instance that doesn’t match any session, this code will still route the command to the first available session, which can send commands to the wrong project in multi‑instance environments. Instead, when a unity_instance is provided but no matching session_id is found, return an error (e.g. 400/404 with "Unity instance '' not found") and only default to the first session when no unity_instance was specified.
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
* Update docs/CLI_USAGE.md
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
* Updated the CLI command registration to only swallow missing optional modules and to surface real import-time failures, so broken command modules don’t get silently ignored.
* Sorted __all__ alphabetically to satisfy RUF022 in __init__.py.
* Validate --params is a JSON object before merging.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
---------
Co-authored-by: Shutong Wu <51266340+Scriptwonder@users.noreply.github.com>
Co-authored-by: dsarno <david@lighthaus.us>
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* feat: Add project-scoped tools flag to control custom tool registration behavior
Add `--project-scoped-tools` CLI flag and `UNITY_MCP_PROJECT_SCOPED_TOOLS` environment variable to control whether custom tools are registered globally or scoped to specific Unity projects.
Closes#416
* Add .meta file
* feat: Add project-scoped tools toggle for local HTTP transport
Add UI toggle in Connection section to control project-scoped tools flag when using HTTP Local transport. The toggle:
- Defaults to enabled (true)
- Persists state in EditorPrefs
- Only displays when HTTP Local transport is selected
- Automatically appends `--project-scoped-tools` flag to uvx server command
- Updates manual config display when toggled
* Update Server/src/services/custom_tool_service.py
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
* Pass project_scoped_tools flag directly without environment variable conversion
Remove unnecessary environment variable conversion for project_scoped_tools flag.
* fix: Improve error handling and logging in global custom tool registration
Split exception handling to distinguish between expected RuntimeError (service not initialized) and unexpected errors.
---------
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
* fix: reduce per-frame GC allocations causing editor hitches (issue #577)
Eliminate memory allocations that occurred every frame, which triggered
garbage collection spikes (~28ms) approximately every second.
Changes:
- EditorStateCache: Skip BuildSnapshot() entirely when state unchanged
(check BEFORE building). Increased poll interval from 0.25s to 1.0s.
Cache DeepClone() results to avoid allocations on GetSnapshot().
- TransportCommandDispatcher: Early exit before lock/list allocation
when Pending.Count == 0, eliminating per-frame allocations when idle.
- StdioBridgeHost: Same early exit pattern for commandQueue.
- MCPForUnityEditorWindow: Throttle OnEditorUpdate to 2-second intervals
instead of every frame, preventing expensive socket checks 60+/sec.
Fixes GitHub issue #577: High performance impact even when MCP server is off
* fix: prevent multiple domain reloads when calling refresh_unity (issue #577)
Root Cause:
- send_command() had a hardcoded retry loop (min 6 attempts) on connection errors
- Each retry resent the refresh_unity command, causing Unity to reload 6 times
- retry_on_reload=False only controlled reload-state retries, not connection retries
The Fix:
1. Unity C# (MCPForUnity/Editor):
- Added --reinstall flag to uvx commands in dev mode
- Ensures local development changes are picked up by uvx/Claude Code
- Applies to all client configurators (Claude Code, Codex, etc.)
2. Python Server (Server/src):
- Added max_attempts parameter to send_command()
- Pass max_attempts=0 when retry_on_reload=False
- Fixed type handling in refresh_unity.py (handle MCPResponse objects)
- Added timeout to connection error recovery conditions
- Recovery logic now returns success instead of error to prevent client retries
Changes:
- MCPForUnity/Editor: Added --reinstall to dev mode uvx commands
- Server/refresh_unity.py: Fixed type handling, improved error recovery
- Server/unity_connection.py: Added max_attempts param, disable retries when retry_on_reload=False
Result: refresh_unity with compile=request now triggers only 1 domain reload instead of 6
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: UI and server stability improvements
Unity Editor (C#):
- Fix "Resuming..." stuck state when manually clicking End Session
Clear ResumeStdioAfterReload and ResumeHttpAfterReload flags in
OnConnectionToggleClicked and EndOrphanedSessionAsync to prevent
UI from getting stuck showing "Resuming..." with disabled button
- Remove unsupported --reinstall flag from all uvx command builders
uvx does not support --reinstall and shows warning when used
Use --no-cache --refresh instead for dev mode cache busting
Python Server:
- Add "aborted" to connection error patterns in refresh_unity
Handle WinError 10053 (connection aborted) gracefully during
Unity domain reload, treating it as expected behavior
- Add WindowsSafeRotatingFileHandler to suppress log rotation errors
Windows file locking prevents log rotation when file is open by
another process; catch PermissionError to avoid noisy stack traces
- Fix packaging: add py-modules = ["main"] to pyproject.toml
setuptools.packages.find only discovers packages (directories with
__init__.py), must explicitly list standalone module files
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* docs: improve refresh_unity connection loss handling documentation
Add detailed comments and logging to clarify why connection loss during
compile is treated as success (expected domain reload behavior, not failure).
This addresses PR feedback about potentially masking real connection errors.
The logic is intentional and correct:
- Connection loss only treated as success when compile='request'
- Domain reload causing disconnect is expected Unity behavior
- Subsequent wait_for_ready loop validates Unity becomes ready
- Prevents multiple domain reload loops (issue #577)
Added logging for observability:
- Info log when expected disconnect detected
- Warning log for non-recoverable errors
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: add missing logger import in refresh_unity
Missing logger import causes NameError at runtime when connection
loss handling paths are triggered (lines 82 and 91).
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: address code review feedback on thread safety and semantics
Addresses four issues raised in code review:
1. EditorStateCache.GetSnapshot() - Remove shared cached clone
- Revert to always returning fresh DeepClone() to prevent mutation bugs
- Main GC optimization remains: state-change detection prevents
unnecessary _cached rebuilds (the expensive operation)
- Removed _cachedClone and _cachedCloneSequence fields
2. refresh_unity.py - Fix blocking reason terminology mismatch
- Changed "asset_refresh" to "asset_import" to match activityPhase
values from EditorStateCache.cs
- Ensures asset import is correctly detected as blocking state
3. TransportCommandDispatcher - Fix unsynchronized Count access
- Moved Pending.Count check inside PendingLock
- Prevents data races and InvalidOperationException from concurrent
dictionary access
4. StdioBridgeHost - Fix unsynchronized Count access
- Moved commandQueue.Count check inside lockObj
- Ensures all collection access is properly serialized
All changes maintain the GC allocation optimizations while fixing
thread safety violations and semantic contract changes.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: address code review feedback on thread safety and timeout handling
- refresh_unity.py: Track readiness explicitly and return failure on timeout
instead of silently returning success when wait loop exits without confirming
ready_for_tools=true
- McpClientConfiguratorBase.cs: Add thread safety guard for Configure() call
in CheckStatusWithProjectDir(). Changed default attemptAutoRewrite to false
and added runtime check to prevent calling Configure() from background threads.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* Fix test job state management after domain reload
- TestRunnerService.RunFinished: Always clean up job state even when
_runCompletionSource is null (happens after PlayMode domain reload)
- TestJobManager: Detect and clear stale jobs (5+ min without updates)
on startup to recover from stuck state after domain reload
- refresh_unity.py: Add "could not connect" to retryable errors when
wait_for_ready=True, so connection failures during domain reload
trigger waiting instead of immediate failure
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add focus nudge to handle OS-level throttling during PlayMode tests
When Unity is unfocused, macOS App Nap (and similar OS features) can
throttle the process, causing PlayMode tests to stall even with Unity
No Throttling mode enabled.
Changes:
- Add ApplyNoThrottlingPreemptive() to TestRunnerNoThrottle for early
throttle prevention before PlayMode Execute()
- Add focus_nudge.py utility that temporarily focuses Unity and returns
focus to the original app (supports macOS, Windows, Linux)
- Integrate focus nudge into get_test_job polling - when tests appear
stalled (unfocused + no progress for 10s), automatically nudge Unity
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix code review issues in focus_nudge.py
- Remove redundant time import (already imported at module level)
- Escape window titles in PowerShell script to prevent injection
- Remove unused Callable import
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Improve focus nudge logging and fix skipped tests
- Improve logging in focus_nudge.py: rate limit skip and focus return at INFO level
- Improve logging in run_tests.py: show nudge completion status
- Fix path resolution in test_logging_stdout.py and test_transport_framing.py
- Add PlayMode tests to UnityMCPTests project for testing PlayMode runner
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add troubleshooting note about focus permission requests
When running PlayMode tests with Unity in the background, the focus
nudge feature may trigger OS permission prompts (especially on macOS
for accessibility/automation). Document this expected behavior.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add test coverage tracking with pytest-cov
- Add pytest-cov>=4.1.0 to dev dependencies
- Configure coverage in pyproject.toml (run, report, html)
- Integrate coverage reports into CI workflow
- Update .gitignore for coverage artifacts
- Document coverage usage in docs/README-DEV.md
Current coverage baseline: 34.45%
* fix: correct TOML escaping and remove redundant
* docs: add Chinese translation for code coverage section
* fix: regenerate uv.lock to resolve merge conflict
* refactor: Split ParseColorOrDefault into two overloads and change default to Color.white
* Auto-format Python code
* Remove unused Python module
* Refactored VFX functionality into multiple files
Tested everything, works like a charm
* Rename ManageVfx folder to just Vfx
We know what it's managing
* Clean up whitespace on plugin tools and resources
* Make ManageGameObject less of a monolith by splitting it out into different files
* Remove obsolete FindObjectByInstruction method
We also update the namespace for ManageVFX
* refactor: Consolidate editor state resources into single canonical implementation
Merged EditorStateV2 into EditorState, making get_editor_state the canonical resource. Updated Unity C# to use EditorStateCache directly. Enhanced Python implementation with advice/staleness enrichment, external changes detection, and instance ID inference. Removed duplicate EditorStateV2 resource and legacy fallback mapping.
* Validate editor state with Pydantic models in both C# and Python
Added strongly-typed Pydantic models for EditorStateV2 schema in Python and corresponding C# classes with JsonProperty attributes. Updated C# to serialize using typed classes instead of anonymous objects. Python now validates the editor state payload before returning it, catching schema mismatches early.
* Consolidate run_tests and run_tests_async into single async implementation
Merged run_tests_async into run_tests, making async job-based execution the default behavior. Removed synchronous blocking test execution. Updated RunTests.cs to start test jobs immediately and return job_id for polling. Changed TestJobManager methods to internal visibility. Updated README to reflect single run_tests_async tool. Python implementation now uses async job pattern exclusively.
* Validate test job responses with Pydantic models in Python
* Change resources URI from unity:// to mcpforunity://
It should reduce conflicts with other Unity MCPs that users try, and to comply with Unity's requests regarding use of their company and product name
* Update README with all tools + better listing for resources
* Update other references to resources
* Updated translated doc - unfortunately I cannot verify
* Update the Chinese translation of the dev docks
* Change menu item from Setup Window to Local Setup Window
We now differentiate whether it's HTTP local or remote
* Fix URIs for menu items and tests
* Shouldn't have removed it
* Minor edits from CodeRabbit feedback
* Don't use reflection which takes longer
* Fix failing python tests
* Add serialization helpers for ParticleSystem curves and MinMaxCurve types
Added SerializeAnimationCurve and SerializeMinMaxCurve helper methods to properly serialize Unity's curve types. Updated GetInfo to use these helpers for startLifetime, startSpeed, startSize, gravityModifier, and rateOverTime instead of only reading constant values.
* Use ctx param
* Update Server/src/services/tools/run_tests.py
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Minor fixes
* Rename anything EditorStateV2 to just EditorState
It's the default, there's no old version
* Make infer_single_instance_id public by removing underscore prefix
* Fix Python tests, again
* Replace AI generated .meta files with actual Unity ones
* ## Pre-Launch Enhancements: Testing Infrastructure & Tool Improvements (#8)
* Add local test harness for fast developer iteration
Scripts for running the NL/T/GO test suites locally against a GUI Unity
Editor, complementing the CI workflows in .github/workflows/.
Benefits:
- 10-100x faster than CI (no Docker startup)
- Real-time Unity console debugging
- Single test execution for rapid iteration
- Auto-detects HTTP vs stdio transport
Usage:
./scripts/local-test/setup.sh # One-time setup
./scripts/local-test/quick-test.sh NL-0 # Run single test
./scripts/local-test/run-nl-suite-local.sh # Full suite
See scripts/local-test/README.md for details.
Also updated .gitignore to:
- Allow scripts/local-test/ to be tracked
- Ignore generated artifacts (reports/*.xml, .claude/local/, .unity-mcp/)
* Fix issue #525: Save dirty scenes for all test modes
Move SaveDirtyScenesIfNeeded() call outside the PlayMode conditional
so EditMode tests don't get blocked by Unity's "Save Scene" modal dialog.
This prevents MCP from timing out when running EditMode tests with unsaved
scene changes.
* fix: add missing FAST_FAIL_TIMEOUT constant in PluginHub
The FAST_FAIL_TIMEOUT class attribute was referenced on line 149 but never
defined, causing AttributeError on every ping attempt. This error was silently
caught by the broad 'except Exception' handler, causing all fast-fail commands
(read_console, get_editor_state, ping) to fail after 6 seconds of retries with
'ping not answered' error.
Added FAST_FAIL_TIMEOUT = 10 to define a 10-second timeout for fast-fail
commands, matching the intent of the existing fast-fail infrastructure.
* feat(ScriptableObject): enhance dry-run validation for AnimationCurve and Quaternion
Dry-run validation now validates value formats, not just property existence:
- AnimationCurve: Validates structure ({keys:[...]} or direct array), checks
each keyframe is an object, validates numeric fields (time, value, inSlope,
outSlope, inWeight, outWeight) and integer fields (weightedMode)
- Quaternion: Validates array length (3 for Euler, 4 for raw) or object
structure ({x,y,z,w} or {euler:[x,y,z]}), ensures all components are numeric
Refactored shared validation helpers into appropriate locations:
- ParamCoercion: IsNumericToken, ValidateNumericField, ValidateIntegerField
- VectorParsing: ValidateAnimationCurveFormat, ValidateQuaternionFormat
Added comprehensive XML documentation clarifying keyframe field defaults
(all default to 0 except as noted).
Added 5 new dry-run validation tests covering valid and invalid formats
for both AnimationCurve and Quaternion properties.
* test: fix integration tests after merge
- test_refresh_unity_retry_recovery: Mock now handles both refresh_unity and
get_editor_state commands (refresh_unity internally calls get_editor_state
when wait_for_ready=True)
- test_run_tests_async_forwards_params: Mock response now includes required
'mode' field for RunTestsStartResponse Pydantic validation
- test_get_test_job_forwards_job_id: Updated to handle GetTestJobResponse as
Pydantic model instead of dict (use model_dump() for assertions)
* Update warning message to apply to all test modes
Follow-up to PR #527: Since SaveDirtyScenesIfNeeded() now runs for all test modes, update the warning message to say 'tests' instead of 'PlayMode tests'.
* feat(run_tests): add wait_timeout to get_test_job to avoid client loop detection
When polling for test completion, MCP clients like Cursor can detect the
repeated get_test_job calls as 'looping' and terminate the agent.
Added wait_timeout parameter that makes the server wait internally for tests
to complete (polling Unity every 2s) before returning. This dramatically
reduces client-side tool calls from 10-20 down to 1-2, avoiding loop detection.
Usage: get_test_job(job_id='xxx', wait_timeout=30)
- Returns immediately if tests complete within timeout
- Returns current status if timeout expires (client can call again)
- Recommended: 30-60 seconds
* fix: use Pydantic attribute access in test_run_tests_async for merge compatibility
* revert: remove local test harness - will be submitted in separate PR
---------
Co-authored-by: Scott Jennings <scott.jennings+CIGINT@cloudimperiumgames.com>
---------
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: dsarno <david@lighthaus.us>
Co-authored-by: Scott Jennings <scott.jennings+CIGINT@cloudimperiumgames.com>
* feat(manage_scriptable_object): harden tool with path normalization, auto-resize, bulk mapping
Phase 1: Path Syntax & Auto-Resizing
- Add NormalizePropertyPath() to convert field[index] to Array.data format
- Add EnsureArrayCapacity() to auto-grow arrays when targeting out-of-bounds indices
Phase 2: Consolidation
- Replace duplicate TryGet* helpers with ParamCoercion/VectorParsing shared utilities
- Add Vector4 parsing support to VectorParsing.cs
Phase 3: Bulk Data Mapping
- Handle JArray values for list/array properties (recursive element setting)
- Handle JObject values for nested struct/class properties
Phase 4: Enhanced Reference Resolution
- Support plain 32-char GUID strings for ObjectReference fields
Phase 5: Validation & Dry-Run
- Add ValidatePatches() for pre-validation of all patches
- Add dry_run parameter to validate without mutating
Includes comprehensive stress test suite covering:
- Big Bang (large nested arrays), Out of Bounds, Friendly Path Syntax
- Deep Nesting, Mixed References, Rapid Fire, Type Mismatch
- Bulk Array Mapping, GUID Shorthand, Dry Run validation
* feat: Add AnimationCurve and Quaternion support to manage_scriptable_object tool
- Implement TrySetAnimationCurve() supporting both {'keys': [...]} and direct [...] formats
* Support keyframe properties: time, value, inSlope, outSlope, weightedMode, inWeight, outWeight
* Gracefully default missing optional fields to 0
* Clear error messages for malformed structures
- Implement TrySetQuaternion() with 4 input formats:
* Euler array [x, y, z] - 3 elements interpreted as degrees
* Raw array [x, y, z, w] - 4 components
* Object format {x, y, z, w} - explicit components
* Explicit euler {euler: [x, y, z]} - labeled format
- Improve error handling:
* Null values: AnimationCurve→empty, Quaternion→identity
* Invalid inputs rejected with specific, actionable error messages
* Validate keyframe objects and array sizes
- Add comprehensive test coverage in ManageScriptableObjectStressTests.cs:
* AnimationCurve with keyframe array format
* AnimationCurve with direct array (no wrapper)
* Quaternion via Euler angles
* Quaternion via raw components
* Quaternion via object format
* Quaternion via explicit euler property
- Fix test file compilation issues:
* Replace undefined TestFolder with _runRoot
* Add System.IO using statement
* refactor: consolidate test utilities to eliminate duplication
- Add TestUtilities.cs with shared helpers:
- ToJObject() - consolidates 11 duplicates across test files
- EnsureFolder() - consolidates 2 duplicates
- WaitForUnityReady() - consolidates 2 duplicates
- FindFallbackShader() - consolidates shader chain duplicates
- SafeDeleteAsset() - helper for asset cleanup
- CleanupEmptyParentFolders() - standardizes TearDown cleanup
- Update 11 test files to use shared TestUtilities via 'using static'
- Standardize TearDown cleanup patterns across all test files
- Net reduction of ~40 lines while improving maintainability
* fix: add missing animCurve and rotation fields to ComplexStressSO
Add AnimationCurve and Quaternion fields required by Phase 6 stress tests.
* feat: Redesign GameObject API for better LLM ergonomics
- find_gameobjects: Search GameObjects, returns paginated instance IDs only
- manage_components: Component lifecycle (add, remove, set_property)
- unity://scene/gameobject/{id}: Single GameObject data (no component serialization)
- unity://scene/gameobject/{id}/components: All components (paginated)
- unity://scene/gameobject/{id}/component/{name}: Single component by type
- manage_scene get_hierarchy: Now includes componentTypes array
- manage_gameobject: Slimmed to lifecycle only (create, modify, delete)
- Legacy actions (find, get_components, etc.) log deprecation warnings
- ParamCoercion: Centralized int/bool/float/string coercion
- VectorParsing: Vector3/Vector2/Quaternion/Color parsing
- GameObjectLookup: Centralized GameObject search logic
- 76 new Unity EditMode tests for ManageGameObject actions
- 21 new pytest tests for Python tools/resources
- New NL/T CI suite for GameObject API (GO-0 to GO-5)
Addresses LLM confusion with parameter overload by splitting into
focused tools and read-only resources.
* feat: Add GameObject API stress tests and NL/T suite updates
Stress Tests (12 new tests):
- BulkCreate small/medium batches
- FindGameObjects pagination with by_component search
- AddComponents to single object
- GetComponents with full serialization
- SetComponentProperties (complex Rigidbody)
- Deep hierarchy creation and path lookup
- GetHierarchy with large scenes
- Resource read performance tests
- RapidFire create-modify-delete cycles
NL/T Suite Updates:
- Added GO-0..GO-10 tests in nl-gameobject-suite.md
- Fixed tool naming: mcp__unity__ → mcp__UnityMCP__
Other:
- Fixed LongUnityScriptClaudeTest.cs compilation errors
- Added reports/, .claude/local/, scripts/local-test/ to .gitignore
All 254 EditMode tests pass (250 run, 4 explicit skips)
* fix: Address code review feedback
- ParamCoercion: Use CultureInfo.InvariantCulture for float parsing
- ManageComponents: Move Transform removal check before GetComponent
- ManageGameObjectFindTests: Use try-finally for LogAssert.ignoreFailingMessages
- VectorParsing: Document that quaternions are not auto-normalized
- gameobject.py: Prefix unused ctx parameter with underscore
* fix: Address more code review feedback
NL/T Prompt Fixes:
- nl-gameobject-suite.md: Remove non-existent list_resources/read_resource from AllowedTools
- nl-gameobject-suite.md: Fix parameter names (component_type, properties)
- nl-unity-suite-nl.md: Remove unused manage_editor from AllowedTools
Test Fixes:
- GameObjectAPIStressTests: Add null check to ToJObject helper
- GameObjectAPIStressTests: Clarify AudioSource usage comment
- ManageGameObjectFindTests: Use built-in 'UI' layer instead of 'Water'
- LongUnityScriptClaudeTest: Clean up NL/T test artifacts (Counte42 typo, HasTarget)
* docs: update README tools and resources lists
- Add missing tools: manage_components, batch_execute, find_gameobjects, refresh_unity
- Add missing resources: gameobject_api, editor_state_v2
- Make descriptions more concise across all tools and resources
- Ensure documentation matches current MCP server functionality
* chore: Remove accidentally committed test artifacts
- Remove Materials folder (40 .mat files from interactive testing)
- Remove Shaders folder (5 noise shaders from testing)
- Remove test scripts (Bounce*, CylinderBounce* from testing)
- Remove Temp.meta and commit.sh
* refactor: remove deprecated manage_gameobject actions
- Remove deprecated switch cases: find, get_components, get_component, add_component, remove_component, set_component_property
- Remove deprecated wrapper methods (423 lines deleted from ManageGameObject.cs)
- Delete ManageGameObjectFindTests.cs (tests deprecated 'find' action)
- Remove deprecated test methods from ManageGameObjectTests.cs
- Add GameObject resource URIs to README documentation
- Add batch_execute performance tips to README, tool description, and gameobject_api resource
- Enhance batch_execute description to emphasize 10-100x performance gains
Total: ~1200 lines removed. New API (find_gameobjects, manage_components, resources) is the recommended path forward.
* refactor: consolidate shared services across MCP tools
Major architectural improvements:
- Create UnityJsonSerializer for shared JSON/Unity type conversion
- Create ObjectResolver for unified object resolution (GameObjects, Components, Assets)
- Create UnityTypeResolver for consolidated type resolution with caching
- Create PropertyConversion for unified JSON→Unity property conversion
- Create ComponentOps for low-level component operations
- Create Pagination helpers for standardized pagination across tools
Tool simplifications:
- ManageGameObject: Remove 68-line prefab redirect anti-pattern, delegate to helpers
- ManageAsset: Remove ~80 lines duplicate ConvertJTokenToType
- ManageScriptableObject: Remove ~40 lines duplicate ResolveType
- ManageComponents: Use ComponentOps, UnityTypeResolver (~90 lines saved)
- ManageMaterial: Standardize to SuccessResponse/ErrorResponse patterns
- FindGameObjects: Use PaginationRequest/PaginationResponse
- GameObjectLookup: FindComponentType delegates to UnityTypeResolver
Tests: 242/246 passed, 4 skipped (expected)
* Apply code review feedback: consolidate utilities and improve compatibility
Python Server:
- Extract normalize_properties() to shared utils.py (removes duplication)
- Move search_term validation before preflight() for fail-fast
- Fix manage_script.py documentation (remove incorrect 'update' reference)
- Remove stale comments in execute_menu_item.py, manage_editor.py
- Remove misleading destructiveHint from manage_shader.py
C# Unity:
- Add Vector4Converter (commonly used, was missing)
- Fix Unity 2021 compatibility: replace FindObjectsByType with FindObjectsOfType
- Add path normalization in ObjectResolver before StartsWith check
- Improve ComponentOps.SetProperty conversion error detection
- Add Undo.RecordObject in ManageComponents before property modifications
- Improve error message clarity in ManageMaterial.cs
- Add defensive error handling to stress test ToJObject helper
- Increase CI timeout thresholds for test stability
GitHub Workflows:
- Fix GO test sorting in markdown output (GO-10 now sorts after GO-9)
- Add warning logging for fragment parsing errors
* Fix animator hash names in test fixture to match parameter names
BlendXHash/BlendYHash now use 'reachX'/'reachY' to match the
actual animator parameter names.
* fix(windows): improve HTTP server detection and auto-start reliability
- Fix netstat detection on Windows by running netstat.exe directly instead
of piping through findstr (findstr returns exit code 1 when no matches,
causing false detection failures)
- Increase auto-start retry attempts (20→30) and delays (2s→3s) to handle
slow server starts during first install, version upgrades, and dev mode
- Only attempt blind connection after 20 failed detection attempts to reduce
connection error spam during server startup
- Remove verbose debug logs that were spamming the console every frame
* fix: auto-create tags and remove deprecated manage_gameobject actions
- ManageGameObject.cs: Check tag existence before setting; auto-create
undefined tags using InternalEditorUtility.AddTag() instead of relying
on exception handling (Unity logs warning, doesn't throw)
- manage_gameobject.py: Remove deprecated actions (find, get_components,
add_component, remove_component, set_component_property, get_component)
from Literal type - these are now handled by find_gameobjects and
manage_components tools
- Update test suite and unit tests to reflect new auto-create behavior
* fix: address code review feedback
Bug fixes:
- Fix searchInactive flag ignored in FindObjectsOfType (use includeInactive overload)
- Fix property lookup to try both original and normalized names for backwards compat
- Remove dead code for deprecated 'find' action validation
- Update error message to list only valid actions
Improvements:
- Add destructiveHint=True to manage_shader tool
- Limit fallback connection attempts (every 3rd attempt) to avoid spamming errors
- Consolidate PropertyConversion exception handlers to single catch block
- Add tag existence assertion and cleanup in tag auto-creation tests
Test fixes:
- Update SetComponentProperties_ContinuesAfterException log regex for new error format
- Update test_manage_gameobject_param_coercion to test valid actions only
* feat: Redesign GameObject API for better LLM ergonomics
## New Tools
- find_gameobjects: Search GameObjects, returns paginated instance IDs only
- manage_components: Component lifecycle (add, remove, set_property)
## New Resources
- unity://scene/gameobject/{id}: Single GameObject data (no component serialization)
- unity://scene/gameobject/{id}/components: All components (paginated)
- unity://scene/gameobject/{id}/component/{name}: Single component by type
## Updated
- manage_scene get_hierarchy: Now includes componentTypes array
- manage_gameobject: Slimmed to lifecycle only (create, modify, delete)
- Legacy actions (find, get_components, etc.) log deprecation warnings
## Extracted Utilities
- ParamCoercion: Centralized int/bool/float/string coercion
- VectorParsing: Vector3/Vector2/Quaternion/Color parsing
- GameObjectLookup: Centralized GameObject search logic
## Test Coverage
- 76 new Unity EditMode tests for ManageGameObject actions
- 21 new pytest tests for Python tools/resources
- New NL/T CI suite for GameObject API (GO-0 to GO-5)
Addresses LLM confusion with parameter overload by splitting into
focused tools and read-only resources.
* feat: Add static gameobject_api helper resource for UI discoverability
Adds unity://scene/gameobject-api resource that:
- Shows in Cursor's resource list UI (no parameters needed)
- Documents the parameterized gameobject resources
- Explains the workflow: find_gameobjects → read resource
- Lists examples and related tools
* feat: Add GO tests to main NL/T CI workflow
- Adds GO pass (GO-0 to GO-5) after T pass in claude-nl-suite.yml
- Includes retry logic for incomplete GO tests
- Updates all regex patterns to recognize GO-* test IDs
- Updates DESIRED lists to include all 21 tests (NL-0..4, T-A..J, GO-0..5)
- Updates default_titles for GO tests in markdown summary
- Keeps separate claude-gameobject-suite.yml for standalone runs
* feat: Add GameObject API stress tests and NL/T suite updates
Stress Tests (12 new tests):
- BulkCreate small/medium batches
- FindGameObjects pagination with by_component search
- AddComponents to single object
- GetComponents with full serialization
- SetComponentProperties (complex Rigidbody)
- Deep hierarchy creation and path lookup
- GetHierarchy with large scenes
- Resource read performance tests
- RapidFire create-modify-delete cycles
NL/T Suite Updates:
- Added GO-0..GO-10 tests in nl-gameobject-suite.md
- Fixed tool naming: mcp__unity__ → mcp__UnityMCP__
Other:
- Fixed LongUnityScriptClaudeTest.cs compilation errors
- Added reports/, .claude/local/, scripts/local-test/ to .gitignore
All 254 EditMode tests pass (250 run, 4 explicit skips)
* fix: Address code review feedback
- ParamCoercion: Use CultureInfo.InvariantCulture for float parsing
- ManageComponents: Move Transform removal check before GetComponent
- ManageGameObjectFindTests: Use try-finally for LogAssert.ignoreFailingMessages
- VectorParsing: Document that quaternions are not auto-normalized
- gameobject.py: Prefix unused ctx parameter with underscore
* fix: Address additional code review feedback
- ManageComponents: Reuse GameObjectLookup.FindComponentType instead of duplicate
- ManageComponents: Log warnings when SetPropertiesOnComponent fails
- GameObjectLookup: Make FindComponentType public for reuse
- gameobject.py: Extract _normalize_response helper to reduce duplication
- gameobject.py: Add TODO comment for unused typed response classes
* fix: Address more code review feedback
NL/T Prompt Fixes:
- nl-gameobject-suite.md: Remove non-existent list_resources/read_resource from AllowedTools
- nl-gameobject-suite.md: Fix parameter names (component_type, properties)
- nl-unity-suite-nl.md: Remove unused manage_editor from AllowedTools
Test Fixes:
- GameObjectAPIStressTests: Add null check to ToJObject helper
- GameObjectAPIStressTests: Clarify AudioSource usage comment
- ManageGameObjectFindTests: Use built-in 'UI' layer instead of 'Water'
- LongUnityScriptClaudeTest: Clean up NL/T test artifacts (Counte42 typo, HasTarget)
* docs: Add documentation for API limitations and behaviors
- GameObjectLookup.SearchByPath: Document and warn that includeInactive
has no effect (Unity API limitation)
- ManageComponents.TrySetProperty: Document case-insensitive lookup behavior
* More test fixes and tighten parameters on python tools
* fix: Align test expectation with implementation error message case
* docs: update README tools and resources lists
- Add missing tools: manage_components, batch_execute, find_gameobjects, refresh_unity
- Add missing resources: gameobject_api, editor_state_v2
- Make descriptions more concise across all tools and resources
- Ensure documentation matches current MCP server functionality
* fix: Address code review feedback
- ParamCoercion: Use InvariantCulture for int/double parsing consistency
- ManageComponents: Remove redundant Undo.RecordObject (AddComponent handles undo)
- ManageScene: Replace deprecated FindObjectsOfType with FindObjectsByType
- GameObjectLookup: Add explanatory comment to empty catch block
- gameobject.py: Extract _validate_instance_id helper to reduce duplication
- Tests: Fix assertion for instanceID (Unity IDs can be negative)
* chore: Remove accidentally committed test artifacts
- Remove Materials folder (40 .mat files from interactive testing)
- Remove Shaders folder (5 noise shaders from testing)
- Remove test scripts (Bounce*, CylinderBounce* from testing)
- Remove Temp.meta and commit.sh
* test: Improve delete tests to verify actual deletion
- Delete_ByTag_DeletesMatchingObjects: Verify objects are actually destroyed
- Delete_ByLayer_DeletesMatchingObjects: Assert deletion using Unity null check
- Delete_MultipleObjectsSameName_DeletesCorrectly: Document first-match behavior
- Delete_Success_ReturnsDeletedCount: Verify count value if present
All tests now verify deletion occurred rather than just checking for a result.
* refactor: remove deprecated manage_gameobject actions
- Remove deprecated switch cases: find, get_components, get_component, add_component, remove_component, set_component_property
- Remove deprecated wrapper methods (423 lines deleted from ManageGameObject.cs)
- Delete ManageGameObjectFindTests.cs (tests deprecated 'find' action)
- Remove deprecated test methods from ManageGameObjectTests.cs
- Add GameObject resource URIs to README documentation
- Add batch_execute performance tips to README, tool description, and gameobject_api resource
- Enhance batch_execute description to emphasize 10-100x performance gains
Total: ~1200 lines removed. New API (find_gameobjects, manage_components, resources) is the recommended path forward.
* fix: Remove starlette stubs from conftest.py
Starlette is now a proper dependency via the mcp package, so we don't need
to stub it anymore. The real package handles all HTTP transport needs.
* feat: Add tool annotations for improved LLM tool understanding
Add readOnlyHint and destructiveHint annotations to all 23 tools
to help LLMs better understand tool behavior and make safer decisions.
Changes:
- Added readOnlyHint: true to 5 read-only tools:
- debug_request_context, find_in_file, validate_script,
manage_script_capabilities, get_sha
- Added destructiveHint: true to 18 tools that modify data:
- All CRUD tools, execution tools, and state-modifying tools
- Added title annotations for human-readable display
- Imported ToolAnnotations from mcp.types in all tool files
This improves tool safety metadata for MCP clients.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: Clarify dual-purpose tool behavior in annotations
Address Sourcery AI review feedback by updating descriptions for
batch_execute and manage_* tools to clarify their safety characteristics
depend on the specific actions/operations being performed.
Updated tools:
- batch_execute: clarifies safety depends on contained tools
- read_console: clarifies 'get' is read-only, 'clear' is destructive
- manage_asset: lists read-only vs destructive actions
- manage_gameobject: lists read-only vs destructive actions
- manage_scene: lists read-only vs destructive actions
- manage_editor: lists read-only vs destructive actions
- manage_material: lists read-only vs destructive actions
- manage_shader: lists read-only vs destructive actions
- manage_script: lists read-only vs destructive actions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Remove destructiveHint from mixed-behavior tools
Address maintainer feedback on annotation semantics. Tools that
have both read-only and modifying actions based on the 'action'
parameter should not be marked as destructive.
Changed to title-only annotations:
- manage_gameobject (find/get vs create/modify/delete)
- manage_scene (get_hierarchy vs create/load/save)
- manage_prefabs (open_stage vs save/create)
- manage_material (ping/get vs create/set)
- manage_shader (read vs create/update/delete)
- manage_editor (telemetry_status vs play/pause)
- manage_script router (read vs create/delete)
- batch_execute (depends on contained operations)
- execute_menu_item (behavior varies by menu item)
- execute_custom_tool (behavior varies by custom tool)
- read_console (get vs clear - ephemeral UI state)
Kept destructiveHint=True for always-destructive tools:
- apply_text_edits (always writes files)
- create_script (always creates files)
- delete_script (always deletes files)
- script_apply_edits (always writes files)
- run_tests (always executes tests)
- set_active_instance (always modifies session)
* fix: Remove destructiveHint from set_active_instance
set_active_instance is a session-scoped operation that switches which
Unity instance is active. It doesn't persist data and is easily reversible,
so it should not be marked as destructive.
* fix: Re-apply destructiveHint per maintainer guidance on MCP spec
Per maintainer feedback referencing MCP docs, tools should have
destructiveHint=True if they MAY perform a destructive action,
even if they also support read-only operations.
Re-applied to tools that can destroy Unity resources:
- manage_gameobject, manage_scene, manage_prefabs
- manage_material, manage_shader, manage_script
- manage_asset, batch_execute
- execute_menu_item, execute_custom_tool
Kept as-is (no destructiveHint):
- read_console (clearing is ephemeral UI state)
- set_active_instance (session toggle, not destructive)
- manage_editor (no destructive actions)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
* feat: Add tool annotations to manage_scriptable_object
Per reviewer request (@dsarno), add ToolAnnotations with destructiveHint=True
to manage_scriptable_object tool since it can create/modify ScriptableObject assets.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
* feat: Add tool annotations to new async test and refresh tools
Add readOnlyHint and destructiveHint annotations to tools added
since the last commit:
- refresh_unity: destructiveHint=True (triggers asset DB refresh)
- run_tests_async: destructiveHint=True (starts test execution)
- get_test_job: readOnlyHint=True (queries job status only)
Also regenerate uv.lock after rebase.
---------
Co-authored-by: triepod-ai <noreply@github.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: triepod-ai <199543909+triepod-ai@users.noreply.github.com>
* fix: Multi-session UI improvements and HTTP instance recognition
- Separate server and session lifecycle in HTTP Local mode
- Show 'Start Server' / 'Stop Server' button for server control
- Show 'Start Session' / 'End Session' button when server is running
- No auto-join on server start (requires manual session start)
- Show instance name instead of port in session status (e.g. 'Session Active (ramble)')
- Use native project_hash for HTTP instance recognition instead of computed SHA256
- Fix test expectations for manage_asset JSON parsing error messages
* fix: Multi-session UI improvements and HTTP instance recognition
- Separate server and session lifecycle in HTTP Local mode
- Show 'Start Server' / 'Stop Server' button for server control
- Show 'Start Session' / 'End Session' button when server is running
- Auto-start session when THIS instance starts the server
- Require manual session start when connecting to external server
- Auto-detect and end orphaned sessions when server stops
- Show instance name instead of port in session status
- Use native project_hash for HTTP instance recognition
- Guard against empty hash with warning log
- Remove dead code (duplicate _safe_response)
- Add defensive path handling for instance name extraction
* Optimize read_console defaults and paging
* Fix read_console truncate test expectations
* Reduce read_console default count from 50 to 10
Further optimize token usage by reducing the default count from 50 to 10 entries. Even 10-20 messages with stack traces can be token-heavy. Added tests for default behavior and paging functionality. Updated tool description to document defaults and paging support.
* Fix ReadConsoleTests to include log type messages
The default types filter changed to ['error', 'warning'] (excluding 'log'), so tests using Debug.Log() need to explicitly request log messages. Also added format='detailed' to HandleCommand_Get_Works test since it accesses structured message fields.
* Address CodeRabbit review feedback
- Fix property naming consistency: next_cursor -> nextCursor (C# camelCase)
- Remove redundant EndGettingEntries call from catch block (already in finally)
- Extract stacktrace stripping to helper function (reduce duplication)
- Fix test mock to match actual C# response structure (items, nextCursor, truncated, total)
* perf: add early exit optimization for ReadConsole paging
- Add early exit in paging loop once page is filled, avoiding iteration
through remaining console entries (total becomes 'at least N')
- Prefix unused mock arguments with underscores in test_read_console_truncate.py
to suppress Ruff linter warnings
* refactor: give pageSize independent default, clarify count semantics
- Change pageSize resolution from 'pageSize ?? count ?? 50' to 'pageSize ?? 50'
so pageSize has its own default independent of count
- count now only serves as the non-paging limit
- Add XML docs to GetConsoleEntries with clear parameter descriptions
- Update Python tool annotations to document pageSize default (50) and
clarify that count is ignored when paging
* Add editor readiness v2, refresh tool, and preflight guards
* Detect external package changes and harden refresh retry
* feat: add TestRunnerNoThrottle and async test running with background stall prevention
- Add TestRunnerNoThrottle.cs: Sets editor to 'No Throttling' mode during test runs
with SessionState persistence across domain reload
- Add run_tests_async and get_test_job tools for non-blocking test execution
- Add TestJobManager for async test job tracking with progress monitoring
- Add ForceSynchronousImport to all AssetDatabase.Refresh() calls to prevent stalls
- Mark DomainReloadResilienceTests as [Explicit] with documentation explaining
the test infrastructure limitation (internal coroutine waits vs MCP socket polling)
- MCP workflow is unaffected - socket messages provide external stimulus that
keeps Unity responsive even when backgrounded
* refactor: simplify and clean up code
- Remove unused Newtonsoft.Json.Linq import from TestJobManager
- Add throttling to SessionState persistence (once per second) to reduce overhead
- Critical job state changes (start/finish) still persist immediately
- Fix duplicate XML summary tag in DomainReloadResilienceTests
* docs: add async test tools to README, document domain reload limitation
- Add run_tests_async and get_test_job to main README tools list
- Document background stall limitation for domain reload tests in DEV readme
* ci: add separate job for domain reload tests
Run [Explicit] domain_reload tests in their own job using -testCategory
* ci: run domain reload tests in same job as regular tests
Combines into single job with two test steps to reuse cached Library
* fix: address coderabbit review issues
- Fix TOCTOU race in TestJobManager.StartJob (single lock scope for check-and-set)
- Store TestRunnerApi reference with HideAndDontSave to prevent GC/serialization issues
* docs: update tool descriptions to prefer run_tests_async
- run_tests_async is now marked as preferred for long-running suites
- run_tests description notes it blocks and suggests async alternative
* docs: update README screenshot to v8.6 UI
* docs: add v8.6 UI screenshot
* docs: update v8.6 UI screenshot
* docs: update v8.6 UI screenshot
* docs: update v8.6 UI screenshot
* Update README for MCP version and instructions for v8.7
* fix: handle preflight busy signals and derive job status from test results
- manage_asset, manage_gameobject, manage_scene now check preflight return
value and propagate busy/retry signals to clients (fixes Sourcery #1)
- TestJobManager.FinalizeCurrentJobFromRunFinished now sets job status to
Failed when resultPayload.Failed > 0, not always Succeeded (fixes Sourcery #2)
* fix: increase HTTP server startup timeout for dev mode
When 'Force fresh server install' is enabled, uvx uses --no-cache --refresh
which rebuilds the package and takes significantly longer to start.
- Increase timeout from 10s to 45s when dev mode is enabled
- Add informative log message explaining the longer startup time
- Show actual timeout value in warning message
* fix: derive job status from test results in FinalizeFromTask fallback
Apply same logic as FinalizeCurrentJobFromRunFinished: check result.Failed > 0
to correctly mark jobs as Failed when tests fail, even in the fallback path
when RunFinished callback is not delivered.
* Bound Unity reload/session waits
* refactor: improve env var parsing and reason extraction
Address code review feedback:
- Catch ValueError specifically (instead of broad Exception) when parsing
UNITY_MCP_RELOAD_MAX_WAIT_S, UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S, and
UNITY_MCP_SESSION_READY_WAIT_SECONDS, with logging for easier diagnosis
of misconfiguration
- Normalize reason values to lowercase in _extract_response_reason() to
avoid case-sensitive mismatches in comparisons
- Simplify refresh_unity.py by removing redundant isinstance check and
reusing _extract_response_reason instead of duplicating reason parsing
* Add upper bound clamp and custom exception for bounded retry
- Add upper bound (30s) to UNITY_MCP_RELOAD_MAX_WAIT_S to prevent
misconfiguration from causing excessive waits
- Add upper bound (30s) to UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S for
consistency with readiness probe
- Introduce NoUnitySessionError custom exception to replace fragile
string matching in send_command_for_instance
Addresses code review feedback for bounded retry policy PR.
* Add editor readiness v2, refresh tool, and preflight guards
* Detect external package changes and harden refresh retry
* feat: add TestRunnerNoThrottle and async test running with background stall prevention
- Add TestRunnerNoThrottle.cs: Sets editor to 'No Throttling' mode during test runs
with SessionState persistence across domain reload
- Add run_tests_async and get_test_job tools for non-blocking test execution
- Add TestJobManager for async test job tracking with progress monitoring
- Add ForceSynchronousImport to all AssetDatabase.Refresh() calls to prevent stalls
- Mark DomainReloadResilienceTests as [Explicit] with documentation explaining
the test infrastructure limitation (internal coroutine waits vs MCP socket polling)
- MCP workflow is unaffected - socket messages provide external stimulus that
keeps Unity responsive even when backgrounded
* refactor: simplify and clean up code
- Remove unused Newtonsoft.Json.Linq import from TestJobManager
- Add throttling to SessionState persistence (once per second) to reduce overhead
- Critical job state changes (start/finish) still persist immediately
- Fix duplicate XML summary tag in DomainReloadResilienceTests
* docs: add async test tools to README, document domain reload limitation
- Add run_tests_async and get_test_job to main README tools list
- Document background stall limitation for domain reload tests in DEV readme
* ci: add separate job for domain reload tests
Run [Explicit] domain_reload tests in their own job using -testCategory
* ci: run domain reload tests in same job as regular tests
Combines into single job with two test steps to reuse cached Library
* fix: address coderabbit review issues
- Fix TOCTOU race in TestJobManager.StartJob (single lock scope for check-and-set)
- Store TestRunnerApi reference with HideAndDontSave to prevent GC/serialization issues
* docs: update tool descriptions to prefer run_tests_async
- run_tests_async is now marked as preferred for long-running suites
- run_tests description notes it blocks and suggests async alternative
* docs: update README screenshot to v8.6 UI
* docs: add v8.6 UI screenshot
* Update README for MCP version and instructions for v8.7
* fix: handle preflight busy signals and derive job status from test results
- manage_asset, manage_gameobject, manage_scene now check preflight return
value and propagate busy/retry signals to clients (fixes Sourcery #1)
- TestJobManager.FinalizeCurrentJobFromRunFinished now sets job status to
Failed when resultPayload.Failed > 0, not always Succeeded (fixes Sourcery #2)
* fix: increase HTTP server startup timeout for dev mode
When 'Force fresh server install' is enabled, uvx uses --no-cache --refresh
which rebuilds the package and takes significantly longer to start.
- Increase timeout from 10s to 45s when dev mode is enabled
- Add informative log message explaining the longer startup time
- Show actual timeout value in warning message
* fix: derive job status from test results in FinalizeFromTask fallback
Apply same logic as FinalizeCurrentJobFromRunFinished: check result.Failed > 0
to correctly mark jobs as Failed when tests fail, even in the fallback path
when RunFinished callback is not delivered.
* Optimize run_tests to return summary by default, reducing token usage by 98%
- Add includeFailedTests parameter: returns only failed/skipped test details
- Add includeDetails parameter: returns all test details (original behavior)
- Default behavior now returns summary only (~150 tokens vs ~13k tokens)
- Make results field optional in Python schema for backward compatibility
Token savings:
- Default: ~13k tokens saved (98.9% reduction)
- With failures: minimal tokens (only non-passing tests)
- Full details: same as before when explicitly requested
This prevents context bloat for typical test runs where you only need
pass/fail counts, while still allowing detailed debugging when needed.
* Add warning when run_tests filters match no tests; fix test organization
TDD Feature:
- Add warning message when filter criteria match zero tests
- New RunTestsTests.cs validates message formatting logic
- Modified RunTests.cs to append "(No tests matched the specified filters)" when total=0
Test Organization Fixes:
- Move MCPToolParameterTests.cs from EditMode/ to EditMode/Tools/ (matches folder hierarchy)
- Fix inconsistent namespaces to MCPForUnityTests.Editor.{Subfolder}:
- MCPToolParameterTests: Tests.EditMode → MCPForUnityTests.Editor.Tools
- DomainReloadResilienceTests: Tests.EditMode.Tools → MCPForUnityTests.Editor.Tools
- Matrix4x4ConverterTests: MCPForUnityTests.EditMode.Helpers → MCPForUnityTests.Editor.Helpers
* Refactor test result message formatting
* Simplify RunTests warning assertions
* Tests: de-flake cold-start EditMode runs
- Make ManageScriptableObjectTests setup yield-based with longer Unity-ready timeout
- Mark DomainReloadResilienceTests explicit to avoid triggering domain reload during Run All
* Avoid blocking Claude CLI status checks on focus
* Fix Claude Code registration to remove existing server before re-registering
When registering with Claude Code, if a UnityMCP server already exists,
remove it first before adding the new registration. This ensures the
transport mode (HTTP vs stdio) is always updated to match the current
UseHttpTransport EditorPref setting.
Previously, if a stdio registration existed and the user tried to register
with HTTP, the command would fail with 'already exists' and the old stdio
configuration would remain unchanged.
* Fix Claude Code transport validation to parse CLI output format correctly
The validation code was incorrectly parsing the output of 'claude mcp get UnityMCP' by looking for JSON format ("transport": "http"), but the CLI actually returns human-readable text format ("Type: http"). This caused the transport mismatch detection to never trigger, allowing stdio to be selected in the UI while HTTP was registered with Claude Code.
Changes:
- Fix parsing logic to check for "Type: http" or "Type: stdio" in CLI output
- Add OnTransportChanged event to refresh client status when transport changes
- Wire up event handler to trigger client status refresh on transport dropdown change
This ensures that when the transport mode in Unity doesn't match what's registered with Claude Code, the UI will correctly show an error status with instructions to re-register.
* Fix Claude Code registration UI blocking and thread safety issues
This commit resolves three issues with Claude Code registration:
1. UI blocking: Removed synchronous CheckStatus() call after registration
that was blocking the editor. Status is now set immediately with async
verification happening in the background.
2. Thread safety: Fixed "can only be called from the main thread" errors
by capturing Application.dataPath and EditorPrefs.GetBool() on the main
thread before spawning async status check tasks.
3. Transport mismatch detection: Transport mode changes now trigger immediate
status checks to detect HTTP/stdio mismatches, instead of waiting for the
45-second refresh interval.
The registration button now turns green immediately after successful
registration without blocking, and properly detects transport mismatches
when switching between HTTP and stdio modes.
* Enforce thread safety for Claude Code status checks at compile time
Address code review feedback by making CheckStatusWithProjectDir thread-safe
by design rather than by convention:
1. Made projectDir and useHttpTransport parameters non-nullable to prevent
accidental background thread calls without captured values
2. Removed nullable fallback to EditorPrefs.GetBool() which would cause
thread safety violations if called from background threads
3. Added ArgumentNullException for null projectDir instead of falling back
to Application.dataPath (which is main-thread only)
4. Added XML documentation clearly stating threading contracts:
- CheckStatus() must be called from main thread
- CheckStatusWithProjectDir() is safe for background threads
5. Removed unreachable else branch in async status check code
These changes make it impossible to misuse the API from background threads,
with compile-time enforcement instead of runtime errors.
* Consolidate local HTTP Start/Stop and auto-start session
* HTTP improvements: Unity-owned server lifecycle + UI polish
* Deterministic HTTP stop via pidfile+token; spawn server in terminal
* Fix review feedback: token validation, host normalization, safer casts
* Fix stop heuristics edge cases; remove dead pid capture
* Fix unity substring guard in stop heuristics
* Fix local server cleanup and connection checks
* Fix read_console default limits; cleanup Unity-managed server vestiges
* Fix unfocused reconnect stalls; fast-fail retryable Unity commands
* Simplify PluginHub reload handling; honor run_tests timeout
* Fix Windows Claude CLI status check threading
* Fix test teardown to avoid dropping MCP bridge
CodexConfigHelperTests was calling MCPServiceLocator.Reset() in TearDown, which disposes the active bridge/transport during MCP-driven test runs. Replace with restoring only the mutated service (IPlatformService).
* Avoid leaking PlatformService in CodexConfigHelperTests
Capture the original IPlatformService before this fixture runs and restore it in TearDown. This preserves the MCP connection safety fix (no MCPServiceLocator.Reset()) while avoiding global state leakage to subsequent tests.
* Fix SO MCP tooling: validate folder roots, normalize paths, expand tests; remove vestigial SO tools
* Remove UnityMCPTests stress artifacts and ignore Assets/Temp
* Ignore UnityMCPTests Assets/Temp only
* Clarify array_resize fallback logic comments
* Refactor: simplify action set and reuse slash sanitization
* Enhance: preserve GUID on overwrite & support Vector/Color types in ScriptableObject tools
* Fix: ensure asset name matches filename to suppress Unity warnings
* Fix: resolve Unity warnings by ensuring asset name match and removing redundant import
* Refactor: Validate assetName, strict object parsing for vectors, remove broken SO logic from ManageAsset
* Hardening: reject Windows drive paths; clarify supported asset types
* Delete FixscriptableobjecPlan.md
* Paginate get_hierarchy and get_components to prevent large payload crashes
* dev: add uvx dev-mode refresh + safer HTTP stop; fix server typing eval
* Payload-safe paging defaults + docs; harden asset search; stabilize Codex tests
* chore: align uvx args + coercion helpers; tighten safety guidance
* chore: minor cleanup + stabilize EditMode SO tests
* Fix test teardown to avoid dropping MCP bridge
CodexConfigHelperTests was calling MCPServiceLocator.Reset() in TearDown, which disposes the active bridge/transport during MCP-driven test runs. Replace with restoring only the mutated service (IPlatformService).
* Avoid leaking PlatformService in CodexConfigHelperTests
Capture the original IPlatformService before this fixture runs and restore it in TearDown. This preserves the MCP connection safety fix (no MCPServiceLocator.Reset()) while avoiding global state leakage to subsequent tests.
* Fix SO MCP tooling: validate folder roots, normalize paths, expand tests; remove vestigial SO tools
* Remove UnityMCPTests stress artifacts and ignore Assets/Temp
* Ignore UnityMCPTests Assets/Temp only
* Clarify array_resize fallback logic comments
* Refactor: simplify action set and reuse slash sanitization
* Enhance: preserve GUID on overwrite & support Vector/Color types in ScriptableObject tools
* Fix: ensure asset name matches filename to suppress Unity warnings
* Fix: resolve Unity warnings by ensuring asset name match and removing redundant import
* Refactor: Validate assetName, strict object parsing for vectors, remove broken SO logic from ManageAsset
* Hardening: reject Windows drive paths; clarify supported asset types
* Delete FixscriptableobjecPlan.md
* docs: Add manage_scriptable_object tool description to README
* Update server instructions with new options
* Upgrade to a later version of Pydantic
This should have improved Python 3.14 support
* Swap order of instructions so Docker comes before local building
* Add fixed versions back to the README
* Update README to clarify the GitHub uvx command
Marcus Sanatan
whatevertogo
Shutong Wu
dsarno
GitHub Actions
Berkant
Bryan Thompson