Erodenn/godot-mcp-runtime

Регистрирует новый autoload в проекте. autoloadPath принимает "res://..." или путь относительно проекта (префикс добавляется автоматически). singleton по умолчанию true (доступен глобально по имени). Процесс Godot не требуется. Предупреждение: autoload'ы инициализируются в headless-режиме: сломанный скрипт приведёт к сбою каждой последующей headless-операции; проверяйте перед добавлением. Возвращает подтверждение в виде обычного текста с зарегистрированным именем, путём и флагом singleton. Возвращает ошибку, если autoload с таким же именем уже существует; используйте update_autoload для изменения.

Добавляет узел в сцену Godot. Сохраняет автоматически. position, rotation, scale, visible, modulate: параметры верхнего уровня; всё остальное помещается в properties. Значения проверяются на соответствие объявленному типу свойства и вызывают ошибку, а не молча сохраняют нулевое значение этого типа. Свойства с типом Object принимают путь res://, словарь {type: ClassName, ...props}, который создаёт Resource на месте, или null; ключи с суффиксом через слэш, например shader_parameter/<uniform>, идут внутрь этого словаря, а не на узел. Правила приведения значений, правила для элементов Packed*Array/Array[T] и подробности об ошибках: Property Values в docs/tools.md. Возвращает подтверждение в виде обычного текста о новом узле и его типе. Вызывает ошибку и ничего не добавляет, если nodeType не зарегистрированный класс, родитель отсутствует или имя или значение свойства недопустимо. Вызывает ошибку, пока активна сессия выполнения Godot; stop_project или detach_project сбрасывает её.

Внедряет MCP-мост в процесс Godot, который вы запускаете сами, затем ждёт до 20 секунд, пока мост начнёт слушать порт, и до 45 секунд в сумме после этого, чтобы поглотить холодный старт большого проекта; если порт слушает, но не отвечает на ping, ожидание прекращается раньше. Вызывайте ДО запуска Godot: Godot читает автозагрузки только при старте процесса, поэтому поздний вызов возвращает «bridge did not respond». Рекомендуемый паттерн: запускайте Godot параллельно с этим вызовом, чтобы ожидание поглощало запуск. Предпочитайте run_project, если только MCP не должен порождать Godot. Одновременно поддерживается только одна attach-сессия на проект (в режиме attach нет канала env-var, поэтому порт и токен должны быть вшиты в единственный общий скрипт); повторный attach_project для проекта, к которому уже подключена другая сессия, отклоняется с указанием этой сессии. Возвращает статус в виде обычного текста с определённым портом моста. По завершении вызывайте detach_project или stop_project.

Прикрепляет скрипт GDScript или C# к узлу в сцене. Используйте после написания и проверки скрипта через инструмент validate. Для C# требуется сборка Godot .NET с классом, скомпилированным в сборку проекта. Заменяет любой предыдущий скрипт. Сохраняет автоматически. Возвращает: при успехе nodePath и scriptPath. Выдаёт ошибку, если скрипт не удаётся инстанцировать (ошибки парсинга, @abstract или нескомпилированный класс C#), scriptPath не существует или nodePath не найден. Выдаёт ошибку, пока активна сессия выполнения Godot; stop_project (или detach_project) сбрасывает её.

Используйте этот инструмент вместо цепочки вызовов add_node / load_sprite / save_scene, когда нужно внести несколько изменений в одни и те же или связанные сцены: он работает в одном процессе Godot (экономит ~3 секунды на запуск при каждом вызове), использует общий кэш сцен в памяти и сохраняет один раз в конце. Каждый элемент выбирает свою подоперацию (add_node, load_sprite, set_node_properties, save) и передаёт свои параметры; элементы add_node принимают те же вынесенные на верхний уровень пространственные параметры (position, rotation, scale, visible, modulate), что и отдельный инструмент; элементы set_node_properties принимают те же параметры обновления (nodePath, property, value) и те же параметры операции scenePath и abortOnError, что и отдельный инструмент; abortOnError останавливает выполнение при первой ошибке (по умолчанию false, выполнение продолжается). Возвращает: results[] в порядке входных элементов, каждый содержит operation и scenePath, а также success или error. Выдаёт ошибку, пока на этом проекте активна сессия Godot runtime; stop_project (или detach_project) завершает её.

Получает метаданные проекта (имя, путь, версию Godot, сводку по структуре) плюс постоянно присутствующий блок runtime, который сообщает, активна ли сессия runtime, отвечает ли её bridge и жив ли её процесс. Опускает projectPath, если нужны только версия Godot и статус runtime. Используется как первый вызов перед управлением запущенным проектом. Никогда не возвращает ошибку при самой проверке runtime. Возвращает: { name?, path?, structure?, godotVersion, runtime }. Вызывает ошибку, если projectPath задан, но отсутствует project.godot.

