Add complete specification and update README

README.md

@@ -4,7 +4,7 @@ AI-powered Unreal Engine development - Generate C++ code, Blueprint conversions,
 
 ## Status: Setup phase
 
-See ../UNREAL_MCP_SPEC.md for complete specifications.
+See [docs/SPEC.md](docs/SPEC.md) for complete specifications.
 
 ## Features
 

docs/SPEC.md

@@ -0,0 +1,395 @@
+# 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

tmpclaude-4a3e-cwd

@@ -0,0 +1 @@
+/c/Users/alexi/Documents/projects/freelance_planning/unreal-mcp