Unreal-mcp/docs/SPEC.md

# Unreal Engine MCP Server - Technical Specification

**Project** : AI-powered Unreal Engine development via MCP
**Target** : Unreal developers, AAA studios, technical designers
**Stack** : TypeScript + FastMCP + Claude API
**Timeline** : 2-3 weeks MVP

---

## 🎯 What is it?

MCP server enabling Claude Desktop to generate Unreal C++ code, Blueprint logic descriptions, debug issues, and optimize performance using AI.

**Key Features** :
✅ Generate Unreal C++ classes (.h + .cpp) from natural language
✅ Blueprint → C++ conversion for performance
✅ Create complete gameplay systems (weapons, abilities, inventory)
✅ Debug Unreal code with AI assistance
✅ Performance analysis (profiling, optimization)
✅ Network replication code generation
✅ Animation Blueprint logic

---

## 🔧 MCP Tools

### C++ Generation

**create_unreal_class** - Generate UE C++ class
```typescript
Input: "Create ACharacter subclass with sprint and crouch"
Output:
- MyCharacter.h (with UCLASS, UPROPERTY, UFUNCTION macros)
- MyCharacter.cpp (implementation)
```

**generate_gameplay_system** - Complete systems
```typescript
Input: "Create weapon system with ammo, reload, and firing modes"
Output:
- AWeapon.h/.cpp (weapon actor)
- UWeaponComponent.h/.cpp (component for characters)
- FWeaponData.h (data struct)
- Network replication setup
```

**generate_actor_component** - UActorComponent classes
```typescript
Input: "Health component with damage, healing, and death"
Output: UHealthComponent with proper UE architecture
```

---

### Blueprint Tools

**blueprint_to_cpp** - Convert BP logic to C++
```typescript
Input: Description of Blueprint logic or visual graph
Output: Optimized C++ equivalent with notes on performance gains
```

**generate_blueprint_library** - Blueprint Function Library
```typescript
Input: "Math utilities for gameplay (lerp, easing, etc.)"
Output: UBlueprintFunctionLibrary with static functions callable from BP
```

---

### AI-Powered Tools

**debug_unreal_code** - AI debugging
```typescript
Input: C++ code + crash logs + callstack
Output: Root cause + fixed code + prevention tips
```

**optimize_unreal_performance** - Performance analysis
```typescript
Input: Unreal C++ code + optional profiler data
Analysis:
- Tick() function overhead
- Blueprint vs C++ performance comparison
- Rendering optimization suggestions
- Memory leak detection
- Thread safety issues
- Network replication bandwidth
Output: Optimized code + profiling recommendations
```

**analyze_crash_dump** - Crash analysis
```typescript
Input: Crash log + callstack
Output: Probable causes + fix suggestions
```

---

### Network & Multiplayer

**generate_replicated_actor** - Network replication
```typescript
Input: "Replicated projectile with client prediction"
Output:
- C++ class with UPROPERTY(Replicated)
- GetLifetimeReplicatedProps implementation
- Client-side prediction code
- Server RPC functions
```

**optimize_network_bandwidth** - Replication analysis
```typescript
Input: Replicated class code
Output: Bandwidth optimization suggestions (relevancy, replication conditions)
```

---

### Advanced Tools

**generate_animation_system** - Animation logic
```typescript
Input: "Animation system with blending and state machines"
Output: Animation Blueprint logic description + C++ notify classes
```

**generate_subsystem** - UE Subsystem
```typescript
Input: "Game instance subsystem for save/load"
Output: UGameInstanceSubsystem class with proper lifecycle
```

**generate_slate_ui** - Slate UI code
```typescript
Input: "Custom editor widget for level design"
Output: Slate C++ code for editor customization
```

---

## 🏗️ Architecture

```
Unreal MCP Server
    ↓ Claude API
Generate C++ files locally
    ↓
User adds to Unreal project
    ↓
Compile in Unreal Editor
```

**Note** : No direct Unreal Editor integration - generates files only

---

## 💼 Use Cases

### Gameplay Programming
- Weapon systems
- Ability systems
- AI controllers
- Inventory systems

### Performance Optimization
- Blueprint → C++ migration
- Reduce tick overhead
- Network optimization
- Memory profiling

### Multiplayer Development
- Replicated actors
- Server RPCs
- Client prediction
- Authority validation

### Technical Design
- Custom editor tools
- Asset pipeline automation
- Blueprint libraries

---

## 📊 Target Market

- **5M+ Unreal developers** worldwide
- AAA game studios
- Indie teams using Unreal
- Technical designers
- Multiplayer game developers
- VR/AR experiences (Unreal is strong here)

