convez.ai
MCP ServerProdutividadeIntermediário
pzalutski-pixel

GodotLens MCP Server

pzalutski-pixel/godotlens-mcp

Análise semântica de GDScript com inteligência de compilador para agentes de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe o Language Server do Godot para análise semântica precisa de código GDScript. Fornece 15 ferramentas de navegação, refatoração e diagnóstico, permitindo que agentes de IA entendam a estrutura real do código além de buscas simples de texto.

Instalação

$npx convez-ai pzalutski-pixel/godotlens-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
10
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
v1.2.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Encontrar referências exatas de funções em projetos Godot sem falsos positivos
  • Refatorar código GDScript com confiança usando renomeação semântica
  • Agentes de IA navegando e entendendo projetos Godot com precisão de compilador

Veredito

GodotLens resolve um problema real: agentes de IA trabalhando com GDScript carecem de compreensão semântica. Integração direta com o LSP do Godot oferece análise confiável e precisa, essencial para refatoração e automação em projetos Godot 4.x.

README

A tradução para o português deste README ainda está na fila.

GodotLens: AI-First Code Analysis for GDScript

GitHub Release npm PyPI License: MIT

An MCP server providing 15 semantic analysis tools for GDScript, powered by Godot's built-in Language Server.

Built for AI Agents

AI coding agents work with text files but lack semantic understanding of GDScript. When an agent uses grep to find usages of a function, it cannot distinguish a function call from a comment containing the same name, a signal declaration from a signal emission, or an overridden method from an unrelated function.

GodotLens bridges this gap by exposing Godot's built-in Language Server through the Model Context Protocol (MCP), giving AI agents compiler-accurate code intelligence for GDScript — go to definition, find references, diagnostics, rename, and more.

Example: Finding all usages of _on_player_hit:

ApproachResult
grep "_on_player_hit"12 matches including comments, strings, and similarly named functions
gdscript_referencesExactly 4 call sites where _on_player_hit is invoked

Prerequisites

  • Godot 4.x editor must be running with your project open — Godot's LSP server starts automatically when the editor opens a project
  • Python 3.10+ (for pip install) or Node.js 16+ (for npx)

Quick Start

Option A: npx (recommended for MCP clients)

Add to your MCP configuration (e.g., .mcp.json for Claude Code):

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

The npm package bundles the full server (~20 KB of Python). Zero external Python dependencies.

Option B: pip

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

Configuration

Environment VariableDefaultDescription
GODOT_LSP_HOST127.0.0.1Godot LSP server host
GODOT_LSP_PORT6005Godot LSP server port

Tools

Health

ToolDescription
gdscript_statusCheck connection to Godot LSP. Use to verify editor is running before other tools.

Navigation (6 tools)

ToolDescription
gdscript_definitionNavigate to where a symbol is defined. Returns file path and line number.
gdscript_declarationNavigate to the declaration site of a symbol.
gdscript_referencesFind all references to a symbol across the project. Essential for impact analysis before refactoring.
gdscript_hoverGet type information and documentation for a symbol. Use to understand types and return values.
gdscript_symbolsList all symbols (classes, functions, variables, signals) in a file. Use to explore file structure.
gdscript_signature_helpGet function signature and parameter info at a call site.

Refactoring

ToolDescription
gdscript_renameRename a symbol across all files. Workflow: references to preview impact, rename, then sync.

Synchronization (3 tools)

ToolDescription
gdscript_sync_fileSync a modified file with the LSP and get updated diagnostics. Call after editing .gd files.
gdscript_sync_filesBatch sync multiple modified files. More efficient than syncing individually.
gdscript_delete_fileNotify LSP a file was deleted. Clears stale diagnostics.

Batch Operations (3 tools)

ToolDescription
gdscript_symbols_batchGet symbols from multiple files in one call.
gdscript_definitions_batchGet definitions for multiple positions in one call.
gdscript_references_batchFind references for multiple symbols in one call. Use for bulk impact analysis.

Diagnostics

ToolDescription
gdscript_diagnosticsGet compiler errors and warnings. Workflow: edit, sync, then diagnostics to verify.

Architecture

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

GodotLens acts as a bridge between the AI agent and Godot's built-in Language Server. The AI agent communicates with GodotLens via MCP (JSON-RPC over stdio). GodotLens translates MCP tool calls into LSP requests and sends them to the Godot editor over TCP. Responses are compacted for efficient AI consumption.

Zero dependencies — the server uses only the Python standard library. The MCP and LSP protocols are implemented directly, keeping the server lightweight and self-contained.

Important: File Synchronization

Godot's LSP does not automatically detect file changes made outside the editor. When the AI agent modifies a .gd file, it should call gdscript_sync_file or gdscript_sync_files so the LSP re-analyzes the changed code. Without this, diagnostics and navigation results may be stale.

Recommended workflow:

  1. Use GodotLens tools to analyze code
  2. Write changes to files
  3. Call gdscript_sync_file to refresh LSP state
  4. Use GodotLens tools to verify changes

Coordinate System

All line and character parameters are 0-indexed, matching the LSP specification:

  • Line 0, Character 0 = first character of the file

License

MIT License — see LICENSE for details.

Ver o original no GitHub

Bom para

Relacionados