unity-api-mcp

Сервер MCP, предоставляющий ИИ-агентам точную документацию по Unity API. Предотвращает галлюцинации сигнатур, неверные пространства имён и использование устаревшего API.

Поддерживает Unity 6 (одна база данных на каждую минорную версию), Unity 2023 и Unity 2022 LTS. Работает с Claude Code, Cursor, Windsurf или любым совместимым с MCP инструментом ИИ. Установка Unity не требуется. Смотрите поддерживаемые версии. Новые релизы Unity обнаруживаются и собираются автоматически каждую неделю.

Быстрый старт

Добавьте в конфигурацию MCP (.mcp.json, mcp.json или настройки MCP вашего инструмента), указав UNITY_VERSION в соответствии с вашим проектом:

{
  "mcpServers": {
    "unity-api": {
      "command": "uvx",
      "args": ["unity-api-mcp"],
      "env": {
        "UNITY_VERSION": "6000.3"
      }
    }
  }
}

Допустимые значения: поток Unity 6, например "6000.3", или "6", "2023", "2022".

При первом запуске сервер загружает соответствующую базу данных (~20-30 МБ) в ~/.unity-api-mcp/.

Как это работает

1. Определение версии. Сервер определяет, какую версию Unity обслуживать:

1. Загрузка базы данных. Если база данных для этой версии не кэширована локально, она загружается с GitHub. Для минорных потоков Unity 6 (6000.0, 6000.3, 6000.5, …) создаётся отдельная база данных для каждого потока, с резервным вариантом на общую базу данных 6, если база данных для потока не опубликована. Кэшированные базы данных проверяются на актуальность при запуске по сравнению с релизом, поэтому еженедельные сборки автоматически доходят до существующих установок.

2. Обслуживание. Все вызовы инструментов обращаются к версии SQLite-базы данных. Каждый запрос выполняется менее чем за 15 мс.

Для каждой версии есть своя база данных с корректными сигнатурами, предупреждениями об устаревании и списками членов для этого релиза.

Инструменты

Покрытие

Все модули UnityEngine и UnityEditor, а также пакеты, распарсенные из исходного кода C#: Input System, Addressables, uGUI (включая TextMeshPro в Unity 6), AI Navigation и Netcode. Около 42 500 записей в каждой базе данных Unity 6, ~500 предупреждений об устаревании в каждой.

Полный список версий: страница релиза db-v1. CI пересобирает эту таблицу при каждой сборке. Новые патчи Unity обнаруживаются и собираются автоматически каждый понедельник.

Не покрывает сторонние ассеты (DOTween, VContainer, Newtonsoft.Json). Для них полагайтесь на исходный код проекта.

Бенчмарки

Измерено, а не обещано: 25 исследовательских вопросов по 3 тестовым наборам, ответы на которые давали 3 конфигурации агентов, каждый ответ оценивался по заранее проверенной истине в исходном коде. Полный набор тестов находится в docs/benchmark/ и запускается одной командой.

Единственный воспроизведённый случай галлюцинации показателен. При запросе перечислить перегрузки SceneManager.LoadSceneAsync оба не-MCP агента выдумали перегрузки с одним параметром LoadSceneAsync(string) и LoadSceneAsync(int), которых не существует. Код, написанный с их использованием, не компилируется. MCP-агент вернул ровно четыре реальные перегрузки.

Почему важна корректность, а не экономия токенов? Агентные инструменты уже хорошо справляются с поиском кода. Claude Code изначально поставляется с инструментом Grep, а современные модели сначала ищут, а затем читают узкий диапазон строк, поэтому использование токенов было сопоставимым во всех конфигурациях в наших тестах. Но точные перегрузки, пространства имён и устаревшие методы вообще не содержатся в файлах вашего проекта. Агент без MCP может только предполагать их на основе примеров использования, и когда он ошибается — вы платите сломанной сборкой.

Методология

• 3 тестовых набора: реальный игровой проект на Unity 6 (11 вопросов), чистые запросы к API Unity (8) и исходный код пакета Unity Input System с файлами от 2700 до 4600 строк (6)
• 3 конфигурации с одинаковой моделью и лимитом ходов: инструменты MCP + Grep/чтение, только Grep/чтение, только чтение
• Эталонная истина проверена чтением исходников до запусков; ответы оценивались отдельной сессией модели в сравнении с эталонной истиной; использование токенов взято из полей использования API
• Запустите сами: python docs/benchmark/run.py --project <путь-к-проекту-unity> (результаты от июля 2026; поведение агентов меняется, поэтому перезапустите перед цитированием)

