AI导哈

GDScript代码分析服务器

一个用于GDScript代码分析的模型上下文协议（MCP）服务器，帮助AI助手高效理解代码结构而无需读取整个文件，适用于大型代码库。

  • by minami110
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 minami110/mcp-gdscript

使用说明

mcp gdscript

用于GDScript代码分析的模型上下文协议（MCP）服务器。该服务器允许AI助手在不读取整个文件的情况下理解GDScript代码结构，使其对大型代码库高效。

特性

  • 文件结构分析：从GDScript文件中提取类、函数、信号、变量和枚举
  • 符号搜索：查找特定符号并获取其位置和类型
  • 依赖关系提取：识别扩展、预加载和导入语句
  • 直接代码分析：分析没有文件I/O的GDScript代码片段
  • 树保姆供电：使用官方GDScript树保姆语法进行精确解析

安装与使用

带uvx（推荐）

使用此服务器的最简单方法-无需安装：

{
  "mcpServers": {
    "gdscript": {
      "command": "uvx",
      "args": ["mcp-gdscript"]
    }
  }
}

使用npm/npx

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

本地安装

# Clone the repository
git clone https://github.com/minami110/mcp-gdscript
cd mcp-gdscript

# Install in development mode
pip install -e .

# Run the server
mcp-gdscript

可用工具

基于文件的分析工具

1. analyze_gdscript_file

分析GDScript文件并提取其完整结构。

输入：

  • file_path （string）：.gd或.gdscript文件的路径

输出： 返回JSON格式：

  • symbols：带有行号的类、函数、信号、变量和枚举列表
  • summary：每种符号类型的总计数

例子：

{
  "file": "scenes/player.gd",
  "symbols": {
    "classes": [],
    "functions": [
      {"name": "_ready", "line": 5, "column": 0},
      {"name": "_process", "line": 10, "column": 0}
    ],
    "signals": [
      {"name": "health_changed", "line": 2, "column": 0}
    ],
    "variables": [],
    "enums": []
  },
  "summary": {
    "total_classes": 0,
    "total_functions": 2,
    "total_signals": 1,
    "total_variables": 0,
    "total_enums": 0
  }
}

2. get_gdscript_structure

获取GDScript文件的可读结构视图。

输入：

  • file_path （string）：.gd或.gdscript文件的路径

输出： 一种格式化的文本表示，用行号显示文件结构。

输出示例：

=== GDScript File Structure ===

Signals:
  - health_changed (line 2)

Functions:
  - _ready (line 5)
  - _process (line 10)

3. find_gdscript_symbol

在文件中搜索特定符号。

输入：

  • file_path （string）：.gd或.gdscript文件的路径
  • symbol_name （string）：要查找的符号的名称

输出： 符号信息，包括类型、名称和位置。

例子：

{
  "type": "function",
  "name": "_ready",
  "line": 5,
  "column": 0
}

4. get_gdscript_dependencies

从GDScript文件中提取所有依赖项。

输入：

  • file_path （string）：.gd或.gdscript文件的路径

输出： 扩展、预加载和导入语句列表。

例子：

{
  "file": "scenes/enemy.gd",
  "dependencies": {
    "extends": ["Character"],
    "preload": ["res://scenes/explosion.tscn"],
    "import": []
  }
}

5. analyze_gdscript_code

分析直接以字符串形式提供的GDScript代码。

输入：

  • code （string）：GDScript源代码

输出： 完整的分析，包括结构、符号和总结。

项目管理工具

6. set_project_root

设置项目根目录以启用项目范围的分析。

输入：

  • project_root （string）：项目根目录的路径

输出： 使用索引的GDScript文件进行确认计数。

例子：

{
  "project_root": "/home/user/godot_project",
  "gdscript_files_count": 42,
  "status": "success"
}

7. get_project_root

获取当前项目根目录和文件计数。

输入：

  • 无

输出： 当前项目根路径和索引文件计数。

例子：

{
  "project_root": "/home/user/godot_project",
  "gdscript_files_count": 42
}

代码分析工具

8. find_references

查找整个项目或特定文件中对符号的所有引用。

输入：

  • symbol_name （string）：要查找引用的符号的名称
  • file_path （可选字符串）：将搜索限制到特定文件。如果未提供且已设置项目根，则搜索整个项目。

输出： 引用符号的所有位置的列表。

例子：

{
  "symbol": "player_name",
  "total_references": 5,
  "references": [
    {
      "file": "scripts/player.gd",
      "line": 15,
      "column": 8,
      "end_line": 15,
      "end_column": 19
    },
    {
      "file": "scripts/manager.gd",
      "line": 42,
      "column": 12,
      "end_line": 42,
      "end_column": 23
    }
  ]
}

使用案例：

  • 查找变量或函数的所有用法
  • 了解文件之间的依赖关系
  • 通过检查所有引用来安全重构
  • 跟踪项目中的数据流

用例

  1. 代码库导航：快速了解大型GDScript文件的结构
  2. API文档：从代码结构生成文档
  3. 相关性分析：了解脚本关系和依赖关系
  4. 代码审查：在详细审查之前获取结构概述
  5. 重构辅助工具：了解重构时需要更新的内容

配置

环境变量

  • RUST_LOG：设置日志记录级别（例如。， debug, info, warn)

性能提示

  • 对于大文件（>10MB），服务器可以有效地提取结构，而无需将完整内容加载到上下文中
  • 符号提取针对典型的GDScript文件（<50MB）进行了优化
  • 树型解析器使用缓存语法来提高性能

局限性

  • 目前已针对GDScript 4.x及更高版本进行了优化
  • 复杂的宏观扩张可能无法得到充分分析
  • 动态代码模式中的一些边缘情况可能无法捕获

发展

设置

pip install -e ".[dev]"

测试

pytest

代码风格

black .
ruff check .

贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

参考文献

故障排除

“找不到模块”错误

请确保您使用的是Python 3.10或更高版本，并且已正确安装服务器。

GDScript 3.x的分析错误

此服务器针对GDScript 4.x进行了优化。对于GDScript 3.x，某些功能可能无法按预期工作。

性能问题

如果分析非常大的文件，请考虑：

  1. 将大型脚本拆分为较小的模块
  2. 使用结构工具而不是全面分析
  3. 分析特定符号而不是整个文件

相关 MCP