GodotLens: AI-ориентированный анализ кода для GDScript

MCP-сервер, предоставляющий 15 инструментов семантического анализа для GDScript, работающий на базе встроенного сервера языка Godot.

Создано для AI-агентов

AI-агенты для написания кода работают с текстовыми файлами, но им не хватает семантического понимания GDScript. Когда агент использует grep для поиска использования функции, он не может отличить вызов функции от комментария, содержащего то же имя, объявление сигнала от его вызова или переопределенный метод от несвязанной функции.

GodotLens устраняет этот разрыв, предоставляя доступ к встроенному серверу языка Godot через протокол Model Context Protocol (MCP), обеспечивая AI-агентам точную, на уровне компилятора, интеллектуальную работу с кодом GDScript — переход к определению, поиск ссылок, диагностика, переименование и многое другое.

Пример: Поиск всех мест использования _on_player_hit:

Подход	Результат
`grep "_on_player_hit"`	12 совпадений, включая комментарии, строки и функции с похожими именами
`gdscript_references`	Ровно 4 места вызова, где используется `_on_player_hit`

Предварительные требования

Редактор Godot 4.x должен быть запущен с открытым проектом — LSP-сервер Godot запускается автоматически при открытии проекта в редакторе.
Python 3.10+ (для установки через pip) или Node.js 16+ (для npx).

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

Вариант А: npx (рекомендуется для MCP-клиентов)

Добавьте в свою конфигурацию MCP (например, .mcp.json для Claude Code):

{
  "mcpServers": {
    "godotlens": {
      "command": "npx",
      "args": ["-y", "godotlens-mcp"]
    }
  }
}

Пакет npm включает в себя полный сервер (~20 КБ Python). Никаких внешних зависимостей Python.

Вариант Б: pip

pip install godotlens-mcp

{
  "mcpServers": {
    "godotlens": {
      "command": "godotlens-mcp"
    }
  }
}

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

Переменная окружения	По умолчанию	Описание
`GODOT_LSP_HOST`	`127.0.0.1`	Хост LSP-сервера Godot
`GODOT_LSP_PORT`	`6005`	Порт LSP-сервера Godot

Инструменты

Состояние (Health)

Инструмент	Описание
`gdscript_status`	Проверка соединения с LSP Godot. Используйте для проверки того, что редактор запущен, перед использованием других инструментов.

Навигация (6 инструментов)

Инструмент	Описание
`gdscript_definition`	Переход к месту определения символа. Возвращает путь к файлу и номер строки.
`gdscript_declaration`	Переход к месту объявления символа.
`gdscript_references`	Поиск всех ссылок на символ в проекте. Важно для анализа влияния перед рефакторингом.
`gdscript_hover`	Получение информации о типе и документации для символа. Используйте для понимания типов и возвращаемых значений.
`gdscript_symbols`	Список всех символов (классов, функций, переменных, сигналов) в файле. Используйте для изучения структуры файла.
`gdscript_signature_help`	Получение сигнатуры функции и информации о параметрах в месте вызова.

Рефакторинг

Инструмент	Описание
`gdscript_rename`	Переименование символа во всех файлах. Рабочий процесс: ссылки для предварительного просмотра влияния, переименование, затем синхронизация.

Синхронизация (3 инструмента)

Инструмент	Описание
`gdscript_sync_file`	Синхронизация измененного файла с LSP и получение обновленной диагностики. Вызывайте после редактирования файлов .gd.
`gdscript_sync_files`	Пакетная синхронизация нескольких измененных файлов. Эффективнее, чем синхронизация по отдельности.
`gdscript_delete_file`	Уведомление LSP об удалении файла. Очищает устаревшую диагностику.

Пакетные операции (3 инструмента)

Инструмент	Описание
`gdscript_symbols_batch`	Получение символов из нескольких файлов за один вызов.
`gdscript_definitions_batch`	Получение определений для нескольких позиций за один вызов.
`gdscript_references_batch`	Поиск ссылок для нескольких символов за один вызов. Используйте для массового анализа влияния.

Диагностика

Инструмент	Описание
`gdscript_diagnostics`	Получение ошибок и предупреждений компилятора. Рабочий процесс: редактирование, синхронизация, затем диагностика для проверки.

Архитектура

┌──────────────┐         ┌────────────────────┐         ┌───────────────────┐
│   AI Agent   │  stdio  │  GodotLens (MCP)   │   TCP   │  Godot Editor     │
│ (Claude, etc)├────────►│  JSON-RPC 2.0      ├────────►│  Built-in LSP     │
│              │◄────────┤  Python 3.10+      │◄────────┤  Port 6005        │
└──────────────┘         └────────────────────┘         └───────────────────┘

GodotLens выступает в качестве моста между AI-агентом и встроенным сервером языка Godot. AI-агент взаимодействует с GodotLens через MCP (JSON-RPC поверх stdio). GodotLens преобразует вызовы инструментов MCP в запросы LSP и отправляет их в редактор Godot по TCP. Ответы сжимаются для эффективного использования AI.

Нулевые зависимости — сервер использует только стандартную библиотеку Python. Протоколы MCP и LSP реализованы напрямую, что делает сервер легким и автономным.

Важно: Синхронизация файлов

LSP Godot не обнаруживает автоматически изменения файлов, сделанные вне редактора. Когда AI-агент изменяет файл .gd, он должен вызвать gdscript_sync_file или gdscript_sync_files, чтобы LSP повторно проанализировал измененный код. Без этого результаты диагностики и навигации могут быть устаревшими.

Рекомендуемый рабочий процесс:

Используйте инструменты GodotLens для анализа кода.
Запишите изменения в файлы.
Вызовите gdscript_sync_file для обновления состояния LSP.
Используйте инструменты GodotLens для проверки изменений.

Система координат

Все параметры строк и символов индексируются с 0, в соответствии со спецификацией LSP:

Строка 0, Символ 0 = первый символ файла

Лицензия

Лицензия MIT — подробности см. в LICENSE.

godotlens-mcp