# Godot MCP Documentation Server

**[中文文档](README_CN.md)** | English

A Model Context Protocol (MCP) server that provides AI assistants with access to the complete Godot Engine documentation, helping developers with Godot development by serving documentation directly to LLMs.

## Purpose

This server bridges the gap between AI assistants and Godot documentation, allowing developers to get instant, accurate answers about Godot classes, tutorials, and features without leaving their AI chat interface.

## Project Origin

This project is based on [godot-mcp-docs](https://github.com/Nihilantropy/godot-mcp-docs/tree/main?tab=readme-ov-file) by Nihilantropy, modified for local development on Windows without Docker.

## Installation

1. **Install uv** (if not already installed):
   ```powershell
   # On Windows with PowerShell:
   Invoke-WebRequest -Uri https://astral.sh/uv/install.ps1 -UseBasicParsing | Invoke-Expression
   ```

2. **Clone the repository:**
   ```bash
   git clone https://github.com/Nihilantropy/godot-mcp-docs.git
   cd godot-mcp-docs
   ```

3. **Install Python dependencies:**
   ```bash
   uv sync
   ```

   This command reads from `pyproject.toml` and creates a virtual environment.

   **Note**: `uv sync` uses `pyproject.toml` as the source of truth, not `requirements.txt`. This is the modern Python packaging standard (PEP 517/518/621). The `uv.lock` file ensures consistent dependency versions across environments.

## Setting Up Documentation

After installing dependencies, you need to download and process the Godot documentation:

1. **Generate documentation:**
   ```bash
   uv run python .\docs_converter\godot_docs_converter.py
   ```

2. **Move docs folder to root:**
   After conversion, move the generated `docs` folder to the project root directory.

3. **Generate documentation tree:**
   ```bash
   cd docs
   tree /f > docs_tree.txt
   cd ..
   ```

   **Note**: If you encounter Chinese encoding issues, use:
   ```powershell
   tree /f | Out-File -Encoding utf8 docs_tree.txt
   ```

## Running the Server

Start the MCP server locally:

```bash
uv run python main.py
```

## Configuring MCP Client

### Claude Desktop Example

Add this to your Claude Desktop configuration file:

```json
{
  "mcpServers": {
    "godot-mcp-docs": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "main.py"
      ]
    }
  }
}
```

## Available Tools

- `get_documentation_tree()` - Get a tree-style overview of the entire documentation structure
- `get_documentation_file(file_path: str)` - Retrieve the content of specific documentation files

## Sample Usage

**Explore documentation structure:**
```
What documentation is available for Godot?
```

**Get specific class documentation:**
```
Show me the documentation for CharacterBody2D
```

**Learn about tutorials:**
```
What tutorials are available for 2D game development?
```

**Get specific tutorial content:**
```
Show me the first 2D game tutorial
```

**Compare classes:**
```
What's the difference between Node2D and CharacterBody2D?
```

## Debugging

### Option 1: FastMCP Dev UI (Recommended)

Start the server in dev mode:

```bash
uv run fastmcp dev main.py
```

Then open your browser to `http://127.0.0.1:8000` to see all tools and test them interactively.

### Option 2: MCP Inspector (Official Debugger)

Use Anthropic's official MCP Inspector:

```bash
npx @modelcontextprotocol/inspector uv run python main.py
```

This opens `http://localhost:5173` in your browser, showing all tools, request/response logs, and allowing manual tool testing. No need to run `uv run python main.py` separately.

### Option 3: HTTP API Debugging

Send JSON-RPC requests to the server:

```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
    }'
```

Or using 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
         }'
```

## Understanding Path Resolution

The `DOCS_DIR = Path("docs").resolve()` in the code is relative to the **current working directory (CWD)** when you run Python, not the script location.

### Example

Assume your directory structure:
```
D:\Codes\16_MCP\           <-- 根目录
├── main.py                <-- 启动脚本
├── docs\                  <-- 文档目录
└── srcs\
    └── util\
        └── docs_utils.py  <-- 工具代码 (里面写了 Path("docs"))
```

**Case A: Running from root directory**
```bash
cd D:\Codes\16_MCP
python main.py
```
- Current Working Directory: `D:\Codes\16_MCP`
- `Path("docs")` resolves to: `D:\Codes\16_MCP\docs` (Success)

**Case B: Running from subdirectory (common error)**
```bash
cd D:\Codes\16_MCP\srcs
python ../main.py
```
- Current Working Directory: `D:\Codes\16_MCP\srcs`
- `Path("docs")` resolves to: `D:\Codes\16_MCP\srcs\docs` (Fails - no docs folder)

### Best Practice

To ensure paths work regardless of where you run from, use `__file__`-based absolute positioning:

```python
from pathlib import Path

# Get current script directory
CURRENT_SCRIPT_DIR = Path(__file__).resolve().parent

# Navigate to project root
PROJECT_ROOT = CURRENT_SCRIPT_DIR.parent.parent

# Locate docs directory
DOCS_DIR = (PROJECT_ROOT / "docs").resolve()
```

## PowerShell Output Redirection Tips

### Save output to file:

- **Overwrite** (clears existing content):
  ```powershell
  ls > list.txt
  ```

- **Append** (preserves existing content):
  ```powershell
  ls >> list.txt
  ```

- **With UTF8 encoding** (recommended for Chinese):
  ```powershell
  ls | Out-File -FilePath output.txt -Encoding utf8
  ```

- **See on screen and save**:
  ```powershell
  ls | Tee-Object -FilePath log.txt
  ```

## Documentation Structure

The server provides access to the complete official Godot documentation with this structure:

```
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
```

## Recommended System Prompt

For optimal results when working with Godot, use this system prompt:

> "When working with Godot game development questions, always search for the latest available documentation using the godot-mcp-docs tools. Start with `get_documentation_tree()` to understand the documentation structure, then use `get_documentation_file()` to retrieve specific information about classes, tutorials, or features. Prioritize official Godot documentation over general knowledge when providing Godot-related assistance."

## Updating Documentation

To update to a newer version of Godot documentation:

```bash
uv run python .\docs_converter\godot_docs_converter.py
cd docs
tree /f > docs_tree.txt
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

The Godot documentation content follows the original Godot documentation licensing:
- Documentation content (excluding `classes/` folder): [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)
- Class reference files (`classes/` folder): MIT License
- Attribution: "Juan Linietsky, Ariel Manzur and the Godot community"