Unity-MCP

Un puente entre el motor de juegos Unity y los asistentes de IA que utiliza el Protocolo de Contexto de Modelo (MCP).

GitHub
7

Documentación

Unity-MCP

Un puente entre Unity y asistentes de IA que utiliza el Protocolo de Contexto de Modelos (MCP).

Descripción general

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

Arquitectura

La arquitectura se ha simplificado 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 STDIO de Unity-MCP utilizando el protocolo MCP
  • Cliente STDIO de Unity-MCP: Reenvía comandos al Cliente de Unity y almacena los resultados en AILogger
  • Cliente de Unity: Ejecuta comandos en Unity y devuelve los 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 endpoints tanto para la ejecución de código como para consultas. La herramienta de consulta transforma las consultas en ejecución de código envolviéndolas en una declaración return.

Características

  • Ejecutar código C# en el entorno de ejecución de Unity
  • Inspeccionar objetos de juego y sus componentes
  • Analizar jerarquías y estructuras de escenas
  • Ejecutar pruebas y recibir resultados
  • Invocar métodos en objetos de juego y componentes
  • 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 contenerizada que se comunica con Unity a través de la red
  • Paquete NPX: Un paquete de Node.js que se puede instalar y ejecutar mediante NPX

Documentación

Primeros pasos

Para comenzar con Unity-MCP, sigue estos pasos:

  1. Clona el repositorio:

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

  2. Instala las dependencias:

    npm install

  3. Compila el proyecto:

    npm run build

  4. Inicia el cliente STDIO MCP:

    npm start

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

    Nota: Asegúrate de que AILogger esté ejecutándose en http://localhost:3030 o configura la variable de entorno AI_LOGGER_URL para que apunte a tu instancia de AILogger.

  5. Ejecuta las 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 instrucciones más detalladas, consulta la Guía de instalación.

Conexión a asistentes de IA

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

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

Coloca este archivo en la ubicación adecuada para tu asistente de IA. Para Claude, normalmente sería 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. query: Ejecuta una consulta utilizando 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 utilizando 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 utilizando la herramienta query. Esto te permite acceder a objetos, propiedades y métodos utilizando 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

Puedes recuperar los resultados de operaciones anteriores desde 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 de 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

MIT

Autor

T Savo (@TSavo)