Соединяет сигнал на исходном узле с методом на целевом узле, сохраняя соединение в .tscn. Сначала используйте get_node_signals, чтобы подтвердить имена: соединение одной и той же пары дважды создаёт дублирующее соединение. Сохраняет автоматически. Возвращает подтверждение в виде простого текста с указанием источника, сигнала, цели и метода. Возвращает ошибку, если сигнал или метод не существует. Возвращает ошибку, пока активна сессия выполнения Godot для этого проекта; stop_project (или detach_project) очищает её.

Создаёт новый файл сцены Godot с одним корневым узлом. Записывает новый .tscn по пути scenePath. Используйте для создания новой сцены с нуля; для добавления узлов в существующую сцену используйте add_node. rootNodeType по умолчанию равен Node2D: передайте "Node3D" для 3D-сцен или "Control" для UI. Сохраняет автоматически. Перезаписывает файл без предупреждения, если он уже существует. Возвращает: success и scenePath, по которому был записан файл. Выдаёт ошибку, пока на этом проекте активна сессия Godot runtime; stop_project (или detach_project) очищает её.

Удаляет один или несколько узлов (и их потомков) из файла сцены. Всегда массив: передайте массив nodePaths из одного элемента для разового удаления. Сохраняет один раз в конце. Нельзя удалить корень сцены: такая запись возвращает ошибку, а остальные всё равно обрабатываются. Возвращает: массив результатов с одной записью для каждого nodePath в порядке ввода (сообщение об успехе или ошибке). Выдаёт ошибку, пока на этом проекте активна сессия Godot runtime; stop_project (или detach_project) сбрасывает её.

Очищает состояние рантайма в режиме присоединения и удаляет внедрённую автозагрузку McpBridge. НЕ останавливает вручную запущенный процесс Godot: он продолжает работать. Используйте после attach_project, когда закончите управлять игрой через MCP. Для порождённых сессий (run_project) вместо этого используйте stop_project. Сейчас это в основном необязательно: когда мост отключается (вы закрыли Godot), следующий вызов инструмента рантайма один раз проверяет и сам завершает присоединённую сессию, удаляя автозагрузку. Последующий вызов всё равно идемпотентен и завершается успешно, а сообщение формулируется так, чтобы отличать «присоединённая сессия существовала и уже завершилась» от «этот сервер никогда не присоединялся к проекту». Возвращает: сообщение, подтверждающее отсоединение, и externalProcessPreserved (здесь всегда true: в этом суть detach в отличие от stop_project). Выдаёт ошибку только тогда, когда активна порождённая сессия; для таких случаев используйте stop_project.

Удаляет существующее соединение сигнала между двумя узлами и сохраняет изменение в .tscn. Сначала вызовите get_node_signals, чтобы убедиться, что соединение существует; для восстановления потребуется повторно подключить его через connect_signal. Автоматически сохраняет. Возвращает текстовое подтверждение, в котором указаны отсоединённый сигнал и цель. Выдаёт ошибку, если соединение не существует. Выдаёт ошибку, пока на этом проекте активна сессия выполнения Godot; stop_project (или detach_project) очищает её.

Дублирует узел и его потомков в сцене Godot, не пересобирая его по узлам через add_node. newName по умолчанию равен исходному имени + "2"; targetParentPath по умолчанию указывает на исходного родителя. Сохраняет автоматически. Возвращает: success с originalPath и newPath, где теперь находится дубликат. Возвращает ошибку, если nodePath не существует или targetParentPath не может принимать дочерние узлы. Возвращает ошибку, пока на этом проекте активна сессия выполнения Godot; stop_project (или detach_project) завершает её.

Экспортирует сцену узлов MeshInstance3D как файл .res библиотеки MeshLibrary для использования в GridMap. Только для сеточных 3D-палитр тайлов, не для 2D-сцен. Исходная сцена должна содержать дочерние узлы MeshInstance3D. Передайте meshItemNames для подмножества или не указывайте для всех. Сохраняет в outputPath, молча перезаписывая. Возвращает подтверждение в виде обычного текста с количеством экспортированных элементов. Выдаёт ошибку, если сцена не содержит допустимых мешей. Выдаёт ошибку, пока на этом проекте активна сессия Godot runtime; stop_project (или detach_project) устраняет её.

