|
| 1 | +# MCP Unity - AI Agent Guide |
| 2 | + |
| 3 | +## 1. Project Overview |
| 4 | +**MCP Unity** bridges AI assistants (Cursor, Claude, Windsurf) to the Unity Editor via the Model Context Protocol (MCP). It allows agents to inspect scenes, manipulate GameObjects, run tests, and manage packages directly within Unity. |
| 5 | + |
| 6 | +## 2. Architecture |
| 7 | +- **Dual Architecture**: |
| 8 | + - **Server (Node.js/TypeScript)**: Runs as the MCP server (stdio), handles protocol messages, and forwards requests to Unity via WebSocket. |
| 9 | + - **Client (Unity/C#)**: Runs inside Unity Editor, listens for WebSocket commands, executes Editor API calls, and returns results. |
| 10 | +- **Communication**: JSON-RPC over WebSocket (default port 8080). |
| 11 | + |
| 12 | +## 3. Directory Structure |
| 13 | +``` |
| 14 | +/ |
| 15 | +├── Editor/ # Unity C# Editor Code (The "Client") |
| 16 | +│ ├── Tools/ # Tool implementations (McpToolBase) |
| 17 | +│ ├── Resources/ # Resource implementations (McpResourceBase) |
| 18 | +│ ├── UnityBridge/ # WebSocket server & message handling |
| 19 | +│ └── Services/ # Core services (Logs, Tests) |
| 20 | +├── Server~/ # Node.js MCP Server Code (The "Server") |
| 21 | +│ ├── src/tools/ # MCP Tool definitions (mirrors Editor/Tools) |
| 22 | +│ ├── src/resources/ # MCP Resource definitions |
| 23 | +│ └── src/unity/ # WebSocket client logic |
| 24 | +└── docs/ # Documentation images |
| 25 | +
|
| 26 | +## 4. Key Files |
| 27 | +- `McpUnitySocketHandler.cs` — WebSocket message routing |
| 28 | +- `McpUnityServer.cs` — Unity-side server lifecycle |
| 29 | +- `McpUnity.ts` — Node.js client connecting to Unity |
| 30 | +- `index.ts` — MCP server entry, tool/resource registration |
| 31 | +``` |
| 32 | + |
| 33 | +## 5. Coding Standards |
| 34 | +- **Unity**: Unity 6 standards. |
| 35 | +- **C#**: C# 9.0 features allowed. |
| 36 | +- **Namespaces**: Explicit namespaces (e.g., `McpUnity.Tools`). No global `using`. |
| 37 | +- **Async**: Use `IsAsync = true` in tools/resources for main thread operations (Editor API). |
| 38 | + |
| 39 | +## 6. Development Workflow |
| 40 | +To add a new capability (e.g., "RotateObject"): |
| 41 | + |
| 42 | +1. **Unity (C#)**: |
| 43 | + - Create `Editor/Tools/RotateObjectTool.cs` inheriting `McpToolBase`. |
| 44 | + - Implement `Execute` (sync) or `ExecuteAsync` (if touching Editor API). |
| 45 | + - Register in `McpUnityServer.cs` (if not auto-discovered). |
| 46 | + |
| 47 | +2. **Server (TS)**: |
| 48 | + - Create `Server~/src/tools/rotateObjectTool.ts`. |
| 49 | + - Define input schema (zod) and tool handler. |
| 50 | + - Forward request to Unity via `McpUnity.instance.callTool("RotateObject", args)`. |
| 51 | + |
| 52 | +3. **Build**: |
| 53 | + - Unity compiles automatically. |
| 54 | + - Server: `cd Server~ && npm run build`. |
| 55 | + |
| 56 | +## 7. Update Policy |
| 57 | +- **Update this file** when architecture changes, whenever tools/resources are added/renamed/removed, or when new core patterns are introduced. |
| 58 | +- **Keep concise**: Focus on high-level patterns for AI context. |
| 59 | + |
0 commit comments