Как мы создали MCP-сервер реального времени для Godot

Почему “реальное время” важно для MCP-сервера в Godot

Большинство MCP-демо работают с REST-подобным миром: модель задает вопрос, инструмент возвращает JSON, и никого не волнует, если круговой запрос занял две секунды. Godot другой. Редактор владеет живым деревом сцены, импортом ресурсов и игровым циклом. Если ваш MCP-сервер блокирует главный поток — или видит только устаревший дамп проекта — AI-клиенты перестают ощущаться как со-пилоты и начинают напоминать удаленные редакторы файлов с дополнительными шагами.

Когда мы проектировали Godot MCP для VberAI, требования были четкими:

• AI-ассистент (Cursor, Claude, Windsurf и подобные MCP-клиенты) должен управлять редактором, а не просто читать .gd файлы с диска
• Действия, такие как создание узла, переименование, прикрепление скрипта и запрос выделения, должны выполняться, пока редактор остается отзывчивым
• Контексты режима игры и редактирования должны быть честными — инструменты должны громко сообщать об ошибке, когда операция небезопасна во время игры

Этот пост — инженерная история: как мы создали MCP-сервер реального времени, который работает рядом с Godot, а не притворяется, что проект — это статический репозиторий.

Проблема “только файлового” MCP для движков

Наивный подход заманчив:

1. Направить MCP-сервер на папку проекта
2. Предоставить read_file / write_file / list_dir
3. Позволить модели придумывать GDScript и надеяться, что редактор перезагрузится нормально

Это работает для сайтов документации. Но терпит неудачу для работы с движком, потому что:

• Владение сценой живет в памяти — несохраненные изменения .tscn, открытые сцены и выделение в редакторе невидимы на диске
• Конвейеры импорта имеют состояние — запись PNG не то же самое, что “ресурс готов с правильными настройками импорта”
• Сигналы и пути узлов — это графовые данные — строковые правки молча разрывают соединения
• Задержка накапливается — каждое подтверждение “появился ли узел?” превращается в очередное полное сканирование файловой системы

Нам нужна была MCP-поверхность, отражающая то, что человек уже видит в панели Godot: иерархию, свойства в стиле инспектора и дескрипторы ресурсов — а не только строки путей.

Обзор архитектуры

На высоком уровне Godot MCP состоит из трех взаимодействующих слоев:

MCP-клиент (Cursor / Claude / …)
        │  JSON-RPC через stdio или локальный транспорт
        ▼
MCP-сервер (процесс-мост VberAI Godot)
        │  очередь команд + конверты результатов
        ▼
Плагин редактора Godot (GDExtension / editor plugin)
        │  отложенные вызовы на главном потоке
        ▼
Дерево сцены редактора / ResourceDB / Редактор скриптов

Слой 1 — MCP-инструменты

Инструменты намеренно малы и имеют форму глаголов:

• godot_get_scene_tree — снимок редактируемой сцены с типами узлов и путями
• godot_create_node / godot_set_property
• godot_attach_script / godot_run_script_snippet (с защитой)
• godot_list_resources / godot_get_selection

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

Слой 2 — мост реального времени

Мост — это то, где на самом деле находится “реальное время”:

• Двунаправленный канал между процессом MCP и плагином редактора (локальный сокет или именованный канал в разработке; в готовых сборках может быть обернут за настольным помощником VberAI)
• Очередь команд, которая сериализует изменения, чтобы два перекрывающихся вызова инструментов не могли гоняться за деревом сцены
• Идентификаторы запросов + подтверждения, чтобы MCP-клиент мог ждать “применено” без опроса файловой системы
• Heartbeat / живость редактора, чтобы клиенты знали, когда Godot завершился во время сессии

Слой 3 — безопасность главного потока в Godot

UI и API сцен Godot не являются свободно-поточными. Плагин никогда не изменяет узлы в потоке ввода-вывода MCP. Вместо этого:

1. MCP-команда поступает в поток моста
2. Полезная нагрузка помещается в очередь
3. Отложенный обратный вызов редактора выполняется на главном потоке (call_deferred / хук кадра простоя)
4. Конверт результата возвращает успех, структурированную ошибку или “повторите после завершения режима игры”

Этот шаблон скучен по замыслу. Скука — это то, что не дает “реальному времени” превратиться в “случайные зависания редактора”.

Как сделать это ощутимым как реальное время (не обманывая насчет задержки)

