# 工程解析与工作流说明 (Project Analysis & Workflow)
本文档旨在解析 Godot MCP Docs 项目的结构、核心原理以及标准操作工作流。
## 1. 工程概述
本项目是一个 **Model Context Protocol (MCP)** 服务器，旨在为 AI 助手（如 Claude, Cursor 等）提供 Godot 游戏引擎的官方文档访问能力。
### 核心原理
1. **文档源获取**：从 Godot GitHub 仓库下载最新的 `.rst` (reStructuredText) 格式文档。
2. **格式转换**：利用转换工具将 `.rst` 转换为 AI 更易理解的 `.md` (Markdown) 格式。
3. **资源服务**：通过 MCP 协议，将转换后的文档作为 Resources 或 Tools 暴露给 AI 客户端。
## 2. 目录结构解析
```text
godot-mcp-docs/
├── main.py # [核心入口] MCP 服务器启动脚本
├── pyproject.toml # 项目依赖配置
├── docs/ # [自动生成] 存放转换后 Markdown 文档的目录
│ └── ...
├── docs_converter/ # [工具集] 文档下载与转换脚本
│ ├── godot_docs_converter.py # 转换程序主入口
│ ├── download_docs.py # 负责下载 Godot 官方文档 ZIP 包
│ ├── converter.py # 负责解析 RST 并转换为 Markdown
│ └── cleanup_docs.py # 转换后的清理工作
└── srcs/ # [源码] MCP 服务器逻辑
├── server.py # MCP Server 实例定义
├── resources/ # 定义 MCP Resources (直接读取文档)
├── tools/ # 定义 MCP Tools (搜索、导航等)
└── utils/
└── docs_utils.py # 路径处理工具 (定义了 DOCS_DIR 的位置)
```
## 3. 标准工作流 (Standard Workflow)
为了确保项目正常运行，请严格按照以下步骤操作。
### 环境准备
确保已安装 Python 环境。推荐使用 `uv` 进行依赖管理和运行，也可以使用标准的 `pip`。
### 步骤一：生成文档 (Documentation Generation)
**关键注意**：MCP 服务器 (`main.py`) 默认在项目根目录下的 `docs/` 文件夹寻找文档。因此，**必须在项目根目录**运行转换脚本，以确保生成的文件夹位置正确。
1. **打开终端**，进入 `godot-mcp-docs` 根目录。
2. **运行转换脚本**：
```powershell
# 使用 uv (推荐)
uv run python docs_converter/godot_docs_converter.py
# 或者使用标准 Python
python docs_converter/godot_docs_converter.py
```
**执行过程详解**：
- 脚本会自动下载 `godot-docs` 的 master 分支 ZIP 包。
- 解压并读取 `.rst` 文件。
- 转换为 `.md` 文件并存入新建的 `docs/` 目录。
- 自动清理临时文件。
- 最终在根目录下生成 `docs/` 文件夹。
> **注意**：由于转换涉及大量文件，该过程可能需要几分钟。
### 步骤二：启动服务 (Run Server)
文档生成完毕后，即可启动 MCP 服务器。
1. **运行主程序**：
```powershell
# 使用 uv
uv run python main.py
# 或者使用标准 Python
python main.py
```
2. **验证启动**：
观察日志输出（输出到 stderr），看到如下信息即代表成功：
```
... - INFO - Starting Godot MCP Server...
... - INFO - Documentation directory is ready for you my love <3.
```
### 步骤三：客户端接入 (Client Configuration)
将此服务配置到你的 MCP 客户端（如 Claude Desktop 或 VS Code 扩展）。
**配置示例 (JSON)**:
```json
{
"mcpServers": {
"godot-docs": {
"command": "uv",
"args": [
"run",
"python",
"D:/Codes/16_MCP/godot-mcp-docs/main.py"
// 请使用 main.py 的绝对路径
]
}
}
}
```
## 4. 常见问题 (Troubleshooting)
**Q: 启动时提示 "Documentation directory not found"？**
A: 这是因为程序没找到 `docs/` 文件夹。通常是因为你在 `docs_converter/` 子目录下运行了转换脚本，导致 `docs/` 文件夹被生成在子目录里了。
**解决方法**：将 `docs_converter/docs` 移动到项目根目录，或者在根目录重新运行转换命令。
**Q: 根目录下的 `godot-docs/` 文件夹是做什么的？**
A: `godot-mcp-docs` 目前的转换脚本 (`download_docs.py`) 默认通过网络下载最新的官方文档，并**不直接使用**本地的 `godot-docs` 文件夹。如果你希望使用本地源，需要修改 `docs_converter/godot_docs_converter.py` 的逻辑。