Получает захваченные stdout/stderr из запущенного проекта Godot. Используйте, когда инструменты времени выполнения неожиданно сбоят: ошибки скриптов, отсутствующие узлы и бэктрейсы краша всплывают именно здесь. Продолжает работать после завершения или падения процесса: сессия очищается при выходе, но захваченные логи сохраняются до stop_project. Требует run_project (не attach_project; в режиме attach вывод не захватывается). Возвращает: output/errors (последние limit строк каждого, по умолчанию 200), running (false после завершения, null в режиме attach), exitCode после завершения, attached:true с пустыми массивами в режиме attach.

Читает текущие значения свойств одного или нескольких узлов из файла сцены в одном процессе Godot. Всегда массив: передавайте массив из одного элемента для однократного чтения. Для каждого узла changedOnly:true отфильтровывает свойства, совпадающие со значениями по умолчанию класса (полезно для компактных diff). Возвращает: { results: [{ nodePath, nodeType, properties?, error? }] }; при неудачном чтении включается error, а properties опускается.

Перечисляет все сигналы, определённые на узле, и их текущие соединения. Используйте перед connect_signal/disconnect_signal для проверки имён сигналов и методов. Поле connections[].target уже задано относительно корня сцены в форме "root/...", которую connect_signal/disconnect_signal принимают как targetNodePath (самоподключение указывается как "root") - передавайте его напрямую без преобразования. Возвращает: nodeType и signals[], каждый с именем и текущими соединениями (signal/target/method). Возвращает ошибку, если узел не найден.

Возвращает рекурсивное дерево файлов проекта Godot. Используйте для изучения структуры проекта, когда пути неизвестны. Передайте расширения для фильтрации (например, ["gd","tscn"]); maxDepth ограничивает глубину рекурсии (-1 без ограничений). Пропускает скрытые элементы (с точкой в начале) и директорию .mcp. Возвращает: { name, type, path, extension?, children? } (вложенное дерево).

Парсит project.godot в структурированный JSON. Используйте для просмотра настроек дисплея, ввода, рендеринга и т.д. без запуска Godot. Передайте section, чтобы оставить только одну INI-секцию (например, "display", "application"). Возвращает: { settings: { [section]: { [key]: value } } } или { settings: { [key]: value } }, если указана section. Сложные типы Godot (в том числе многострочные массивы/словари, например полная карта действий из секции "[input]") возвращаются как полная исходная строка, а не только первая строка; ключи, не входящие ни в одну секцию, попадают в global.

Парсит файл .tscn для поиска ссылок на ext_resource (скрипты, текстуры, под-сцены). Используйте, чтобы проверить, от чего зависит сцена перед рефакторингом или перемещением файлов. Возвращает: запрошенный путь к сцене и dependencies[] из ссылок ext_resource (path, type, optional uid). Ошибка, если файл сцены не существует.

Получает иерархию сцены как вложенное дерево { name, type, path, script, children }. Используйте maxDepth:1 для плоского списка только прямых потомков; значение -1 по умолчанию возвращает полное дерево. parentPath ограничивает результат поддеревом. Возвращает вложенное дерево в формате JSON. Ошибка, если сцена не существует или parentPath не найден.

Обходит дерево сцены во время выполнения и возвращает все узлы Control с позициями, размерами, типами и текстовым содержимым. Всегда вызывайте это перед действиями simulate_input click_element, чтобы узнать допустимые имена и пути элементов. Требует активной сессии выполнения (run_project или attach_project). visibleOnly по умолчанию true; передайте false, чтобы включить скрытые элементы Control. filter сужает поиск по классу. Возвращает: elements[] с path/type/rect/visible и опционально text/disabled/tooltip.

Открывает графический интерфейс редактора Godot для проекта пользователя-человека. Используйте только тогда, когда пользователь явно просит «открыть редактор»; для любой работы, выполняемой агентом, используйте инструменты без графического интерфейса для сцен и узлов (add_node, set_node_properties и т. д.) вместо этого: редактор нельзя контролировать программно. Возвращает подтверждение в виде обычного текста после запуска процесса редактора. Выдает ошибку, если в projectPath отсутствует project.godot.

Перечисляет все зарегистрированные автозагрузки в проекте с путями и статусом singleton. Используйте в первую очередь при диагностике headless-сбоев - сломанные автозагрузки роняют все headless-операции, поэтому этот инструмент показывает, что загружено. Не требует запущенного процесса Godot (читает project.godot напрямую). Возвращает: [{ name, path, singleton }].

Находит проекты Godot в каталоге по файлам project.godot. Используется для обнаружения доступных проектов, если пользователь не указал конкретный; для проверки известного проекта используйте check_project. recursive:true спускается в подкаталоги (пропуская скрытые); по умолчанию false проверяет только сам каталог и его непосредственные подкаталоги. Возвращает: [{ path, name }], пустой массив при отсутствии совпадений.

