umg-material-mcp

name	umg-material-mcp
description	Use when Codex needs to create, inspect, edit, delete, or validate UE5.8 material assets through Unreal Motion Graphics MCP/FabUmgMcp HLSL material tools, especially one-HLSL Custom-node authoring, UI-default versus non-UI material type selection, union-only writes, semantic outputs, hlsl_delete recovery, or Material ToolMode protocol work.

UMG Material MCP

Use the Material HLSL MCP path for material authoring. Do not mutate .uasset files directly. Keep Unreal Editor open with the UMG MCP bridge listening before runtime tool calls.

For concrete command examples and regression cases, read demo-cases.md.

Primary Workflow

1. Set or create the HLSL target with hlsl_set_target.

   • New targets default to UI material behavior.
   • For non-UI materials, pass type fields directly on hlsl_set_target: domain, blend_mode, shading_model, two_sided.
   • Prefer this over material_modify_type; that command is compatibility-only.

2. Read with hlsl_get.

   • Treat the response as semantic state: HLSL text, parameter snapshot, and output_contract.
   • Do not request or reconstruct full material graphs unless the HLSL protocol cannot express the task.

3. Write with hlsl_set(hlsl?, parameters?, outputs?).

   • hlsl_set is union-only: update existing entries and append missing entries.
   • It must not delete parameters or outputs.
   • Use parameters for Custom node inputs such as {"name":"Intensity","kind":"Scalar"}.
   • Use outputs for root material outputs such as "Roughness", "Metallic", "Normal", or objects with name, target, and type.
   • Additional outputs are UE5.8 Custom node AdditionalOutputs; assign same-name variables in HLSL, for example Roughness = 0.35;.

4. Delete with hlsl_delete(names, confirm_delete=true, kind?).

   • Omit kind in the normal path.
   • If a name matches both parameter and output, expect failure with requires_kind: true; retry with kind="parameter" or kind="output".
   • Do not use hlsl_delete_parameter or hlsl_delete_output in primary flows; they are compatibility aliases.

5. Compile with hlsl_compile.

   • Treat compile diagnostics as the feedback loop.
   • Prefer small repair writes with hlsl_set(hlsl=...) rather than resetting the target.

Protocol Rules

• The material is represented as one HLSL program on a single Custom node.
• The Custom node primary return is float4.
• output_contract describes where rgb/a and any additional outputs are wired.
• UI, PostProcess, LightFunction, and Unlit output rgb to EmissiveColor; lit Surface output rgb usually maps to BaseColor.
• Alpha maps only when semantically useful: UI/translucent to Opacity, masked to OpacityMask.
• Do not fall back to legacy material_* graph editing unless the requested operation cannot be modeled by HLSL target, parameters, outputs, delete, and compile.

Validation

Use the narrowest relevant checks:

python -m py_compile Resources\Python\UmgMcpServer.py Resources\Python\Material\UMGMaterial.py Resources\Python\APITest\Material_HLSL_Type_Demo.py Resources\Python\APITest\Material_Protocol_Static_Check.py
python Resources\Python\APITest\Material_Protocol_Static_Check.py
& 'D:\UE_5.8\Engine\Build\BatchFiles\Build.bat' FabUMGMCPEditor Win64 Development -Project='D:\UE5Project\FabUMGMCP\FabUMGMCP.uproject' -NoHotReloadFromIDE -Progress
python Resources\Python\APITest\Material_HLSL_Type_Demo.py

The runtime demo requires Unreal Editor to be open and the MCP socket in Resources/Python/mcp_config.py to be reachable.