Godot Doc MCP
No description available
Ask AI about Godot Doc MCP
Powered by Claude · Grounded in docs
I know everything about Godot Doc MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Godot API Docs MCP Server
Offline Model Context Protocol (MCP) server that serves Godot Engine API documentation from a local doc/ folder. It provides fast search and retrieval of class/method/signal/property docs over stdio to any MCP‑capable client.
- Zero network at runtime (local docs only)
- Parses Godot 4.x XML docs; tolerates 3.x variants
- Builds an in‑memory search index with optional on‑disk warm start
- Exposes stable MCP tools for search and retrieval
Quick Start
Prereqs:
- Node.js 20+
- pnpm (recommended) or npm
Docs source:
-
Place Godot XML docs under
./doc/classes/*.xml(this repo already includes a representative set for local testing). PointGODOT_DOC_DIRelsewhere if you keep docs outside the repo. -
Need fresh docs from an existing Godot checkout? Run the editor binary with
--doctoolpointing at your targetdoc/classesfolder (add--headlessfor CI/servers). If you don't already have the CLI binary on yourPATH, follow the official command line instructions to install or alias it (package install, manual build, or exporting the editor).# inside the upstream Godot repo after building the editor, or anywhere godot is on PATH godot --doctool ./doc/classes --headlessThe command exports the full XML set (classes, signals, etc.). Repeat whenever you update your Godot source to keep docs in sync.
Run (stdio):
# from repo root
export GODOT_DOC_DIR=./doc
pnpm install
pnpm dev # hot reload via tsx, runs the stdio MCP server
# or run without watch
pnpm start
Smoke tests and examples:
# Lightweight end‑to‑end checks
pnpm test
# Example local smoke against the parser/index/tools (no external clients)
pnpm run smoke:local
# Minimal MCP client demo (stdio handshake + tool calls)
pnpm run smoke:mcp
# Manual, step‑by‑step stdio session (prints what to send/expect)
node --import tsx scripts/manual-stdio.mjs
What This Is
This project turns the Godot docs you already have locally into an MCP server so LLM tooling can search and retrieve authoritative API information offline. The server:
- Parses
doc/classes/*.xmlinto typed objects - Builds a compact inverted index covering class names and text fields
- Serves MCP tools over stdio for search and direct lookup
- Optionally writes
.cache/godot-index.jsonfor warm starts
Non‑goals (for now): authoring docs, live web fetching, or general web search.
Repository Layout
server/— MCP server implementation (TypeScript)server/src/index.ts— bootstrap/containerserver/src/cli.ts— CLI (stdio by default)server/src/mcp/stdio.ts— MCP wiring: tools/resources/promptsserver/src/parser/xmlParser.ts— Godot XML → typed docsserver/src/indexer/— index build + persistence (if present)server/src/search/searchEngine.ts— in‑memory searchserver/src/resolver/— class/symbol resolution helpersserver/src/types.ts— shared TypeScript interfaces
server/test/— unit tests (parser, index, resolver, tools, server)doc/— read‑only Godot XML docs (classes, schema, tools).cache/— generated index file (ignored in VCS)scripts/— local utilities and MCP client demos
Configuration
Environment variables:
GODOT_DOC_DIR(default./doc) — Root that containsclasses/.GODOT_INDEX_PATH(default./.cache/godot-index.json) — On‑disk index for warm start.MCP_SERVER_LOG(defaultinfo) —silent|error|warn|info|debug.MCP_STDIO(default1) — Use stdio transport.
Examples:
export GODOT_DOC_DIR=$HOME/src/godot/docs
export MCP_SERVER_LOG=debug
pnpm start
Using With an MCP Client
Transport: stdio (process pipes). Start the server and configure your MCP client to launch it with the working directory set to this repo and environment variables as needed.
Resources and tools are exposed with stable names and return shapes. The following examples show the intent; exact envelopes depend on your client SDK.
Search:
{
"tool": "godot_search",
"args": { "query": "Vector2.x", "limit": 5 }
}
Get a class (optionally include ancestors):
{
"tool": "godot_get_class",
"args": { "name": "Node", "includeAncestors": true, "maxDepth": 2 }
}
Get a symbol by qualified name:
{
"tool": "godot_get_symbol",
"args": { "qname": "Button.pressed" }
}
List classes by prefix:
{
"tool": "godot_list_classes",
"args": { "prefix": "Visu", "limit": 20 }
}
URIs your client can open as resources:
godot://class/<ClassName>{?ancestors,maxDepth}godot://symbol/<ClassName>/<kind>/<name>godot://search?q=<q>&kind=<kind>
Optional helper prompt exposed as an MCP Prompt:
how_to_use_godot_docs— Teaches the model to callgodot_searchfirst, thengodot_get_*.
Tool Reference
-
godot_search- params:
{ query: string, kind?: "class"|"method"|"property"|"signal"|"constant", limit?: number } - returns:
Array<{ uri: string, name: string, kind: string, score: number, snippet?: string }>
- params:
-
godot_get_class- params:
{ name: string, includeAncestors?: boolean, maxDepth?: number } - returns:
GodotClassDoc | { inheritanceChain: string[], classes: GodotClassDoc[], warnings?: string[] }
- params:
-
godot_get_symbol- params:
{ qname: string } // e.g., "Node._ready", "Vector2.x", "Button.pressed" - returns:
GodotSymbolDoc
- params:
-
godot_list_classes- params:
{ prefix?: string, limit?: number } - returns:
string[]
- params:
Type shapes (subset):
export interface GodotMethod {
name: string;
returnType?: string;
arguments: Array<{ name: string; type?: string; default?: string }>;
description?: string;
qualifiers?: string[]; // e.g., virtual, const, static
}
export interface GodotProperty {
name: string;
type?: string;
default?: string;
description?: string;
}
export interface GodotSignal {
name: string;
arguments: Array<{ name: string; type?: string }>;
description?: string;
}
export interface GodotConstant { name: string; value?: string; description?: string }
export interface GodotClassDoc {
name: string;
inherits?: string;
category?: string;
brief?: string;
description?: string;
methods: GodotMethod[];
properties: GodotProperty[];
signals: GodotSignal[];
constants: GodotConstant[];
themeItems?: Record<string, string[]>; // optional, Godot 4.x
annotations?: string[]; // optional
since?: string; // Godot version detected
}
export type GodotSymbolDoc =
| ({ kind: 'method'; className: string } & GodotMethod)
| ({ kind: 'property'; className: string } & GodotProperty)
| ({ kind: 'signal'; className: string } & GodotSignal)
| ({ kind: 'constant'; className: string } & GodotConstant);
How It Works
Parsing:
- Uses a tolerant XML parser to handle entities and CDATA
- Preserves inline code spans and normalizes whitespace
- Treats missing sections as empty arrays
Search index:
- Tokenizes names (
Camera3D→camera,3d,camera3d) - Tokenizes text fields; lowercases; removes stopwords; keeps 2+ char tokens
- Scores via a BM25‑ish heuristic; boosts exact class and symbol matches
- Stores postings in memory; persists to
.cache/godot-index.json
Performance targets:
- Cold start (parse + index) ≤ 3s on a modern laptop for typical Godot 4 docs
- Search p95 ≤ 20ms (simple) / ≤ 60ms (multi‑term)
- Memory overhead ≤ 150MB for the in‑memory index
Development
Install and run:
pnpm install
pnpm dev
Type checking and formatting:
pnpm run check:biome
pnpm run format:check
pnpm run format --write
Tests:
pnpm test
Code style:
- TypeScript strict mode; ESM modules
- Prefer composition; small, testable modules
- Logging is behind a minimal wrapper, controllable via
MCP_SERVER_LOG
Adding or changing MCP tools:
- Keep tool names and return schemas stable once published
- Update this README and
AGENTS.mdif you introduce new tools or change shapes
Troubleshooting
-
Invalid
GODOT_DOC_DIR- Symptom: startup fails with a clear message
- Fix: ensure the path exists and contains
classes/XML files
-
Missing class or symbol
- Symptom:
NOT_FOUNDtool error with suggestions - Fix: check spelling/case; use
godot_searchfirst to confirm availability
- Symptom:
-
XML parse error
- Symptom: error includes filename and, when available, line/column
- Fix: validate the XML; re‑sync docs from the Godot repo
-
Slow cold start
- Cause: very large docs set or constrained disk
- Mitigation: keep
.cache/godot-index.jsonfor warm starts
Security & Privacy
- Reads only within
GODOT_DOC_DIRand.cache/ - Makes no network calls during normal operation
- Treats docs as plain text; never executes embedded code
FAQ
-
Where do the docs come from?
- From a local copy of the official Godot docs (XML). Point
GODOT_DOC_DIRto your copy; by default the server uses./doc.
- From a local copy of the official Godot docs (XML). Point
-
Does this support Godot 3.x docs?
- Yes, with graceful handling of older schema differences (some sections may be missing).
-
Which clients can use this?
- Any MCP‑compatible client that can launch a stdio server process and call tools.
-
Can I rebuild the index when docs change?
- Yes. Restart the server after updating XML files. A file watcher may be added in the future.
Credits
Godot Engine and documentation are trademarks of their respective owners. This project is not affiliated with or endorsed by the Godot project.
