# Godot Documentation MCP Server

Local [MCP](https://modelcontextprotocol.io/) server that lets Cursor search the [Godot 4.7 documentation](https://docs.godotengine.org/en/4.7/) via hybrid keyword + semantic retrieval over RST source files.

## Features

- Indexes `.rst` files from a local `docs-source/` checkout
- Hybrid search (keyword + semantic, Reciprocal Rank Fusion)
- Compact results with file path, section hierarchy, and docs URLs
- On-disk index cache under `.index/` (fast startup; incremental reindex)
- MCP tools: `search_docs`, `list_versions`, `status`, `reindex`

## Requirements

- Python 3.11+
- A clone of the Godot docs repository in `docs-source/`

## Setup

```bash
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
```

Clone the documentation source (branch `4.7`):

```bash
git clone --branch 4.7 --depth 1 https://github.com/godotengine/godot-docs.git docs-source
```

Do not modify files under `docs-source/` during normal use.

## Run the server

With the virtual environment activated:

```bash
python server.py
```

The server listens at `http://127.0.0.1:8901/mcp`.

On startup it loads a compatible cache from `.index/` when available; otherwise it rebuilds the index (first run downloads the embedding model and may take several minutes).

## Add the MCP configuration in Cursor

Start the server first, then register it in Cursor.

Open **Cursor Settings → MCP** (or edit your user MCP config) and add:

```json
{
  "mcpServers": {
    "godot-doc-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8901/mcp"
    }
  }
}
```

After saving, ensure `godot-doc-mcp` shows as connected. You can verify with the `status` tool, then try `search_docs` with a query such as `"CharacterBody2D move_and_slide"`.

### Recommended Cursor rule

MCP registration alone does not make the agent prefer the docs over its training data. Add a project or user rule so Godot 4.7 answers go through this server:

```markdown
# Godot 4.7 documentation

For Godot 4.7 APIs, nodes, signals, methods, and engine behavior:

- Treat the `godot-doc-mcp` MCP tools as the source of truth.
- Call `search_docs` before answering; do not rely on memorized Godot knowledge.
- Prefer returned documentation URLs and section metadata when citing sources.
- If search returns nothing useful, say so instead of inventing API details.
```

Put this in `.cursor/rules/` (project) or your user rules (all projects). Scope it to Godot work so it does not force doc search for unrelated tasks.

## MCP tools

| Tool | Purpose |
|------|---------|
| `search_docs` | Search docs (`query`, optional `max_results`, optional `version`) |
| `list_versions` | List indexed documentation versions |
| `status` | Index stats, cache source, docs version, git revision |
| `reindex` | Update the index (`force=false` incremental; `force=true` full rebuild) |

## Configuration

Main settings live in `config.py`:

| Setting | Default | Notes |
|---------|---------|--------|
| `DOCS_SOURCE_DIR` | `docs-source/` | Local RST checkout |
| `DOCS_VERSION` | `4.7` | Version stamped on chunks |
| `DOCS_BASE_URL` | `https://docs.godotengine.org/en/4.7/` | Used for result URLs |
| `SEARCH_BACKEND` | `hybrid` | Also supports `semantic` or `keyword` |
| `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Local sentence-transformers model |
| `REINDEX_ON_STARTUP` | `True` | Load cache or rebuild on start |
| `INDEX_CACHE_DIR` | `.index/` | Generated cache (gitignored) |

## Project layout

```text
server.py          MCP HTTP entrypoint
tools.py           Thin MCP tool adapters
indexer.py         RST discovery, parsing, chunking, embedding
search.py          Keyword, semantic, and hybrid retrieval
persistence.py     On-disk index save/load
models.py          Shared data structures
config.py          Paths, version, search backend
docs-source/       External Godot docs checkout
.index/            Generated index cache
```

See `PROJECT_PLAN.md` and `TODO.md` for architecture details and phase status.