Unity MCP Efficient

Una fachada MCP independiente y eficiente en tokens, con una skill de Codex para MCP for Unity.

Mantiene todo el conjunto de funciones de Unity detrás de una API pequeña orientada al modelo. El modelo ve seis herramientas estables, busca en el catálogo upstream bajo demanda, recibe respuestas compactas adaptadas a Unity y puede encadenar trabajo rutinario sin incorporar todos los resultados intermedios a la conversación.

[!IMPORTANT] Este proyecto no sustituye al paquete de Unity ni a su servidor Python. MCP for Unity sigue siendo el backend. Registra la fachada, no el servidor upstream, con el cliente de IA. Exponer ambas superficies reduce la mayoría del ahorro de contexto.

Reducción de contexto medida

On 2026-08-24, the scripts in benchmarks/ produced these results against MCP for Unity v10.1.0 (c14de1e6).

El catálogo dinámico indexó 377 operaciones de Unity. Una pequeña suite de búsqueda determinista en inglés/ruso devolvió la operación esperada en el rango 1 en los 15 casos y dentro del top 3 en los 15 casos. La candidata a versión pasa 35 pruebas de la fachada. Una prueba de humo real no modificó el proyecto y verificó la superficie de seis herramientas, editor.refresh en el puesto 1, el estado del editor y un lote de inspección de escena en dos pasos contra un Editor de Unity abierto.

¹ Los recuentos de tokens usan una estimación transparente de cuatro caracteres por token. Describen la huella de contexto, no la facturación de la API. La tokenización real varía según el modelo y la carga útil.

² El benchmark de jerarquías modela una respuesta ruidosa con 250 objetos, 300 índices de vértice por objeto y los mismos datos en cargas útiles de texto y estructuradas. Este caso extremo no garantiza la misma reducción en todas las escenas. Consulta BENCHMARKS.md para el método y los valores brutos.

Related MCP server: Agent Bridge for Unity

Qué hacen las seis herramientas

El modelo sigue llegando a las 377 operaciones indexadas detrás de la fachada. Esas operaciones ya no ocupan el prompt todas a la vez.

Problemas gestionados en el límite

Arquitectura

Codex or another MCP client
        |
        | sees 6 tools
        v
Unity MCP Efficient (stdio by default)
        |-- capability search over the live upstream catalog
        |-- compact Unity-specific post-processing
        |-- bounded workflow runtime
        |-- local SQLite result and request receipts
        |
        | HTTP, default http://127.0.0.1:8080/mcp
        v
MCP for Unity server
        |
        v
Unity Editor package

Una skill por sí sola no puede esconder los esquemas de herramientas que un cliente MCP ya ha cargado. Por eso este repositorio contiene dos piezas:

• la fachada impone la API más pequeña y las respuestas compactas;

• la skill enseña a Codex cómo buscar, agrupar, recuperar y verificar de forma eficiente.

Instalación

1. Iniciar MCP for Unity en modo HTTP

Instala CoplayDev/MCP for Unity usando el método crudo del proyecto. En Unity, abre Window → MCP, for Unity, selecciona transporte HTTP local y arranca el servidor.

El endpoint por defecto upstream es:

http://127.0.0.1:8080/mcp

Si tu proyecto usa otro puerto, pásalo mediante UNITY_MCP_BACKEND_URL incluida más abajo.

2. Registrar la fachada en Codex

Instala uv si es necesario, y luego, ejecuta:

codex mcp add unity-efficient \
  --env UNITY_MCP_BACKEND_URL=http://127.0.0.1:8080/mcp \
  -- uvx --from git+https://github.com/Vangardo/unity-mcp-efficient.git unity-mcp-efficient

En PowerShell, usa el mismo comando en una sola línea:

codex mcp add unity-efficient --env UNITY_MCP_BACKEND_URL=http://127.0.0.1:8080/mcp -- uvx --from git+https://github.com/Vangardo/unity-mcp-efficient.git unity-mcp-efficient

Elimina o desactiva cualquier entrada directa a MCP for Unity en el mismo cliente de Codex. Mantén el servidor HTTP upstream en ejecución, pero no registres su superficie de 48 herramientas para este modelo.

3. Instalar la skill de Codex

La vía más fácil es pedir a Codex:

