PHXH
/
unity-mcp
51
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
unity-mcp/README-zh.md

441 lines
18 KiB
Markdown
Raw Normal View History

HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
<img width="676" height="380" alt="MCP for Unity" src="docs/images/logo.png" />
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
| [English](README.md) | [简体中文](README-zh.md) |
|----------------------|---------------------------------|
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
#### 由 [Coplay](https://www.coplay.dev/?ref=unity-mcp) 荣誉赞助和维护 -- Unity 最好的 AI 助手。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
[![Discord](https://img.shields.io/badge/discord-join-red.svg?logo=discord&logoColor=white)](https://discord.gg/y4p8KfzrN4)
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
[![](https://img.shields.io/badge/Website-Visit-purple)](https://www.coplay.dev/?ref=unity-mcp)
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
[![](https://img.shields.io/badge/Unity-000000?style=flat&logo=unity&logoColor=blue 'Unity')](https://unity.com/releases/editor/archive)
feat: lower minimum Python requirement to 3.10+ (#362) * feat: lower minimum Python requirement to 3.10+ - Updated Python version requirement from 3.11+ to 3.10+ across all platform detectors - Added Python 3.10 to MacOS framework search paths for broader compatibility - Modified version validation logic to accept Python 3.10 or higher - Updated documentation and error messages to reflect new minimum Python version - Changed pyproject.toml requires-python field to ">=3.10" - Updated badges and requirements in README files to show Python 3.10 support * feat: add Python 3.10 and 3.11 to Windows path detection - Added Python 3.10 installation path to LocalApplicationData search locations - Added Python 3.10 and 3.11 paths to ProgramFiles search locations - Expanded Python version compatibility to support older installations while maintaining support for newer versions * feat: add Python 3.14 support and update path detection - Added Python 3.14 installation paths to Windows and macOS platform detectors - Removed legacy Python 3.9 paths from Windows path detection - Updated Windows installation recommendations to suggest Python 3.10 or higher - Added additional Python framework paths (3.10, 3.11) for macOS UV package manager detection - Extended UV executable path detection to include Python 3.14 locations on both platforms * Reduce size of README img * Revert "Reduce size of README img" This reverts commit 6fb99c7047bdef3610fb94dd3741c71c9e3ffcc1. * Adjust size in README to maintain quality but be smaller
2025-11-01 03:44:10 +08:00
[![python](https://img.shields.io/badge/Python-3.10+-3776AB.svg?style=flat&logo=python&logoColor=white)](https://www.python.org)
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
[![](https://badge.mcpx.dev?status=on 'MCP Enabled')](https://modelcontextprotocol.io/introduction)
![GitHub commit activity](https://img.shields.io/github/commit-activity/w/CoplayDev/unity-mcp)
![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/CoplayDev/unity-mcp)
[![](https://img.shields.io/badge/License-MIT-red.svg 'MIT License')](https://opensource.org/licenses/MIT)
**使用大语言模型创建您的 Unity 应用！**
MCP for Unity 作为桥梁，允许 AI 助手（如 Claude、Cursor）通过本地 **MCP（模型上下文协议）客户端** 直接与您的 Unity 编辑器交互。为您的大语言模型提供管理资源、控制场景、编辑脚本和自动化 Unity 任务的工具。
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
<img width="406" height="704" alt="MCP for Unity screenshot" src="docs/images/readme_ui.png">
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
### 💬 加入我们的 [Discord](https://discord.gg/y4p8KfzrN4)
**获得帮助、分享想法，与其他 MCP for Unity 开发者协作！**
---
## 主要功能 🚀
* **🗣️ 自然语言操控：** 指示您的大语言模型执行 Unity 任务。
* **🛠️ 强大工具：** 管理资源、场景、材质、脚本和编辑器功能。
* **🤖 自动化：** 自动化重复的 Unity 工作流程。
* **🧩 可扩展：** 设计为与各种 MCP 客户端协作。
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
* **🌐 HTTP 优先传输：** 默认启用 HTTP 连接（stdio 仍可作为备选方案）。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
<details open>
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
<summary><strong>工具</strong></summary>
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
您的大语言模型可以使用以下功能：
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
* `execute_custom_tool`: 执行由 Unity 注册的项目范围自定义工具。
Move Get commands to editor resources + Run Python tests every update (#368) * Add a function to reload the domain Closes #357 * feat: restructure server instructions into workflow-focused format - Reorganized instructions from flat bullet list into categorized workflow sections - Emphasized critical script management workflow with numbered steps - Improved readability and scannability for AI agents using the MCP server It doesn't make sense to repeat the fucnction tools, they're already parsed * docs: reorder tool list alphabetically in README + add reload_domain tool * feat: add Unity editor state and project info resources - Implemented resources for querying active tool, editor state, prefab stage, selection, and open windows - Added project configuration resources for layers and project metadata - Organized new resources into Editor and Project namespaces for better structure * feat: clarify script management workflow in system prompt - Expanded guidance to include scripts created by any tool, not just manage_script - Added "etc" to tools examples for better clarity * refactor: remove reload_domain tool and update script management workflow - Removed reload_domain tool as Unity automatically recompiles scripts when modified - Updated script management instructions to rely on editor_state polling and console checking instead of manual domain reload - Simplified workflow by removing unnecessary manual recompilation step * Change name of menu items resource as the LLM seems it * refactor: reorganize tests into src/tests/integration directory - Moved all test files from root tests/ to MCPForUnity/UnityMcpServer~/src/tests/integration/ for better organization - Added conftest.py with telemetry and dependency stubs to simplify test setup - Removed redundant path manipulation and module loading code from individual test files * feat: expand Unity test workflow triggers - Run tests on all branches instead of only main - Add pull request trigger to catch issues before merge - Maintain path filtering to run only when relevant files change * chore: add GitHub Actions workflow for Python tests - Configured automated testing on push and pull requests using pytest - Set up uv for dependency management and Python 3.10 environment - Added test results artifact upload for debugging failed runs * refactor: update import path for fastmcp Context * docs: update development setup instructions to use uv - Changed installation commands from pip to uv pip for better dependency management - Updated test running instructions to use uv run pytest - Added examples for running integration and unit tests separately * Formatting [skip ci] * refactor: optimize CI workflow with path filters and dependency installation - Added path filters to only trigger tests when Python source or workflow files change - Split dependency installation into sync and dev install steps for better clarity - Fixed YAML indentation for improved readability * Update .github/workflows/python-tests.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * fix: standardize test mode values to match Unity's naming convention - Changed default mode from "edit" to "EditMode" in C# code - Updated Python tool to use "EditMode" and "PlayMode" instead of lowercase variants * refactor: convert test imports to relative imports - Changed absolute imports to relative imports in integration tests for better package structure - Removed test packages from pyproject.toml package list * refactor: use Field with default_factory for mutable default in TagsResponse * refactor: remove duplicate PrefabStageUtility call * Update this as well [skip ci] * Update MCPForUnity/UnityMcpServer~/src/tests/integration/test_script_tools.py Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * chore: remove pull_request triggers from test workflows [skip ci] It's already covered by pushes * refactor: update resource function return types to include MCPResponse union * refactor: remove manual domain reload tool - Removed reload_domain tool as Unity handles script recompilation automatically - Updated documentation to reflect automatic compilation workflow - Simplified script management workflow instructions in server description * refactor: add context support to resource handlers - Updated all resource handlers to accept Context parameter for Unity instance routing - Replaced direct async_send_command_with_retry calls with async_send_with_unity_instance wrapper - Added imports for get_unity_instance_from_context and async_send_with_unity_instance helpers * fix: correct grammar in menu items documentation * docs: update README with expanded tools and resources documentation - Added new tools: manage_prefabs, create_script, delete_script, get_sha - Added new resources: editor state, windows, project info, layers, and tags - Clarified manage_script as compatibility router with recommendation to use newer edit tools - Fixed run_test to run_tests for consistency * refactor: convert unity_instances function to async [skip ci] - Changed function signature from synchronous to async - Added await keywords to ctx.info() and ctx.error() calls to properly handle async context methods --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-06 04:06:48 +08:00
* `execute_menu_item`: 执行 Unity 编辑器菜单项（例如，"File/Save Project"）。
* `manage_asset`: 执行资源操作（导入、创建、修改、删除等）。
* `manage_editor`: 控制和查询编辑器的状态和设置。
* `manage_gameobject`: 管理游戏对象：创建、修改、删除、查找和组件操作。
* `manage_prefabs`: 执行预制件操作（创建、修改、删除等）。
* `manage_scene`: 管理场景（加载、保存、创建、获取层次结构等）。
* `manage_script`: 传统脚本操作的兼容性路由器（创建、读取、删除）。建议使用 `apply_text_edits` 或 `script_apply_edits` 进行编辑。
* `manage_shader`: 执行着色器 CRUD 操作（创建、读取、修改、删除）。
* `read_console`: 获取控制台消息或清除控制台。
* `run_tests`: 在 Unity 编辑器中运行测试。
* `set_active_instance`: 将后续工具调用路由到特定的 Unity 实例（当运行多个实例时）。
* `apply_text_edits`: 具有前置条件哈希和原子多编辑批次的精确文本编辑。
* `script_apply_edits`: 结构化 C# 方法/类编辑（插入/替换/删除），具有更安全的边界。
* `validate_script`: 快速验证（基本/标准）以在写入前后捕获语法/结构问题。
* `create_script`: 在给定的项目路径创建新的 C# 脚本。
* `delete_script`: 通过 URI 或 Assets 相对路径删除 C# 脚本。
* `get_sha`: 获取 Unity C# 脚本的 SHA256 和基本元数据，而不返回文件内容。
</details>
<details open>
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
<summary><strong>资源</strong></summary>
Move Get commands to editor resources + Run Python tests every update (#368) * Add a function to reload the domain Closes #357 * feat: restructure server instructions into workflow-focused format - Reorganized instructions from flat bullet list into categorized workflow sections - Emphasized critical script management workflow with numbered steps - Improved readability and scannability for AI agents using the MCP server It doesn't make sense to repeat the fucnction tools, they're already parsed * docs: reorder tool list alphabetically in README + add reload_domain tool * feat: add Unity editor state and project info resources - Implemented resources for querying active tool, editor state, prefab stage, selection, and open windows - Added project configuration resources for layers and project metadata - Organized new resources into Editor and Project namespaces for better structure * feat: clarify script management workflow in system prompt - Expanded guidance to include scripts created by any tool, not just manage_script - Added "etc" to tools examples for better clarity * refactor: remove reload_domain tool and update script management workflow - Removed reload_domain tool as Unity automatically recompiles scripts when modified - Updated script management instructions to rely on editor_state polling and console checking instead of manual domain reload - Simplified workflow by removing unnecessary manual recompilation step * Change name of menu items resource as the LLM seems it * refactor: reorganize tests into src/tests/integration directory - Moved all test files from root tests/ to MCPForUnity/UnityMcpServer~/src/tests/integration/ for better organization - Added conftest.py with telemetry and dependency stubs to simplify test setup - Removed redundant path manipulation and module loading code from individual test files * feat: expand Unity test workflow triggers - Run tests on all branches instead of only main - Add pull request trigger to catch issues before merge - Maintain path filtering to run only when relevant files change * chore: add GitHub Actions workflow for Python tests - Configured automated testing on push and pull requests using pytest - Set up uv for dependency management and Python 3.10 environment - Added test results artifact upload for debugging failed runs * refactor: update import path for fastmcp Context * docs: update development setup instructions to use uv - Changed installation commands from pip to uv pip for better dependency management - Updated test running instructions to use uv run pytest - Added examples for running integration and unit tests separately * Formatting [skip ci] * refactor: optimize CI workflow with path filters and dependency installation - Added path filters to only trigger tests when Python source or workflow files change - Split dependency installation into sync and dev install steps for better clarity - Fixed YAML indentation for improved readability * Update .github/workflows/python-tests.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * fix: standardize test mode values to match Unity's naming convention - Changed default mode from "edit" to "EditMode" in C# code - Updated Python tool to use "EditMode" and "PlayMode" instead of lowercase variants * refactor: convert test imports to relative imports - Changed absolute imports to relative imports in integration tests for better package structure - Removed test packages from pyproject.toml package list * refactor: use Field with default_factory for mutable default in TagsResponse * refactor: remove duplicate PrefabStageUtility call * Update this as well [skip ci] * Update MCPForUnity/UnityMcpServer~/src/tests/integration/test_script_tools.py Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * chore: remove pull_request triggers from test workflows [skip ci] It's already covered by pushes * refactor: update resource function return types to include MCPResponse union * refactor: remove manual domain reload tool - Removed reload_domain tool as Unity handles script recompilation automatically - Updated documentation to reflect automatic compilation workflow - Simplified script management workflow instructions in server description * refactor: add context support to resource handlers - Updated all resource handlers to accept Context parameter for Unity instance routing - Replaced direct async_send_command_with_retry calls with async_send_with_unity_instance wrapper - Added imports for get_unity_instance_from_context and async_send_with_unity_instance helpers * fix: correct grammar in menu items documentation * docs: update README with expanded tools and resources documentation - Added new tools: manage_prefabs, create_script, delete_script, get_sha - Added new resources: editor state, windows, project info, layers, and tags - Clarified manage_script as compatibility router with recommendation to use newer edit tools - Fixed run_test to run_tests for consistency * refactor: convert unity_instances function to async [skip ci] - Changed function signature from synchronous to async - Added await keywords to ctx.info() and ctx.error() calls to properly handle async context methods --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-06 04:06:48 +08:00
您的大语言模型可以检索以下资源：
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
* `custom_tools`: 列出活动 Unity 项目可用的自定义工具。
Move Get commands to editor resources + Run Python tests every update (#368) * Add a function to reload the domain Closes #357 * feat: restructure server instructions into workflow-focused format - Reorganized instructions from flat bullet list into categorized workflow sections - Emphasized critical script management workflow with numbered steps - Improved readability and scannability for AI agents using the MCP server It doesn't make sense to repeat the fucnction tools, they're already parsed * docs: reorder tool list alphabetically in README + add reload_domain tool * feat: add Unity editor state and project info resources - Implemented resources for querying active tool, editor state, prefab stage, selection, and open windows - Added project configuration resources for layers and project metadata - Organized new resources into Editor and Project namespaces for better structure * feat: clarify script management workflow in system prompt - Expanded guidance to include scripts created by any tool, not just manage_script - Added "etc" to tools examples for better clarity * refactor: remove reload_domain tool and update script management workflow - Removed reload_domain tool as Unity automatically recompiles scripts when modified - Updated script management instructions to rely on editor_state polling and console checking instead of manual domain reload - Simplified workflow by removing unnecessary manual recompilation step * Change name of menu items resource as the LLM seems it * refactor: reorganize tests into src/tests/integration directory - Moved all test files from root tests/ to MCPForUnity/UnityMcpServer~/src/tests/integration/ for better organization - Added conftest.py with telemetry and dependency stubs to simplify test setup - Removed redundant path manipulation and module loading code from individual test files * feat: expand Unity test workflow triggers - Run tests on all branches instead of only main - Add pull request trigger to catch issues before merge - Maintain path filtering to run only when relevant files change * chore: add GitHub Actions workflow for Python tests - Configured automated testing on push and pull requests using pytest - Set up uv for dependency management and Python 3.10 environment - Added test results artifact upload for debugging failed runs * refactor: update import path for fastmcp Context * docs: update development setup instructions to use uv - Changed installation commands from pip to uv pip for better dependency management - Updated test running instructions to use uv run pytest - Added examples for running integration and unit tests separately * Formatting [skip ci] * refactor: optimize CI workflow with path filters and dependency installation - Added path filters to only trigger tests when Python source or workflow files change - Split dependency installation into sync and dev install steps for better clarity - Fixed YAML indentation for improved readability * Update .github/workflows/python-tests.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * fix: standardize test mode values to match Unity's naming convention - Changed default mode from "edit" to "EditMode" in C# code - Updated Python tool to use "EditMode" and "PlayMode" instead of lowercase variants * refactor: convert test imports to relative imports - Changed absolute imports to relative imports in integration tests for better package structure - Removed test packages from pyproject.toml package list * refactor: use Field with default_factory for mutable default in TagsResponse * refactor: remove duplicate PrefabStageUtility call * Update this as well [skip ci] * Update MCPForUnity/UnityMcpServer~/src/tests/integration/test_script_tools.py Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * chore: remove pull_request triggers from test workflows [skip ci] It's already covered by pushes * refactor: update resource function return types to include MCPResponse union * refactor: remove manual domain reload tool - Removed reload_domain tool as Unity handles script recompilation automatically - Updated documentation to reflect automatic compilation workflow - Simplified script management workflow instructions in server description * refactor: add context support to resource handlers - Updated all resource handlers to accept Context parameter for Unity instance routing - Replaced direct async_send_command_with_retry calls with async_send_with_unity_instance wrapper - Added imports for get_unity_instance_from_context and async_send_with_unity_instance helpers * fix: correct grammar in menu items documentation * docs: update README with expanded tools and resources documentation - Added new tools: manage_prefabs, create_script, delete_script, get_sha - Added new resources: editor state, windows, project info, layers, and tags - Clarified manage_script as compatibility router with recommendation to use newer edit tools - Fixed run_test to run_tests for consistency * refactor: convert unity_instances function to async [skip ci] - Changed function signature from synchronous to async - Added await keywords to ctx.info() and ctx.error() calls to properly handle async context methods --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-06 04:06:48 +08:00
* `unity_instances`: 列出所有正在运行的 Unity 编辑器实例及其详细信息（名称、路径、端口、状态）。
* `menu_items`: 检索 Unity 编辑器中所有可用的菜单项。
* `tests`: 检索 Unity 编辑器中所有可用的测试。可以选择特定类型的测试（例如，"EditMode"、"PlayMode"）。
* `editor_active_tool`: 当前活动的编辑器工具（移动、旋转、缩放等）和变换手柄设置。
* `editor_prefab_stage`: 如果预制件在隔离模式下打开，则为当前预制件编辑上下文。
* `editor_selection`: 有关编辑器中当前选定对象的详细信息。
* `editor_state`: 当前编辑器运行时状态，包括播放模式、编译状态、活动场景和选择摘要。
* `editor_windows`: 所有当前打开的编辑器窗口及其标题、类型、位置和焦点状态。
* `project_info`: 静态项目信息，包括根路径、Unity 版本和平台。
* `project_layers`: 项目 TagManager 中定义的所有层及其索引（0-31）。
* `project_tags`: 项目 TagManager 中定义的所有标签。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
</details>
---
## 工作原理
MCP for Unity 使用两个组件连接您的工具：
1. **MCP for Unity Bridge：** 在编辑器内运行的 Unity 包。（通过包管理器安装）。
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
2. **MCP for Unity Server：** 本地运行的 Python 服务器（从终端窗口运行），通过 HTTP/JSON-RPC 与您的 MCP 客户端通信。Unity 窗口默认以 HTTP 模式为您启动它；如果您切换传输方式，stdio 仍然可用。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
<img width="562" height="121" alt="image" src="https://github.com/user-attachments/assets/9abf9c66-70d1-4b82-9587-658e0d45dc3e" />
---
## 安装 ⚙️
### 前置要求
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
* **Python：** 版本 3.10 或更新。[下载 Python](https://www.python.org/downloads/)
* **Unity Hub 和编辑器：** 版本 2021.3 LTS 或更新。[下载 Unity](https://unity.com/download)
* **uv（Python 工具链管理器）：**
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
# Windows (PowerShell)
winget install --id=astral-sh.uv -e
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
# 文档: https://docs.astral.sh/uv/getting-started/installation/
```
* **MCP 客户端：** [Claude Desktop](https://claude.ai/download) | [Claude Code](https://github.com/anthropics/claude-code) | [Cursor](https://www.cursor.com/en/downloads) | [Visual Studio Code Copilot](https://code.visualstudio.com/docs/copilot/overview) | [Windsurf](https://windsurf.com) | 其他客户端可通过手动配置使用
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
* <details> <summary><strong>[可选] Roslyn 用于高级脚本验证</strong></summary>
对于捕获未定义命名空间、类型和方法的**严格**验证级别：
**方法 1：Unity 的 NuGet（推荐）**
1. 安装 [NuGetForUnity](https://github.com/GlitchEnzo/NuGetForUnity)
2. 前往 `Window > NuGet Package Manager`
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
3. 搜索 `Microsoft.CodeAnalysis`，选择版本 4.14.0 并安装包
4. 同时安装包 `SQLitePCLRaw.core` 和 `SQLitePCLRaw.bundle_e_sqlite3`。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
5. 前往 `Player Settings > Scripting Define Symbols`
6. 添加 `USE_ROSLYN`
7. 重启 Unity
**方法 2：手动 DLL 安装**
1. 从 [NuGet](https://www.nuget.org/packages/Microsoft.CodeAnalysis.CSharp/) 下载 Microsoft.CodeAnalysis.CSharp.dll 和依赖项
2. 将 DLL 放置在 `Assets/Plugins/` 文件夹中
3. 确保 .NET 兼容性设置正确
4. 将 `USE_ROSLYN` 添加到脚本定义符号
5. 重启 Unity
**注意：** 没有 Roslyn 时，脚本验证会回退到基本结构检查。Roslyn 启用完整的 C# 编译器诊断和精确错误报告。</details>
---
### 🌟 步骤 1：安装 Unity 包
#### 通过 Git URL 安装
1. 打开您的 Unity 项目。
2. 前往 `Window > Package Manager`。
3. 点击 `+` -> `Add package from git URL...`。
4. 输入：
```
chore: bump version to 8.0.0
2025-11-25 11:22:14 +08:00
https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v8.0.0
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
```
5. 点击 `Add`。
#### 通过 OpenUPM 安装
1. 安装 [OpenUPM CLI](https://openupm.com/docs/getting-started-cli.html)
2. 打开终端（PowerShell、Terminal 等）并导航到您的 Unity 项目目录
3. 运行 `openupm add com.coplaydev.unity-mcp`
**注意：** 如果您在 Coplay 维护之前安装了 MCP 服务器，您需要在重新安装新版本之前卸载旧包。
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
### ⚡️ 步骤 2：启动本地 HTTP 服务器（默认）
HTTP 传输默认启用。Unity 窗口可以为您启动 FastMCP 服务器：
1. 打开 `Window > MCP for Unity`。
2. 确保**传输**下拉菜单设置为 `HTTP`（默认），并且 **HTTP URL** 是您想要的（默认为 `http://localhost:8080`）。
3. 点击**启动本地 HTTP 服务器**。Unity 会生成一个新的操作系统终端，运行 `uv ... server.py --transport http`。
4. 在您工作时保持该终端窗口打开；关闭它会停止服务器。如果您需要干净地关闭它，请使用 Unity 窗口中的**停止会话**按钮。
> 更喜欢 stdio？将传输下拉菜单更改为 `Stdio`，Unity 将回退到嵌入式 TCP 桥接器，而不是启动 HTTP 服务器。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
**手动启动（可选）**
您也可以从终端自己启动服务器——对 CI 或当您想查看原始日志时很有用：
```bash
chore: bump version to 8.0.0
2025-11-25 11:22:14 +08:00
uvx --from "git+https://github.com/CoplayDev/unity-mcp@v8.0.0#subdirectory=Server" mcp-for-unity --transport http --http-url http://localhost:8080
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
```
在客户端连接时保持进程运行。
### 🛠️ 步骤 3：配置您的 MCP 客户端
将您的 MCP 客户端（Claude、Cursor 等）连接到步骤 2（自动）的 HTTP 服务器或通过手动配置（如下）。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
**选项 A：自动设置（推荐用于 Claude/Cursor/VSC Copilot）**
1. 在 Unity 中，前往 `Window > MCP for Unity`。
2. 点击 `Auto-Setup`。
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
3. 寻找绿色状态指示器 🟢 和"Connected ✓"。*（这会写入指向您在步骤 2 中启动的服务器的 HTTP `url`）。*
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
<details><summary><strong>客户端特定故障排除</strong></summary>
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
- **VSCode**：使用 `Code/User/mcp.json` 和顶级 `servers.unityMCP`、`"type": "http"` 以及步骤 2 中的 URL。在 Windows 上，当您切换回 stdio 时，MCP for Unity 仍然偏好绝对 `uv.exe` 路径。
- **Cursor / Windsurf** [(**帮助链接**)](https://github.com/CoplayDev/unity-mcp/wiki/1.-Fix-Unity-MCP-and-Cursor,-VSCode-&-Windsurf)：如果缺少 `uv`，MCP for Unity 窗口会显示"uv Not Found"和快速 [HELP] 链接以及"Choose `uv` Install Location"按钮。
- **Claude Code** [(**帮助链接**)](https://github.com/CoplayDev/unity-mcp/wiki/2.-Fix-Unity-MCP-and-Claude-Code)：如果找不到 `claude`，窗口会显示"Claude Not Found"和 [HELP] 以及"Choose Claude Location"按钮。注销现在会立即更新 UI。</details>
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
**选项 B：手动配置**
如果自动设置失败或您使用不同的客户端：
1. **找到您的 MCP 客户端配置文件。**（查看客户端文档）。
* *Claude 示例（macOS）：* `~/Library/Application Support/Claude/claude_desktop_config.json`
* *Claude 示例（Windows）：* `%APPDATA%\Claude\claude_desktop_config.json`
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
2. **编辑文件** 以添加/更新 `mcpServers` 部分，使其指向步骤 2 中的 HTTP 端点。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
<details>
<summary><strong>点击查看客户端特定的 JSON 配置片段...</strong></summary>
---
**Claude Code**
如果您正在使用 Claude Code，您可以使用以下命令注册 MCP 服务器：
**macOS：**
```bash
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
claude mcp add --scope user UnityMCP -- uv --directory /Users/USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src run server.py
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
```
**Windows：**
```bash
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
claude mcp add --scope user UnityMCP -- "C:/Users/USERNAME/AppData/Local/Microsoft/WinGet/Links/uv.exe" --directory "C:/Users/USERNAME/AppData/Local/UnityMCP/UnityMcpServer/src" run server.py
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
```
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
**VSCode（所有操作系统 – HTTP 默认）**
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
```json
{
"servers": {
"unityMCP": {
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
"type": "http",
"url": "http://localhost:8080/mcp"
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
}
}
}
```
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
**macOS / Windows / Linux（Claude Desktop、Cursor、Claude Code、Windsurf 等 – HTTP 默认）**
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
```json
{
"mcpServers": {
"UnityMCP": {
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
"url": "http://localhost:8080/mcp"
}
}
}
```
将 URL 设置为与您在 Unity 窗口中输入的内容匹配（包括 `/mcp`）。
#### Stdio 配置示例（传统 / 可选）
将 Unity 传输下拉菜单切换到 `Stdio`，然后使用以下 `command`/`args` 块之一。
**VSCode（stdio）**
```json
{
"servers": {
"unityMCP": {
"type": "stdio",
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
"command": "uv",
"args": [
"--directory",
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
"<ABSOLUTE_PATH_TO>/UnityMcpServer/src",
"run",
"server.py",
"--transport",
"stdio"
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
]
}
}
}
```
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
**macOS / Linux（stdio）**
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
```json
{
"mcpServers": {
"UnityMCP": {
"command": "uv",
"args": [
"run",
"--directory",
"/Users/YOUR_USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src",
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
"server.py",
"--transport",
"stdio"
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
]
}
}
}
```
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
**Windows（stdio）**
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
```json
{
"mcpServers": {
"UnityMCP": {
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
"command": "C:/Users/YOUR_USERNAME/AppData/Local/Microsoft/WinGet/Links/uv.exe",
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
"args": [
"run",
"--directory",
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
"C:/Users/YOUR_USERNAME/AppData/Local/UnityMCP/UnityMcpServer/src",
"server.py",
"--transport",
"stdio"
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
]
}
}
}
```
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
根据您的平台需要替换 `YOUR_USERNAME` 和 `AppSupport` 路径段。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
</details>
---
## 使用方法 ▶️
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
1. **打开您的 Unity 项目** 并验证 HTTP 服务器正在运行（Window > MCP for Unity > Start Local HTTP Server）。一旦服务器启动，指示器应显示"Session Active"。
2. **启动您的 MCP 客户端**（Claude、Cursor 等）。它连接到步骤 3 中配置的 HTTP 端点——客户端不会生成额外的终端。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
3. **交互！** Unity 工具现在应该在您的 MCP 客户端中可用。
示例提示：`创建一个 3D 玩家控制器`，`创建一个 3D 井字游戏`，`创建一个酷炫的着色器并应用到立方体上`。
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
### 使用多个 Unity 实例
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
MCP for Unity 同时支持多个 Unity 编辑器实例。每个实例在每个 MCP 客户端会话中是隔离的。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
**要将工具调用定向到特定实例：**
Make it easier to add tools (#301) * Add a decorate that wraps around the `mcp.tool` decorator. This will allow us to more easily collect tools * Register tools that's defined in the tools folder * Update Python tools to use new decorator * Convert script_apply_edits tool * Convert last remaining tools with new decorator * Create an attribute so we can identify tools via Reflection * Add attribute to all C# tools * Use reflection to load tools * Initialize command registry to load tools at startup * Update tests * Move Dev docs to docs folder * Add docs for adding custom tools * Update function docs for Python decorator * Add working example of adding a screenshot tool * docs: update relative links in README files Updated the relative links in both README-DEV.md and README-DEV-zh.md to use direct filenames instead of paths relative to the docs directory, improving link correctness when files are accessed from the root directory. * docs: update telemetry documentation path reference Updated the link to TELEMETRY.md in README.md to point to the new docs/ directory location to ensure users can access the telemetry documentation correctly. Also moved the TELEMETRY.md file to the docs/ directory as part of the documentation restructuring. * rename CursorHelp.md to docs/CURSOR_HELP.md Moved the CursorHelp.md file to the docs directory to better organize documentation files and improve project structure. * docs: update CUSTOM_TOOLS.md with improved tool naming documentation and path corrections - Clarified that the `name` argument in `@mcp_for_unity_tool` decorator is optional and defaults to the function name - Added documentation about using all FastMCP `mcp.tool` function decorator options - Updated class naming documentation to mention snake_case conversion by default - Corrected Python file path from `tools/screenshot_tool.py` to `UnityMcpServer~/src/tools/screenshot_tool.py` - Enhanced documentation for tool discovery and usage examples * docs: restructure development documentation and add custom tools guide Rearranged the development section in README.md to better organize the documentation flow. Added a dedicated section for "Adding Custom Tools" with a link to the new CUSTOM_TOOLS.md file, and renamed the previous "For Developers" section to "Contributing to the Project" to better reflect its content. This improves discoverability and organization of the development setup documentation. * docs: update developer documentation and add README links - Added links to developer READMEs in CUSTOM_TOOLS.md to guide users to the appropriate documentation - Fixed typo in README-DEV.md ("roote" → "root") for improved clarity - These changes improve the developer experience by providing better documentation navigation and correcting technical inaccuracies * feat(tools): enhance tool registration with wrapped function assignment Updated the tool registration process to properly chain the mcp.tool decorator and telemetry wrapper, ensuring the wrapped function is correctly assigned to tool_info['func'] for proper tool execution and telemetry tracking. This change improves the reliability of tool registration and monitoring. * Remove AI generated code that was never used... * feat: Rebuild MCP server installation with embedded source Refactored the server repair logic to implement a full rebuild of the MCP server installation using the embedded source. The new RebuildMcpServer method now: - Uses embedded server source instead of attempting repair of existing installation - Deletes the entire existing server directory before re-copying - Handles UV process cleanup for the target path - Simplifies the installation flow by removing the complex Python environment repair logic - Maintains the same installation behavior but with a cleaner, more reliable rebuild approach This change improves reliability of server installations by ensuring a clean slate rebuild rather than attempting to repair potentially corrupted environments. * Add the rebuild server step * docs: clarify tool description field requirements and client compatibility * fix: move initialization flag after tool discovery to prevent race conditions * refactor: remove redundant TryParseVersion overrides in platform detectors * refactor: remove duplicate UV validation code from platform detectors * Update UnityMcpBridge/Editor/Tools/CommandRegistry.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * refactor: replace WriteToConfig reflection with direct McpConfigurationHelper call --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-10-04 06:53:09 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
1. 列出可用实例：要求您的大语言模型检查 `unity_instances` 资源
2. 设置活动实例：使用 `set_active_instance` 与实例名称（例如，`MyProject@abc123`）
3. 所有后续工具路由到该实例，直到更改
Make it easier to add tools (#301) * Add a decorate that wraps around the `mcp.tool` decorator. This will allow us to more easily collect tools * Register tools that's defined in the tools folder * Update Python tools to use new decorator * Convert script_apply_edits tool * Convert last remaining tools with new decorator * Create an attribute so we can identify tools via Reflection * Add attribute to all C# tools * Use reflection to load tools * Initialize command registry to load tools at startup * Update tests * Move Dev docs to docs folder * Add docs for adding custom tools * Update function docs for Python decorator * Add working example of adding a screenshot tool * docs: update relative links in README files Updated the relative links in both README-DEV.md and README-DEV-zh.md to use direct filenames instead of paths relative to the docs directory, improving link correctness when files are accessed from the root directory. * docs: update telemetry documentation path reference Updated the link to TELEMETRY.md in README.md to point to the new docs/ directory location to ensure users can access the telemetry documentation correctly. Also moved the TELEMETRY.md file to the docs/ directory as part of the documentation restructuring. * rename CursorHelp.md to docs/CURSOR_HELP.md Moved the CursorHelp.md file to the docs directory to better organize documentation files and improve project structure. * docs: update CUSTOM_TOOLS.md with improved tool naming documentation and path corrections - Clarified that the `name` argument in `@mcp_for_unity_tool` decorator is optional and defaults to the function name - Added documentation about using all FastMCP `mcp.tool` function decorator options - Updated class naming documentation to mention snake_case conversion by default - Corrected Python file path from `tools/screenshot_tool.py` to `UnityMcpServer~/src/tools/screenshot_tool.py` - Enhanced documentation for tool discovery and usage examples * docs: restructure development documentation and add custom tools guide Rearranged the development section in README.md to better organize the documentation flow. Added a dedicated section for "Adding Custom Tools" with a link to the new CUSTOM_TOOLS.md file, and renamed the previous "For Developers" section to "Contributing to the Project" to better reflect its content. This improves discoverability and organization of the development setup documentation. * docs: update developer documentation and add README links - Added links to developer READMEs in CUSTOM_TOOLS.md to guide users to the appropriate documentation - Fixed typo in README-DEV.md ("roote" → "root") for improved clarity - These changes improve the developer experience by providing better documentation navigation and correcting technical inaccuracies * feat(tools): enhance tool registration with wrapped function assignment Updated the tool registration process to properly chain the mcp.tool decorator and telemetry wrapper, ensuring the wrapped function is correctly assigned to tool_info['func'] for proper tool execution and telemetry tracking. This change improves the reliability of tool registration and monitoring. * Remove AI generated code that was never used... * feat: Rebuild MCP server installation with embedded source Refactored the server repair logic to implement a full rebuild of the MCP server installation using the embedded source. The new RebuildMcpServer method now: - Uses embedded server source instead of attempting repair of existing installation - Deletes the entire existing server directory before re-copying - Handles UV process cleanup for the target path - Simplifies the installation flow by removing the complex Python environment repair logic - Maintains the same installation behavior but with a cleaner, more reliable rebuild approach This change improves reliability of server installations by ensuring a clean slate rebuild rather than attempting to repair potentially corrupted environments. * Add the rebuild server step * docs: clarify tool description field requirements and client compatibility * fix: move initialization flag after tool discovery to prevent race conditions * refactor: remove redundant TryParseVersion overrides in platform detectors * refactor: remove duplicate UV validation code from platform detectors * Update UnityMcpBridge/Editor/Tools/CommandRegistry.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * refactor: replace WriteToConfig reflection with direct McpConfigurationHelper call --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-10-04 06:53:09 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
**示例：**
```
用户: "列出所有 Unity 实例"
大语言模型: [显示 ProjectA@abc123 和 ProjectB@def456]
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
用户: "将活动实例设置为 ProjectA@abc123"
大语言模型: [调用 set_active_instance("ProjectA@abc123")]
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
用户: "创建一个红色立方体"
大语言模型: [在 ProjectA 中创建立方体]
```
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
---
## 开发和贡献 🛠️
### 开发设置和指南
查看 [README-DEV.md](docs/README-DEV.md) 获取完整的开发设置和工作流程文档。
### 添加自定义工具
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
MCP for Unity 使用与 Unity 的 C# 脚本绑定的 Python MCP 服务器来实现工具功能。如果您想使用自己的工具扩展功能，请参阅 **[CUSTOM_TOOLS.md](docs/CUSTOM_TOOLS.md)** 了解如何操作。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
### 如何贡献
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
1. **Fork** 主仓库。
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
2. **创建问题** 讨论您的想法或错误。
3. **创建分支**（`feature/your-idea` 或 `bugfix/your-fix`）。
4. **进行更改。**
5. **提交**（feat: Add cool new feature）。
6. **推送** 您的分支。
7. **对主分支开启拉取请求**，引用您之前创建的问题。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
---
## 📊 遥测和隐私
docs: replace "Unity MCP" with "MCP for Unity" in all text strings (#314)
2025-10-11 16:01:51 +08:00
MCP for Unity 包含**注重隐私的匿名遥测**来帮助我们改进产品。我们收集使用分析和性能数据，但**绝不**收集您的代码、项目名称或个人信息。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
- **🔒 匿名**：仅随机 UUID，无个人数据
- **🚫 轻松退出**：设置 `DISABLE_TELEMETRY=true` 环境变量
Make it easier to add tools (#301) * Add a decorate that wraps around the `mcp.tool` decorator. This will allow us to more easily collect tools * Register tools that's defined in the tools folder * Update Python tools to use new decorator * Convert script_apply_edits tool * Convert last remaining tools with new decorator * Create an attribute so we can identify tools via Reflection * Add attribute to all C# tools * Use reflection to load tools * Initialize command registry to load tools at startup * Update tests * Move Dev docs to docs folder * Add docs for adding custom tools * Update function docs for Python decorator * Add working example of adding a screenshot tool * docs: update relative links in README files Updated the relative links in both README-DEV.md and README-DEV-zh.md to use direct filenames instead of paths relative to the docs directory, improving link correctness when files are accessed from the root directory. * docs: update telemetry documentation path reference Updated the link to TELEMETRY.md in README.md to point to the new docs/ directory location to ensure users can access the telemetry documentation correctly. Also moved the TELEMETRY.md file to the docs/ directory as part of the documentation restructuring. * rename CursorHelp.md to docs/CURSOR_HELP.md Moved the CursorHelp.md file to the docs directory to better organize documentation files and improve project structure. * docs: update CUSTOM_TOOLS.md with improved tool naming documentation and path corrections - Clarified that the `name` argument in `@mcp_for_unity_tool` decorator is optional and defaults to the function name - Added documentation about using all FastMCP `mcp.tool` function decorator options - Updated class naming documentation to mention snake_case conversion by default - Corrected Python file path from `tools/screenshot_tool.py` to `UnityMcpServer~/src/tools/screenshot_tool.py` - Enhanced documentation for tool discovery and usage examples * docs: restructure development documentation and add custom tools guide Rearranged the development section in README.md to better organize the documentation flow. Added a dedicated section for "Adding Custom Tools" with a link to the new CUSTOM_TOOLS.md file, and renamed the previous "For Developers" section to "Contributing to the Project" to better reflect its content. This improves discoverability and organization of the development setup documentation. * docs: update developer documentation and add README links - Added links to developer READMEs in CUSTOM_TOOLS.md to guide users to the appropriate documentation - Fixed typo in README-DEV.md ("roote" → "root") for improved clarity - These changes improve the developer experience by providing better documentation navigation and correcting technical inaccuracies * feat(tools): enhance tool registration with wrapped function assignment Updated the tool registration process to properly chain the mcp.tool decorator and telemetry wrapper, ensuring the wrapped function is correctly assigned to tool_info['func'] for proper tool execution and telemetry tracking. This change improves the reliability of tool registration and monitoring. * Remove AI generated code that was never used... * feat: Rebuild MCP server installation with embedded source Refactored the server repair logic to implement a full rebuild of the MCP server installation using the embedded source. The new RebuildMcpServer method now: - Uses embedded server source instead of attempting repair of existing installation - Deletes the entire existing server directory before re-copying - Handles UV process cleanup for the target path - Simplifies the installation flow by removing the complex Python environment repair logic - Maintains the same installation behavior but with a cleaner, more reliable rebuild approach This change improves reliability of server installations by ensuring a clean slate rebuild rather than attempting to repair potentially corrupted environments. * Add the rebuild server step * docs: clarify tool description field requirements and client compatibility * fix: move initialization flag after tool discovery to prevent race conditions * refactor: remove redundant TryParseVersion overrides in platform detectors * refactor: remove duplicate UV validation code from platform detectors * Update UnityMcpBridge/Editor/Tools/CommandRegistry.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * refactor: replace WriteToConfig reflection with direct McpConfigurationHelper call --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-10-04 06:53:09 +08:00
- **📖 透明**：查看 [TELEMETRY.md](docs/TELEMETRY.md) 获取完整详情
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
您的隐私对我们很重要。所有遥测都是可选的，旨在尊重您的工作流程。
---
## 故障排除 ❓
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
<details>
<summary><strong>点击查看常见问题和修复方法...</strong></summary>
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
- **Unity Bridge 未运行/连接：**
- 确保 Unity 编辑器已打开。
- 检查状态窗口：Window > MCP for Unity。
- 重启 Unity。
- **MCP 客户端未连接/服务器未启动：**
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
- 确保本地 HTTP 服务器正在运行（Window > MCP for Unity > Start Local HTTP Server）。保持生成的终端窗口打开。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
- **验证服务器路径：** 双重检查您的 MCP 客户端 JSON 配置中的 --directory 路径。它必须完全匹配安装位置：
- **Windows：** `%USERPROFILE%\AppData\Local\UnityMCP\UnityMcpServer\src`
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
- **macOS：** `~/Library/AppSupport/UnityMCP/UnityMcpServer\src`
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
- **Linux：** `~/.local/share/UnityMCP/UnityMcpServer\src`
- **验证 uv：** 确保 `uv` 已安装并正常工作（`uv --version`）。
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
- **手动运行：** 尝试直接从终端运行服务器以查看错误：
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
```bash
cd /path/to/your/UnityMCP/UnityMcpServer/src
uv run server.py
```
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
- **配置失败：**
- 使用手动配置步骤。插件可能缺乏写入 MCP 客户端配置文件的权限。
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
</details>
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
仍然卡住？[开启问题](https://github.com/CoplayDev/unity-mcp/issues) 或 [加入 Discord](https://discord.gg/y4p8KfzrN4)！
---
## 许可证 📜
MIT 许可证。查看 [LICENSE](LICENSE) 文件。
---
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
## Star 历史
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
[![Star History Chart](https://api.star-history.com/svg?repos=CoplayDev/unity-mcp&type=Date)](https://www.star-history.com/#CoplayDev/unity-mcp&Date)
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
## Unity AI 工具由 Coplay 提供
Coplay 提供 2 个 Unity AI 工具
- **MCP for Unity** 在 MIT 许可证下免费提供。
- **Coplay** 是一个高级 Unity AI 助手，位于 Unity 内部，功能比 MCP for Unity 更多。
（这些工具有不同的技术栈。查看这篇博客文章[比较 Coplay 和 MCP for Unity](https://www.coplay.dev/blog/comparing-coplay-and-unity-mcp)。）
<img alt="Coplay" src="docs/images/coplay-logo.png" />
## 免责声明
Add Language: zh 中文
2025-09-24 02:41:29 +08:00
HTTP Server, uvx, C# only custom tools (#375) * Remove temp folder from repo * Ignore boot.config * Remove buttons to download or rebuild the server * Remove embedded MCP server in plugin We'll reference the remote server in GitHub and configure clients to use `uvx` * As much as possible, rip out logic that installs a server * feat: migrate to uvx-based server configuration - Replaced local server execution with uvx package-based configuration for improved reliability - Added GetUvxCommand helper to generate correct package version command string - Updated config generation to use `uvx mcp-for-unity` instead of local Python server - Modified Codex and client configuration validation to support uvx-based setup - Removed unused server source directory handling and related preferences - Updated tests to verify uvx command generation * Cleanup the temp folders created by tests We don't commit temp folders, tests are expected to clean up after themselves * The test kept failing but the results looked correct, floating point comparisons are not precise * feat: migrate from local server to uvx-based configuration - Replaced local server path detection with uvx-based package installation from git repository - Updated all configuration generators to use structured uvx command parts (command, --from URL, package) - Renamed UV path references to UVX for clarity and consistency - Added GetUvxCommandParts() helper to centralize uvx command generation - Added GetMcpServerGitUrl() to handle git repository URL construction - Updated client configuration validation * refactor: use dynamic package version instead of hardcoded value * Update CI so it only updates the Server folder * feat: implement uvx package source path resolution - Added GetUvxPackageSourcePath method to locate unity-mcp package in uv cache by traversing git checkouts - Replaced hardcoded "Dummy" path in PythonToolSyncProcessor with dynamic path resolution - Added validation for Server directory structure and pyproject.toml to ensure correct package location * refactor: replace Python tool syncing with custom tool registration system - Removed PythonToolsAsset and file-based sync processor in favor of attribute-based tool discovery - Implemented CustomToolRegistrationProcessor with automatic registration on startup and script reload - Added registration enable/disable preference and force re-registration capability * feat: add HTTP transport support and cache management - Implemented HTTP transport option with configurable URL/port alongside existing stdio mode - Added cache management service with menu item to clear uvx package cache - Updated config builder to generate transport-specific arguments and VSCode type field based on selected mode * refactor: simplify HTTP configuration to use URL-based approach - Replaced separate host/port arguments with single --http-url parameter for cleaner configuration - Updated server to parse URL and allow individual host/port overrides when needed - Consolidated HTTP client implementation with connection testing and tool execution support * refactor: standardize transport configuration with explicit --transport flag - Replaced --enable-http-server flag with --transport choice parameter (stdio/http) for clearer intent - Removed redundant HTTP port field from UI since HTTP mode uses the same URL/port as MCP client - Simplified server startup logic by consolidating transport mode determination * refactor: move MCP menu items under Window menu * feat: restructure config generation for HTTP transport mode - Changed HTTP mode to use URL-based configuration instead of command-line arguments - Added proper cleanup of incompatible fields when switching between stdio and HTTP transports - Moved uvx command parsing inside stdio-specific block to avoid unnecessary processing in HTTP mode * feat: add local HTTP server management with Git URL override - Implemented server management service with menu item to start local HTTP server in new terminal window - Added Git URL override setting in advanced configuration to allow custom server source for uvx --from - Integrated server management into service locator with validation for local-only server startup * fix: remove automatic HTTP protocol prefix from URL field - Removed auto-prefixing logic that added "http://" to URLs without protocol - Added placeholder text to guide users on expected URL format - Created dedicated url-field style class for better URL input styling * feat: implement proper MCP session lifecycle with HTTP transport - Added initialize, ping, and disconnect methods to HttpMcpClient for proper MCP protocol session management - Implemented session ID tracking and header management for stateful HTTP connections - Added cross-platform terminal launcher support for Windows and Linux (previously macOS-only) * feat: implement JSON-RPC protocol for MCP tool execution - Added proper JSON-RPC 2.0 request/response handling with request ID tracking - Included MCP protocol headers (version, session ID) for standard compliance - Added error handling for JSON-RPC error responses * feat: improve text wrapping in editor window UI - Added white-space: normal and flex-shrink properties to section headers and override labels to prevent text overflow - Created new help-text style class for consistent formatting of help text elements * refactor: refresh git URL override from EditorPrefs on validation * fix: improve responsive layout for editor window settings - Added flex-wrap to setting rows to prevent overflow on narrow windows - Set flex-shrink: 0 on labels to maintain consistent width - Replaced max-width and margin-left with flex-basis for better flex behavior * refactor: improve thread safety in tool registration - Capture Unity API calls on main thread before async operations to prevent threading issues - Update RegisterAllTools to use Task.Run pattern instead of GetAwaiter().GetResult() to avoid potential deadlocks - Add optional projectId parameter to RegisterAllToolsAsync for pre-captured values * refactor: replace MCP tool calls with direct HTTP endpoints for tool registration - Removed synchronous registration method and unused MCP bridge logic from CustomToolRegistrationService - Changed tool registration to use direct HTTP POST to /register-tools endpoint instead of MCP protocol - Added FastAPI HTTP routes alongside existing MCP tools for more flexible tool management access * refactor: centralize HTTP endpoint URL management - Created HttpEndpointUtility to normalize and manage base URLs consistently - Replaced scattered EditorPrefs calls with utility methods that handle URL normalization - Ensured base URL storage excludes trailing paths like "/mcp" for cleaner configuration * refactor: simplify custom tools management with in-memory registry - Removed CustomToolsManager and fastmcp_tool_registry modules in favor of inline implementation - Replaced class-based tool management with direct HTTP route handlers using FastMCP's custom_route decorator - Consolidated tool registration logic into simple dictionary-based storage with helper functions * feat: add dynamic custom tool registration system - Implemented CustomToolService to manage project-scoped tool registration with validation and conflict detection - Added HTTP endpoints for registering, listing, and unregistering custom tools with proper error handling - Converted health and registry endpoints from HTTP routes to MCP tools for better integration * feat: add AutoRegister flag to control tool registration - Added AutoRegister property to McpForUnityToolAttribute (defaults to true) - Modified registration service to filter and only register tools with AutoRegister enabled - Disabled auto-registration for all built-in tools that already exist server-side * feat: add function signature generation for dynamic tools - Implemented _build_signature method to create proper inspect.Signature objects for dynamically created tools - Signature includes Context parameter and all tool parameters with correct required/optional defaults - Attached generated signature to dynamic_tool functions to improve introspection and type checking * refactor: remove unused custom tool registry endpoints * test: add transport configuration validation for MCP client tests - Added HTTP transport preference setup in test fixtures to ensure consistent behavior - Implemented AssertTransportConfiguration helper to validate both HTTP and stdio transport modes - Added tests to verify stdio transport fallback when HTTP preference is disabled * refactor: simplify uvx path resolution to use PATH by default - Removed complex platform-specific path detection logic and verification - Changed to rely on system PATH environment variable instead of searching common installation locations - Streamlined override handling to only use EditorPrefs when explicitly set by user * feat: use serverUrl property for Windsurf HTTP transport - Changed Windsurf configs to use "serverUrl" instead of "url" for HTTP transport to match Windsurf's expected format - Added cleanup logic to remove stale transport properties when switching between HTTP and stdio modes - Updated Windsurf to exclude "env" block (only required for Kiro), while preserving it for clients that need it * feat: ensure client configurations stay current on each setup - Removed skip logic for already-configured clients to force re-validation of core fields - Added forced re-registration for ClaudeCode clients to keep transport settings up-to-date * feat: add automatic migration for legacy embedded server configuration - Created LegacyServerSrcMigration to detect and migrate old EditorPrefs keys on startup - Automatically reconfigures all detected clients to use new uvx/stdio path - Removes legacy keys only after successful migration to prevent data loss * feat: add automatic stdio config migration on package updates - Implemented StdIoVersionMigration to detect package version changes and refresh stdio MCP client configurations - Added support for detecting stdio usage across different client types (Codex, VSCode, and generic JSON configs) - Integrated version tracking via EditorPrefs to prevent redundant migrations * Centralize where editor prefs are defined It's really hard to get a view of all the editor prfes in use. This should help humans and AI know what's going on at a glance * Update custom tools docs * refactor: consolidate server management UI into main editor window - Removed server and maintenance menu items from top-level menu - Moved "Start Local HTTP Server" and "Clear UVX Cache" buttons into editor window settings - Added dynamic button state management based on transport protocol and server availability * Don't show error logs when custom tools are already registerd with the server * Only autoconnect to port 6400 if the user is using stdio for connections * Don't double register tools on startup * feat: switch to HTTP transport as default connection method - Changed default transport from stdio to HTTP with server running on localhost:8080 - Added UI controls to start/stop local HTTP server directly from Unity window - Updated all documentation and configuration examples to reflect HTTP-first approach with stdio as fallback option * Automatically bump the versions in the READMEs. The `main` branch gets updated before we do a release. Using versions helps users get a stable, tested installation * docs: add HTTP transport configuration examples - Added HTTP transport setup instructions alongside existing stdio examples - Included port mapping and URL configuration for Docker deployments - Reorganized client configuration sections to clearly distinguish between HTTP and stdio transports * feat: add WebSocket-based plugin hub for Unity connections - Implemented persistent WebSocket connections with session management, heartbeat monitoring, and command routing - Created PluginRegistry for tracking active Unity instances with hash-based lookup and automatic reconnect handling - Added HTTP endpoints for session listing and health checks, plus middleware integration for instance-based routing * refactor: consolidate Unity instance discovery with shared registry - Introduced StdioPortRegistry for centralized caching of Unity instance discovery results - Refactored UnityConnection to use stdio_port_registry instead of direct PortDiscovery calls - Improved error handling with specific exception types and enhanced logging clarity * Use websockets so that local and remote MCP servers can communicate with Unity The MCP server supports HTTP and stdio protocols, and the MCP clients use them to communicate. However, communication from the MCP server to Unity is done on the local port 6400, that's somewhat hardcoded. So we add websockets so oure remotely hosted MCP server has a valid connection to the Unity plugin, and can communicate with - Created ProjectIdentityUtility for centralized project hash, name, and session ID management - Moved command processing logic from MCPForUnityBridge to new TransportCommandDispatcher service - Added WebSocket session ID and URL override constants to EditorPrefKeys - Simplified command queue processing with async/await pattern and timeout handling - Removed duplicate command execution code in favor of shared dispatcher implementation * refactor: simplify port management and improve port field validation - Removed automatic port discovery and fallback logic from GetPortWithFallback() - Changed GetPortWithFallback() to return stored port or default without availability checks - Added SetPreferredPort() method for explicit port persistence with validation - Replaced Debug.Log calls with McpLog.Info/Warn for consistent logging - Added port field validation on blur and Enter key press with error handling - Removed automatic port waiting * Launch the actual local webserver via the button * Autoformat * Minor fixes so the server can start * Make clear uvx button work * Don't show a dialog after clearing cache/starting server successfully It's annoying, we can just log when successful, and popup if something failed * We no longer need a Python importer * This folder has nothing in it * Cleanup whitespace Most AI generated code contains extra space, unless they're hooked up to a linter. So I'm just cleaning up what's there * We no longer need this folder * refactor: move MCPForUnityBridge to StdioBridgeHost and reorganize transport layer - Renamed MCPForUnityBridge class to StdioBridgeHost and moved to Services.Transport.Transports namespace - Updated all references to StdioBridgeHost throughout codebase (BridgeControlService, TelemetryHelper, GitHub workflow) - Changed telemetry bridge_version to use AssetPathUtility.GetPackageVersion() instead of hardcoded version - Removed extensive inline comments and documentation throughout StdioBridgeHost * Skip tools registration if the user is not connected to an HTTP server * Fix VS Code configured status in UI Serializing the config as dynamic and then reading null properties (in this case, args) caused the error. So we just walk through the properities and use JObject, handling null value explicitily * Stop blocking the main thread when connecting via HTTP Now that the bridge service is asynchronous, messages back and forth the server work well (including the websocket connection) * Separate socket keep-alive interval from application keep-alive interval Split the keep-alive configuration into two distinct intervals: _keepAliveInterval for application-level keep-alive and _socketKeepAliveInterval for WebSocket-level keep-alive. This allows independent control of socket timeout behavior based on server configuration while maintaining the application's keep-alive settings. * Add a debug log line * Fix McpLog.Debug method, so it actually reads the checkbox value from the user * Add HTTP bridge auto-resume after domain reload Implement HttpBridgeReloadHandler to automatically resume HTTP/HttpPush transports after Unity domain reloads, matching the behavior of the legacy stdio bridge. Add ResumeHttpAfterReload EditorPref key to persist state across reloads and expose ActiveMode property in IBridgeControlService to check current transport mode. * Add health verification after HTTP bridge auto-resume Trigger health check in all open MCPForUnityEditorWindow instances after successful HTTP bridge resume following domain reload. Track open windows using static HashSet and schedule async health verification via EditorApplication.delayCall to ensure UI updates reflect the restored connection state. * Add name and path fields to code coverage settings Initialize m_Name and m_Path fields in code coverage Settings.json to match Unity's expected settings file structure. * Only register custom tools AFTER we established a healthy HTTP connection * Convert custom tool handlers to async functions Update dynamic_tool wrapper to use async/await pattern and replace synchronous send_with_unity_instance/send_command_with_retry calls with their async counterparts (async_send_with_unity_instance/async_send_command_with_retry). * Correctly parse responses from Unity in the server so tools and resources can process them We also move the logic to better places than the __init__.py file for tools, since they're shared across many files, including resources * Make some clarifications for custom tools in docs * Use `async_send_with_unity_instance` instead of `send_with_unity_instance` The HTTP protocol doesn't working with blocking commands, so now we have our tools set up to work with HTTP and stdio fullly. It's coming together :-) * Fix calls to async_send_with_unity_instance in manage_script * Rename async_send_with_unity_instance to send_with_unity_instance * Fix clear uv cache command Helps a lot with local development * Refactor HTTP server command generation into reusable method and display in UI Extract HTTP server command building logic from StartLocalHttpServer into new TryGetLocalHttpServerCommand method. Add collapsible foldout in editor window to display the generated command with copy button, allowing users to manually start the server if preferred. Update UI state management to refresh command display when transport or URL settings change. * Ctrl/Cmd + Shift + M now toggles the window Might as well be able to close the window as well * Fallback to a git URL that points to the main branch for the MCP git URL used by uvx * Add test setup/teardown to preserve and reset Git URL override EditorPref Implement OneTimeSetUp/OneTimeTearDown to save and restore the GitUrlOverride EditorPref state, and add SetUp to delete the key before each test. This ensures tests run with deterministic Git URLs while preserving developer overrides between test runs. * Update docs, scripts and GH workflows to use the new MCP server code location * Update plugin README * Convert integration tests to async/await pattern Update all integration tests to use pytest.mark.asyncio decorator and async/await syntax. Change test functions to async, update fake_send/fake_read mocks to async functions with **kwargs parameter, and patch async_send_command_with_retry instead of send_command_with_retry. Add await to all tool function calls that now return coroutines. * Update image with new UI * Remove unused HttpTransportClient client Before I had the realization that I needed webscokets, this was my first attempt * Remove copyright notice * Add a guide to all the changes made for this version A lot of code was written by AI, so I think it's important that humans can step through how all these new systems work, and know where to find things. All of these docs were written by hand, as a way to vet that I understand what the code I wrote and generated are doing, but also to make ti easy to read for you. * Organize imports and remove redundant import statements Clean up import organization by moving imports to the top of the file, removing duplicate imports scattered throughout the code, and sorting imports alphabetically within their groups (standard library, third-party, local). Remove unnecessary import aliases and consolidate duplicate urlparse and time imports. * Minor edits * Fix stdio serializer to use the new type parameter like HTTP * Fix: Automatic bridge reconnection after domain reload without requiring Unity focus - Add immediate restart attempt in OnAfterAssemblyReload() when Unity is not compiling - Enhanced compile detection to check both EditorApplication.isCompiling and CompilationPipeline.isCompiling - Add brief port release wait in StdioBridgeHost before switching ports to reduce port thrash - Fallback to delayCall/update loop only when Unity is actively compiling This fixes the issue where domain reloads (e.g., script edits) would cause connection loss until Unity window was refocused, as EditorApplication.update only fires when Unity has focus. * Make the server work in Docker We use HTTP mode by default in docker, this is what will be hosted remotely if one chooses to. We needed to update the uvicorn package to a version with websockets, at least so the right version is explicitly retrieved * Cache project identity on initialization to avoid repeated computation Add static constructor with [InitializeOnLoad] attribute to cache project hash and name at startup. Introduce volatile _identityCached flag and cached values (_cachedProjectName, _cachedProjectHash) to store computed identity. Schedule cache refresh on initialization and when project changes via EditorApplication.projectChanged event. Extract ComputeProjectHash and ComputeProjectName as private methods that perform the actual computation. Update public * Fix typos * Add unity_instance_middleware to py-modules list in pyproject.toml * Remove Foldout UI elements and simplify HTTP server command section Replace Foldout with VisualElement for http-server-command-section to display HTTP server command directly without collapsible wrapper. Remove unused manualConfigFoldout field and associated CSS styles. Remove unused _identityCached volatile flag from ProjectIdentityUtility as caching logic no longer requires it. * Reduce height of HTTP command box * Refresh HTTP server command display when Git URL override changes * Make the box a bit smaller * Split up main window into various components Trying to avoid to monolithic files, this is easier to work, for humans and LLMs * Update the setup wizard to be a simple setup popup built with UI toolkit We also fix the Python/uv detectors. Instead of searching for binaries, we just test that they're available in the PATH * Ensure that MCP configs are updated when users switch between HTTP and stdio These only work for JSON configs, we'll have to handle Codex and Claude Code separately * Detect Codex configuration when using HTTP or stdio configs * Use Claude Code's list command to detect whether this MCP is configured It's better than checking the JSON and it can verify both HTTP and stdio setups * Fix and add tests for building configs * Handle Unity reload gaps by retrying plugin session resolution * Add polling support for long-running tools with state persistence Introduce polling middleware to handle long-running operations that may span domain reloads. Add McpJobStateStore utility to persist tool state in Library folder across reloads. Extend McpForUnityToolAttribute with RequiresPolling and PollAction properties. Update Response helper with Pending method for standardized polling responses. Implement Python-side polling logic in custom_tool_service.py with configurable intervals and 10-minute timeout. * Polish domain reload resilience tests and docs * Refactor Response helper to use strongly-typed classes instead of anonymous objects Replace static Response.Success/Error/Pending methods with SuccessResponse, ErrorResponse, and PendingResponse classes. Add IMcpResponse interface for type safety. Include JsonProperty attributes for serialization and JsonIgnore properties for backward compatibility with reflection-based tests. Update all tool and resource classes to use new response types. * Rename Setup Wizard to Setup Window and improve UV detection on macOS/Linux Rename SetupWizard class to SetupWindowService and update all references throughout the codebase. Implement platform-specific UV detection for macOS and Linux with augmented PATH support, including TryValidateUv methods and BuildAugmentedPath helpers. Split single "Open Installation Links" button into separate Python and UV install buttons. Update UI styling to improve installation section layout with proper containers and button * Update guide on what's changed in v8 Lots of feedback, lots of changes * Update custom tool docs to use new response objects * Update image used in README Slightly more up to date but not final * Restructure backend Just make it more organized, like typical Python projects * Remove server_version.txt * Feature/http instance routing (#5) * Fix HTTP instance routing and per-project session IDs * Drop confusing log message * Ensure lock file references later version of uvicorn with key fixes * Fix test imports * Update refs in docs --------- Co-authored-by: David Sarno <david@lighthaus.us> * Generate the session ID from the server We also make the identifying hashes longer * Force LLMs to choose a Unity instance when multiple are connected OK, this is outright the best OSS Unity MCP available * Fix tests caused by changes in session management * Whitespace update * Exclude stale builds so users always get the latest version * Set Pythonpath env var so Python looks at the src folder for modules Not required for the fix, but it's a good guarantee regardless of the working directory * Replace Optional type hints with modern union syntax (Type | None) Update all Optional[Type] annotations to use the PEP 604 union syntax Type | None throughout the transport layer and mcp_source.py script * Replace Dict type hints with modern dict syntax throughout codebase Update all Dict[K, V] annotations to use the built-in dict[K, V] syntax across services, transport layer, and models for consistency with PEP 585 * Remove unused type imports across codebase Clean up unused imports of Dict, List, and Path types that are no longer needed after migration to modern type hint syntax * Remove the old telemetry test It's working, we have a better integration test in any case * Clean up stupid imports No AI slop here lol * Replace dict-based session data with Pydantic models for type safety Introduce Pydantic models for all WebSocket messages and session data structures. Replace dict.get() calls with direct attribute access throughout the codebase. Add validation and error handling for incoming messages in PluginHub. * Correctly call `ctx.info` with `await` No AI slop here! * Replace printf-style logging with f-string formatting across transport and telemetry modules Convert all logger calls using %-style string formatting to use f-strings for consistency with modern Python practices. Update telemetry configuration logging, port discovery debug messages, and Unity connection logging throughout the codebase. * Register custom tools via websockets Since we'll end up using websockets for HTTP and stdio, this will ensure custom tools are available to both. We want to compartmentalize the custom tools to the session. Custom tools in 1 unity project don't apply to another one. To work with our multi-instance logic, we hide the custom tools behind a custom tool function tool. This is the execute_custom_tool function. The downside is that the LLM has to query before using it. The upside is that the execute_custom_tool function goes through the standard routing in plugin_hub, so custom tools are always isolated by project. * Add logging decorator to track tool and resource execution with arguments and return values Create a new logging_decorator module that wraps both sync and async functions to log their inputs, outputs, and exceptions. Apply this decorator to all tools and resources before the telemetry decorator to provide detailed execution traces for debugging. * Fix JSONResponse serialization by converting Pydantic model to dict in plugin sessions endpoint * Whitespace * Move import of get_unity_instance_from_context to module level in unity_transport Relocate the import from inside the with_unity_instance decorator function to the top of the file with other imports for better code organization and to avoid repeated imports on each decorator call. * Remove the tool that reads resources They don't perform well at all, and confuses the models most times. However, if they're required, we'll revert * We have buttons for starting and stopping local servers Instead of a button to clear uv cache, we have start and stop buttons. The start button pulls the latest version of the server as well. The stop button finds the local process of the server and kills. Need to test on Windows but it works well * Consolidate cache management into ServerManagementService and remove standalone CacheManagementService Move the ClearUvxCache method from CacheManagementService into ServerManagementService since cache clearing is primarily used during server operations. Remove the separate ICacheManagementService interface and CacheManagementService class along with their service locator registration. Update StartLocalServer to call the local ClearUvxCache method instead of going through the service locator. * Update MCPForUnity/Editor/Helpers/ProjectIdentityUtility.cs Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update .github/workflows/claude-nl-suite.yml Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Cancel existing background loops before starting a new connection Nice bug found from CodeRabbit * Try to kill all processes using the port of the local webserver * Some better error handling when stopping a server * Cache fallback session ID to maintain consistency when EditorPrefs are unavailable Store the fallback session ID in a static field instead of generating a new GUID on each call when EditorPrefs are unavailable during batch tests. Clear the cached fallback ID when resetting the session to ensure a fresh ID is generated on the next session. * Clean up empty parent temp folder after domain reload tests complete Check if Assets/Temp folder is empty after deleting test-specific temp directories and remove it if no other files or directories remain. Also remove trailing blank lines from the file. * Minor fixes * Change "UV" to "uv" in strings. Capitlization looks weird * Rename functions that capitalized "UV" * Ensure WebSocket transport is properly stopped before disposing shared resources Add disposal guard and call StopAsync() in Dispose() to prevent race conditions when disposing the WebSocket transport while background loops are still running. Log warnings if cleanup fails but continue with resource disposal. * Replace volatile bool with Interlocked operations for reconnection flag to prevent race conditions * Replace byte array allocation with ArrayPool to reduce GC pressure in WebSocket message receiving Rent buffer from ArrayPool<byte>.Shared instead of allocating new byte arrays for each receive operation. Pre-size MemoryStream to 8192 bytes and ensure rented buffer is returned in finally block to prevent memory leaks. * Consolidate some of the update/refresh logic * UI tweak disable start/stop buttons while they code is being fired * Add error dialog when Unity socket port persistence fails * Rename WebSocketSessionId to SessionId in EditorPrefKeys By the next version stdio will use Websockets as well, so why be redundant * No need to send session ID in pong payload * Add a debug message when we don't have an override for the uvx path * Remove unused function * Remove the unused verifyPath argument * Simplify server management logic * Remove unused `GetUvxCommand()` function We construct it in parts now * Remove `IsUvxDetected()` The flow changed so it checks editor prefs and then defaults to the command line default. So it's always true. * Add input validation and improve shell escaping in CreateTerminalProcessStartInfo - Validate command is not empty before processing - Strip carriage returns and newlines from command - macOS: Use osascript directly instead of bash to avoid shell injection, escape backslashes and quotes for AppleScript - Windows: Add window title and escape quotes in command - Linux: Properly escape single quotes for bash -c and double quotes for process arguments * Update technical changes guide * Add custom_tools resource and execute_custom_tool to README documentation * Update v8 docs * Update docs UI image * Handle when properties are sent as a JSON string in manage_asset * Fix backend tests --------- Co-authored-by: David Sarno <david@lighthaus.us> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2025-11-25 11:21:06 +08:00
本项目是一个免费开源的 Unity 编辑器工具，与 Unity Technologies 无关。