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
}
]
}使用案例：
- 查找变量或函数的所有用法
- 了解文件之间的依赖关系
- 通过检查所有引用来安全重构
- 跟踪项目中的数据流
用例
- 代码库导航：快速了解大型GDScript文件的结构
- API文档：从代码结构生成文档
- 相关性分析：了解脚本关系和依赖关系
- 代码审查：在详细审查之前获取结构概述
- 重构辅助工具：了解重构时需要更新的内容
配置
环境变量
RUST_LOG：设置日志记录级别（例如。，debug,info,warn)
性能提示
- 对于大文件（>10MB），服务器可以有效地提取结构，而无需将完整内容加载到上下文中
- 符号提取针对典型的GDScript文件（\<50MB）进行了优化
- 树型解析器使用缓存语法来提高性能
局限性
- 目前已针对GDScript 4.x及更高版本进行了优化
- 复杂的宏观扩张可能无法得到充分分析
- 动态代码模式中的一些边缘情况可能无法捕获
发展
设置
pip install -e ".[dev]"测试
pytest代码风格
black .
ruff check .贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 进行更改
- 提交拉取请求
许可证
MIT许可证-有关详细信息，请参阅许可证文件
参考文献
故障排除
“找不到模块”错误
请确保您使用的是Python 3.10或更高版本，并且已正确安装服务器。
GDScript 3.x的分析错误
此服务器针对GDScript 4.x进行了优化。对于GDScript 3.x，某些功能可能无法按预期工作。
性能问题
如果分析非常大的文件，请考虑：
- 将大型脚本拆分为较小的模块
- 使用结构工具而不是全面分析
- 分析特定符号而不是整个文件