/ue-mcp-native-cpp

name: ue-mcp-native-cpp
description: Use when writing or modifying native C++ UCLASSes in an Unreal project via ue-mcp. Covers create_cpp_class → write_cpp_file → live_coding_compile loop, when to use build vs Live Coding, and the add_module_dependency workflow. Pulls in any time the user asks to write a new native class, add a UPROPERTY, or implement a UFUNCTION.

ue-mcp native C++ authoring

The `project` tool wraps `GameProjectUtils::AddCodeToProject` and `ILiveCodingModule` so agents can author native C++ end-to-end without Python or the editor UI.

The authoring loop

1. **Pick a module.** `project(action="list_project_modules")` enumerates the project's native modules (name, host type, source path). Feed the module name into `create_cpp_class`. 2. **Create the class.** `project(action="create_cpp_class", className, parentClass?, moduleName?, classDomain?, subPath?)` writes `.h` and `.cpp` using the same engine template that `File → New C++ Class` uses. The class-name prefix (`A`, `U`, `F`) is derived from `parentClass` - pass the bare name (`"BotSpawner"`, not `"ABotSpawner"`). 3. **Inspect the generated files.** `project(action="read_cpp_header", headerPath=...)` and `project(action="read_cpp_source", sourcePath=...)`. Both paths are relative to `Source/` or absolute within it. 4. **Append declarations and bodies.** `project(action="write_cpp_file", path=..., content=...)` writes the full file contents (scoped to the `Source/` tree for safety). Read first, then write the amended content. 5. **Compile.**

• **New UCLASS** → `project(action="build")`. Live Coding doesn't reliably register brand-new UCLASSes; you need a full build and an editor restart. `create_cpp_class` surfaces this via `needsEditorRestart` in its response.
• **Existing UCLASS** (editing method bodies, adding UPROPERTYs, etc.) → `project(action="live_coding_compile", wait=true)`. Hot-patches method bodies without restart - the fast inner loop. Check `live_coding_status` first to confirm Live Coding is available and not already compiling.

Adding module dependencies

When you need a new module in a project's `Build.cs`:

• `project(action="add_module_dependency", moduleName=<target Build.cs>, dependency=<module to add>, access="public"|"private")`
• Deduplicates automatically. Creates the `AddRange` block if missing.
• Rebuild afterwards (`project(action="build")`).

Reading the engine source

When you need to know *how* UE does something, reach for engine source lookup:

• `project(action="read_engine_header", headerPath=...)` - parse a `.h` from `Engine/Source` (relative to `Engine/Source` or absolute).
• `project(action="find_engine_symbol", symbol=..., maxResults?)` - grep engine runtime headers for a symbol.
• `project(action="search_engine_cpp", query, tree?, subdirectory?, maxResults?)` - broader grep across `.h` / `.cpp` / `.inl` in `Runtime` / `Editor` / `Developer` / `Plugins` (or `all`).
• `project(action="list_engine_modules")` - enumerate modules in `Engine/Source/Runtime`.

Pitfalls

• **UCLASSes need UnrealBuildTool + MSVC/Clang** on the host. Same requirement as the editor's own Build menu.
• **`write_cpp_file` refuses writes outside `Source/`** and rejects extensions other than `.h` / `.cpp` / `.inl` / `.cs`.
• **Live Coding ≠ full build.** If behavior doesn't reflect your code changes, check whether you added a new UCLASS, UFUNCTION reflection macro, or UPROPERTY annotation - those usually need a full build.
• **Don't edit Intermediate/ or Binaries/.** These are regenerated.

Testing the new class

Once a class is compiled and registered, you can typically:

• `asset(action="read_properties", assetPath=...)` or `reflection(action="reflect_class", className=...)` to verify UE sees the UCLASS.
• `blueprint(action="create", parentClass="/Script/<Module>.<Class>")` to subclass it from a Blueprint.
• `level(action="place_actor", actorClass=...)` to drop an instance into the level.