Unreal-mcp/README.md

# Unreal Engine Development Suite

AI-powered Unreal Engine development combining native C++ expertise, Blueprint workflows, and live editor interaction.

## What is it?

A complete development suite for Unreal Engine featuring:
- **CLAUDE.md** - Expert C++ code generation (no tools needed!)
- **Skills** - Blueprint workflows (bidirectional BP <-> C++)
- **MCP Server** - Runtime debugging + project intelligence

**Unique**: The only solution offering native C++ generation + bidirectional Blueprint workflows + live editor interaction.

---

## Architecture

```
CLAUDE.md (Expert Context)
    | Natural C++ generation
Skills (Blueprint Workflows)
    | Uses MCP when needed
MCP Server (Python - Runtime + Intelligence)
    -> get_spawnable_classes()
    -> spawn_actor()
    -> debug tools
```

---

## Features

### C++ Generation (via CLAUDE.md)
```
User: "Create an AWeapon with ammo and reload"
-> Claude generates production-ready C++ (no MCP tool!)
```

- Production-ready code that compiles first try
- Epic Coding Standards compliant
- Proper Unreal macros (UCLASS, UPROPERTY, UFUNCTION)
- Network replication patterns
- Blueprint-friendly code

### Blueprint Workflows (via Skills)

**`/blueprint-workflow bp-to-cpp`** - Optimize Blueprints
```
BP_Enemy.uasset -> Enemy.h/cpp (+120% performance)
```

**`/blueprint-workflow cpp-to-bp`** - Generate Blueprints
```
Weapon.h -> BP_Weapon (designer-friendly)
```

**`/blueprint-workflow transform`** - Round-Trip Magic
```
BP_Character -> Add dash ability -> BP_Character_v2
```

**`/blueprint-workflow analyze`** - Performance Analysis
```
Detects: Tick overhead, Blueprint casts, anti-patterns
```

### Live Editor (via MCP)

**Project Intelligence**
- `get_spawnable_classes()` - Discover what can be spawned
- `get_project_assets()` - List all project assets
- `scan_cpp_classes()` - Find C++ classes

**Scene Manipulation**
- `spawn_actor()` - Spawn actors in scene
- `get_scene_hierarchy()` - Get level structure
- `modify_actor_transform()` - Move/rotate/scale

**Debug & Profiling**
- `get_console_logs()` - Real-time logs
- `analyze_crash_dump()` - Crash analysis
- `profile_blueprint()` - Performance profiling

**Blueprint Operations**
- `create_blueprint_from_cpp()` - Generate BP from C++
- `compile_blueprint()` - Compile and get errors
- `execute_python_script()` - Run Python in editor

---

## Quick Start

### 1. Setup CLAUDE.md

The `CLAUDE.md` file contains expert Unreal C++ context. Claude reads it automatically.

Just ask Claude to generate code:
```
"Create a health component with damage and healing"
-> Code generated instantly!
```

### 2. Use Skills for Blueprints

```bash
# Analyze a Blueprint
/blueprint-workflow analyze BP_Enemy.uasset

# Convert Blueprint to C++
/blueprint-workflow bp-to-cpp BP_Enemy.uasset

# Generate Blueprint from C++
/blueprint-workflow cpp-to-bp Weapon.h

# Transform with AI
/blueprint-workflow transform BP_Character.uasset "add dash ability"
```

### 3. MCP for Runtime/Debug

The MCP server provides live editor interaction:
```
User: "Spawn 5 enemies in a circle"
-> Claude uses get_spawnable_classes()
-> Claude spawns actors via spawn_actor()
```

---

## Installation

### Prerequisites
- Python 3.11+
- Unreal Engine 5.3+ (optional, for MCP features)
- Claude Code

### Setup

```bash
# Clone repository
git clone https://github.com/AlexisTrouve/unreal-mcp.git
cd unreal-mcp

# Install with pip
pip install -e .

# Or with uv (recommended)
uv pip install -e .
```

### Configure Claude Code

The `.mcp.json` file is already included in the repo. Just update `UE_PROJECT_PATH`:

```json
{
  "mcpServers": {
    "unreal-mcp": {
      "command": "python",
      "args": ["-m", "unreal_mcp.server"],
      "env": {
        "UE_PROJECT_PATH": "C:/MyProject"
      }
    }
  }
}
```

Then restart Claude Code or run `/mcp` to reload MCP servers.

### Configure Unreal Editor (Optional - for runtime features)

1. Enable **Python Editor Script Plugin**
2. Enable **Python Remote Execution** in Project Settings
3. Restart Unreal Editor

---

## Usage Examples

### Example 1: Simple C++ Generation

```
User: "Create a rifle with 30 ammo and auto-reload"

Claude: [Reads CLAUDE.md]
        [Generates Rifle.h + Rifle.cpp]

-> Production-ready C++ code!
```

### Example 2: Blueprint Optimization

```
User: /blueprint-workflow analyze BP_AI.uasset

Result:
Performance Analysis: BP_AI

Issues Found:
- Event Tick: 23 operations/frame (HIGH COST)
  -> Suggestion: Replace with Events + Timer

Estimated Gain: +180% performance
```

### Example 3: Scene Manipulation

```
User: "Spawn 10 enemies in a circle"

Claude: [MCP: get_spawnable_classes()]
        "Found BP_Enemy"

        [MCP: spawn_actor() x 10]

        10 enemies spawned in a circle (500 unit radius)
```

---

## Why This Architecture?

### Simple Things Stay Simple

Generate C++ -> Just ask Claude (CLAUDE.md only)
- No tool overhead
- Instant response
- Natural conversation

### Complex Things Are Powerful

Blueprint workflows -> Skills handle complexity
- Multi-step processes
- Parsing .uasset files
- Code transformation

Runtime debugging -> MCP provides live access
- Real-time logs
- Scene manipulation
- Project intelligence

### Works Online and Offline

- **CLAUDE.md** - Always available
- **Skills** - Can generate scripts for later
- **MCP** - Gracefully degrades if editor closed

---

## Unique Differentiators

### vs Other MCP Servers
- **Them:** Runtime scene manipulation only
- **Us:** C++ generation + Blueprint workflows + Runtime

### vs NodeToCode
- **Them:** Blueprint -> C++ only (one-way)
- **Us:** Bidirectional BP <-> C++ + Round-trip transformations

### vs Bluepy
- **Them:** Text -> Blueprint only
- **Us:** Full workflows including C++ -> BP

---

## Documentation

- [**SPEC.md**](docs/SPEC.md) - Complete technical specification
- [**IMPLEMENTATION_PLAN.md**](docs/IMPLEMENTATION_PLAN.md) - Implementation roadmap
- [**REFERENCES.md**](docs/REFERENCES.md) - All research and sources
- [**CLAUDE.md**](CLAUDE.md) - Dev guide

---

## Status

**Current:** Architecture finalized, Python stack chosen

### Phase 0: Setup (Current)
- [x] Architecture defined
- [x] Documentation updated for Python
- [ ] pyproject.toml + structure
- [ ] MCP SDK setup

### Phase 1: Project Intelligence
- [ ] get_spawnable_classes()
- [ ] get_project_assets()
- [ ] Unreal connection

---

## Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## License

MIT License - see [LICENSE](LICENSE) for details

---

## Author

**Alexis Trouve**
- GitHub: [@AlexisTrouve](https://github.com/AlexisTrouve)

---

**Ready to supercharge your Unreal development!**