$skill-installer Install the skill from https://github.com/Vangardo/unity-mcp-efficient/tree/main/skills/unity-mcp-efficient

Para installación manual a nivel de usuario, clona el repositorio y copia skills/unity-mcp-efficient en:

$HOME/.agents/skills/unity-mcp-efficient

Codex detecta automatic los cambios de skill. Reinícialo si la skill no aparece.

Otros clientes MCP

Usa esta forma de configuración stdio:

{
  "mcpServers": {
    "unity-efficient": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Vangardo/unity-mcp-efficient.git",
        "unity-mcp-efficient"
      ],
      "env": {
        "UNITY_MCP_BACKEND_URL": "http://127.0.0.1:8080/mcp"
      }
    }
  }
}

Instala la skill empaquetada si el cliente es compatible con Agent Skills. La fachada funciona sin ella, pero la skill sea la capacidad básica para mejorar la selección y recuperación de errores.

Bucle de agente recomendado

1. Lee una sola vez el estado por defecto de Unity.

2. Haz una búsqueda con una frase concreta.

3. Solicite el esquema completo de la operación cuando sus argumentos no estén claros.

4. Agrupa en lote secuencial el trabajo dependiente. Paraleliza solo lecturas independientes, no mutaciones de Unity.

5. Mantén la salida compacta y expande los resultados guardados por página o por ruta.

6. Haz la revisión semántica del resultado, no de cada objeto brutal intermedio.

Este bucle ya se describe en skills/unity-mcp-efficient/SKILL.md.

Configuración

Usa el transporte stdio por defecto a menos que tengas una razón para exponer la fachada por red. Lee SECURITY.md antes de usar HTTP o SSE.

Desarrollo y verificación

git clone https://github.com/Vangardo/unity-mcp-efficient.git
cd unity-mcp-efficient
uv sync --extra dev
uv run pytest -q

Con el servidor HTTP upstream en ejecución:

uv run python benchmarks/evaluate_facade.py
uv run python benchmarks/measure_surface.py
uv run python benchmarks/live_smoke.py

evaluate_facade.py y measure_surface.py leen el catálogo upstream en vivo. live_smoke.py hache mutaciones, pero requiere un Editor de Unity abierto y conectado.

Límites conocidos

• La salida compacta es intencionadamente con pérdidas. El resultado crudo queda disponible a través de get_result durante un tiempo acotado.

• La fachada no hace seguras las mutaciones arbitrarias de Unity. Permisos y revisiones siguen siendo una tarea de cliente MCP y del usuario.

• El modo paralelo es conservador, ya que Unity puede serializar internamente el trabajo del editor.

• Evita las capaces opcionales desplegables, como Soporte de Roslyn, aunque no estén presentes en un proyecto Unity concreto.

• La captura de las vistas Scene y Game puede omitan la superposición IMGUI o solapas del editor.

• Las pruebas de compatibilidad usan MCP for Unity v10.1.0. El catálogo es dinámico; ejecuta comparativas de versiones futures antes de afirmar compatibilidad.

Origen del diseño

Tomamos la idea de divulgación progresiva del proyecto Vangardo/mcp_hub, una puerta MAC más amplia que redirige un catálogo grande de integraciones mediante una interfaz pequeña de búsqueda y llamada. Unity MCP Efficient aplica esa disciplina de contexto en Unity y, además, añade compresiones específicas de Unity, revisiones de estado, protección tras mutativas, capturas de pantalla de visión y flujos locales acotados.

Si necesitas este patrón para Slack, Teamwork, Telegram, calendario, memoria, automatización o agentes integrados con varios marketplaces, consulta MCP Hub.

El backend de compatibilidad es CoplayDev/MCP for Unity, distribuido con la Licencia MIT. Este repositorio es un proyecto independiente y no incluye su código fuente. Ve [NOTICE.md] y [THIRD_PARTY_NOTICES.md].

Licencia y marcas comerciales

El código original de este repositorio está disponible con la Licencia MIT.

Unity es una marca comercial o registrada de Unity Technologies o sus filiales en partes de todo el mundo. Este proyecto no está afiliado ni permanentizado por Unity Technologies ni por CoplayDev. Los demás nombres y marcas pertenecen a sus respectivos propietarios.