GodotLens：面向 AI 的 GDScript 代码分析工具

一个为 GDScript 提供 15 种语义分析工具的 MCP 服务器，由 Godot 内置的语言服务器驱动。

专为 AI 智能体打造

AI 编码智能体可以处理文本文件，但缺乏对 GDScript 的语义理解。当智能体使用 grep 查找函数用法时，它无法区分函数调用与包含相同名称的注释、信号声明与信号发射，或者重写的方法与无关函数。

GodotLens 通过模型上下文协议 (MCP) 暴露 Godot 内置的语言服务器，从而弥补了这一差距，为 AI 智能体提供编译器级的 GDScript 代码智能——包括跳转到定义、查找引用、诊断、重命名等。

示例： 查找 _on_player_hit 的所有用法：

方法	结果
`grep "_on_player_hit"`	12 个匹配项，包括注释、字符串和名称相似的函数
`gdscript_references`	准确的 4 个调用 `_on_player_hit` 的位置

前置要求

Godot 4.x 编辑器必须处于运行状态并打开了你的项目——当编辑器打开项目时，Godot 的 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`	将修改后的文件与 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 智能体通过 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 重新分析更改后的代码。否则，诊断和导航结果可能会过时。

推荐工作流：

使用 GodotLens 工具分析代码
将更改写入文件
调用 gdscript_sync_file 以刷新 LSP 状态
使用 GodotLens 工具验证更改

坐标系

所有行和字符参数均为 0 索引，符合 LSP 规范：

第 0 行，第 0 字符 = 文件的第一个字符

许可证

MIT 许可证 — 详情请参阅 LICENSE。

godotlens-mcp