Unidad-MCP

Un puente entre Unity y los asistentes de IA que utilizan el Protocolo de contexto de modelo (MCP).

Descripción general

Unity-MCP es una implementación de código abierto del Protocolo de Contexto de Modelo para el desarrollo de juegos Unity. Permite que los asistentes de IA interactúen con los entornos de juego Unity a través de una interfaz estandarizada, lo que facilita el desarrollo de juegos asistido por IA, las pruebas automatizadas, el análisis de escenas y la depuración en tiempo de ejecución.

Arquitectura

Se ha simplificado la arquitectura para utilizar AILogger para la persistencia, eliminando la necesidad de un componente de servidor separado:

AI Assistant <-> Unity-MCP STDIO Client <-> Unity Client <-> AILogger

• Asistente de IA : se comunica con el cliente Unity-MCP STDIO mediante el protocolo MCP

• Cliente Unity-MCP STDIO : reenvía comandos al cliente Unity y almacena los resultados en AILogger

• Cliente de Unity : ejecuta comandos en Unity y devuelve resultados

• AILogger : almacena registros y resultados para su posterior recuperación

El cliente STDIO de Unity-MCP se comunica directamente con el cliente de Unity, que proporciona puntos finales tanto para la ejecución de código como para las consultas. La herramienta de consultas transforma las consultas en ejecución de código envolviéndolas en una declaración return .

Related MCP server: Advanced Unity MCP

Características

• Ejecutar código C# en el entorno de ejecución de Unity

• Inspeccionar los objetos del juego y sus componentes

• Analizar jerarquías y estructuras de escenas

• Ejecutar pruebas y recibir resultados

• Invocar métodos en objetos y componentes del juego

• Modificar el estado del juego durante el tiempo de ejecución

Opciones de implementación

• Extensión del editor de Unity: una extensión del editor que persiste más allá de los ciclos de ejecución del juego

• Contenedor Docker: una versión en contenedor que se comunica con Unity a través de la red

• Paquete NPX: un paquete Node.js que se puede instalar y ejecutar a través de NPX

Documentación

• Arquitectura MCP : descripción general de la arquitectura y los espacios de nombres de MCP

• Cliente MCP STDIO : información sobre el cliente MCP STDIO y sus capacidades de registro

• Herramienta de consulta : información detallada sobre la herramienta de consulta y cómo funciona

• Integración con AILogger : información detallada sobre la integración con AILogger

• Referencia de API : información detallada sobre los puntos finales de la API

• Guía de instalación : instrucciones paso a paso para instalar y configurar Unity-MCP

• Guía de desarrollo : información sobre el entorno de desarrollo y el flujo de trabajo

• Guía de recarga en caliente : información detallada sobre la recarga en caliente en el entorno de desarrollo

• Referencia rápida de recarga en caliente : Guía de referencia rápida para comandos y consejos de recarga en caliente

• Guía de contribución : Pautas para contribuir al proyecto

Empezando

Para comenzar a utilizar Unity-MCP, siga estos pasos:

1. Clonar el repositorio:

   git clone https://github.com/TSavo/Unity-MCP.git
   cd Unity-MCP

2. Instalar dependencias:

   npm install

3. Construir el proyecto:

   npm run build

4. Inicie el cliente MCP STDIO:

   npm start

   Esto iniciará el cliente MCP STDIO que se comunica con Unity y utiliza AILogger para la persistencia.

   Nota: asegúrese de que AILogger se esté ejecutando en http://localhost:3030 o configure la variable de entorno AI_LOGGER_URL para que apunte a su instancia de AILogger.

5. Ejecutar pruebas:

   # Run all tests
   npm test
   
   # Run only unit tests
   npm run test:unit
   
   # Run only e2e tests
   npm run test:e2e
   
   # Run tests with a specific pattern
   npm test -- --testNamePattern="should return the server manifest"
   npm run test:unit -- --testNamePattern="should return the server manifest"
   npm run test:e2e -- --testNamePattern="should discover the test server"

Para obtener instrucciones más detalladas, consulte la Guía de instalación .

Conexión con asistentes de IA

Para conectar el puente Unity-MCP a un asistente de IA, debe crear un archivo de configuración MCP:

{
  "mcpServers": {
    "unity-ai-bridge": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Coloque este archivo en la ubicación adecuada para su asistente de IA. En el caso de Claude, normalmente se encuentra en el directorio de configuración de la aplicación Claude Desktop.

Herramientas disponibles

El puente Unity-MCP proporciona las siguientes herramientas:

1. execute_code : ejecuta código C# directamente en Unity.

2. consulta : ejecuta una consulta utilizando la notación de puntos para acceder a objetos, propiedades y métodos.

3. get_logs : recupera registros de AILogger.

4. get_log_by_name : recupera un registro específico de AILogger.

Ejemplos de uso

Ejecución de código en Unity

Puedes ejecutar código C# en Unity con la herramienta execute_code . El código se ejecutará en el entorno de ejecución de Unity y el resultado se almacenará en AILogger para su posterior recuperación.

Solicitud JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
      "code": "Debug.Log(\"Hello from Unity!\"); return GameObject.FindObjectsOfType<GameObject>().Length;",
      "timeout": 5000
    }
  }
}

Respuesta JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"success\",\"logName\":\"unity-execute-1712534400000\",\"result\":{\"success\":true,\"result\":42,\"logs\":[\"Hello from Unity!\"],\"executionTime\":123}}"
      }
    ]
  }
}

Consulta de objetos de Unity

Puedes consultar objetos de Unity con la herramienta query . Esto te permite acceder a objetos, propiedades y métodos mediante notación de puntos.

Solicitud JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "query": "Camera.main.transform.position",
      "timeout": 5000
    }
  }
}

Respuesta JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"success\",\"logName\":\"unity-query-1712534400000\",\"result\":{\"success\":true,\"result\":{\"x\":0,\"y\":1,\"z\":-10},\"executionTime\":45}}"
      }
    ]
  }
}

Recuperación de resultados de AILogger

Puede recuperar los resultados de operaciones anteriores de AILogger utilizando la herramienta get_log_by_name .

Solicitud JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_log_by_name",
    "arguments": {
      "log_name": "unity-execute-1712534400000",
      "limit": 1
    }
  }
}

Respuesta JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"success\",\"name\":\"unity-execute-1712534400000\",\"entries\":[{\"id\":\"123e4567-e89b-12d3-a456-426614174000\",\"name\":\"unity-execute-1712534400000\",\"data\":{\"result\":{\"success\":true,\"result\":42,\"logs\":[\"Hello from Unity!\"],\"executionTime\":123},\"timestamp\":\"2025-04-08T00:00:00.000Z\"},\"timestamp\":\"2025-04-08T00:00:00.000Z\"}]}"
      }
    ]
  }
}

Ejemplo de uso

Una vez que el asistente de IA tenga acceso a la herramienta Unity, puedes pedirle que realice tareas como:

Can you execute the following C# code in Unity?

GameObject.Find("Player").transform.position = new Vector3(0, 1, 0);

Licencia

Instituto Tecnológico de Massachusetts (MIT)

Autor

T Savo ( @TSavo )