#UECopilot Plugin Documentation

Version: 1.0.0 | Last Updated: 2026-05-08 Target Engine: Unreal Engine 5.7

#1. Plugin Overview

#1.1 What is UECopilot?

UECopilot is an AI-assisted development plugin integrated into the Unreal Engine 5 editor. Through the Blueprint MCP Server (Blueprint Model Context Protocol Server, UEMCP), it exposes UE5's Blueprint data structures and editing operations as HTTP APIs, allowing AI models (such as Claude, GPT, etc.) to directly read, understand, create, and modify Blueprint assets.

One-sentence summary: UECopilot enables AI to "understand" your Blueprints and operate them for you like an experienced TA/programmer.

#1.2 Operation Mode

#2. Core Capabilities Overview

UECopilot's UEMCP module has been comprehensively analyzed and currently provides 80+ MCP tools, covering the following 9 major capability domains:

Capability Rating Descriptions:

• Mature: Full tool functionality, edge cases well handled, SEH protection in place
• Stable: Core paths usable, some boundary conditions to watch for
• Developing: Basic capabilities available, advanced scenarios need improvement

#2.1 What Can It Do? (Scenario Descriptions)

Scenario 1: AI-Assisted Blueprint Debugging

User: "Help me check if there are any disconnected pins in this Blueprint"
AI → calls find_disconnected_pins → returns all unconnected input pins
AI → provides fix suggestions

Scenario 2: AI-Assisted Blueprint Refactoring

User: "Change all function calls referencing OldClass to NewClass"
AI → calls replace_function_calls (supports dry_run preview) → executes replacement

Scenario 3: AI-Assisted Material Creation

User: "Help me create a material with a normal map and color adjustment"
AI → create_material → add_material_expression (TextureSample, Multiply, etc.)
     → connect_material_pins → completes the material network

Scenario 4: AI-Assisted Animation State Machine

User: "Add an Idle→Run transition in this Anim Blueprint"
AI → add_anim_state → add_anim_transition → set_transition_rule

Scenario 5: Safe Experimentation

User: "I want to modify this function parameter type, but I'm worried about issues"
AI → snapshot_graph (take snapshot first) → change_function_parameter_type → if error, restore_graph

#3. System Requirements

• Unreal Engine: 5.7+
• Operating System: Windows 64-bit (fully tested)
• Additional Dependencies: Node.js (for Web UI service, MCP service does not require it)

#4. Usage Guide

#4.1 Recommended Workflow

The recommended workflow follows four steps: "Preview → Snapshot → Execute → Verify":

Step 1: Preview & Analysis
  ├── Use get_blueprint / get_blueprint_graph to understand current state
  ├── Use search_blueprints to search for relevant nodes
  └── Use check_pin_compatibility to pre-check pin connection feasibility

Step 2: Create Safety Snapshot
  └── Use snapshot_graph to save the current graph state

Step 3: Execute Changes
  ├── Use add_node / connect_pins / delete_node, etc.
  ├── Tools with dryRun parameter should be used for a dry run first
  └── For major changes, use validate_blueprint to check compilation results

Step 4: Verify & Restore
  ├── Use validate_blueprint to verify Blueprint integrity
  ├── Use diff_graph to compare differences before and after changes
  └── If issues arise, use restore_graph to roll back to the snapshot state

#4.2 AI Prompt Tips

Good prompt examples:

# Clearly specify the target object
"Add a Print String node to the EventGraph of Blueprint MyCharacter, printing 'Hello'"

# Step-by-step operations
"1. First take a snapshot of MyCharacter's EventGraph
 2. Then change the input parameter type of the MoveForward function from float to double
 3. Finally verify if the Blueprint has compilation errors"

# Query first, then operate
"First list all Blueprints in the project that inherit from Character,
 then tell me their names and paths"

Vague prompts to avoid:

✗ "Help me fix this Blueprint" — Which Blueprint? Fix what?
✗ "Add a feature" — What feature? Where to add it?
✗ "Modify the material" — Which material? Change it to what?

#4.3 Usage Notes

1. MCP service is not head-safe: Although SEH (Structured Exception Handling) protection is used, erroneous operations in extreme cases could still cause the editor to crash. It is recommended to save the project and back up important Blueprints before operating.

2. All write operations support Ctrl+Z undo: The server wraps each write operation in an Undo transaction, but it is recommended to manually save promptly after continuous operations.

3. Snapshots are saved to disk: Snapshot files are stored in the Project/Saved/BlueprintMCP/Snapshots/ directory and are not included in project version control. Manual backup is recommended for important operations.

4. AI model differences in understanding UE terminology: Different AI models may have varying understandings of UE-specific terms (such as "pin connection", "break struct", "event dispatcher"). Please use UE5 official terminology in your prompts.

#5. MCP Tools Complete Reference

Note: The following lists all MCP tools that can be directly invoked through AI conversation. Tool names use snake_case convention. You can use these tool names directly in your prompts.

#5.1 Blueprint Retrieval & Reading (8 Tools)

#5.2 Blueprint Node Editing (15 Tools)

#5.3 Blueprint Variable System (6 Tools)

#5.4 Function & Parameter Management (4 Tools)

#5.5 Blueprint Structure & Metadata (9 Tools)

#5.6 Component System (3 Tools)

#5.7 User-Defined Types (4 Tools)

#5.8 Material System (18 Tools)

Material Reading:

Material Writing:

Material Instances:

Material Functions:

Material Safety:

#5.9 Animation Blueprint System (12 Tools)

#5.10 Safety & Snapshot System (6 Tools)

#5.11 Asset Discovery & Reflection (5 Tools)

#5.12 Utility Functions & Safety Mechanisms

Type Resolver (ResolveTypeFromString)

Supported type resolution formats:

