# ue-codegraph-mcp

**MCP server for indexing and querying Unreal Engine C++ codebases.**

Indexes your UE project's `Source/` directory into a local SQLite database and exposes 17 MCP tools so Claude Code can answer questions about call graphs, class structure, `#include` dependencies, and Blueprint-exposed symbols — without reading raw files every time.

---

## Features

- **Call graph analysis** — find all callers of a function, trace call chains from A → B
- **Class analysis** — methods, fields, base classes, UE macros (`UCLASS`, `UPROPERTY`, `UFUNCTION`)
- **Blueprint exposure** — list all `BlueprintCallable` functions and `BlueprintReadWrite` properties
- **`#include` dependency graph** — what a file includes, and what includes it (transitive support)
- **Symbol search** — FTS5 full-text search across 40k+ symbols with prefix matching
- **Incremental indexing** — re-indexes only changed files (hash + mtime based)
- **Standalone CLI** — use `ue-graph` commands directly from the terminal without Claude

---

## Prerequisites

| Requirement | Version | Check |
|---|---|---|
| **Node.js** | **22 LTS** | `node --version` |
| npm | 9+ | `npm --version` |
| Claude Code | latest | `claude --version` |

> **Use an even-numbered Node.js release (20, 22 LTS or 24).** Odd-numbered "Current" releases (v23, v25, etc.) are incompatible with tree-sitter's native bindings and will fail to parse files. Node 24 needs `better-sqlite3` 12+ (this repo ships 13); the older 11.x crashes the process under garbage collection on Node 24.

---

## Installation

### 1. Install Node.js 22 LTS

Download from https://nodejs.org (click the **LTS** tab) or use winget:

```powershell
winget install OpenJS.NodeJS.LTS
```

### 2. Run `setup.bat`

```powershell
cd C:\path\to\ue-codegraph-mcp
.\setup.bat
```

`setup.bat` will:
1. Verify Node.js 22 LTS
2. Install `node-gyp` globally (needed for native module builds)
3. Run `npm install` (builds tree-sitter and better-sqlite3 from source)
4. Run `npm link` to register the `ue-graph` CLI globally
5. Optionally index your project and generate `mcp.json`

> If the native build fails, install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with the **C++ build tools** workload, then re-run `setup.bat`.

### 3. Index your project

```powershell
ue-graph index "G:\YourProject\Source" my-project
```

Output:
```
Indexing G:\YourProject\Source as "my-project" (project)...

Done!
  Files:   1784  (new: 1784, changed: 0)
  Symbols: 45623
  Macros:  3210
  Calls:   28450
  Includes: 9120
  Time: 32.5s
```

### 4. Register with Claude Code

```powershell
claude mcp add -s user ue-codegraph node "C:\path\to\ue-codegraph-mcp\build\index.js"
```

Verify with `claude mcp list`. Then start Claude Code in your project directory and run `/mcp` to confirm the server is connected.

---

## Usage in Claude Code

Once registered, Claude automatically uses the MCP tools when you ask natural-language questions:

```
"Find everything that calls SetHP"
"Trace the call chain from DamageMyPlayer to ApplyDamage"
"Analyze the UAMirLuaManager class"
"Which files include AMirCharacter.h?"
"Show all BlueprintCallable functions in UAMirAbilityComponent"
```

---

## CLI Commands

Use `ue-graph` directly from the terminal without Claude Code.

### Index management

```powershell
ue-graph index <path> [name]     # Index a codebase
ue-graph status                  # Show indexed codebases and stats
ue-graph reindex <file...>       # Re-index specific files (deleted files are removed)
ue-graph watch [path]            # Watch for edits and re-index changed files automatically
ue-graph ui [--port N]           # Open the visual explorer in your browser
ue-graph delete <id|name|all>    # Remove a codebase from the index
```

### Call graph

```powershell
ue-graph callers SetHP                       # Who calls SetHP?
ue-graph callees BeginPlay                   # What does BeginPlay call?
ue-graph chain DamageMyPlayer SetHP          # Call path from A to B
```

### Class analysis

```powershell
ue-graph analyze UAMirLuaManager             # Methods, fields, UE macros
ue-graph hierarchy AAMirCharacter            # Inheritance tree (up + down)
ue-graph blueprint UAMirLuaManager           # Full Blueprint interface
```

### Search

```powershell
ue-graph search "SetHP"                      # FTS symbol search
ue-graph code "CL2LG_MY_CHARACTER_SPAWN_REQ" # Code text pattern search
ue-graph refs DamageMyPlayer                 # Where is this symbol used?
```

### UE Macros

```powershell
ue-graph macros UFUNCTION                    # All UFUNCTION macros
ue-graph macros UFUNCTION BlueprintCallable  # Filter by specifier
ue-graph deps "G:\...\MyActor.h"            # #include dependency graph
```

