godot-mcp

MCP-сервер, который позволяет ИИ-агенту работать с проектом Godot 4.x так же, как это делает разработчик: читать и редактировать сцены, писать скрипты, собирать, тестировать, запускать, смотреть на результат и отлаживать то, что пошло не так.

Две вещи отличают его от угадывания форматов файлов или слепого вызова команд оболочки:

• Он спрашивает сам Godot. Файлы сцен и ресурсов разбираются и повторно сериализуются структурно (доказано побайтовой идентичностью при обратном преобразовании на реальном корпусе проектов), но всё, что зависит от поведения самого движка — интроспекция C#, компиляция шейдеров, привязки ввода, состояние редактора — отвечается фактическим запуском Godot в headless-режиме или запросом к работающему редактору, а не переписыванием семантики Godot по памяти.

• Он громко сообщает об ошибках. Каждый измеримый режим отказа в этом проекте — отсутствующий дисплей, несобранная C#-сборка, закрытый редактор, не-.NET бинарник — это именованная, отдельная ошибка с решением, а не молчаливый пустой результат. См. docs/capability-matrix.md о измерениях, на которых это построено; некоторые из них существуют именно потому, что очевидный сигнал (код выхода, ненулевое возвращаемое значение) оказался лживым.

50 инструментов, организованных в четыре уровня по тому, что им нужно для работы. Полный справочник — в docs/tools.md, а что делать, когда инструмент отказывается работать — в docs/troubleshooting.md.

Требования

• Node.js >= 20

• Бинарник Godot 4.7+ (матрица возможностей измерялась на 4.7; ожидается, что другие версии 4.x ведут себя аналогично, но это не проверено)

• Для любого C#-инструмента (build_csharp, run_tests, csharp_script_info, validate_node_property и путей к C#-скриптам через validate_script): .NET/mono-сборка Godot — обычный дистрибутив только с GDScript не может загружать или интроспектировать .cs-скрипты, и каждый C#-инструмент обнаруживает это заранее и отказывается с NOT_MONO_BINARY, а не падает на полпути. Вывод --version mono-сборки содержит .mono., и она поставляется с соседним каталогом GodotSharp/.

• Для C#-инструментов конкретно нужен SDK dotnet в PATH (build_csharp и run_tests вызывают его напрямую; csharp_script_info и validate_node_property требуют, чтобы Debug-сборка уже существовала, а она получается из build_csharp или build_godot_artifacts).

Related MCP server: godot-mcp-pilot

Установка и сборка

git clone <this-repo> godot-mcp
cd godot-mcp
npm install
npm run build

Это создаёт dist/server.js — точку входа, которую запускает MCP-клиент.

Настройка MCP-клиента

Укажите вашему клиенту на dist/server.js через node и дайте ему способ найти бинарник Godot. Простейшая настройка задаёт GODOT_PATH явно:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/dist/server.js"],
      "env": {
        "GODOT_PATH": "/path/to/Godot_v4.7-stable_mono_linux.x86_64"
      }
    }
  }
}

Как сервер находит бинарник Godot

По порядку, побеждает первый найденный:

1. Явный аргумент binary, переданный в вызов инструмента.

2. Переменная окружения GODOT_PATH.

3. Бинарник, включённый в собственный каталог vendor/ проекта (поиск до 3 уровней вглубь, предпочтение отдаётся файлу, имя которого содержит mono) — для проектов, поставляющих собственную сборку Godot.

4. godot, godot4 или godot-mono в PATH.

Как сервер находит проект

По порядку:

1. Явный аргумент project, переданный в вызов инструмента.

2. Переменная окружения GODOT_PROJECT.

3. Подъём от рабочего каталога процесса сервера в поисках project.godot.

Если ни один из этих вариантов не приводит к каталогу, содержащему project.godot, инструменты, которым нужен проект, завершаются с ошибкой PROJECT_NOT_FOUND.

GODOT_MCP_DOCS_CACHE

godot_class_doc и search_classes строят индекс справочника классов, спрашивая сам бинарник Godot, что достаточно медленно, чтобы стоило кэшировать. По умолчанию индекс записывается в $TMPDIR/godot-mcp-docs-cache/<godot-version>/; задайте GODOT_MCP_DOCS_CACHE, чтобы поместить его в постоянное место. Кэш привязан к версии Godot, поэтому обновление бинарника строит свежий индекс, а не выдаёт устаревший. Если ваш MCP-клиент запускает сервер с рабочим каталогом вне целевого проекта, задайте GODOT_PROJECT явно:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/dist/server.js"],
      "env": {
        "GODOT_PATH": "/path/to/Godot_v4.7-stable_mono_linux.x86_64",
        "GODOT_PROJECT": "/path/to/your/godot-project"
      }
    }
  }
}

Вызывайте godot_status первым в любой новой сессии — он сообщает разрешённый путь к бинарнику, версию, является ли это mono-сборкой, доступность дисплея, корень проекта и собрана ли C#-сборка, чтобы агент (или вы) мог видеть, что реально возможно, прежде чем что-либо пробовать.

Четыре уровня

Каждый инструмент обслуживается самым низким уровнем, который может его обработать. Если инструмент завершается с TIER_UNAVAILABLE или DISPLAY_REQUIRED, причина в этом:

Уровень D — не отдельный транспорт, а ограничение возможностей поверх уровня B. Только capture_screenshot относится к уровню D: в Godot нет пути headless-рендеринга, поэтому скриншоты требуют реального дисплея, виртуального или физического. run_project с windowed: true имеет то же требование.

