graph LR
    subgraph Claude Code
        A[MCP Client]
    end

    subgraph Python
        B[MCP Server<br/><i>FastMCP · stdio</i>]
        B --> C[Tool Modules<br/><i>14 modules · 56 tools</i>]
        C --> D[Remote Control Bridge<br/><i>httpx · circuit breaker</i>]
    end

    subgraph Unreal Engine 5.7
        E[Remote Control API<br/><i>localhost:30010</i>]
        E --> F[Editor Runtime]
        G[ViewportPerception<br/><i>localhost:30011</i>]
        G --> F
    end

    A -- stdio --> B
    D -- HTTP --> E
    C -. viewport capture .-> G

    style A fill:#5CFFDB,color:#05050D
    style B fill:#5CFFDB,color:#05050D
    style C fill:#12121F,color:#fff
    style D fill:#12121F,color:#fff
    style E fill:#FFCC33,color:#05050D
    style F fill:#12121F,color:#fff
    style G fill:#FFCC33,color:#05050D

git clone https://github.com/JosephOIbrahim/UnrealEngine_Bridge.git
cd UnrealEngine_Bridge
pip install -e .

{
  "mcpServers": {
    "unreal": {
      "command": "python",
      "args": ["-m", "ue_mcp.mcp_server"],
      "cwd": "/path/to/UnrealEngine_Bridge"
    }
  }
}

graph TB
    subgraph "Python Layer"
        MCP["MCP Server<br/><code>ue_mcp/mcp_server.py</code>"]
        Tools["Tool Modules (14)<br/><code>ue_mcp/tools/</code>"]
        RC["Remote Control Bridge<br/><code>remote_control/</code>"]
        Val["Validation & Sandbox<br/><code>_validation.py</code>"]
        Met["Metrics & Circuit Breaker<br/><code>metrics.py</code>"]
        Log["JSON Logger<br/><code>logging.py</code>"]
    end

    subgraph "File Bridge Layer"
        Orch["Bridge Orchestrator<br/><code>bridge_orchestrator.py</code>"]
        USD["USD Bridge<br/><code>usd_bridge/</code>"]
        FS[("~/.translators/<br/>bridge_state.usda<br/>heartbeat.json")]
    end

    subgraph "C++ Plugins (UE5)"
        Sub["UEBridgeSubsystem<br/><i>State machine · polling</i>"]
        Ed["BridgeEditorSubsystem<br/><i>File watching · process mgmt</i>"]
        VP["ViewportPerception<br/><i>GPU readback · ring buffer</i>"]
        RCAPI["Remote Control API<br/><i>REST · port 30010</i>"]
    end

    MCP --> Tools
    Tools --> Val
    Tools --> RC
    RC --> Met
    MCP --> Log
    RC -- "HTTP" --> RCAPI
    RCAPI --> Sub
    Orch --> USD
    USD --> FS
    FS --> Sub
    Sub --> Ed
    VP -- "HTTP :30011" --> Tools

    style MCP fill:#5CFFDB,color:#05050D
    style Tools fill:#5CFFDB,color:#05050D
    style RCAPI fill:#FFCC33,color:#05050D
    style Sub fill:#12121F,color:#fff
    style VP fill:#FFCC33,color:#05050D

UnrealEngine_Bridge/
├── ue_mcp/                        # MCP server package
│   ├── mcp_server.py              # FastMCP entry point (stdio)
│   ├── metrics.py                 # Telemetry + observability
│   ├── logging.py                 # Structured JSON logging
│   └── tools/                     # 14 tool modules (56 tools)
│       ├── actors.py              # Spawn, delete, list, transform
│       ├── scene.py               # Query, details, hierarchy
│       ├── spatial.py             # Ground trace, snap-to-ground, measure
│       ├── materials.py           # Create, set params, assign
│       ├── lighting.py            # Sky/atmosphere rig, time of day, mood presets
│       ├── blueprints.py          # Create, compile, components
│       ├── sequencer.py           # Animation / Level Sequence
│       ├── perception.py          # Viewport capture + diff
│       ├── editor.py              # Console, undo/redo, focus
│       ├── level.py               # Save, load, world info
│       ├── assets.py              # Find, create, delete
│       ├── mograph.py             # Cloner, Niagara, PCG
│       ├── properties.py          # Get/set UObject properties
│       ├── python_exec.py         # Sandboxed Python execution
│       ├── _validation.py         # Input sanitization + AST sandbox
│       ├── _codegen.py            # Shared code generation snippets
│       ├── _console_parsers.py    # Structured stat output parsers
│       └── _types.py              # Protocol types
│
├── remote_control/                # UE5 HTTP bridge package
│   ├── circuit_breaker.py         # CLOSED/OPEN/HALF_OPEN state machine
│   ├── async_client.py            # AsyncUnrealRemoteControl (MCP)
│   ├── sync_client.py             # UnrealRemoteControl (standalone)
│   ├── codegen.py                 # UE5 Python script generation
│   ├── execution.py               # File-based result polling
│   └── constants.py               # URLs, timeouts, pool config
│
├── usd_bridge/                    # USD file I/O package
│   ├── io.py                      # Atomic writes, locking, paths
│   ├── question.py                # Question read/write
│   ├── transition.py              # State transitions, finales
│   ├── signals.py                 # Behavioral signal extraction
│   ├── profile.py                 # Cognitive profiling + checksums
│   └── validation.py              # Bridge state validation
│
├── Plugins/
│   ├── UEBridge/                  # Core bridge C++ plugin
│   │   ├── UEBridgeRuntime/       # Subsystem, types, UI, style
│   │   └── UEBridgeEditor/        # File watching, process management
│   └── ViewportPerception/        # GPU readback, ring buffer, HTTP endpoint
│
├── bridge_orchestrator.py         # Game flow orchestration
├── remote_control_bridge.py       # Backward-compat shim → remote_control/
├── usd_bridge.py                  # Backward-compat shim → usd_bridge/
├── tests/                         # 415 tests (pytest)
├── pyproject.toml                 # Build config, dependencies, tooling
└── .github/workflows/ci.yml       # CI: Python 3.11/3.12, coverage, lint

pip install -e ".[dev]"
python -m pytest tests/ -v

python -m pytest tests/ --cov=ue_mcp --cov=remote_control --cov-report=term-missing

pip install ruff
ruff check ue_mcp/ remote_control/ tests/