Unitymcp

🚀 Unity MCP Getting Started Guide

This guide provides a comprehensive introduction to integrating and using the Model Context Protocol (MCP) in your Unity project, including installation, configuration, basic usage, and troubleshooting.

🚀 Quick Start

Unity Installation Steps

1. Download the latest version of the MCP module.
2. Import the module file (.unitypackage) into your Unity project.
3. Create a new empty file named McpServerSettings.cs under the Assets/Editor folder.
4. Add the following content to the file:

using UnityEngine;
using ModelContextProtocol;

public static class McpServerSettings {
    public const bool StartOnLaunch = true; // Whether to automatically start the server when Unity launches
    public const bool RestartOnPlayModeChange = true; // Whether to restart the server when switching Play mode
}

5. Open Edit > Preferences > Projects > External Tools and check Enable MCP Server Support.

TypeScript Installation Steps

1. Clone the MCP example project repository.
2. Install the dependencies:

npm install @model-context-protocol/mcp-typings @model-context-protocol/mcp-server

3. Start the TypeScript server:

npm run start

💻 Usage Examples

Create a Basic Command Handler (C#)

Create a new C# script named HelloWorldCommandHandler.cs under the Assets/Editor folder:

using UnityEngine;
using ModelContextProtocol;

public class HelloWorldCommandHandler : CommandHandler {
    protected override void Handle(string[] args) {
        // Implement your business logic here
        Debug.Log("Hello, World!");
    }
}

Create a Basic Resource Handler (C#)

Create a new C# script named MyResourceHandler.cs under the Assets/Editor folder:

using UnityEngine;
using ModelContextProtocol;

public class MyResourceHandler : ResourceHandler {
    protected override async Task<HttpResponse> Handle(Request request) {
        // Implement your business logic here
        return await Response.Ok("Hello, World!");
    }
}

Create a Basic Command Handler (TypeScript)

Create a new TypeScript file named hello-world.ts under the handlers/commands folder:

import { CommandHandler } from "@model-context-protocol/mcp-server";

export class HelloWorldCommand extends CommandHandler {
    async execute(args: string[]): Promise<string> {
        // Implement your business logic here
        return "Hello, World!";
    }
}

📦 Communication Protocol

Basic Request-Response Structure (JSON)

{
    "id": "123",         // Unique identifier for the request
    "type": "command",   // Request type, can be command, resource, or prompt
    "method": "GET",     // HTTP method, such as GET, POST, etc.
    "path": "/hello",    // Request path
    "body": {           // Request body
        "message": "Hello"
    }
}

Response Structure (JSON)

{
    "id": "123",
    "success": true,     // Whether the request was successful
    "result": {         // Response result
        "greeting": "World"
    }
}

📃 Request Flow

1. The client sends a request to the TypeScript server.
2. The server forwards the request to the Unity MCP Server.
3. Unity finds the corresponding Handler based on the request path.
4. The Handler processes the request on the Unity main thread.
5. The response result is returned to the TypeScript server.
6. The server formats the result as JSON and returns it to the client.

📚 Documentation

Example McpServerSettings.cs

using UnityEngine;
using ModelContextProtocol;

public static class McpServerSettings {
    public const bool StartOnLaunch = true; // Whether to automatically start the server when Unity launches
    public const bool RestartOnPlayModeChange = true; // Whether to restart the server when switching Play mode
}

Example mcp-config.json

{
  "port": 5005,         // The port that the MCP Server listens on
  "workers": 4,        // Number of worker processes
  "logging": {
    "level": "debug",   // Log level: debug, info, warning, error
    "console": true      // Whether to enable console logging
  }
}

🔧 Troubleshooting

Common Issues and Solutions

📚 More Resources

• Official Documentation
• Example Projects
• Developer Forum

By following the steps above, you can easily integrate and use the MCP protocol in your Unity project.