Инструменты уровня A (большинство операций редактирования сцен, узлов, скриптов и конфигурации проекта) работают вообще без установленного Godot — это чистые файловые операции, протестированные на корпусе реальных файлов .tscn/.tres/project.godot, повторно сериализованных побайтово идентично. Уровню B нужен бинарник Godot и/или dotnet в PATH или разрешённый как указано выше. Уровню C нужен аддон редактора (следующий раздел) — пока он не установлен и не запущен редактор с включённым аддоном, все пять инструментов моста к редактору завершаются с TIER_UNAVAILABLE; это ожидаемо, а не баг, и сообщение об ошибке сообщает, какая из двух различных ситуаций применима (см. docs/troubleshooting.md).

Уровень каждого инструмента — в docs/tools.md.

Установка аддона редактора (уровень C)

Пять инструментов — editor_state, get_selected_node, live_scene_tree, open_scene_in_editor и execute_editor_script — общаются с живым, запущенным редактором Godot через loopback TCP-сокет вместо запуска процесса. Для этого нужен небольшой GDScript-аддон редактора, установленный и включённый в целевом проекте. Инструмента установки нет: запись в каталог addons/ пользователя и изменение его project.godot — это ровно то, чего дисциплина path-jail этого проекта существует, чтобы избегать автоматически. Это одноразовый ручной шаг:

1. Скопируйте addon/godot_mcp/ из этого репозитория в каталог addons/ целевого проекта, чтобы он оказался в <project>/addons/godot_mcp/plugin.cfg.

2. Включите плагин — либо в редакторе (Project Settings > Plugins > godot_mcp > Enable), либо добавив его напрямую в project.godot:

   [editor_plugins]
   
   enabled=PackedStringArray("res://addons/godot_mcp/plugin.cfg")

3. Запустите (или перезапустите) редактор Godot для этого проекта — headless подойдёт (--headless --editor --path <project>), дисплей не требуется. При запуске аддон записывает файл рукопожатия в <project>/.godot/mcp_bridge.json; пять инструментов читают его, чтобы найти порт моста и токен сессии.

Обратите внимание, что состояние выделения в редакторе всегда пусто в headless-редакторе — это ожидаемо (get_selected_node сообщает «ничего не выбрано» как обычный результат, а не ошибку).

Безопасность и границы

• Path jail. Каждый путь записи — сцена, скрипт, ресурс, вывод скриншота — разрешается и должен находиться внутри корня проекта. Путь, выходящий за его пределы, напрямую или через симлинк, отклоняется с PATH_OUTSIDE_PROJECT до того, как что-либо будет затронуто.

• dry_run. Каждый изменяющий инструмент принимает dry_run и возвращает unified diff вместо записи. Используйте его, чтобы просмотреть изменение перед тем, как его применить.

• Нет хранилища резервных копий. Система отмены — это контроль версий. Это осознанное упрощение — в самом сервере нет механизма снимков или резервного копирования. Если ваш проект не под контролем версий, используйте dry_run перед любым изменяющим вызовом или начните использовать контроль версий.

• execute_editor_script — не песочница. Он выполняет произвольный GDScript внутри вашего реально запущенного процесса редактора, с теми же привилегиями, что и сам редактор — он может читать и изменять живое состояние редактора, открытую сцену и всё остальное, доступное из GDScript. Относитесь к нему так же, как к передаче агенту оболочки: подходит для доверенного агента, работающего над вашим собственным проектом, а не для недоверенного ввода.

Тестирование

npm test

Запускает tsc --noEmit для обоих tsconfig.json и tsconfig.test.json, затем полный набор Vitest. Почти каждый тест — на уровне парсера: он пропускает заранее подготовленный вывод Godot/MSBuild через парсеры и проверяет структурированный результат, поэтому набор запускается без установленного Godot и без .NET-тулчейна и остаётся быстрым и переносимым (CI, контейнеры, ноутбук без того и другого).

GODOT_TEST_BINARY

Два блока отличаются: tests/integration/tier-b.test.ts управляет реальным бинарником Godot — создаёт временные проекты на диске и вызывает validate_script, check_shaders, run_project и godot_class_doc против него — потому что парсер можно тестировать на заранее подготовленном тексте бесконечно, так и не доказав, что собственный код инструмента по запуску процессов, построению аргументов и чтению потоков реально работает с настоящим движком. tests/integration/tier-c.test.ts делает то же для инструментов моста к редактору, с существенно иным требованием: он должен запустить реальный редактор Godot как долгоживущий, отсоединённый процесс (редакторы не выходят сами по себе) и надёжно завершить его после, в том числе при сбое теста.

• Не задана (по умолчанию): оба блока сообщают SKIPPED. Ничто другое в npm test не затрагивается.

• Задана путём к бинарнику Godot 4.7+: оба блока реально выполняются end-to-end против него.

GODOT_TEST_BINARY=/path/to/Godot_v4.7-stable_linux.x86_64 npm test

Mono/.NET-сборка не требуется для этого блока. Если вы также работаете над C#-ориентированными инструментами (build_csharp, run_tests), вам отдельно понадобится dotnet в PATH; сейчас для этого нет эквивалентной переменной-переключателя, поскольку ни один из тестов блока GODOT_TEST_BINARY в ней не нуждается.

Документация

• docs/tools.md — каждый инструмент, сгруппированный по областям, с уровнем и ключевыми входными данными.

• docs/troubleshooting.md — измеренные режимы отказа и их исправления.

• docs/capability-matrix.md — эмпирические измерения, на которых основано поведение этого проекта.