OtraUnidadMcp más

NO USAR ESTO. ESTO ES UN PROYECTO DE JUGUETE PARA VER QUÉ PUEDO HACER CON Claude Code. ESTOY TRATANDO DE EVALUAR SI UN DESARROLLADOR PUEDE TRABAJAR CORRECTAMENTE SOLO CON VIBE CODING, HASTA AHORA, PARECE QUE NO ES EL CASO.

Una implementación del Protocolo de control maestro (MCP) de Unity que permite a los agentes de IA controlar e interactuar con Unity.

Descripción general

YetAnotherUnityMcp es un sistema que conecta el motor de juego Unity con herramientas basadas en IA mediante el Protocolo de Contexto de Modelo (MCP) . Consiste en un complemento de Unity .NET/C# que actúa como servidor TCP de MCP y un cliente MCP de Python (desarrollado con FastMCP) que gestiona las solicitudes de los agentes de IA. La comunicación entre Unity y el cliente se realiza mediante un protocolo TCP personalizado , lo que permite el intercambio bidireccional en tiempo real de mensajes JSON y datos de imagen.

Esta arquitectura separa claramente las preocupaciones del motor de juego de la lógica de la IA, mejorando la escalabilidad y la facilidad de mantenimiento. El objetivo es permitir que los agentes de IA (por ejemplo, un asistente basado en LLM) inspeccionen y controlen una escena de Unity en ejecución de forma estructurada y segura. El enfoque basado en contenedores para organizar recursos y herramientas mejora aún más la organización del código y reduce el texto repetitivo.

Los componentes clave incluyen:

Complemento Unity MCP (Servidor) : complemento AC# integrado en el Editor de Unity que aloja un servidor TCP
Cliente Python FastMCP : una aplicación Python que implementa la interfaz MCP para Unity
Cliente MCP (IA o externo) : la entidad externa (como un asistente de IA o un script de prueba) que envía solicitudes MCP

¿Qué es MCP?

El Protocolo de Contexto de Modelo (MCP) es una forma estandarizada para que los modelos de IA interactúen con las aplicaciones. Separa la provisión de contexto de la interacción LLM, lo que permite:

Recursos : Proporcionar datos a los LLM (como jerarquías de escenas de Unity)
Herramientas : Permiten a los LLM realizar acciones (como ejecutar código en Unity)
Instrucciones : Definición de plantillas de interacción (por ejemplo, cómo crear GameObjects)

YetAnotherUnityMcp implementa la especificación oficial de MCP con total conformidad, que incluye:

Respuestas basadas en matrices de contenido
Descriptores de recursos basados en URI
Matrices de parámetros obligatorias a nivel de esquema
Especificaciones de tipo MIME para recursos

Características

Ejecutar código C# en Unity desde agentes de IA
Consulta el estado del Editor de Unity a través de recursos MCP con manejo dinámico de parámetros
Organice los recursos y herramientas de MCP en contenedores lógicos para una mejor organización
Captura capturas de pantalla con parámetros controlados por IA
Obtenga registros e información de depuración de Unity con monitoreo en tiempo real y recuperación incremental
Modificar propiedades de GameObject con asistencia de IA
Enumerar y navegar por las jerarquías de GameObject
Proporcionar plantillas contextuales a través de indicaciones de MCP
Comunicación en tiempo real a través de sockets TCP
Servidor TCP alojado directamente en Unity
Serialización JSON rápida y eficiente
Invocación de recursos dinámicos con mapeo de parámetros de tipo seguro
Validación de entrada basada en esquemas para herramientas y recursos

Empezando

Configuración del servidor Unity

Abra su proyecto de Unity (2020.3 o posterior)
Importe el complemento YetAnotherUnityMcp utilizando uno de estos métodos:
- Copie la carpeta plugin/Scripts al directorio Assets de su proyecto Unity
- Crea un paquete de Unity e impórtalo
- Crear un enlace simbólico para el desarrollo (ejemplo de Windows PowerShell):
  New-Item -ItemType SymbolicLink -Target "D:\Dev\YetAnotherUnityMcp\plugin" -Path "C:\Users\azrea\My project\Assets\Plugins\YetAnotherUnityMcp"
Inicie el servidor TCP:
- Desde el menú: MCP > Servidor TCP > Iniciar servidor
- O bien: Ventana > Servidor MCP > Iniciar servidor
Anote la dirección del servidor TCP (predeterminada: localhost:8080)

Configuración del cliente Python

# Clone the repository
git clone https://github.com/yourusername/YetAnotherUnityMcp.git
cd YetAnotherUnityMcp

# Create and activate a virtual environment using uv
uv venv -p 3.11
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the server with development dependencies
uv pip install -e ".[dev]"

# Run the MCP client
python -m server.mcp_server

Integración MCP

# Install FastMCP and tools
uv pip install fastmcp

# Run the client with MCP inspector for debugging
fastmcp dev server/mcp_server.py

