docs/migrations/v6_NEW_UI_CHANGES.md
UI Toolkit-based window with service-oriented architecture
Dark theme
Light theme
The new MCP Editor Window is a complete rebuild using UI Toolkit (UXML/USS) with a service-oriented architecture. The design philosophy emphasizes explicit over implicit behavior, making the system more predictable, testable, and maintainable.
Quick Access: Cmd/Ctrl+Shift+M or Window > MCP For Unity > Open MCP Window
Key Improvements:
| Feature | Old Window | New Window | Notes |
|---|---|---|---|
| Architecture | Monolithic | Service-based | Better testability & reusability |
| UI Framework | IMGUI | UI Toolkit (UXML/USS) | Modern, responsive, themeable |
| Auto-Setup | ✅ Automatic | ❌ Manual | Users have explicit control |
| Path Overrides | ⚠️ Python only | ✅ Python + UV + Claude CLI | Advanced troubleshooting |
| Bridge Health | ⚠️ Hidden | ✅ Visible with test button | Separate from connection status |
| Configure All | ❌ None | ✅ Batch with summary | Configure all clients at once |
| Manual Config | ✅ Popup windows | ✅ Inline foldout | Less window clutter |
| Server Download | ❌ None | ✅ Asset Store support | Download server from GitHub |
| Keyboard Shortcut | ❌ None | ✅ Cmd/Ctrl+Shift+M | Quick access |
Cmd/Ctrl+Shift+M opens the window quicklyAsset Store version showing the "Download & Install Server" button
The new window intentionally removes implicit behaviors and complex edge-case handling to provide a cleaner, more predictable UX.
Window > MCP For Unity > Setup WizardVSCodeManualSetupWindow, ManualConfigEditorWindow popup dialogsThe new window uses a service locator pattern to access business logic without tight coupling. This provides flexibility for testing and future dependency injection migration.
Purpose: Central access point for MCP services
Usage:
// Access bridge service
MCPServiceLocator.Bridge.Start();
// Access client configuration service
MCPServiceLocator.Client.ConfigureAllDetectedClients();
// Access path resolver service
string mcpServerPath = MCPServiceLocator.Paths.GetMcpServerPath();
Benefits:
Register())Purpose: Manages MCP for Unity Bridge lifecycle and health verification
Key Methods:
Start() / Stop() - Bridge lifecycle managementVerify(port) - Health check with handshake + ping/pong validationIsRunning - Current bridge statusCurrentPort - Active port numberImplementation: BridgeControlService
Usage Example:
var bridge = MCPServiceLocator.Bridge;
bridge.Start();
var result = bridge.Verify(bridge.CurrentPort);
if (result.Success && result.PingSucceeded)
{
Debug.Log("Bridge is healthy");
}
Purpose: Handles MCP client configuration and registration
Key Methods:
ConfigureClient(client) - Configure a single clientConfigureAllDetectedClients() - Batch configure with summaryCheckClientStatus(client) - Verify client status + auto-rewrite pathsRegisterClaudeCode() / UnregisterClaudeCode() - Claude Code managementGenerateConfigJson(client) - Get JSON for manual configurationImplementation: ClientConfigurationService
Usage Example:
var clientService = MCPServiceLocator.Client;
var summary = clientService.ConfigureAllDetectedClients();
Debug.Log($"Configured: {summary.SuccessCount}, Failed: {summary.FailureCount}");
Purpose: Resolves paths to required tools with override support
Key Methods:
GetMcpServerPath() - MCP server directoryGetUvPath() - UV executable pathGetClaudeCliPath() - Claude CLI pathSetMcpServerOverride(path) / ClearMcpServerOverride() - Manage MCP server overridesSetUvPathOverride(path) / ClearUvPathOverride() - Manage UV overridesSetClaudeCliPathOverride(path) / ClearClaudeCliPathOverride() - Manage Claude CLI overridesIsPythonDetected() / IsUvDetected() - Detection checksImplementation: PathResolverService
Usage Example:
var paths = MCPServiceLocator.Paths;
// Check if UV is detected
if (!paths.IsUvDetected())
{
Debug.LogWarning("UV not found");
}
// Set an override
paths.SetUvPathOverride("/custom/path/to/uv");
Services:
MCPForUnity/Editor/Services/
├── IBridgeControlService.cs # Bridge lifecycle interface
├── BridgeControlService.cs # Bridge lifecycle implementation
├── IClientConfigurationService.cs # Client config interface
├── ClientConfigurationService.cs # Client config implementation
├── IPathResolverService.cs # Path resolution interface
├── PathResolverService.cs # Path resolution implementation
└── MCPServiceLocator.cs # Service locator pattern
Helpers:
MCPForUnity/Editor/Helpers/
└── AssetPathUtility.cs # Package path detection & package.json parsing
UI:
MCPForUnity/Editor/Windows/
├── MCPForUnityEditorWindowNew.cs # Main window (~850 lines)
├── MCPForUnityEditorWindowNew.uxml # UI Toolkit layout
└── MCPForUnityEditorWindowNew.uss # UI Toolkit styles
CI/CD:
.github/workflows/
└── bump-version.yml # Server upload to releases
ServerInstaller.cs - Added download/install logic for Asset StoreSetupWizard.cs - Integration with new service locatorPackageDetector.cs - Uses AssetPathUtility for version detectionImmediate Changes (v6.x):
Cmd/Ctrl+Shift+M or menuUpcoming Changes (v8.x):
Using the Services:
// Accessing services from any editor script
var bridge = MCPServiceLocator.Bridge;
var client = MCPServiceLocator.Client;
var paths = MCPServiceLocator.Paths;
// Services are lazily initialized on first access
// No need to check for null
Testing with Custom Implementations:
// In test setup
var mockBridge = new MockBridgeService();
MCPServiceLocator.Register(mockBridge);
// Services are now testable without Unity dependencies
Reusing Service Logic: The service layer is designed to be reused by other parts of the codebase. For example:
IClientConfigurationService to auto-configure clientsIBridgeControlService to verify bridge healthIPathResolverService for consistent path resolutionNotes:
PR #313: feat: New UI with service architecture
Key Commits:
Last Updated: 2025-10-10
Unity Versions: Unity 2021.3+ through Unity 6.x
Architecture: Service Locator + UI Toolkit
Status: Active (Old window deprecated in v8.0)