unreal-python-api-rag

The Unreal Engine Python API as a retrieval / MCP knowledge server — so any AI agent writes correct, version-exact UE Editor Python instead of guessing.

LLMs hallucinate the unreal API (wrong class names, arg orders, deprecated calls). This grounds them: it introspects the API straight from your engine and serves it over MCP, so agents retrieve the real signatures/docs before they write code. Plugs into Forge, Claude, kiro, GPT — anything that speaks MCP.

Install

pip install git+https://github.com/stanlink-games/unreal-python-api-rag.git

Python 3.10+. Lexical search needs no extra deps; semantic search is the optional [semantic] extra.

1. Build the corpus (version-exact, from your engine)

Run inside the UE editor's Python (only there is import unreal available) — e.g. via ForgeMCP's run_editor_python or the editor console:

import unreal_api_rag.build as b
b.dump("/path/to/ue_api_5.8.jsonl")   # one JSON line per class/method/function

Ship that JSONL in src/unreal_api_rag/data/ and it's bundled with the package.

2. Serve it over MCP

unreal-api-rag mcp --host 127.0.0.1 --port 8780
# → http://127.0.0.1:8780/mcp/   (Streamable HTTP, stateless)

Tools:

• search_ue_api(query, k=8, kind=None) — rank matching classes/methods by relevance (signatures + docs). kind optionally filters to class / method / function.
• get_symbol(name) — exact lookup (e.g. unreal.EditorActorSubsystem or spawn_actor_from_class; case-insensitive, accepts the bare member name).

Query it from the terminal too (no server needed):

unreal-api-rag search set actor location
unreal-api-rag search sky atmosphere --kind class -k 5

3. Plug into an agent

Add it as an MCP server (e.g. Forge game.yaml):

mcp_servers:
  editor: http://127.0.0.1:8000/mcp
  clay:   http://127.0.0.1:8770/mcp/
  ue_api: http://127.0.0.1:8780/mcp/

Then the agent calls search_ue_api before writing UE Python, so it uses the real API — dramatically fewer tracebacks.

Design

• Corpus (data/*.jsonl) — one entry per API symbol, introspected from the engine (authoritative, version-pinned).

• Retrieval — dependency-light lexical ranking tuned for API queries:

  • a tokenizer that splits snake_case, CamelCase and letter/digit runs into words, so "set actor location" matches set_actor_location;
  • IDF weighting so discriminative terms (heightmap) beat ubiquitous ones (get);
  • field boosting — a name hit outweighs a docstring hit;
  • phrase/prefix bonuses + conservative plural stemming (materials→material).

  Optional embedding search ([semantic] extra) is a drop-in upgrade behind the same interface. Ranking quality is guarded by a benchmark suite that runs against the real 27k-symbol corpus.

• Server — stateless MCP Streamable HTTP, mounted at /mcp (same shape as ForgeMCP/Clay), so it's multi-worker + edge-hostable.

Hosted (mcp.stanl.ink/unreal, Cloudflare Workers + Vectorize) is tracked separately. This repo is the open, local-first core.

License

MIT.