Фрагмент CLAUDE.md

Добавьте это в CLAUDE.md вашего проекта (или аналогичный файл с инструкциями). Этот шаг важен. Без него ИИ будет иметь инструменты, но не будет знать, когда их использовать.

## Unity API Lookup (unity-api MCP)

Use the `unity-api` MCP tools to verify Unity API usage instead of guessing. **Do not hallucinate signatures.**

| When | Tool | Example |
|------|------|---------|
| Unsure about a method's parameters or return type | `get_method_signature` | `get_method_signature("UnityEngine.Tilemaps.Tilemap.SetTile")` |
| Need the `using` directive for a type | `get_namespace` | `get_namespace("SceneManager")` |
| Want to see all members on a class | `get_class_reference` | `get_class_reference("InputAction")` |
| Searching for an API by keyword | `search_unity_api` | `search_unity_api("async load scene")` |
| Checking if an API is deprecated | `get_deprecation_warnings` | `get_deprecation_warnings("FindObjectOfType")` |

**Rules:**
- Before writing a Unity API call you haven't used in this conversation, verify the signature with `get_method_signature`
- Before adding a `using` directive, verify with `get_namespace` if unsure
- Covers: all UnityEngine/UnityEditor modules, Input System, Addressables, uGUI/TextMeshPro, AI Navigation, Netcode
- Does NOT cover: DOTween, VContainer, Newtonsoft.Json (third-party)

Детали настройки

Автоопределение версии по пути к проекту

Вместо установки UNITY_VERSION можно указать путь к вашему проекту Unity. Сервер автоматически считывает ProjectSettings/ProjectVersion.txt:

{
"mcpServers": {
  "unity-api": {
    "command": "uvx",
    "args": ["unity-api-mcp"],
    "env": {
      "UNITY_PROJECT_PATH": "/path/to/your/unity-project"
    }
  }
}
}

Альтернативные способы установки

С помощью pip install:

pip install unity-api-mcp

{
"mcpServers": {
  "unity-api": {
    "command": "unity-api-mcp",
    "args": [],
    "env": {
      "UNITY_VERSION": "6000.3"
    }
  }
}
}

Переменные окружения

Локальное создание баз данных

Если вы хотите создать базу данных из собственной установки Unity вместо загрузки:

# Install with ingest dependencies
pip install unity-api-mcp[ingest]

# Windows
python -m unity_api_mcp.ingest --unity-version 6000.3 --unity-install "D:/Unity/6000.3.8f1" --project "F:/Unity Projects/MyProject"

# macOS
python -m unity_api_mcp.ingest --unity-version 6000.3 --unity-install "/Applications/Unity/Hub/Editor/6000.3.20f1" --project "/path/to/UnityProject"

# Legacy versions
python -m unity_api_mcp.ingest --unity-version 2022 --unity-install "D:/Unity/2022.3.62f1"

Базы данных по умолчанию записываются в ~/.unity-api-mcp/unity_docs_{version}.db.

Настройка с помощью ИИ

Если ИИ-агент настраивает это для вас:

Добавьте unity-api-mcp в мою конфигурацию MCP с помощью uvx с установкой UNITY_VERSION в соответствии с моим проектом, добавьте фрагмент из CLAUDE.md из README и проверьте с помощью get_namespace("SceneManager").

Структура проекта

unity-api-mcp/
├── src/unity_api_mcp/
│   ├── server.py          # MCP server (5 tools)
│   ├── db.py              # SQLite + FTS5 database layer
│   ├── version.py         # Version detection + DB download
│   ├── xml_parser.py      # Parse Unity XML IntelliSense files
│   ├── cs_doc_parser.py   # Parse C# doc comments from package source
│   ├── unity_paths.py     # Locate Unity install + package dirs
│   └── ingest.py          # CLI ingestion pipeline
└── pyproject.toml

Базы данных хранятся в ~/.unity-api-mcp/ (загружаются при первом запуске).

Устранение неполадок

См. также

unreal-api-mcp: та же концепция для Unreal Engine (C++), с еженедельными автоматически собираемыми базами данных для каждой версии UE.

Контакты

Нужен кастомный MCP-сервер для вашего движка или фреймворка? Я разрабатываю MCP-инструменты, которые сокращают расход токенов и предотвращают галлюцинации при AI-ассистированной разработке игр. Если вы хотите нечто подобное для стека вашей команды — свяжитесь со мной.

fuatcankoseoglu@gmail.com

Лицензия

MIT