Устанавливает текстуру на существующий узел Sprite2D, Sprite3D или TextureRect. Для новых узлов вместо этого передавайте текстуру через свойства add_node. Сохраняет автоматически. texturePath должен указывать на существующий файл внутри projectPath. Возвращает текстовое подтверждение с именем загруженной текстуры. Выдаёт ошибку, если узел не относится к одному из этих трёх классов или файл текстуры не существует. Выдаёт ошибку, пока для этого проекта активна сессия выполнения Godot; stop_project (или detach_project) завершает её.

Захватывает окно функционального профайлера Godot - данные вкладки Profiler редактора. Требует run_project с profiling: true. Блокирует выполнение на seconds секунд (по умолчанию 5). Время указано затраченное, а не процессорное; вложенные строки перекрываются - никогда не суммируйте totalMs. Возвращает: rows (function, file, line, calls, selfMs/totalMs, средние значения за кадр, percentOfFrame, peak), бюджет кадра, servers, worstFrame, а также frames/frameGaps/limitReached для оценки качества захвата. Возвращает ошибку, если профилирование было отключено при запуске или если захват уже открыт.

Отменяет регистрацию автозагрузки в проекте по имени. Используйте для восстановления после сломанной автозагрузки, которая вызывает сбой headless-операций. Процесс Godot не требуется. Возвращает подтверждение в виде обычного текста при успехе. Ошибка, если автозагрузки с таким именем не существует.

Запускает проект Godot как дочерний процесс с захватом stdout/stderr. Обязателен перед take_screenshot, simulate_input, get_ui_elements, run_script или get_debug_output. Устанавливает profiling: true при запуске, чтобы включить инструменты профилирования. Использует attach_project для проекта, который вы запустили самостоятельно. Проверяет готовность моста MCP перед возвратом успешного результата. Возвращает статус с назначенным портом моста. Вызывает stop_project по завершении. Возвращает ошибку, если projectPath не является проектом Godot или другая сессия уже активна.

Выполняет пользовательский GDScript в живом запущенном проекте с полным доступом к дереву сцены. Требует активную сессию выполнения. Скрипт должен расширять RefCounted и определять функцию execute(scene_tree: SceneTree) -> Variant. Возвращаемые значения сериализуются в JSON (примитивы, Vector2/3, Color, Dictionary, Array и строки путей Node). Используйте print() для отладочного вывода: он появляется в get_debug_output, а не в результате. В порожденном режиме ошибки выполнения stderr становятся ошибками (когда скрипт возвращает null) или всплывают как предупреждения. Возвращает: { success, result, warnings?, tip? }, где result - это сериализованное в JSON возвращаемое значение execute().

Перепаковывает и сохраняет сцену, опционально в другой путь (save-as). Большинство мутаций (add_node, set_node_properties, delete_nodes и т.д.) сохраняются автоматически - используйте это только для save-as через newPath или для повторной канонизации вручную отредактированного .tscn. Перезаписывает молча. Возвращает подтверждение в виде обычного текста с указанием пути сохранения. Возвращает ошибку, если файл сцены не существует. Возвращает ошибку, пока активна сессия Godot runtime для этого проекта; stop_project (или detach_project) очищает её.

Ищет подстроку в файлах проекта. Используется для поиска ссылок, вызывающих функций или сигнатур в кодовой базе. По умолчанию fileTypes: ["gd","tscn","cs","gdshader"]; caseSensitive по умолчанию false; maxResults по умолчанию 100. Пропускает скрытые элементы и каталог .mcp. Возвращает: matches[] (файл относительно проекта, lineNumber с индексацией от 1, текст строки) и truncated:true, если достигнут maxResults: подумайте об увеличении.

Устанавливает одно или несколько свойств узла в сцене в одном процессе Godot. Всегда массив: передавайте массив updates с одним элементом для разовых правок. Значения проверяются на соответствие объявленному типу свойства и вызывают ошибку, а не молча сохраняют нулевое значение этого типа. Свойства объектного типа (например, CollisionShape2D.shape) принимают путь res://, словарь {type: ClassName, ...props}, который создаёт Resource на месте, или null для очистки; ключи с суффиксом через слэш, такие как shader_parameter/<uniform>, помещаются внутрь этого словаря, а не на узел. Приведение значений, правила для элементов Packed*Array/Array[T] и сведения об ошибках: Property Values в docs/tools.md. Сохраняет один раз в конце. Возвращает: results[] с одной записью на каждое обновление в порядке ввода (успех или ошибка). Вызывает ошибку, пока активна сессия Godot runtime; stop_project или detach_project сбрасывает её.

