Metadata-Version: 2.4
Name: godotlens-mcp
Version: 1.0.5
Summary: MCP server providing 15 AI-optimized tools for GDScript code analysis via Godot's built-in LSP
Project-URL: Homepage, https://github.com/pzalutski-pixel/godotlens-mcp
Project-URL: Repository, https://github.com/pzalutski-pixel/godotlens-mcp
Project-URL: Issues, https://github.com/pzalutski-pixel/godotlens-mcp/issues
Author: Peter Zalutski
License: MIT
License-File: LICENSE
Keywords: ai-agents,claude,code-analysis,code-intelligence,developer-tools,gdscript,godot,lsp,mcp,mcp-server,semantic-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.7.0; extra == 'dev'
Description-Content-Type: text/markdown

# GodotLens: AI-First Code Analysis for GDScript

[![GitHub Release](https://img.shields.io/github/v/release/pzalutski-pixel/godotlens-mcp)](https://github.com/pzalutski-pixel/godotlens-mcp/releases)
[![npm](https://img.shields.io/npm/v/godotlens-mcp)](https://www.npmjs.com/package/godotlens-mcp)
[![PyPI](https://img.shields.io/pypi/v/godotlens-mcp)](https://pypi.org/project/godotlens-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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`:

| Approach | Result |
|----------|--------|
| `grep "_on_player_hit"` | 12 matches including comments, strings, and similarly named functions |
| `gdscript_references` | Exactly 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):

```json
{
  "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

```bash
pip install godotlens-mcp
```

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

## Configuration

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `GODOT_LSP_HOST` | `127.0.0.1` | Godot LSP server host |
| `GODOT_LSP_PORT` | `6005` | Godot LSP server port |

## Tools

### Health

| Tool | Description |
|------|-------------|
| `gdscript_status` | Check connection to Godot LSP. Use to verify editor is running before other tools. |

### Navigation (6 tools)

| Tool | Description |
|------|-------------|
| `gdscript_definition` | Navigate to where a symbol is defined. Returns file path and line number. |
| `gdscript_declaration` | Navigate to the declaration site of a symbol. |
| `gdscript_references` | Find all references to a symbol across the project. Essential for impact analysis before refactoring. |
| `gdscript_hover` | Get type information and documentation for a symbol. Use to understand types and return values. |
| `gdscript_symbols` | List all symbols (classes, functions, variables, signals) in a file. Use to explore file structure. |
| `gdscript_signature_help` | Get function signature and parameter info at a call site. |

### Refactoring

| Tool | Description |
|------|-------------|
| `gdscript_rename` | Rename a symbol across all files. Workflow: references to preview impact, rename, then sync. |

### Synchronization (3 tools)

| Tool | Description |
|------|-------------|
| `gdscript_sync_file` | Sync a modified file with the LSP and get updated diagnostics. Call after editing .gd files. |
| `gdscript_sync_files` | Batch sync multiple modified files. More efficient than syncing individually. |
| `gdscript_delete_file` | Notify LSP a file was deleted. Clears stale diagnostics. |

### Batch Operations (3 tools)

| Tool | Description |
|------|-------------|
| `gdscript_symbols_batch` | Get symbols from multiple files in one call. |
| `gdscript_definitions_batch` | Get definitions for multiple positions in one call. |
| `gdscript_references_batch` | Find references for multiple symbols in one call. Use for bulk impact analysis. |

### Diagnostics

| Tool | Description |
|------|-------------|
| `gdscript_diagnostics` | Get 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](LICENSE) for details.

<!-- mcp-name: io.github.pzalutski-pixel/godotlens -->
