Why soft-ue-cli?

• MCP server + CLI in one package -- use as an MCP server (mcp-serve) for Claude Desktop, Cursor, Windsurf, and other MCP clients, or as a standard CLI for Claude Code, shell scripts, and CI/CD. Same 120+ tool surface either way.
• AI-native UE automation -- purpose-built so LLM agents can read, modify, and test Unreal Engine projects without a human touching the editor.
• 120+ commands and tools covering actors, Blueprints, materials, MetaSounds, StateTrees, Mutable/CustomizableObject, widgets, assets, config files, PIE sessions, profiling, screenshots, and local Unreal file analysis.
• Command families, not one-off names -- UMG, capture, Mutable, StateTree, MetaSound, animation, asset, and Blueprint workflows are grouped under umg, capture, mutable, statetree, metasound, anim, asset, and blueprint.
• Plugin-aware metadata -- soft-ue-cli commands --json reports bridge/editor/PIE requirements plus optional Unreal plugin dependencies, and bridge tools return structured plugin_unavailable errors when a plugin is missing.
• Token-aware visual feedback -- viewport and screenshot capture can resize output by scale, width, or height and can emit color, grayscale, or monochrome images for lower LLM token cost.
• Online + offline workflows -- bridge-backed UE mutation and runtime inspection when Unreal is open, plus direct local inspection, diff, and config tooling when it is not.
• Config-aware workflows ??inspect hierarchy, trace overrides, diff layers, and patch .ini, BuildConfiguration.xml, and .uproject data from one config command group.
• UMG authoring loop -- draft editable Widget Blueprint trees, wire navigation contracts, run PIE interaction checks, and compare designer/runtime layout artifacts.
• LLM skill prompts -- ships with markdown workflows (e.g. Blueprint-to-C++ conversion) exposed as MCP prompts or CLI commands.
• Works everywhere UE runs -- editor, cooked builds, Windows, macOS, Linux.
• Small dependency footprint -- only requires httpx and Pillow. Add [mcp] extra for MCP server mode.
• Team-friendly -- conditional compilation via SOFT_UE_BRIDGE environment variable means only developers who need the bridge get it compiled in.

Current Direction

Recent releases moved soft-ue-cli from a flat list of one-off bridge calls toward a discoverable automation surface for agents:

• commands is the source of truth for command status, replacement names, runtime requirements, optional plugin requirements, and examples.
• Canonical families (umg, capture, mutable, statetree, metasound, anim, asset, blueprint) are the supported public command surface.
• UMG and screenshot workflows now support the full agent loop: author, inspect, run PIE, capture visual evidence, compare layout, and keep image payloads small.
• Optional plugin workflows are expected to compile cleanly without those plugins installed, then fail at runtime with actionable plugin_unavailable diagnostics.
• CLI/Python/bridge probing is treated as the exploration layer; durable gameplay regressions should move into project-native C++ Automation Specs.

UE 5.8 MCP Positioning

UE 5.8 official MCP is preferred when it covers native execution for the workflow you need.

UE 5.8 is adding first-party Unreal MCP support. Use it when you want an Epic-managed, UE 5.8-native MCP endpoint and it already covers the workflow you need.

soft-ue-cli's main development target is now Unreal Engine 5.8. UE 5.7 compatibility remains maintained, so fixes and bridge code should continue to compile and run on UE 5.7 unless a release note explicitly says otherwise.

soft-ue-cli is intentionally a different layer rather than a replacement for first-party MCP:

• It works as both a normal terminal CLI and an MCP server, so the same automation can run from Claude Code, shell scripts, CI, or any MCP client.
• It includes offline commands for .uasset, .uexp, .ini, .uproject, .uplugin, and BuildConfiguration.xml files, even when the editor is closed.
• It ships curated LLM skill prompts and a test-tools smoke workflow for repeatable agent execution, not just raw editor operations.
• It supports UE 5.7 today and also runs in Development/DebugGame cooked builds, while still exposing a normal terminal CLI and an MCP server from the same package.
• Runtime bridge support and future binary install/update workflows are treated as primary post-UE-5.8-MCP differentiators, especially for packaged Development/DebugGame builds and CI automation.
• It reports command requirements and optional plugin dependencies in structured metadata so agents can choose the right workflow without guessing.
• It reports optional plugin requirements and missing-plugin failures in structured JSON so agents can recover instead of guessing.