# Install in Claude Desktop
fastmcp install server/mcp_server.py --name "Unity Controller"

Estructura del proyecto

YetAnotherUnityMcp/
├── server/                      # Python MCP client
│   ├── unity_client_util.py     # Unity client utility functions
│   ├── unity_tcp_client.py      # High-level Unity TCP client
│   ├── mcp_server.py            # MCP server implementation
│   ├── dynamic_tool_invoker.py  # Dynamic tool invocation system
│   ├── dynamic_tools.py         # Dynamic tool manager
│   ├── connection_manager.py    # Connection lifecycle management
│   └── websocket_client.py      # Low-level TCP client (legacy name)
├── plugin/                      # Unity C# plugin
│   ├── Scripts/                 # Plugin source code
│   │   ├── Editor/              # Editor extensions
│   │   │   ├── Commands/        # Editor command implementations
│   │   │   ├── MCPWindow.cs     # Server control window
│   │   │   ├── MCPMenu.cs       # Unity menu integration
│   │   │   ├── MCPTcpServer.cs  # Primary TCP server implementation
│   │   │   ├── CommandExecutionMonitor.cs # Performance monitoring
│   │   │   ├── Models/          # Data models for Editor
│   │   │   └── Net/             # TCP communication implementation
│   │   └── YetAnotherUnityMcp.asmdef  # Assembly definition
│   └── README.md                # Plugin documentation
└── tests/                       # Test suite

Arquitectura

Servidor TCP de Unity

El complemento de Unity aloja un servidor TCP que escucha las conexiones de los clientes MCP. Este servidor:

Administra las conexiones de clientes y el enrutamiento de mensajes con un protocolo de trama simple
Admite protocolo de enlace y ping/pong para supervisar el estado de la conexión.
Utiliza un registro dinámico de herramientas y recursos con descubrimiento de atributos basado en reflexión
Proporciona invocadores para acceder dinámicamente a recursos y herramientas por nombre
Admite la organización de herramientas y recursos basada en contenedores
Ejecuta comandos enviados por los clientes (por ejemplo, ejecutar código C#, tomar capturas de pantalla)
Devuelve los resultados a los clientes.
Proporciona una interfaz de usuario para supervisar conexiones y depurar.

Para obtener información detallada sobre el enfoque basado en contenedores, consulte la Documentación de contenedores de MCP .

Cliente MCP de Python

El cliente Python se conecta al servidor TCP de Unity y proporciona una interfaz MCP para herramientas de IA. Permite:

Traduce solicitudes MCP en mensajes TCP enmarcados para Unity
Maneja reintentos de conexión y pings de mantenimiento de conexión
Convierte las respuestas de Unity en datos de recursos de MCP
Utiliza la gestión de vida útil de FastMCP para el ciclo de vida de la conexión
Proporciona manejo de errores estandarizado y lógica de reconexión.
Implementa un patrón de ejecución unificado para todas las operaciones
Proporciona herramientas y recursos a través del marco FastMCP

Recursos y herramientas de MCP

Recursos

unity://info - Información básica sobre el entorno de Unity
unity://logs - Registros del editor para depuración
unity://scene/{scene_name} - Información sobre una escena específica
unity://object/{object_id} - Detalles sobre un GameObject específico

Herramientas

execute_code_in_unity - Ejecutar código C# en el Editor de Unity
unity_screenshot - Toma capturas de pantalla del Editor de Unity
unity_modify_object - Cambiar propiedades de GameObjects de Unity
unity_logs : obtiene registros de Unity con la opción de recuperar solo registros nuevos

Protocolo de comunicación

Toda la comunicación entre el servidor Unity y el cliente Python utiliza una conexión de socket TCP con un protocolo de trama simple, lo que permite la mensajería bidireccional persistente y de baja latencia. La conexión la inicia el cliente Python con el punto final TCP del servidor Unity (p. ej., localhost:8080 ).

El protocolo utiliza un mecanismo de encuadre simple:

Marcador de inicio (STX, 0x02)
Prefijo de 4 bytes de longitud
Contenido del mensaje JSON
Marcador de fin (ETX, 0x03)

Cada mensaje es un objeto JSON que contiene al menos un tipo de comando o respuesta , un ID único (para emparejar solicitudes con respuestas) y un objeto de parámetros o resultado . La conexión se mantiene mediante mensajes ping/pong periódicos. Para más detalles sobre el protocolo de comunicación, consulte el documento de Detalles Técnicos .

Desarrollo

# Python client development
python -m pytest                    # Run tests
python -m black .                   # Format code
python -m flake8                    # Lint code
python -m mypy .                    # Type check

# MCP Development
fastmcp dev server/mcp_server.py    # Run with MCP Inspector UI

# Unity server development
# Use the MCP Server window in Unity for debugging
# Monitor connections and messages in real-time

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Para obtener más detalles sobre la arquitectura, la implementación y la extensibilidad, consulte el documento Detalles técnicos .

YetAnotherUnityMcp

Integrations