Metadata-Version: 2.4
Name: godot-mcp-docs
Version: 1.0.1
Summary: MCP server that serves Godot documentation to LLM agents, version-aware, backed by godot-docs and godotengine/godot XML.
Author: Matthew Scott
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: docutils>=0.20
Requires-Dist: mcp>=1.0.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic>=2.5
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# godot-mcp

[![CI](https://github.com/Zei33/godot-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Zei33/godot-mcp/actions/workflows/ci.yml)
[![Tests](https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2FZei33%2F1197e7f32093f7bba67543e258d107d7%2Fraw%2Fgodot-mcp-tests.json)](https://github.com/Zei33/godot-mcp/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2FZei33%2F1197e7f32093f7bba67543e258d107d7%2Fraw%2Fgodot-mcp-coverage.json)](https://github.com/Zei33/godot-mcp/actions/workflows/ci.yml)
[![Version](https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2FZei33%2F1197e7f32093f7bba67543e258d107d7%2Fraw%2Fgodot-mcp-version.json)](https://github.com/Zei33/godot-mcp/blob/main/pyproject.toml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2)](https://modelcontextprotocol.io/)
[![Last commit](https://img.shields.io/github/last-commit/Zei33/godot-mcp?logo=github)](https://github.com/Zei33/godot-mcp/commits/main)
[![Issues](https://img.shields.io/github/issues/Zei33/godot-mcp?logo=github)](https://github.com/Zei33/godot-mcp/issues)
[![Stars](https://img.shields.io/github/stars/Zei33/godot-mcp?style=flat&logo=github)](https://github.com/Zei33/godot-mcp/stargazers)

An MCP server that gives AI coding agents (Claude Code, Cursor, OpenAI Codex, …) structured, version-aware access to the official Godot documentation.

## Please don't bother the Godot maintainers about this

This is an **unofficial**, third-party project. It is not affiliated with, endorsed by, or supported by the Godot Engine project or its maintainers. Please do not file issues, ask questions, or request support about `godot-mcp` on `godotengine/godot`, `godotengine/godot-docs`, the Godot community channels, or to any Godot contributor. File issues on this repo instead.

**Scope:** this project supports using AI assistants for **programming** against Godot — GDScript, C#, engine APIs, editor scripting, shaders-as-code, etc. It does **not** endorse or facilitate using generative AI for **art, audio, music, voice, writing, or other creative assets** in your games. Use human-made (or properly licensed) creative work for those.

- **Class reference** — parsed from `godotengine/godot`'s authoritative engine XML (`doc/classes/*.xml`).
- **Prose docs** — served from a user-maintained clone of [`godotengine/godot-docs`](https://github.com/godotengine/godot-docs).
- **Version-aware** — auto-detects the Godot version from your project's `project.godot` and serves docs from the matching branch. No manual branch switching required.
- **External docs repo** — the docs clone lives outside any individual game project, so game repos stay small.
- **Non-invasive** — per-version git worktrees mean your docs checkout's current branch is never modified.

## Install

### macOS / Linux

One-liner (clones the repo to `~/.local/share/godot-mcp`, creates a venv, installs, and runs the interactive configurator):

```bash
curl -fsSL https://raw.githubusercontent.com/Zei33/godot-mcp/main/install.sh | bash
```

### Windows (PowerShell)

```powershell
irm https://raw.githubusercontent.com/Zei33/godot-mcp/main/install.ps1 | iex
```

Installs to `%LOCALAPPDATA%\godot-mcp` by default. If you'd rather download the script first and inspect it before running, `irm -OutFile install.ps1 <url>` then `.\install.ps1`; you may need `Set-ExecutionPolicy -Scope Process Bypass` for the local invocation (the piped-to-`iex` form is unaffected).

Codex CLI has no Windows build, so the Windows configurator offers only Claude Code and Cursor.

### Configurator

The configurator will:
1. Ask where your `godot-docs` clone lives (default `~/godot-docs`, i.e. `%USERPROFILE%\godot-docs` on Windows). If it doesn't exist there, it offers to clone it for you.
2. Ask whether to install **globally** (all your projects) or for **this project only**.
3. Ask which AI clients to register with — any combination of Claude Code, Cursor, and (on POSIX) OpenAI Codex.
4. Write each client's config file (safe to re-run — it merges rather than overwrites).

### Prerequisites

- `git`
- Python ≥ 3.10 (on Windows, either the [python.org installer](https://www.python.org/downloads/) with "Add to PATH" enabled, or via `py` launcher)

### Non-interactive install

```bash
curl -fsSL https://raw.githubusercontent.com/Zei33/godot-mcp/main/install.sh \
  | GODOT_MCP_NONINTERACTIVE=1 bash

# then, later:
~/.local/share/godot-mcp/.venv/bin/python \
  ~/.local/share/godot-mcp/scripts/configure.py \
  --install-dir ~/.local/share/godot-mcp \
  --wrapper    ~/.local/share/godot-mcp/bin/godot-mcp \
  --docs-path  ~/godot-docs \
  --scope      global \
  --clients    claude,cursor,codex

# or, project-scoped:
~/.local/share/godot-mcp/.venv/bin/python \
  ~/.local/share/godot-mcp/scripts/configure.py \
  --install-dir ~/.local/share/godot-mcp \
  --wrapper    ~/.local/share/godot-mcp/bin/godot-mcp \
  --docs-path  ~/godot-docs \
  --scope      project \
  --project-dir ~/games/my-game \
  --clients    claude,cursor
```

### Install-script environment variables

These apply to both `install.sh` and `install.ps1` (PowerShell reads them as `$env:GODOT_MCP_*`).

| Var | Purpose | Default (POSIX) | Default (Windows) |
|---|---|---|---|
| `GODOT_MCP_REPO` | Git URL to clone | `https://github.com/Zei33/godot-mcp.git` | (same) |
| `GODOT_MCP_INSTALL_DIR` | Destination | `$HOME/.local/share/godot-mcp` | `%LOCALAPPDATA%\godot-mcp` |
| `GODOT_MCP_REF` | Branch / tag | `main` | (same) |
| `GODOT_MCP_NONINTERACTIVE` | Skip the configurator | unset | unset |

### From PyPI (advanced)

If you'd rather manage the install yourself:

```bash
pipx install godot-mcp-docs   # or: pip install --user godot-mcp-docs
```

This gives you the `godot-mcp` command but skips the configurator — you'll need to register it with your MCP client manually (see [Manual config](#manual-config-if-youd-rather-skip-the-configurator) below). You'll also need a local `godot-docs` clone and to set `GODOT_DOCS_PATH` yourself.

## Supported clients

After install, restart the client — each should auto-discover the `godot-docs` MCP server.

| Client | Global config | Project config | Shape |
|---|---|---|---|
| **Claude Code** | `~/.claude.json` | `<project>/.mcp.json` | `mcpServers.godot-docs` |
| **Cursor** | `~/.cursor/mcp.json` | `<project>/.cursor/mcp.json` | `mcpServers.godot-docs` |
| **OpenAI Codex CLI** [^1] | `~/.codex/config.toml` | _(n/a — user-level only)_ | `[mcp_servers.godot-docs]` |

[^1]: Codex CLI ships POSIX-only; the Windows configurator hides it.

Codex CLI has no per-project config, so it always installs globally even when you choose project scope (a note is printed so you know).

### Manual config (if you'd rather skip the configurator)

Claude Code and Cursor both use this shape:

```json
{
  "mcpServers": {
    "godot-docs": {
      "command": "/Users/you/.local/share/godot-mcp/bin/godot-mcp",
      "args": [],
      "env": {
        "GODOT_DOCS_PATH": "/Users/you/godot-docs"
      }
    }
  }
}
```

OpenAI Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.godot-docs]
command = "/Users/you/.local/share/godot-mcp/bin/godot-mcp"
args = []

[mcp_servers.godot-docs.env]
GODOT_DOCS_PATH = "/Users/you/godot-docs"
```

Windows uses the same `mcpServers` shape — just point `command` at the `.cmd` wrapper (forward slashes work inside JSON strings, or escape backslashes as `\\`):

```json
{
  "mcpServers": {
    "godot-docs": {
      "command": "C:/Users/you/AppData/Local/godot-mcp/bin/godot-mcp.cmd",
      "args": [],
      "env": {
        "GODOT_DOCS_PATH": "C:/Users/you/godot-docs"
      }
    }
  }
}
```

## Version handling

When an MCP tool is called, the version served is chosen in this order:

1. Explicit `version` argument on the tool call.
2. The version written in the current working directory's `project.godot` (`config/features = PackedStringArray("4.4", ...)`).
3. `GODOT_DOCS_DEFAULT_VERSION` env var.
4. `master`.

If the resolved version has no matching docs branch, the server snaps to the closest lower branch (e.g. `4.4.1` → `4.4`) and reports `snapped: true` so agents can surface a warning.

On startup, the server detects the project's Godot version from the client's working directory, pre-warms the matching docs worktree and FTS index, and logs:

```
godot-mcp: auto-detected Godot 4.4 → using docs branch '4.4' (project.godot)
```

Your working checkout of `godot-docs` stays on whatever branch you left it on — the server uses isolated per-version worktrees in its cache directory.

## Environment variables

| Key | Purpose | Default |
|---|---|---|
| `GODOT_DOCS_PATH` | Path to your local godot-docs git clone | **required** |
| `GODOT_DOCS_DEFAULT_VERSION` | Fallback version when auto-detection fails | `master` |
| `GODOT_MCP_CACHE_DIR` | Where indexes + engine XML cache live | platform cache dir |
| `GODOT_ENGINE_REPO_PATH` | Local engine clone to use instead of fetching | unset |
| `GODOT_MCP_OFFLINE` | If `1`, refuse network operations | `0` |
| `GODOT_MCP_AUTO_FETCH` | `git fetch` the docs repo on startup | `1` |

## Tools exposed

| Tool | Purpose |
|---|---|
| `get_class` | Full class reference (inheritance, properties, methods, signals, constants, enums). |
| `get_member` | One property / method / signal / constant / enum value with full description. |
| `list_members` | Names + signatures for members of a given kind. |
| `search_classes` | BM25 search over class names and brief descriptions. |
| `search_docs` | BM25 search over prose docs (tutorials, guides). |
| `get_page` | Parsed prose page content, LLM-friendly. |
| `list_toctree` | Walk the toctree rooted at a given path. |
| `resolve_ref` | Resolve an RST `:ref:` label to a docs path. |
| `resolve_redirect` | Look up legacy URLs in `_static/redirects.csv`. |
| `list_versions` | Enumerate available docs branches and which are cached. |
| `prepare_version` | Warm the cache for a version ahead of time. |

## Uninstall

macOS / Linux:

```bash
curl -fsSL https://raw.githubusercontent.com/Zei33/godot-mcp/main/uninstall.sh | bash
```

Windows:

```powershell
irm https://raw.githubusercontent.com/Zei33/godot-mcp/main/uninstall.ps1 | iex
```

Mirrors the installer: prompts which scope and clients to clean up, then optionally removes the install directory at `~/.local/share/godot-mcp`. The uninstaller never touches your godot-docs checkout and never deletes the client config files — it only removes the `godot-docs` server entry from each.

Non-interactive:

```bash
# Remove from all global client configs, keep the install dir:
curl -fsSL https://raw.githubusercontent.com/Zei33/godot-mcp/main/uninstall.sh \
  | GODOT_MCP_NONINTERACTIVE=1 bash

# Remove everything including the install dir:
curl -fsSL https://raw.githubusercontent.com/Zei33/godot-mcp/main/uninstall.sh \
  | GODOT_MCP_NONINTERACTIVE=1 GODOT_MCP_DELETE_INSTALL=1 bash
```

Per-project uninstall:

```bash
~/.local/share/godot-mcp/.venv/bin/python \
  ~/.local/share/godot-mcp/scripts/unconfigure.py \
  --scope project --project-dir ~/games/my-game \
  --clients claude,cursor
```

## Development

```bash
git clone https://github.com/Zei33/godot-mcp.git
cd godot-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ruff check .
pytest
```

## License

MIT.