The two can coexist: use UE's first-party MCP for native UE 5.8 editor coverage when it fits, and use soft-ue-cli for UE 5.7 projects, cooked Development/DebugGame builds, CLI/CI automation, offline inspection, curated workflows, visual capture transforms, optional plugin diagnostics, and bridge tools that move independently of engine releases.

Run soft-ue-cli mcp-surface-status inside a project workspace to probe the local UE 5.8 official MCP endpoint and SoftUEBridge health endpoint. It reports official-only, bridge-only, both, or neither, plus a recommendation without executing editor mutations.

Private soft-ue-expert Pro distribution is separate from this public package. Expert Packs provide skills, cases, rules, agents, and verification through local owner operation; hosted Pro is deferred.

Quick Start

1. Install

pip install soft-ue-cli          # CLI only
pip install soft-ue-cli[mcp]     # CLI + MCP server

2. Install the plugin into your UE project

Run the setup command inside your LLM client (Claude Code, Cursor, etc.) ??it outputs step-by-step instructions that the AI agent will follow to copy the plugin, edit your .uproject, and configure itself:

soft-ue-cli setup /path/to/YourProject

If you're running manually (not via an LLM), follow the printed instructions yourself: copy the plugin directory, add the "Plugins" entry to your .uproject, and create the CLAUDE.md snippet.

3. Rebuild and launch Unreal Engine

After regenerating project files and rebuilding, launch the editor. Look for this log line to confirm the bridge is running:

LogSoftUEBridge: Bridge server started on port 8080

4. Verify the connection

soft-ue-cli check-setup

You should see all checks pass:

[OK]   Plugin files found.
[OK]   SoftUEBridge enabled in YourGame.uproject.
[OK]   Bridge server reachable.

5. (Optional) Connect your MCP client

Add to your MCP client config (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "soft-ue-cli": {
      "command": "soft-ue-cli",
      "args": ["mcp-serve"]
    }
  }
}

The AI editor now has direct access to 120+ UE tools and skill prompts -- no terminal needed.

How It Works

soft-ue-cli command
    |
    +-- Bridge-backed commands ----------------------------------------+
    |      HTTP / JSON-RPC
    |      -> SoftUEBridge plugin (UGameInstanceSubsystem inside UE)
    |      -> UE APIs on the game thread
    |      -> Runtime/editor operations such as spawn-actor, PIE, query-level
    |
    +-- Offline commands ----------------------------------------------+
           Local parsers and file readers
           -> Package tables / tagged properties / config hierarchy
           -> asset inspect-file, asset diff-file, config *, skills get/list

The SoftUEBridge plugin is a lightweight C++ UGameInstanceSubsystem that starts an embedded HTTP server on port 8080 when UE launches. Bridge-backed commands send JSON-RPC requests to this server, and the plugin executes the corresponding UE operations on the game thread, returning structured JSON responses. Offline commands bypass the bridge entirely and operate directly on local files.

Automation commands return structured JSON to stdout (except get-logs --raw). Discovery and support commands use human-readable output by default where that is more useful, and expose --json where applicable. Exit code 0 means success, 1 means error.

Skills Architecture

LLM client (Claude Code, Cursor, etc.)
    |
    |  soft-ue-cli skills get <name>
    v
Skill file  (markdown shipped with CLI pip package)
    |
    |  LLM reads instructions, type mappings, pre-filled commands
    v
LLM executes soft-ue-cli commands (blueprint inspect, blueprint graph inspect, ...)
    |
    v
LLM generates output (e.g. .h/.cpp files) following the skill's rules

Skills are markdown files at cli/soft_ue_cli/skills/*.md, shipped as package data in the pip distribution. Each skill is self-contained: workflow instructions, reference tables, example CLI commands, and verification test cases. The CLI discovers them via skills list / skills get. When running as an MCP server, the same files are exposed via the prompts/list and prompts/get protocol.

Test Workflow

Use soft-ue-cli to explore and debug a gameplay bug quickly, then move the final regression into the project's C++ Automation Spec suite.

CLI + bridge + Python exploration
    -> find the signal
    -> validate the repro
    -> identify the exact assert