Metadata-Version: 2.4
Name: unreal-api-mcp
Version: 0.1.0
Summary: MCP server providing ground-truth Unreal Engine API documentation -- prevents AI hallucination of signatures, includes, and deprecated APIs
Project-URL: Homepage, https://github.com/Codeturion/unreal-api-mcp
Project-URL: Repository, https://github.com/Codeturion/unreal-api-mcp
Project-URL: Issues, https://github.com/Codeturion/unreal-api-mcp/issues
Author-email: Codeturion <fuatcankoseoglu@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Codeturion
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,api,claude,cursor,documentation,game-development,mcp,mcp-server,model-context-protocol,ue5,unreal-engine,windsurf
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.8.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: ingest
Description-Content-Type: text/markdown

# unreal-api-mcp

<!-- mcp-name: io.github.Codeturion/unreal-api-mcp -->

[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/servers/io.github.Codeturion/unreal-api-mcp)
[![PyPI Version](https://img.shields.io/pypi/v/unreal-api-mcp.svg)](https://pypi.org/project/unreal-api-mcp/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/unreal-api-mcp.svg)](https://pypi.org/project/unreal-api-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

**MCP server that gives AI agents accurate Unreal Engine C++ API documentation. Prevents hallucinated signatures, wrong `#include` paths, and deprecated API usage.**

Supports **UE 5.5**, **5.6**, and **5.7** with separate databases for each version. Works with Claude Code, Cursor, Windsurf, or any MCP-compatible AI tool. No Unreal Engine installation required.

## Quick Start

```bash
pip install unreal-api-mcp
```

Add to your MCP config (`.mcp.json`, `mcp.json`, or your tool's MCP settings), setting `UNREAL_VERSION` to match your project:

```json
{
  "mcpServers": {
    "unreal-api": {
      "command": "unreal-api-mcp",
      "args": [],
      "env": {
        "UNREAL_VERSION": "5.5"
      }
    }
  }
}
```

Valid values: `"5.5"`, `"5.6"`, or `"5.7"`. On Windows, use `unreal-api-mcp.exe`.

On first run the server downloads the correct database (~43-48 MB) to `~/.unreal-api-mcp/`.

## How It Works

1. **Version detection.** The server figures out which UE version to serve:

| Priority | Source | Example |
|----------|--------|---------|
| 1 | `UNREAL_VERSION` env var | `"5.5"`, `"5.6"`, `"5.7"` |
| 2 | `UNREAL_PROJECT_PATH` | Reads `.uproject` `EngineAssociation` field, maps `5.5.1` to `"5.5"` |
| 3 | Default | `"5.7"` |

2. **Database download.** If the database for that version isn't cached locally, it downloads from GitHub (one time).

3. **Serve.** All tool calls query the version-specific SQLite database. Exact lookups return in <1ms, searches in <5ms.

Each version has its own database with the correct signatures, deprecation warnings, and member lists for that release.

## Tools

| Tool | Purpose | Example |
|------|---------|---------|
| `search_unreal_api` | Find APIs by keyword | "character movement", "spawn actor" |
| `get_function_signature` | Exact signature with parameters and return type | `AActor::GetActorLocation` |
| `get_include_path` | Resolve `#include` for a type | "ACharacter" -> `#include "GameFramework/Character.h"` |
| `get_class_reference` | Full class reference card | "APlayerController" -> all functions/properties/delegates |
| `get_deprecation_warnings` | Check if an API is obsolete | "K2_AttachRootComponentTo" -> Use AttachToComponent() instead |

## Coverage

All Engine Runtime, Editor, Developer modules, plus built-in plugins (Enhanced Input, Gameplay Abilities, Common UI, Niagara, Chaos, and hundreds more).

| Version | Records | Deprecated | Modules | DB Size |
|---------|---------|------------|---------|---------|
| UE 5.5 | 99,591 | 3,689 | 860 | 43 MB |
| UE 5.6 | 109,530 | 4,205 | 981 | 48 MB |
| UE 5.7 | 114,724 | 4,409 | 1,019 | 50 MB |

Record breakdown (UE 5.7):

| Type | Count | Source |
|------|-------|--------|
| Classes (UCLASS) | 10,075 | `AActor`, `ACharacter`, `UGameplayStatics`, ... |
| Structs (USTRUCT) | 9,014 | `FHitResult`, `FVector`, `FTransform`, ... |
| Enums (UENUM) | 3,475 | `EMovementMode`, `ECollisionChannel`, ... |
| Functions (UFUNCTION) | 23,414 | Signatures with params, return types, specifiers |
| Properties (UPROPERTY) | 66,340 | Types, specifiers, doc comments |
| Delegates | 2,406 | Dynamic multicast, delegate declarations |

Does **not** cover third-party plugins or marketplace assets. For those, rely on project source.

## Benchmarks

In a 10-step character movement development workflow, MCP consistently uses far fewer tokens than agents working with grep and file reads:

![Total Tokens - 10-Step Development Workflow](https://raw.githubusercontent.com/Codeturion/unreal-api-mcp/master/docs/images/01-total-tokens.png)

The gap holds across every question type. MCP wins on simple include lookups and complex class references alike:

![Hallucination Risk: Grep+Read vs MCP](https://raw.githubusercontent.com/Codeturion/unreal-api-mcp/master/docs/images/04-hallucination.png)

Even in a realistic hybrid workflow where MCP results are followed up with targeted file reads, it still uses significantly fewer tokens than a skilled agent working without MCP:

![Realistic Workflow: MCP + Targeted Read](https://raw.githubusercontent.com/Codeturion/unreal-api-mcp/master/docs/images/03-hybrid.png)

"Without MCP" estimates assume full or partial file reads. A skilled agent with good tooling may use fewer tokens than shown. What MCP guarantees is a correct, structured answer in one call every time.

<details>
<summary>Per-question breakdown</summary>

![Token Cost Per Question](https://raw.githubusercontent.com/Codeturion/unreal-api-mcp/master/docs/images/02-per-step.png)

</details>

<details>
<summary>Query latency</summary>

Measured on UE 5.7 database (114,724 records), 50 iterations per query:

| Query | Median | p95 |
|-------|--------|-----|
| Exact FQN lookup (`get_function_signature`) | <1ms | <1ms |
| FTS search: specific function name | <1ms | <1ms |
| FTS search: keyword ("spawn actor") | 1ms | 1ms |
| Include path resolution | 2ms | 2ms |
| Class reference (full member list) | 22ms | 23ms |
| Deprecation check | 24ms | 25ms |

</details>

<details>
<summary>Accuracy</summary>

| Test | Result |
|------|--------|
| Search top-1 relevance (8 common queries) | 100% |
| Include path resolution (6 key classes) | 100% |
| Function signature accuracy (3 common functions) | 100% |
| Class reference completeness (2 classes) | 100% |
| Deprecation detection (1 deprecated API) | 100% |

Ranking uses BM25 with tuned column weights (member name 10x, class name 5x) plus core module boosting to ensure `AActor::GetActorLocation` ranks above niche plugin APIs.

</details>

## CLAUDE.md Snippet

Add this to your project's `CLAUDE.md` (or equivalent instructions file). **This step is important.** Without it, the AI has the tools but won't know when to reach for them.

```markdown
## Unreal Engine API Lookup (unreal-api MCP)

Use the `unreal-api` MCP tools to verify UE C++ API usage instead of guessing. **Do not hallucinate signatures or #include paths.**

| When | Tool | Example |
|------|------|---------|
| Unsure about a function's parameters or return type | `get_function_signature` | `get_function_signature("AActor::GetActorLocation")` |
| Need the `#include` for a type | `get_include_path` | `get_include_path("ACharacter")` |
| Want to see all members on a class | `get_class_reference` | `get_class_reference("UCharacterMovementComponent")` |
| Searching for an API by keyword | `search_unreal_api` | `search_unreal_api("spawn actor")` |
| Checking if an API is deprecated | `get_deprecation_warnings` | `get_deprecation_warnings("K2_AttachRootComponentTo")` |

**Rules:**
- Before writing a UE API call you haven't used in this conversation, verify the signature with `get_function_signature`
- Before adding a `#include`, verify with `get_include_path` if unsure
- Covers: all Engine Runtime/Editor modules, built-in plugins (Enhanced Input, GAS, CommonUI, Niagara, etc.)
- Does NOT cover: third-party plugins or marketplace assets
```

## Setup Details

<details>
<summary>Auto-detect version from .uproject</summary>

Instead of setting `UNREAL_VERSION`, you can point to your Unreal project. The server reads the `EngineAssociation` field from your `.uproject` file:

```json
{
  "mcpServers": {
    "unreal-api": {
      "command": "unreal-api-mcp",
      "args": [],
      "env": {
        "UNREAL_PROJECT_PATH": "F:/Unreal Projects/MyProject"
      }
    }
  }
}
```

</details>

<details>
<summary>Environment variables</summary>

| Variable | Purpose | Example |
|----------|---------|---------|
| `UNREAL_VERSION` | UE version to serve | `5.5`, `5.6`, `5.7` |
| `UNREAL_PROJECT_PATH` | Auto-detect version from .uproject | `F:/Unreal Projects/MyProject` |
| `UNREAL_INSTALL_PATH` | Override UE install path (for `ingest` only) | `H:/UE_5.6` |

</details>

<details>
<summary>Building databases locally</summary>

If you want to build a database from your own Unreal Engine installation instead of downloading:

```bash
# Build for a specific version
python -m unreal_api_mcp.ingest --unreal-version 5.6 --unreal-install "H:/UE_5.6"
python -m unreal_api_mcp.ingest --unreal-version 5.5 --unreal-install "H:/UE_5.5"
```

Databases are written to `~/.unreal-api-mcp/unreal_docs_{version}.db` by default.

</details>

<details>
<summary>Project structure</summary>

```
unreal-api-mcp/
├── src/unreal_api_mcp/
│   ├── server.py          # MCP server (5 tools)
│   ├── db.py              # SQLite + FTS5 database layer
│   ├── version.py         # Version detection + DB download
│   ├── header_parser.py   # Parse Unreal C++ headers (UCLASS, UFUNCTION, etc.)
│   ├── unreal_paths.py    # Locate UE installs + discover modules
│   └── ingest.py          # CLI ingestion pipeline
└── pyproject.toml
```

Databases are stored in `~/.unreal-api-mcp/` (downloaded on first run).

</details>

## Troubleshooting

| Problem | Fix |
|---------|-----|
| "Could not download UE X database" | Check internet connection. Or build locally: `python -m unreal_api_mcp.ingest --unreal-version 5.6 --unreal-install H:/UE_5.6` |
| Wrong API version being served | Set `UNREAL_VERSION` explicitly. Check stderr: `unreal-api-mcp: serving UE <version>` |
| Server won't start | Check `python --version` (needs 3.10+). Check path: `which unreal-api-mcp` or `where unreal-api-mcp` |
| Third-party plugins return no results | Marketplace/third-party plugins are not indexed. Only built-in Engine and Plugin APIs are covered. |

---

## Contact

Need a custom MCP server for your engine or framework? I build MCP tools that cut token waste and prevent hallucinations for AI-assisted game development. If you want something similar for your team's stack, reach out.

fuatcankoseoglu@gmail.com

## License

MIT