“Реальное время” здесь не означает магическую нулевую задержку. Это означает, что цикл обратной связи соответствует тому, как люди работают в редакторе.

Снимок vs поток

Ранние прототипы возвращали все дерево сцены при каждом вызове. Это рухнуло на больших open-world настройках. Мы переключились на:

• Поверхностные снимки по умолчанию (корень + один уровень, или сфокусированные на выделении)
• Чтение с областью пути, когда модель уже знает поддерево
• Опциональные токены изменений, чтобы последующие вызовы могли спросить “что изменилось с X?” вместо повторной сериализации всего

Результаты, удобные для сравнения

Результаты инструментов включают:

• Канонические строки NodePath
• Имена типов (CharacterBody2D, Control, …)
• Ключи свойств, которые чисто отображаются на поля инспектора
• Явные предупреждения, когда запись была применена, но сцена все еще грязная / несохраненная

Модели итеративно работают быстрее, когда результаты выглядят как состояние UI, а не как пост в блоге из свободного текста.

Ограниченное поведение в режиме игры

Режим игры — это источник половины тикетов “AI сломал мой проект”. Наши правила:

Режим	Разрешено	Заблокировано или ограничено
Редактирование	Изменения сцены, запросы ресурсов	Разрушительные удаления проекта без подтверждения
Игра	В основном чтение / запрос узлов времени выполнения	Структурные правки редактируемой сцены
Переход	Ожидание / подсказки повтора	Тихие бездействия

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

Сложные проблемы, с которыми мы столкнулись (и сохранили)

1. Редактор — это не база данных

Порядок узлов, отношения владельца и упакованные сцены взаимодействуют так, что выглядят просто в GIF и запутанно в .tscn. Мы опирались на собственные API Godot (Node, EditorInterface, загрузчики ресурсов), а не изобретали параллельную модель сцены, которая бы расходилась.

2. Скрипты vs сцены как два источника истины

Прикрепление скрипта — это не то же самое, что обеспечение компиляции скрипта и разрешения имени класса. Сервер сообщает результаты компиляции/прикрепления отдельно. Это остановило класс ошибок “инструмент сказал успех, инспектор ничего не показывает”.

3. Многооконные / многопроектные сессии

Разработчики открывают более одного экземпляра Godot. Мост привязывается к явному ID сессии редактора, чтобы вызовы инструментов не попадали в неправильный проект после выходных сна + повторного открытия.

4. Границы безопасности

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

Как это вписывается рядом с AI Studio и остальной частью VberAI

Godot MCP — это оператор движка. Дополнительные части:

• VberAI AI Studio (AI Studio) — структура от дизайна к движку для Figma/PSD → иерархии Control; затем MCP подключает кнопки и переименовывает узлы после импорта
• Unity MCP / Cocos MCP — та же идея MCP, другие хосты редактора и правила безопасности
• AI Super Matting — очищает альфа-канал, прежде чем текстуры станут ресурсами движка, которые MCP позже назначает

Общая теза: AI должен касаться живой производственной поверхности (редактор, ассеты, сцены), а не только репозитория как текста.

Практические советы, если вы создаете свой собственный MCP для движка

1. Ставьте изменения в очередь на главном потоке движка — никогда не притворяйтесь, что игровые движки — это серверы без общего состояния
2. Предпочитайте маленькие инструменты со схемами — валидация лучше, чем поэзия промптов
3. Возвращайте NodePath и типы, а не прозу — моделям нужны управляемые дескрипторы
4. Кодируйте режимы игры/редактирования в каждом ответе — неоднозначность здесь разрушает доверие
5. Измеряйте круговой путь до “видно в панели” — а не только время JSON-кодирования

Если вы оптимизируете только MCP-процесс и игнорируете мост редактора, вы получите быстрый цикл галлюцинаций.

Заключение

Создание MCP-сервера реального времени для Godot означало отношение к редактору как к живому соавтору: мост с очередью и безопасностью главного потока; инструменты, сформированные как действия редактора; и честность в отношении ограничений режима игры. Только файловый MCP проще — и неполон для работы с нативными сценами.

Хотите готовый путь вместо прототипа на выходные? Начните с VberAI Godot MCP, подключите ваш любимый MCP-клиент и попробуйте тривиальный первый вызов инструмента: вывести текущее дерево сцены, затем создать один узел под выделением. Этот единственный цикл — запрос → изменение → увидеть в панели — и есть продукт. Все остальное — инженерия надежности вокруг него.