mcp-unity: Cursor rule for Windsurf

1. Project Structure

• The project consists of two main parts:
  • Editor/ (Unity C#/Editor Package): A C# Unity Editor package that exposes Unity Editor functionality via a WebSocket bridge.
  • Server/ (Node.js/TypeScript): A Node.js server implementing the Model Context Protocol (MCP), using the official TypeScript SDK.

2. Communication & Protocol

• Primary Protocol: Model Context Protocol (MCP).
  • The Unity side uses the websocket-sharp library: https://github.com/sta/websocket-sharp/tree/master/websocket-sharp/Server
  • The Node.js server uses the @modelcontextprotocol/sdk for protocol implementation and exposes tools/resources/prompts to LLMs and AI clients.
• Transport Layer: WebSockets.
  • Node.js server (Server/) acts as a WebSocket client to the WebSocket server running within the Unity Editor (Editor/).
• Message Format: JSON. MCP defines the structure for tool/resource calls.
  • Node.js tools typically send a request like: { method: "csharp_tool_name", params: { ... } } to Unity via mcpUnity.sendRequest().
  • Unity C# tools receive this, execute, and return a JObject response.
• Response Format: JSON. MCP defines the structure for tool/resource responses.
  • Unity C# tools return a JObject response.
  • Node.js tools receive this and return a JObject response.
• Error Handling: MCP defines a standard error format.
  • Unity C# tools return an error object if an exception occurs.
  • Node.js tools receive this and return an error object.

Communication Flow:

• Request: AI LLM Assistant -> Node.js MCP Server -> WebSocket Bridge -> Unity Editor Package -> Unity Editor API
• Response: Unity Editor Package -> WebSocket Bridge -> Node.js MCP Server -> AI LLM Assistant

3. Minimum Supported Versions

• Unity: 2022.3 or newer
• Node.js: 18.0.0 or newer

4. Key Components

Unity Editor Package (Editor/)

• UnityBridge/:
  • McpUnityServer.cs: Singleton. The central nervous system on the Unity side. Initializes WebSocket server, registers tools/resources, and dispatches incoming requests to appropriate handlers.
    • LLM Assistant Note: When adding new tools/resources, they must be registered here in RegisterTools() or RegisterResources(). Pay attention to how existing tools are instantiated (currently direct new Tool()).
  • McpUnitySocketHandler.cs: Handles individual WebSocket client connections, message parsing, and routing requests to McpUnityServer for tool/resource execution.
  • McpUnityEditorWindow.cs: // TODO: Complete
• Tools/: Contains C# classes inheriting from McpToolBase. Each class implements a specific action that can be triggered in Unity.
  • LLM Assistant Note: New tools should follow the McpToolBase pattern: define Name (matching Node.js tool name), Description, IsAsync, and override Execute() or ExecuteAsync(). Use Undo.RecordObject for actions that modify the scene or assets.
• Resources/: Contains C# classes inheriting from McpResourceBase (assumption, or similar base). These provide read-only access to Unity Editor state.
  • LLM Assistant Note: New resources should follow the McpResourceBase pattern: define Name (matching Node.js resource name), Description, and override Fetch() or FetchAsync()
• Services/: Contains classes providing specific functionalities, often designed for dependency injection.
  • Example: TestRunnerService.cs, ConsoleLogsService.cs.
  • LLM Assistant Note: Prefer dependency injection for new services. If a tool needs a complex piece of logic, consider abstracting it into a service.
• Utils/: Utility classes for common tasks like logging (McpLogger.cs), settings management (McpUnitySettings.cs), GameObject creation (GameObjectHierarchyCreator.cs)