TypeScript Server Architecture
Relevant source files
The following files were used as context for generating this wiki page:
- Packages/src/TypeScriptServer~/src/server.ts
- Packages/src/TypeScriptServer~/src/infrastructure/service-locator.ts
- Packages/src/TypeScriptServer~/src/unity-discovery.ts
- Packages/src/TypeScriptServer~/src/connection-manager.ts
- Packages/src/ARCHITECTURE.md
- Packages/src/TypeScriptServer~/README.md
- Packages/src/TypeScriptServer~/package.json
- Packages/src/Editor/Build/TypeScriptBuilder.cs
- Packages/src/TypeScriptServer~/src/tools/dynamic-unity-command-tool.ts
- Packages/src/TypeScriptServer~/src/tools/base-tool.ts
- Packages/src/Cli~/src/tests/cli-e2e.test.ts
- Packages/src/Cli~/scripts/generate-bundled-skills.ts
The TypeScript Server is a core component of the uLoopMCP system, acting as a bridge between Model Context Protocol (MCP) clients (e.g., Cursor, Claude Code) and the Unity Editor. It is a Node.js process that implements the MCP server specification, receives tool execution requests from LLM-powered clients, and forwards them to a C# TCP server running within the Unity Editor. The server is designed with a Domain-Driven Design (DDD) architecture to ensure clean separation of concerns, extensibility, and maintainability.
This server is responsible for managing the connection to Unity, dynamically discovering and exposing Unity-side tools to MCP clients, and handling the communication flow. It is built for resilience, with features like automatic reconnection and graceful degradation. For more details on the overall system, see the Unity Editor-Side Architecture and the main System Overview.
Sources: Packages/src/ARCHITECTURE.md, Packages/src/TypeScriptServer~/README.md
High-Level System View
The uLoopMCP system is composed of three primary components: MCP Clients, the TypeScript Server, and the Unity Editor. The TypeScript server sits in the middle, orchestrating communication.
This diagram shows the communication flow from LLM clients to the TypeScript server via the MCP protocol, and then from the TypeScript server to the Unity Editor via TCP/JSON-RPC.
Sources: Packages/src/ARCHITECTURE.md, Packages/src/ARCHITECTURE_ja.md
Key Architectural Features
| Feature | Description |
|---|---|
| Domain-Driven Design | A clean architecture with Use Cases orchestrating business workflows, separating business logic from infrastructure concerns. |
| Service Locator Pattern | Provides type-safe dependency injection using symbol-based tokens and factory functions. |
| Interface Segregation | Employs small, focused interfaces for specific responsibilities, promoting high cohesion. |
| Dynamic Tool Management | Automatically discovers tools exposed by the Unity Editor and makes them available to MCP clients. |
| Connection Resilience | Features automatic reconnection and discovery of the Unity TCP server, with graceful degradation of service. |
Sources: Packages/src/ARCHITECTURE.md, Packages/src/TypeScriptServer~/README.md:28-32
Core Components and Design
The server is structured following Domain-Driven Design (DDD) principles, separating the system into distinct layers.
Sources: Packages/src/ARCHITECTURE.md:32-35
DDD Layers
This diagram illustrates the dependency flow in the DDD architecture, where inner layers have no knowledge of outer layers.
- Domain Layer: Contains the core business logic, models, and use cases. It is pure and has no dependencies on external systems or frameworks. Example:
RefreshToolsUseCase. - Application Layer: Defines service contracts (interfaces) that shield the Domain Layer from the details of the infrastructure. Examples:
IConnectionService,IToolManagementService. - Infrastructure Layer: Implements the interfaces defined in the Application Layer. It handles all external system integrations, such as TCP communication (
ConnectionManager) and framework-specific code.
Sources: Packages/src/ARCHITECTURE.md:65-68, Packages/src/TypeScriptServer~/src/tests/integration/refresh-tools-use-case.integration.test.ts:18-20
Tool Management
A key responsibility of the server is to manage tools. This includes both tools defined within the TypeScript server itself and, more importantly, tools dynamically discovered from the connected Unity Editor.
Tool Class Hierarchy
The system uses a BaseTool abstract class to provide a common structure and template method pattern for all tools. Unity-side commands are wrapped in DynamicUnityCommandTool instances.
This diagram shows that DynamicUnityCommandTool inherits from the abstract BaseTool, which implements the ToolHandler interface.
Sources: Packages/src/TypeScriptServer~/src/tools/base-tool.ts, Packages/src/TypeScriptServer~/src/tools/dynamic-unity-command-tool.ts
Dynamic Tool Generation
When the TypeScript server connects to Unity, it fetches a list of available tools. For each tool exposed by Unity, it creates an instance of DynamicUnityCommandTool. This class dynamically generates a JSON schema for the tool's inputs based on the schema provided by Unity.
When an MCP client invokes one of these dynamic tools, the execute method of DynamicUnityCommandTool is called, which then uses the unityClient to send a JSON-RPC request to the Unity Editor to execute the actual tool logic.
Sources: Packages/src/TypeScriptServer~/src/tools/dynamic-unity-command-tool.ts:29-41, 137-149
Connection Management
The ConnectionManager is responsible for establishing and maintaining the TCP/JSON-RPC connection to the Unity Editor.
- Discovery: It uses
UnityDiscoveryto find the correct port for the Unity TCP server. - Resilience: It handles automatic reconnection if the connection is lost, which is crucial for surviving Unity's domain reloads (e.g., after a script compilation).
- Communication: It provides the
executeToolmethod, which is used by dynamic tools to send commands to Unity.
Sources: Packages/src/ARCHITECTURE.md:40, Packages/src/TypeScriptServer~/src/tools/dynamic-unity-command-tool.ts:141
Communication and Execution Flow
The following sequence diagram illustrates the end-to-end flow when an MCP client executes a Unity tool.
This diagram shows a request originating from an MCP client, being processed by the TypeScript server and its components, executed in Unity, and the response flowing back.
Sources: Packages/src/TypeScriptServer~/src/tools/base-tool.ts:28-35, Packages/src/TypeScriptServer~/src/tools/dynamic-unity-command-tool.ts:137-149
Build and Packaging
The TypeScript server is built and bundled using esbuild. The build process is integrated into both the npm lifecycle and the Unity Editor workflow.
Build Scripts
The package.json file defines several scripts for building, running, and testing the server.
| Script | Description |
|---|---|
build | Bundles the server using esbuild into dist/server.bundle.js. |
dev | Builds the server and runs it in development mode with source maps enabled. |
start | Runs the bundled production server. |
postinstall | Automatically runs the build script after npm install. |
Sources: Packages/src/TypeScriptServer~/package.json:8-11, 33
Unity Build Integration
The Unity side of the project contains a C# class, TypeScriptBuilder, which is responsible for triggering the TypeScript build process from within the Unity Editor.
The build process is as follows:
- The
TypeScriptBuilderlocates theTypeScriptServer~directory. - It finds the
npmexecutable on the system usingNodeEnvironmentResolver. - It executes
npm cito ensure dependencies are installed correctly frompackage-lock.json. - It executes
npm run build:bundleto create the finalserver.bundle.jsfile.
This ensures that the TypeScript server is always up-to-date when working within Unity.
Sources: Packages/src/Editor/Build/TypeScriptBuilder.cs:21-44, 56-62
CLI and Skills Integration
The project also includes a standalone CLI tool, uloop, which provides an alternative way to interact with the Unity Editor. The CLI reuses the same tool definitions but interacts with them through a command-line interface instead of the MCP protocol.
"Skills" are Markdown files (SKILL.md) that describe a tool's purpose and usage. A script (generate-bundled-skills.ts) collects these files from various locations and bundles them into a bundled-skills.ts file. This allows LLM tools that support "Skills" (like Claude Code) to automatically discover and use the uloop CLI commands without requiring manual MCP configuration.
End-to-end tests (cli-e2e.test.ts) validate the CLI's functionality by executing commands against a running Unity instance and asserting the expected outcomes, such as successful compilation or log retrieval.
Sources: Packages/src/README.md, Packages/src/Cli~/scripts/generate-bundled-skills.ts, Packages/src/Cli~/src/tests/cli-e2e.test.ts
Summary
The TypeScript Server is a well-architected, decoupled component that serves as the central communication hub in the uLoopMCP ecosystem. Its adherence to Domain-Driven Design, use of a dynamic tool discovery mechanism, and resilient connection management make it an extensible and robust foundation for enabling AI-driven development within the Unity Editor. The build automation and CLI integration further enhance its usability and streamline the development workflow for both end-users and contributors.
Sources: Packages/src/ARCHITECTURE.md, Packages/src/TypeScriptServer~/README.md