Симулирует последовательный ввод в запущенном проекте и сообщает, что сделало каждое действие. Параметр type задаёт действие: key, mouse_button, mouse_motion, click_element, action, text, wait. Для key/mouse_button/action опустите pressed, чтобы выполнить тап (нажатие+отпускание); установите его в hold или release. click_element разрешает элемент по пути/имени узла (см. get_ui_elements), а не по видимому тексту. Возвращает: results[] для каждого действия с ok, timing, signals fired, затронутым Control, изменениями UI changes (appeared/disappeared/changed), сэмплами watch и ошибками errors из обработчиков ввода (только для порождённых сессий). Недопустимые пакеты ничего не вводят; ошибка выполнения останавливает пакет и пропускает остальные действия.

Запускает захват профилировщика и сразу возвращает управление, чтобы simulate_input, run_script и screenshots могли управлять игрой во время записи. Требует run_project с profiling: true. Останавливается сам через seconds (по умолчанию 30, максимум 60); вызывайте stop_profiler для получения результатов. Возвращает: active, firstFrame, captureLimit, maxSeconds. Используйте profile_project для работы без присмотра. Возвращает ошибку, если захват уже запущен или профилирование не было включено при запуске.

Останавливает захват, запущенный start_profiler, и ранжирует записанные функции; захват, уже достигший временного лимита, считывается как есть, и его можно перечитать с другой сортировкой. Времена указаны как прошедшие, а не процессорные; инклюзивные строки перекрываются - не суммируйте totalMs. Возвращает: ту же полезную нагрузку, что и profile_project - rows (file, line, function, calls, selfMs/totalMs, средние значения на кадр, percentOfFrame, пиковый кадр), frame budget, servers, worstFrame, frames, frameGaps, limitReached. Возвращает ошибку, если захват не был запущен.

Останавливает запущенный проект Godot и очищает состояние моста. Вызывайте, когда закончите runtime-тестирование, даже после крэша и даже если вы сами закрыли окно Godot: инструмент освобождает слот процесса и снимает флаг, блокирующий инструменты редактирования сцены. Процесс, завершившийся сам по себе, уже удалил автозагрузку моста к этому моменту, и вызов всё равно срабатывает: возвращает alreadyExited:true вместе с кодом выхода и логами, собранными до завершения, а завершённый снимок профилировщика остаётся читаемым. Прикреплённые сессии отсоединяются, не убивая внешний процесс. Возвращает: message, mode, externalProcessPreserved, alreadyExited, exitCode (для случая уже завершённого процесса) и сокращённые finalOutput/finalErrors (не более 200); полный лог доступен через get_debug_output. Ошибка возникает только тогда, когда нет ни сессии, ни завершённого процесса, о котором можно сообщить.

Захватывает PNG работающего окна просмотра. responseMode: preview (по умолчанию: сохраняет полный PNG, возвращает встроенное изображение предпросмотра, ограниченное до 960x540), full (полное встроенное PNG; для мелкого текста или попиксельного просмотра), path_only (только сохранённый путь, без встроенного изображения). Сохраняется в .mcp/godot-runtime/screenshots/ (остаётся после stop_project). Возвращает: встроенный блок изображения (в режимах full/preview), а также путь и размер сохранённого PNG; previewPath/previewSize в режиме preview; предупреждения о некритических ошибках выполнения. Завершается ошибкой, если нет сессии или истекает время ожидания моста (по умолчанию 10000 мс).

Изменяет путь или флаг singleton у существующего autoload. Передайте один из них или оба: пропущенные поля сохраняют текущее значение. Используйте вместо remove_autoload + add_autoload (одна правка, без промежуточного состояния). Не требует процесса Godot. Возвращает подтверждение в виде обычного текста при успехе. Выдаёт ошибку, если autoloadName не зарегистрирован.

Проверяет синтаксис GDScript или целостность сцены с помощью headless Godot. Необходимо использовать перед attach_script или run_script, чтобы выявлять ошибки парсинга на раннем этапе. Передайте ровно один из scriptPath, source или scenePath, либо массив targets, проверяемый в одном процессе Godot. Возвращает { valid, errors } для одного target или { results: [{ target, valid, errors }] } для пакета. Элемент errors имеет вид { line?, message } для ошибки парсинга или { check, problem?, message } для результата проверки checks[]. checks требует scenePath и создаёт экземпляр сцены, запуская _init() каждого прикреплённого скрипта. Любая ошибка парсинга приводит к valid:false.