**Revenue Potential** : €10k-50k/project (higher than Unity, more enterprise)

---

## 🚀 Implementation Timeline

**Week 1** : Core C++ generation (classes, components, basic systems)
**Week 2** : Blueprint tools (BP→C++, libraries)
**Week 3** : Advanced (networking, optimization, debugging)

**MVP** : 2-3 weeks

---

## 📝 Example Output Quality

### Input
```
"Create a replicated weapon with firing, ammo, and reload for multiplayer FPS"
```

### Output
```cpp
// Weapon.h
#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Weapon.generated.h"

UCLASS()
class MYGAME_API AWeapon : public AActor
{
    GENERATED_BODY()

public:
    AWeapon();

    virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override;

    UFUNCTION(BlueprintCallable, Category = "Weapon")
    void Fire();

    UFUNCTION(BlueprintCallable, Category = "Weapon")
    void Reload();

protected:
    virtual void BeginPlay() override;

    UFUNCTION(Server, Reliable, WithValidation)
    void ServerFire();

    UFUNCTION(NetMulticast, Unreliable)
    void MulticastPlayFireEffects();

    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Weapon")
    int32 MaxAmmo = 30;

    UPROPERTY(ReplicatedUsing = OnRep_CurrentAmmo, BlueprintReadOnly, Category = "Weapon")
    int32 CurrentAmmo;

    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Weapon")
    float FireRate = 0.1f;

    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Weapon")
    float ReloadTime = 2.0f;

private:
    UFUNCTION()
    void OnRep_CurrentAmmo();

    float LastFireTime = 0.0f;
    bool bIsReloading = false;

    void ConsumeAmmo();
    bool CanFire() const;
};

// Weapon.cpp
#include "Weapon.h"
#include "Net/UnrealNetwork.h"
#include "TimerManager.h"

AWeapon::AWeapon()
{
    PrimaryActorTick.bCanEverTick = false;
    bReplicates = true;
    CurrentAmmo = MaxAmmo;
}

void AWeapon::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
    Super::GetLifetimeReplicatedProps(OutLifetimeProps);

    DOREPLIFETIME_CONDITION(AWeapon, CurrentAmmo, COND_OwnerOnly);
}

void AWeapon::Fire()
{
    if (!CanFire()) return;

    if (HasAuthority())
    {
        ServerFire();
    }
    else
    {
        ServerFire();
        // Client prediction: play effects immediately
        MulticastPlayFireEffects();
    }
}

bool AWeapon::ServerFire_Validate()
{
    return CanFire();
}

void AWeapon::ServerFire_Implementation()
{
    if (!CanFire()) return;

    ConsumeAmmo();
    LastFireTime = GetWorld()->GetTimeSeconds();

    // Perform hit detection
    // ...

    MulticastPlayFireEffects();
}

void AWeapon::MulticastPlayFireEffects_Implementation()
{
    // Play muzzle flash, sound, etc.
    // ...
}

void AWeapon::Reload()
{
    if (bIsReloading || CurrentAmmo == MaxAmmo) return;

    bIsReloading = true;

    FTimerHandle ReloadTimer;
    GetWorld()->GetTimerManager().SetTimer(ReloadTimer, [this]()
    {
        CurrentAmmo = MaxAmmo;
        bIsReloading = false;
    }, ReloadTime, false);
}

void AWeapon::ConsumeAmmo()
{
    CurrentAmmo = FMath::Max(0, CurrentAmmo - 1);
}

bool AWeapon::CanFire() const
{
    const float CurrentTime = GetWorld()->GetTimeSeconds();
    return !bIsReloading
        && CurrentAmmo > 0
        && (CurrentTime - LastFireTime) >= FireRate;
}

void AWeapon::OnRep_CurrentAmmo()
{
    // Update UI
    // ...
}
```

**Quality** : Production-ready multiplayer code with proper replication, validation, client prediction

---

## 🎯 Unique Value

- ✅ Proper Unreal macros (UCLASS, UPROPERTY, UFUNCTION)
- ✅ Network replication out of the box
- ✅ Client prediction patterns
- ✅ Authority validation
- ✅ Follows Epic coding standards
- ✅ Optimized for performance
- ✅ Both .h and .cpp generated

---

## 💡 Why Separate from Unity?

**Completely different ecosystems** :
- Unity = C#, .NET, MonoBehaviour, ScriptableObject
- Unreal = C++, Blueprints, UCLASS/UPROPERTY macros, replication

**Different markets** :
- Unity = Indie, mobile, smaller teams
- Unreal = AAA, high-end graphics, larger budgets

**Separate projects = Better focus**

---

**Last Updated** : 2026-01-19