---

## Incremental indexing

Edits are applied in proportion to what changed, not to the size of the codebase.

- **Change detection** compares size, mtime and content hash, so only touched files are parsed.
- **File watcher**: while the MCP server runs (or `ue-graph watch`), saving a `.h`/`.cpp` re-indexes just that file
  (debounced). On start-up the server also catches up on edits made while it was off.
  Disable with `UE_CODEGRAPH_WATCH=0`.
- **Scoped linking**: after a re-parse only the affected rows are re-linked: the file's own calls, references,
  base classes and includes, plus unresolved rows elsewhere that point at a symbol name that was re-created.
  Files keep their row id on re-index, so `#include` links from other files stay valid.
- **Include-aware resolution**: when several symbols share a name (`Tick`, `BeginPlay`...), a call resolves to
  the one in the same file, then the paired header, then the include closure (3 hops), instead of an arbitrary match.
  If a file's `#include` list changes, the files that include it (2 hops) are re-ranked.
- **Parallel parsing**: large batches are parsed on worker threads (`UE_CODEGRAPH_WORKERS=N`, `0` = single thread)
  while the main thread writes the previous batch to SQLite.
- When more than 30% of files changed (or on the first index) a full link pass runs instead.

Parsing is file-local, so a header edit does **not** require re-parsing its includers. Their links are refreshed
instead, which is what the scoped linking above does.

Rough numbers on a synthetic 3000-header project: full index 17 s single-threaded, 5.5 s with 6 workers;
re-indexing one saved file takes about 50 ms.

## Visual explorer

```powershell
ue-graph ui            # http://localhost:4177
```

or ask Claude to call the `open_viewer` tool. Everything runs locally (bound to 127.0.0.1) and the page refreshes by
itself when the index changes.

| Tab | Shows |
|---|---|
| Overview | Counts, link quality, symbols by kind, UE macros, biggest classes, most-called functions, most-included headers |
| Class hierarchy | Ancestors and descendants of a class (engine/unindexed bases appear as dashed nodes) |
| Call graph | Callers and callees of a function, up to 4 levels |
| Includes | `#include` neighbourhood of a file in both directions |
| Modules | Folder-level dependency map (aggregated `#include` counts) |

Click a node for details (members, UE macros, signature, includes), double-click to re-center, drag to rearrange,
scroll to zoom. Purple dot = carries a UE macro (`UCLASS`...), green dot = Blueprint-exposed.

---

## MCP Tools Reference

| Tool | Description |
|---|---|
| `init_codebase` | Index a UE source directory |
| `get_index_status` | Show registered codebases and stats |
| `reindex_file` | Re-index specific files (normally automatic, see below) |
| `open_viewer` | Start the local web viewer and return its URL |
| `find_callers` | Find all callers of a function |
| `find_callees` | Find all functions called by a function |
| `find_call_chain` | Shortest call path from function A to B |
| `get_file_dependencies` | `#include` graph (includes + included-by) |
| `analyze_class` | Class methods, fields, UE macros, base classes |
| `get_class_hierarchy` | Ancestor and descendant class tree |
| `find_ue_macros` | Search UE macros by type and specifier |
| `get_macro_specifiers` | Get specifiers for a specific symbol's macro |
| `find_blueprint_exposed` | All `BlueprintCallable`/`BlueprintReadWrite` symbols |
| `get_blueprint_interface` | Full Blueprint interface of a class |
| `search_symbols` | FTS5 symbol search |
| `search_code` | Code text pattern search |
| `find_references` | Cross-reference lookup |

---

## Known Limitations

| Issue | Workaround |
|---|---|
| `analyze_class` may fail on 3000+ line headers (forward declarations) | Use Grep + Read instead |
| Parent class lookup broken when `GENERATED_BODY()` is the only inheritance hint | Use `grep 'class Foo.*public'` |
| `find_callees` can mix results when multiple classes share the same method name | Calls are ranked by include closure, but without type information it can still pick the wrong overload |
| Databases indexed before the scoped-linking release attach `UCLASS`/`USTRUCT` to the class constructor | Delete the codebase and index it once more (`ue-graph delete <name>`) |

---

## Troubleshooting

**All files fail with `Invalid argument` during indexing**
→ Wrong Node.js version. Install Node.js 22 LTS, delete `node_modules/`, re-run `setup.bat`.

**Native build errors (`node-gyp`, `better-sqlite3`)**
→ Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (C++ workload), then re-run `setup.bat`.

**MCP server not visible in Claude Code**
→ Confirm the path in `claude mcp list` is an absolute path. Restart Claude Code and run `/mcp`.

---

## License

MIT