GodotLens: Análisis de código centrado en IA para GDScript

Un servidor MCP que proporciona 15 herramientas de análisis semántico para GDScript, impulsado por el servidor de lenguaje integrado de Godot.

Creado para agentes de IA

Los agentes de codificación de IA trabajan con archivos de texto pero carecen de comprensión semántica de GDScript. Cuando un agente utiliza grep para encontrar usos de una función, no puede distinguir una llamada a función de un comentario que contenga el mismo nombre, una declaración de señal de una emisión de señal, o un método sobrescrito de una función no relacionada.

GodotLens cierra esta brecha exponiendo el servidor de lenguaje integrado de Godot a través del Protocolo de Contexto de Modelo (MCP), brindando a los agentes de IA inteligencia de código con precisión de compilador para GDScript: ir a la definición, encontrar referencias, diagnósticos, renombrar y más.

Ejemplo: Encontrar todos los usos de _on_player_hit:

Enfoque	Resultado
`grep "_on_player_hit"`	12 coincidencias incluyendo comentarios, cadenas y funciones con nombres similares
`gdscript_references`	Exactamente 4 sitios de llamada donde se invoca `_on_player_hit`

Requisitos previos

El editor de Godot 4.x debe estar ejecutándose con su proyecto abierto: el servidor LSP de Godot se inicia automáticamente cuando el editor abre un proyecto.
Python 3.10+ (para la instalación mediante pip) o Node.js 16+ (para npx).

Inicio rápido

Opción A: npx (recomendado para clientes MCP)

Añadir a su configuración de MCP (por ejemplo, .mcp.json para Claude Code):

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

El paquete npm incluye el servidor completo (~20 KB de Python). Cero dependencias externas de Python.

Opción B: pip

pip install godotlens-mcp

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

Configuración

Variable de entorno	Predeterminado	Descripción
`GODOT_LSP_HOST`	`127.0.0.1`	Host del servidor LSP de Godot
`GODOT_LSP_PORT`	`6005`	Puerto del servidor LSP de Godot

Herramientas

Salud

Herramienta	Descripción
`gdscript_status`	Comprobar la conexión con el LSP de Godot. Úselo para verificar que el editor esté ejecutándose antes de usar otras herramientas.

Navegación (6 herramientas)

Herramienta	Descripción
`gdscript_definition`	Navegar a donde se define un símbolo. Devuelve la ruta del archivo y el número de línea.
`gdscript_declaration`	Navegar al sitio de declaración de un símbolo.
`gdscript_references`	Encontrar todas las referencias a un símbolo en todo el proyecto. Esencial para el análisis de impacto antes de refactorizar.
`gdscript_hover`	Obtener información de tipo y documentación para un símbolo. Úselo para entender tipos y valores de retorno.
`gdscript_symbols`	Listar todos los símbolos (clases, funciones, variables, señales) en un archivo. Úselo para explorar la estructura del archivo.
`gdscript_signature_help`	Obtener la firma de la función y la información de los parámetros en un sitio de llamada.

Refactorización

Herramienta	Descripción
`gdscript_rename`	Renombrar un símbolo en todos los archivos. Flujo de trabajo: referencias para previsualizar el impacto, renombrar y luego sincronizar.

Sincronización (3 herramientas)

Herramienta	Descripción
`gdscript_sync_file`	Sincronizar un archivo modificado con el LSP y obtener diagnósticos actualizados. Llamar después de editar archivos .gd.
`gdscript_sync_files`	Sincronizar por lotes varios archivos modificados. Más eficiente que sincronizar individualmente.
`gdscript_delete_file`	Notificar al LSP que un archivo fue eliminado. Borra diagnósticos obsoletos.

Operaciones por lotes (3 herramientas)

Herramienta	Descripción
`gdscript_symbols_batch`	Obtener símbolos de varios archivos en una sola llamada.
`gdscript_definitions_batch`	Obtener definiciones para varias posiciones en una sola llamada.
`gdscript_references_batch`	Encontrar referencias para varios símbolos en una sola llamada. Úselo para análisis de impacto masivo.

Diagnósticos

Herramienta	Descripción
`gdscript_diagnostics`	Obtener errores y advertencias del compilador. Flujo de trabajo: editar, sincronizar y luego diagnósticos para verificar.

Arquitectura

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

GodotLens actúa como un puente entre el agente de IA y el servidor de lenguaje integrado de Godot. El agente de IA se comunica con GodotLens a través de MCP (JSON-RPC sobre stdio). GodotLens traduce las llamadas a herramientas de MCP en solicitudes LSP y las envía al editor de Godot a través de TCP. Las respuestas se compactan para un consumo eficiente por parte de la IA.

Cero dependencias: el servidor utiliza solo la biblioteca estándar de Python. Los protocolos MCP y LSP se implementan directamente, manteniendo el servidor ligero y autónomo.

Importante: Sincronización de archivos

El LSP de Godot no detecta automáticamente los cambios de archivo realizados fuera del editor. Cuando el agente de IA modifica un archivo .gd, debe llamar a gdscript_sync_file o gdscript_sync_files para que el LSP vuelva a analizar el código cambiado. Sin esto, los diagnósticos y los resultados de navegación pueden estar obsoletos.

Flujo de trabajo recomendado:

Usar las herramientas de GodotLens para analizar el código
Escribir cambios en los archivos
Llamar a gdscript_sync_file para actualizar el estado del LSP
Usar las herramientas de GodotLens para verificar los cambios

Sistema de coordenadas

Todos los parámetros de línea y carácter están indexados en 0, coincidiendo con la especificación LSP:

Línea 0, Carácter 0 = primer carácter del archivo

Licencia

Licencia MIT: consulte LICENSE para obtener más detalles.

godotlens-mcp