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 .

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:

Clonar el repositorio:
git clone https://github.com/TSavo/Unity-MCP.git cd Unity-MCP
Instalar dependencias:
npm install
Construir el proyecto:
npm run build
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.
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:

execute_code : ejecuta código C# directamente en Unity.
consulta : ejecuta una consulta utilizando la notación de puntos para acceder a objetos, propiedades y métodos.
get_logs : recupera registros de AILogger.
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 )

Unity-MCP

Integrations

Unidad-MCP

Descripción general

Arquitectura

Características

Opciones de implementación

Documentación

Empezando

Conexión con asistentes de IA

Herramientas disponibles

Ejemplos de uso

Ejecución de código en Unity

Solicitud JSON-RPC

Respuesta JSON-RPC

Consulta de objetos de Unity

Solicitud JSON-RPC

Respuesta JSON-RPC

Recuperación de resultados de AILogger

Solicitud JSON-RPC

Respuesta JSON-RPC

Ejemplo de uso

Licencia

Autor

Tools

Related Resources