pzalutski-pixel/godotlens-mcp

# GodotLens：GDScript 的 AI 优先代码分析 [](https://github.com/pzalutski-pixel/godotlens-mcp/releases) [](https://www.npmjs.com/package/godotlens-mcp) [](https://pypi.org/project/godotlens-mcp/) [](LICENSE) 一个通过 Godot 内置语言服务器为 GDScript 提供 15 种语义分析工具的 MCP 服务器。 ## 专为 AI 代理设计 AI 编码代理处理的是文本文件，但缺乏对 GDScript 的语义理解。当代理使用 `grep` 查找函数用法时，它无法区分函数调用、包含同名函数的注释、信号声明与信号发射，或被重写的方法与无关函数。 GodotLens 通过暴露 Godot 内置的语言服务器（Model Context Protocol / MCP）填补这一空白，为 AI 代理提供编译器级别的代码智能，支持转到定义、查找引用、诊断、重命名等功能。 **示例：查找 `_on_player_hit` 的所有用法** | 方法 | 结果 | |------|------| | `grep "_on_player_hit"` | 12 个匹配项，包括注释、字符串和同名函数 | | `gdscript_references` | 精确的 4 个调用位置 | ## 先决条件 - **Godot 4.x** 编辑器必须 **正在运行** 并打开项目 —— 编辑器打开项目时会自动启动 LSP 服务器 - **Python 3.10+**（用于 pip 安装）或 **Node.js 16+**（用于 npx） ## 快速开始 ### 选项 A：npx（推荐用于 MCP 客户端） 添加到你的 MCP 配置（例如 Claude Code 的 `.mcp.json`）： ``` { "mcpServers": { "godotlens": { "command": "npx", "args": ["-y", "godotlens-mcp"] } } } ``` npm 包打包了完整的服务器（~20 KB 的 Python），无外部 Python 依赖。 ### 选项 B：pip ``` pip install godotlens-mcp ``` ``` { "mcpServers": { "godotlens": { "command": "godotlens-mcp" } } } ``` ## 配置 | 环境变量 | 默认值 | 说明 | |----------|--------|------| | `GODOT_LSP_HOST` | `127.0.0.1` | Godot LSP 服务器主机 | | `GODOT_LSP_PORT` | `6005` | Godot LSP 服务器端口 | ## 工具 ### 健康检查 | 工具 | 描述 | |------|------| | `gdscript_status` | 检查与 Godot LSP 的连接。建议在其他工具前验证编辑器是否正在运行。 | ### 导航（6 个工具） | 工具 | 描述 | |------|------| | `gdscript_definition` | 跳转到符号定义位置，返回文件路径和行号。 | | `gdscript_declaration` | 跳转到符号声明位置。 | | `gdscript_references` | 查找项目中符号的所有引用，用于重构前的影响分析。 | | `gdscript_hover` | 获取符号的类型信息和文档说明。 | | `gdscript_symbols` | 列出文件中的所有符号（类、函数、变量、信号）。 | | `gdscript_signature_help` | 获取调用位置处的函数签名和参数信息。 | ### 重构 | 工具 | 描述 | |------|------| | `gdscript_rename` | 在所有文件中重命名符号。流程：预览引用 → 重命名 → 同步。 | ### 同步（3 个工具） | 工具 | 描述 | |------|------| | `gdscript_sync_file` | 同步已修改的文件并获取更新后的诊断信息。编辑 `.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 代理通过 MCP（基于 stdio 的 JSON-RPC）与 GodotLens 通信，GodotLens 将 MCP 工具调用转换为 LSP 请求并通过 TCP 发送给 Godot 编辑器，响应结果会被压缩以提升 AI 处理效率。 **零依赖** —— 服务器仅使用 Python 标准库，直接实现 MCP 与 LSP 协议，保持轻量且自包含。 ## 重要：文件同步 Godot 的 LSP 不会自动检测编辑器外部对文件的修改。当 AI 代理修改 `.gd` 文件时，应调用 `gdscript_sync_file` 或 `gdscript_sync_files` 使 LSP 重新分析代码。否则，诊断和导航结果可能已过期。 **推荐工作流：** 1. 使用 GodotLens 工具分析代码 2. 将更改写入文件 3. 调用 `gdscript_sync_file` 刷新 LSP 状态 4. 使用 GodotLens 工具验证更改 ## 坐标系统 所有行列参数均为 **从 0 开始**，与 LSP 规范一致： - 第 0 行，第 0 字符 = 文件首字符 ## 许可证 MIT 许可证 —— 详见 [LICENSE](LICENSE)。

标签：AI代理, AI编码, GDScript, GitHub Release, GNU通用公共许可证, Godot, Godot 4, GoTo定义, MCP, MCP服务器, MITM代理, Node.js, npm, PyPI, Python, 代码分析, 代码智能, 凭证管理, 引用查找, 文本文件, 无后门, 模型上下文协议, 游戏开发, 编译器准确, 诊断, 语言服务, 逆向工具, 重命名