# Godot MCP 文档服务器
中文 | [English](README.md)
一个 Model Context Protocol (MCP) 服务器，为 AI 助手提供完整的 Godot 引擎文档访问能力，帮助开发者在 AI 聊天界面中直接获取 Godot 开发文档。
## 用途
该服务器架起了 AI 助手与 Godot 文档之间的桥梁，让开发者无需离开 AI 聊天界面即可即时、准确地获取关于 Godot 类、教程和功能的答案。
## 项目来源
本项目基于 [godot-mcp-docs](https://github.com/Nihilantropy/godot-mcp-docs/tree/main?tab=readme-ov-file)（作者：Nihilantropy）修改而来，适配 Windows 本地开发环境，无需 Docker。
## 安装
1. **安装 uv**（如果尚未安装）：
```powershell
# Windows PowerShell:
Invoke-WebRequest -Uri https://astral.sh/uv/install.ps1 -UseBasicParsing | Invoke-Expression
```
2. **克隆仓库：**
```bash
git clone https://github.com/Nihilantropy/godot-mcp-docs.git
cd godot-mcp-docs
```
3. **安装 Python 依赖：**
```bash
uv sync
```
该命令会读取 `pyproject.toml` 并创建虚拟环境。
**注意**：`uv sync` 使用 `pyproject.toml` 作为依赖来源，而非 `requirements.txt`。这是现代 Python 打包标准（PEP 517/518/621）。`uv.lock` 文件确保各环境的依赖版本一致。
## 设置文档
安装依赖后，需要下载并处理 Godot 文档：
1. **生成文档：**
```bash
uv run python .\docs_converter\godot_docs_converter.py
```
2. **将 docs 文件夹移动到根目录：**
转换完成后，将生成的 `docs` 文件夹移动到项目根目录。
3. **生成文档目录树：**
```bash
cd docs
tree /f > docs_tree.txt
cd ..
```
**注意**：如果遇到中文编码问题，请使用：
```powershell
tree /f | Out-File -Encoding utf8 docs_tree.txt
```
## 运行服务器
本地启动 MCP 服务器：
```bash
uv run python main.py
```
## 配置 MCP 客户端
### Claude Desktop 示例
在 Claude Desktop 配置文件中添加：
```json
{
"mcpServers": {
"godot-mcp-docs": {
"command": "uv",
"args": [
"run",
"python",
"main.py"
]
}
}
}
```
## 可用工具
- `get_documentation_tree()` - 获取文档结构的树状概览
- `get_documentation_file(file_path: str)` - 获取特定文档文件的内容
## 使用示例
**浏览文档结构：**
```
Godot 有哪些可用文档？
```
**获取特定类文档：**
```
显示 CharacterBody2D 的文档
```
**了解教程：**
```
有哪些 2D 游戏开发教程？
```
**获取特定教程内容：**
```
显示第一个 2D 游戏教程
```
**比较类：**
```
Node2D 和 CharacterBody2D 有什么区别？
```
## 调试
### 方式一：FastMCP 内置 Dev UI（推荐）
以开发模式启动服务器：
```bash
uv run fastmcp dev main.py
```
然后在浏览器中打开 `http://127.0.0.1:8000` 查看所有工具并进行交互式测试。
### 方式二：MCP Inspector（官方调试器）
使用 Anthropic 官方 MCP 调试器：
```bash
npx @modelcontextprotocol/inspector uv run python main.py
```
这会在浏览器中打开 `http://localhost:5173`，显示所有工具、请求/响应日志，并允许手动测试工具。无需单独运行 `uv run python main.py`。
### 方式三：HTTP API 调试
向服务器发送 JSON-RPC 请求：
```powershell
Invoke-WebRequest -Uri http://localhost:8000/message `
-Method POST `
-ContentType "application/json" `
-Body '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_documentation_file",
"arguments": {
"file_path": "classes/class_characterbody2d.md"
}
},
"id": 1
}'
```
或使用 curl：
```bash
curl -X POST http://localhost:8000/message `
-H "Content-Type: application/json" `
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": { "name": "search_godot_docs", "arguments": { "query": "DisplayServer" } },
"id": 1
}'
```
## 理解路径解析
代码中的 `DOCS_DIR = Path("docs").resolve()` 是相对于**当前工作目录（CWD）**的，而不是脚本文件所在的位置。
### 示例
假设目录结构如下：
```
D:\Codes\16_MCP\ <-- 根目录
├── main.py <-- 启动脚本
├── docs\ <-- 文档目录
└── srcs\
└── util\
└── docs_utils.py <-- 工具代码（包含 Path("docs")）
```
**情况 A：从根目录运行**
```bash
cd D:\Codes\16_MCP
python main.py
```
- 当前工作目录：`D:\Codes\16_MCP`
- `Path("docs")` 解析为：`D:\Codes\16_MCP\docs`（成功）
**情况 B：从子目录运行（常见错误）**
```bash
cd D:\Codes\16_MCP\srcs
python ../main.py
```
- 当前工作目录：`D:\Codes\16_MCP\srcs`
- `Path("docs")` 解析为：`D:\Codes\16_MCP\srcs\docs`（失败 - 没有 docs 文件夹）
### 最佳实践
为确保路径无论从哪里运行都能正常工作，请使用基于 `__file__` 的绝对定位：
```python
from pathlib import Path
# 获取当前脚本目录
CURRENT_SCRIPT_DIR = Path(__file__).resolve().parent
# 导航到项目根目录
PROJECT_ROOT = CURRENT_SCRIPT_DIR.parent.parent
# 定位 docs 目录
DOCS_DIR = (PROJECT_ROOT / "docs").resolve()
```
## PowerShell 输出重定向技巧
### 将输出保存到文件：
- **覆盖**（清除现有内容）：
```powershell
ls > list.txt
```
- **追加**（保留现有内容）：
```powershell
ls >> list.txt
```
- **UTF8 编码**（中文推荐）：
```powershell
ls | Out-File -FilePath output.txt -Encoding utf8
```
- **同时显示和保存**：
```powershell
ls | Tee-Object -FilePath log.txt
```
## 文档结构
服务器提供对完整官方 Godot 文档的访问，结构如下：
```
docs/
├── _styleguides
├── _tools
│ └── redirects
├── about
├── classes
├── community
│ └── asset_library
├── contributing
│ ├── development
│ │ ├── compiling
│ │ ├── configuring_an_ide
│ │ ├── core_and_modules
│ │ ├── debugging
│ │ │ └── vulkan
│ │ ├── editor
│ │ └── file_formats
│ ├── documentation
│ └── workflow
├── getting_started
│ ├── first_2d_game
│ ├── first_3d_game
│ ├── introduction
│ └── step_by_step
├── img
└── tutorials
├── 2d
├── 3d
│ ├── global_illumination
│ ├── particles
│ └── procedural_geometry
├── animation
├── assets_pipeline
│ ├── escn_exporter
│ └── importing_3d_scenes
├── audio
├── best_practices
├── editor
├── export
├── i18n
├── inputs
├── io
├── math
├── migrating
├── navigation
├── networking
├── performance
│ └── vertex_animation
├── physics
│ └── interpolation
├── platform
│ ├── android
│ ├── ios
│ └── web
├── plugins
│ └── editor
├── rendering
├── scripting
│ ├── c_sharp
│ │ └── diagnostics
│ ├── cpp
│ ├── debug
│ ├── gdextension
│ └── gdscript
├── shaders
│ ├── shader_reference
│ └── your_first_shader
├── ui
└── xr
```
## 推荐系统提示词
为获得最佳 Godot 开发体验，请使用以下系统提示词：
> "在处理 Godot 游戏开发问题时，请始终使用 godot-mcp-docs 工具搜索最新可用文档。首先使用 `get_documentation_tree()` 了解文档结构，然后使用 `get_documentation_file()` 获取关于类、教程或功能的特定信息。在提供 Godot 相关帮助时，优先使用官方 Godot 文档而非通用知识。"
## 更新文档
要更新到较新版本的 Godot 文档：
```bash
uv run python .\docs_converter\godot_docs_converter.py
cd docs
tree /f > docs_tree.txt
```
## 许可证
本项目采用 MIT 许可证 - 详情请参阅 [LICENSE](LICENSE) 文件。
Godot 文档内容遵循原始 Godot 文档许可：
- 文档内容（不包括 `classes/` 文件夹）：[CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)
- 类参考文件（`classes/` 文件夹）：MIT 许可证
- 归属："Juan Linietsky, Ariel Manzur 和 Godot 社区"