SEH Safety Protection (Windows Only)

For high-risk operations (Blueprint compilation, material expression addition, package saving, etc.), the __try/__except Structured Exception Handling (SEH) mechanism is used. This means that even if an operation causes an internal engine crash (such as an access violation), the service will not completely crash, but will instead return an error message.

Undo Transaction Support

All tool calls that modify Blueprints are wrapped in Undo/Redo transactions. This means that when used in the editor, operations executed by AI can be undone with Ctrl+Z.

#6. Usage Boundaries & Limitations

#6.1 Known Limitations

#6.2 Unsupported Scenarios

1. C++ Code Operations: Can only operate on Blueprints and assets; cannot create or modify C++ code files
2. Runtime Debugging: Does not support debugging features such as breakpoints or step execution
3. Multi-User Collaboration: No concurrency control mechanism; not suitable for multiple users operating the same Blueprint simultaneously
4. Content Migration: Cross-project content migration is not supported
5. Source Control Integration: Does not directly interact with Perforce/Git/SVN
6. Packaging and Building: Does not support packaging, baking, or other build processes
7. Level Editing: Does not directly support Actor placement and editing in levels
8. Data Table Operations: Editing of DataTable/CurveTable is not currently supported
9. Niagara System: Operations on Niagara particle systems are not supported
10. UI/UW Editing: Editing of Widget Blueprints is not supported

#6.3 Security Boundaries

✅ Allowed:
   · Read/Create/Modify Blueprint assets
   · Read/Create/Modify Material assets
   · Read/Create/Modify Anim Blueprint assets
   · Create structs and enums
   · Perform safe snapshots and restoration
   · Use Ctrl+Z to undo in the editor

❌ Not Allowed:
   · Expose the editor to external network access
   · Batch modifications without version control
   · Relying on AI to fully understand the semantics of complex graph structures
   · Skipping tests and using directly on critical nodes

⚠️ Proceed with Caution:
   · Modifying the parent class of an existing Blueprint (may cause numerous broken connections)
   · Batch renaming/deleting assets
   · Changing variable types (may disconnect existing connections)
   · Large-scale modifications in Anim Blueprint state machines

#7. Challenges in Prompt Accuracy for Dialogue-Based MCP Operations

#7.1 Core Challenges

Using natural language to operate UE5 Blueprints through AI models presents the following core challenges:

#Challenge 1: Loss of 3D Semantics in Graph Structure

A Blueprint graph is a two-dimensional visual structure. AI only sees a flat JSON node list, losing spatial information such as:

• Node position and layout (proximity implies logical grouping)
• Visual grouping through comment boxes
• Execution flow direction (left-to-right, top-to-bottom conventions)
• Color cues (node type indication, execution wire colors)

Impact: AI struggles to understand the "design intent" of a graph, only seeing structured connection data.

#Challenge 2: Tacit Knowledge of Pin Types

Pin types in UE5 are a complex system:

Impact: When constructing connect_pins requests, AI may provide semantically incorrect pin pairings.

#Challenge 3: Cascading Effects of Changes

A simple modification can trigger a chain reaction:

Change variable type (int → float)
  → Output pin types of all Get/Set nodes change
    → Nodes connected to these pins may become disconnected
      → Input values of downstream nodes become invalid
        → Compilation warnings or errors occur

Impact: AI struggles to fully predict all cascading effects of a change, even with dryRun support.

#Challenge 4: Ambiguity of UE Terminology

Impact: AI may confuse terminology meanings across different contexts, leading to incorrect request parameters.

#Challenge 5: Session State Maintenance

Round 1: AI → "List all Blueprints"
         Service → Returns 50 Blueprint names

Round 2: AI → "Open the first one"
         Problem → Which "first one"? The user needs to maintain dialog context

Impact: The plugin itself is stateless; each tool call is independent. AI models need to maintain state within the conversation, but context windows are limited.

#7.2 Current Mitigation Strategies

Mitigation measures already implemented at the plugin level:

1. Detailed Error Messages: When an operation fails, return specific error reasons and a list of available options (such as available pin names, available graph names, etc.)
2. dryRun Mode: Key modification operations support a preview mode that returns impact analysis
3. Snapshot Mechanism: Supports taking snapshots before operations and restoring after
4. SEH Protection: Crash protection for extreme cases

#10. FAQ and Troubleshooting

#10.1 Operation Issues

Q: Changes to Blueprint did not take effect

1. Check whether the saved field in the returned JSON is true
2. Manually save the asset in the editor (Ctrl+S)
3. Reopen the Blueprint graph to view changes

Q: Blueprint compilation error

1. Use the validate_blueprint tool to view specific error details
2. If a snapshot is available, use restore_graph to restore
3. Or use Ctrl+Z in the editor to undo

Q: AI cannot find the specified Blueprint

1. Ensure the Blueprint name is correct (case-sensitive)
2. Use the list_blueprints tool to view all available Blueprints
3. Level Blueprint needs to be referenced by map name

#10.2 Performance Issues

Q: First list_blueprints call is slow

#The first call triggers a full scan of the asset registry. Subsequent calls use the cache and will be faster.

#11. Appendix: Capability Statistics

#11.1 Overview Data

#11.3 Type Support Coverage

#Conclusion

UECopilot's goal is to make AI a trusted co-pilot for UE5 developers — not to replace your judgment, but to help you complete repetitive tasks faster, reduce human error, and maintain accuracy and traceability in large-scale projects.

Recommendations for Users:

• Start small: Try it on simple Blueprints first
• Use snapshots: Take a snapshot before any major operation
• Gradual usage: Progress from reading → simple modifications → complex creation
• Provide feedback: When encountering issues, please provide detailed logs to help the plugin improve continuously

UECopilot - Empowering Unreal Engine development with AI wings