Unity MCP Efficient

Независимый, экономный по токенам MCP-фасад и навык Codex для MCP for Unity.

Фасад сохраняет все возможности Unity за компактным API, ориентированным на модель. Модель видит шесть стабильных инструментов, выполняет поиск по каталогу по мере необходимости, получает сжатые ответы с учётом специфики Unity и может выполнять рутинные операции цепочкой, не перетаскивая в диалог каждый промежуточный результат.

[!IMPORTANT] Этот проект не заменяет пакет Unity или его Python-сервер. MCP for Unity остаётся серверной частью. Регистрируйте у AI-клиента именно фасад, а не вышестоящий сервер. Если оставить активными обе поверхности инструментов, почти вся экономия контекста будет потеряна.

Измеренное сокращение потребления контекста

24 августа 2026 года скрипты из benchmarks/ дали следующие результаты против MCP for Unity v10.1.0 (c14de1e6).

Динамический каталог проиндексировал 377 операций Unity. Небольшой детерминированный набор поисковых тестов на английском и русском вернул ожидаемую операцию на позицию 1 для всех 15 случаев и в первую тройку для всех 15 случаев. Релизный кандидат проходит 35 тестов фасада. Живой смоук-тест без изменения проекта подтвердил в открытом редакторе Unity поверхность из шести инструментов, editor.refresh на позиции 1, состояние редактора и двухэтапную пакетную инспекцию сцены.

¹ Подсчёт токенов использует прозрачную оценку в четыре символа на токен. Это показатель занимаемого контекста, а не тарификации API. Фактическая токенизация зависит от модели и содержимого нагрузки.

² Бенчмарк иерархии моделирует зашумлённый ответ: 250 объектов, 300 индексов вершин на объект и те же данные в текстовом и структурированном виде. Такой стрессовый сценарий не обещает такого же сокращения для любой сцены. Методика и исходные значения — в BENCHMARKS.md.

Related MCP server: Agent Bridge for Unity

Что делают шесть инструментов

Модель по-прежнему имеет доступ ко всем 377 проиндексированным операциям за фасадом. Просто эти операции больше не занимают весь промпт разом.

Проблемы, решаемые на границе

Архитектура

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

Один навык сам по себе не может скрыть схемы инструментов, которые MCP-клиент уже загрузил. Именно поэтому в репозитории есть обе части:

• фасад обеспечивает небольшое API и компактные ответы;

• навык учит Codex эффективно искать, пакетировать, восстанавливать выполнение и проверять результаты.

Установка

1. Запустите MCP for Unity в режиме HTTP

Установите CoplayDev/MCP for Unity по его официальной инструкции. В Unity откройте Window → MCP for Unity, выберите локальный HTTP-транспорт и запустите сервер.

Адрес вышестоящего endпоинта по умолчанию:

http://127.0.0.1:8080/mcp

Если в вашем проекте используется другой порт, передайте его ниже через UNITY_MCP_BACKEND_URL.

2. Зарегистрируйте фасад в Codex

При необходимости установите uv, затем выполните:

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

В PowerShell та же команда в одну строку:

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

Удалите или отключите прямую запись дистрибутива MCP for Unity у того же клиента Codex. Вышестоящий HTTP-сервер остаётся запущенным, но его поверхность и 48 инструментов модели регистрировать не нужно.

3. Установите навык Codex

Проще всего попросить Codex:

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

Для ручной установки на уровне пользователя склонируйте репозиторий и скопируйте папку skills/unity-cheap-efficient:

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

Codex автоматически выявляет изменливые нав заложения. Если навык не появился, перезапустите его.

Другие MCP-клиенты

Используйте такую форму 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"
      }
    }
  }
}

Если клиент поддерживает формат Agent Skills, поставьте упакованный навык. Фасад работает и без него, но навык улучшает выбор инструментов и поведение при восстановлении.

Рекомендуемый цикл работы агента

1. Один раз получите состояние Unity в низкой детализации.

2. Сформулируйте одну конкретную фразу задачи для поиска.

3. Запросите схему конкретногоинструмента выбранного инструмента, если его аргументы не очевидны.

4. Зависимые построения последовательный serie; параллелить только независимые операции чтения, никогда — мутации в Unity.

5. Оставляйте вывод компактным, а сохранённые результаты расширяйте по ключу или странице.

6. Проверяйте смысловой результат, а не каждый промежуточный «полосат» объекта.

Этот цикл уже заложен в
`skills/unity-mcp-efficient/SKILL.md`.

Конфигурация

Оставьте transport stdio по умолчанию, если у вас нет причины публиковать фасад наружу через сеть. Прочитайте SECURITY.md на перед использования HTTP или SSE.

Разработка и проверка

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

При запущенном вышестоящем HTTP-сервере:

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

Скрипты evaluate_facade.py и measure_surface.py читают динамический каталог вышестоящего сервера. live_smoke.py не производит никаких изменений, но требует открытого и подключённого редактор Unity.

Известные границы

• Компактный вывод осознанно «с потерями». Нетронутый исходный результат остаётся доступным через get_result в течение ограниченного времени.

• Фасад не делает мутации в Unity безопасными. Права и проверку выполняемых действий по-прежнему контролируются MCP-клиент и пользователь.

• Параллельный режим консервативен. Unity всё равно может сериализовать внутреннюю работу редактора.

• Обнаружимаемая опциональная возможность, например поддержка Roslyn, всё ещё может отсутствовать в конкретном проекте Unity.

• Захват вида Scene или Game может не включать IMGUI или различные редактор о оверлеи.

• Тесты совместимости основаны на MCP for Unity v10.1.0. Каталог динамичен; более поздние релизы проектов отслеживайте по собственным бенчмаркам.

Преемственность дизайна

Идею progressive disclosure мы заимствовали из работы над Vangardo/mcp_hub — более широким MCP-шлюзом, который пропускает большой каталог интеграций через маленькую поверхность «поиск-и-вызов». Unity MCP Efficient применяет этот подход к Unity, добавляя специфическое сжатие данных, проверки по ревизиям, восстановление после мутаций, скриншоты и ограниченные локальные сценарии работы.

Если этот паттерн нужен для Slack, Teamwork, Telegram, календаря, памяти, автоматизации или кросс-сервисных агентов, — смотрите MCP Hub.

Совместимый с Unity бэкенд — это CoplayDev/MCP for Unity, который распространяется по лицензии MIT. Этот репозиторий — независимый проект, и он не включает в себя его исходный код. См. NOTICE.md и THIRD_PARTY_NOTICES.md.

Лицензия и товарные знаки

Автор руссный код и содержимое данного репозитория доступны в the terms MIT License.

Unity является товарным знаком или зарегистрированным товарным знаком Unity Technologies и её аффилированных лиц в США и других странах. Проект не связан с Unity Technologies или CoplayDev и не поддерживается ими. Остальные названия и бренды могут использовать переданные им владельцам.