Unreal_mcp: Instructions file for Codex

PROJECT KNOWLEDGE BASE

MCP tooling for Unreal Engine 5.0-5.8 Preview. Server package version 0.5.30; bridge plugin version 0.5.30 (separate .uplugin). Two user-facing surfaces: a TypeScript stdio MCP server, and the bridge plugin's WebSocket transport and optional native /mcp HTTP/SSE transport.

Area-specific guidance lives in nested AGENTS.md files (see AREA GUIDES below). This root file is the workspace-wide view; do not duplicate their detail here.

STRUCTURE

./
|-- src/                         # TypeScript MCP server, NodeNext ESM (strict)
|   |-- cli.ts index.ts config.ts constants.ts server-setup.ts   # entry + facades
|   |-- unreal-bridge*.ts        # UnrealBridge (connection/console/properties/system) at src root
|   |-- automation/         (45) # WebSocket CLIENT: handshake, request tracking/correlation, frames
|   |-- config/              (1) # class-aliases.ts ONLY (DIR; env schema is src/config.ts — name collision)
|   |-- gateway/             (4) # gateway manifest DATA + loader; 2 of 4 are *.generated.*
|   |-- handlers/            (2) # MCP RESOURCE handlers — NOT tool logic (see tools/handlers)
|   |-- resources/          (18) # resource providers behind handlers/ (actors, assets, levels, editor state)
|   |-- server/             (13) # SDK construction, stdio lifecycle, tool/resource registry shards
|   |   |-- gateway/        (27) # gateway search/describe/execute ROUTING — NOT src/gateway
|   |   `-- mcp-primitives/ (48) # resources/prompts/completions/subscriptions/progress + client profiles, configure store
|   |-- services/            (9) # health-monitor, metrics-server (Prometheus), readiness, telemetry
|   |-- tools/                   # catalog/ (contracts), handlers/<38 domains>/ (action logic),
|   |                            #   orchestration/, dynamic/, editor/, level/, schemas/
|   |   `-- definitions/shared/  # ONLY 2 files (tool-definition.ts, action-sets.ts) — NOT a contract source
|   |-- types/ utils/            # utils: commands config interaction logging paths responses serialization validation
|-- plugins/McpAutomationBridge/ # the ONLY plugin; editor-only UE (bridge + native MCP + Fab adapter)
|   |-- Source/McpAutomationBridge/{Public (17), Private/}
|   |   Private/: Core(36) Domains(1120 / 66 domains) Foundation(96) MCP(166) Safety(21) Transport(23) Tests(29) UI(2)
|   |   Core/: Compatibility Errors Module Requests Security Settings Subsystem
|   |   MCP/:  DynamicTools Execute Gateway Generated Primitives Protocol Registry Resources Routing Tools Transport
|   `-- Source/McpAutomationBridgeFab/     # Fab asset-store adapter module (delay-loaded, optional)
|       Private/: Fab browser bridge, import watcher, add-to-project, search, details, downloads
|-- tests/                       # Vitest unit tests + custom MCP integration runner
|-- scripts/                     # generators, packaging, sync, smoke, cleanup
|-- docs/                        # handler maps, testing, protocol, plugin extension
`-- .github/workflows/           # pinned CI, release, bump-version, smoke-test (registry/security gates are steps inside ci.yml)

NOTE: src/server/ tool-registry is split (tool-registry.ts + tool-registry-{client,elicitation,gateway,listing,manage-tools}.ts + resource-registry.ts — there is no tool-registry-legacy.ts). src/unreal-bridge*.ts is unreal-bridge.ts + -{connection,console,properties,response,system,types}.ts. The plugin Private/Core/Subsystem/ holds the registration shards; the subsystem .cpp is there (not directly in Core/).