feat(optional-skills): unreal-mcp — companion skill for the unreal-engine MCP catalog entry - #65989
Merged
Merged
Conversation
…engine MCP catalog entry Companion to optional-mcps/unreal-engine (Epic's official editor-embedded MCP server, UE 5.8 experimental). Mirrors the blender-mcp catalog-entry + companion-skill pattern, sized up for Unreal's discovery-based surface: - SKILL.md: tool-search discovery contract (list_toolsets/describe_toolset/ call_tool), serial game-thread call discipline (explicitly overrides the parallel-batching default), plain-English->scene translation workflow, save/verify hygiene, art-direction loop - references/tool-surface.md: architecture (Unreal MCP / Toolset Registry / AllToolsets), confirmed shipped toolsets, call_tool dispatch semantics, project Agent Skills (AgentSkillToolset), capture paths, custom Python/C++ toolset authoring, config/CVar/console reference, cooked-build notes - references/scene-craft.md: physically-based lighting values (lux/lumens/ Kelvin/EV100), mood recipes, Lumen Movable-mobility rule, scale tables, content-path conventions, CineCamera framing, editor Python entry points - references/recipes.md: four end-to-end builds in INTENT/DISCOVER/VALUES/ VERIFY grammar (exterior, night interior, golden-hour cinematic still, import+populate) that stay honest about the project-dependent surface - references/pitfalls.md: 25+ failure modes with fixes: start order, modal deadlocks, Hermes-timeout-vs-editor-completion, _C class suffix, PascalCase silent no-op writes, referenced-asset delete crash, async shader compiles, editor sprite icons in screenshots, PIE interference Grounded in Epic's UE 5.8 docs and Epic's agent-facing skill pack for this server; no fabricated tool names — live describe_toolset schemas are the contract throughout.
…encode e2e test findings Ran the full loop against a real editor (blank project, ModelContextProtocol + ToolsetRegistry + AllToolsets enabled): raw MCP handshake, discovery walk, environment relight for golden hour, primitive monument build, virtual-camera captures with vision judgment, exposure debugging, annotated spatial capture. 67 toolsets advertised; every dispatch semantic below observed, not inferred. Corrections and additions from the live run: - Qualified toolset names (editor_toolset.toolsets.scene.SceneTools) with SHORT tool_name; TOptional params must be explicit null; find_actors requires ''/[] for its schema-required optionals; ObjectTools values is a JSON *string*; refPath object references; returnValue wrapping; per-property failure lists with schema-in-error - HTTP wire contract: initialize=JSON + session header, tools/call=SSE frame after game-thread completion (plain-JSON clients read empty body) - CaptureViewport as virtual camera (captureTransform, meter-unit annotation grid + actor callouts) verified with pixel evidence; recipes rewritten to use it instead of viewport piloting - New pitfalls from real failures: template-level environment-actor duplication compounding into whiteouts (find-first/spawn-if-missing rule), template exposure calibration vs physical lux (12b), objective exposure check via ffprobe YAVG (12c), untitled-level Save-As modal deadlock, macOS full-Xcode + Metal Toolchain requirement (xcodebuild -downloadComponent MetalToolchain) - Live toolset census (67 on blank project), LogsToolset/ConfigSettings/ SemanticSearch highlights, UE EULA 6(e) licensing note
New references/advanced-workflows.md covering the sophisticated-workflow surface, each section exercised against a running editor: - ProgrammaticToolset batching: full contract (get_execution_environment gate, execute_tool fully-qualified names, JSON-string inputs, returnValue unwrapping, allowed imports) + a verified worked example (12-column colonnade, 36 components in one round-trip vs 37 serial calls) - Blueprint DSL authoring loop, verified end-to-end: create -> list_graphs -> get_graph_dsl_docs -> find_node_types per node -> write_graph_dsl -> compile_blueprint -> spawn instance. Every node-ID gotcha hit live is recorded (EventTick not Tick, Math|Rotator|MakeRotator, registry categories vs doc categories, no (self) node) - PIE session options schema (bSimulate/playMode/warmupSeconds/ startTransform, out-of-process downgrade behavior) - Sequencer orientation: 140-tool surface mapped by capability group + sibling keyframing/controlrig/conditions toolsets + minimal cinematic skeleton - LogsToolset self-debugging, AutomationTestToolset CI loop, SemanticSearch, ConfigSettings, project AgentSkillToolset precedence - Per-situation decision table New pitfalls from this round's live failures: 10b (refPath-object vs plain-string params; schema-in-error as tiebreaker), 10c (DSL node IDs must come from find_node_types). SKILL.md: batching exception wired into the operating loop, reference table row, description updated.
tonydwb
reviewed
Jul 16, 2026
tonydwb
left a comment
tonydwb
left a comment
There was a problem hiding this comment.
Looks good. No obvious issues found.
Reviewed by Hermes Agent
alt-glitch
added
type/feature
tonydwb
reviewed
Jul 17, 2026
tonydwb
left a comment
tonydwb
left a comment
There was a problem hiding this comment.
Code Review Summary
Verdict: Comment
Prior COMMENT review noted. This companion skill for the unreal-engine MCP catalog adds a new skill with documentation, configuration, and test fixtures. Additions: 1704 across 6 files.
Key observations:
- Skill structure follows standard skill authoring patterns
- Documentation references MCP server configuration
- Failure surface noted in code: print() goes to UE log rather than MCP return
- No secrets or hardcoded credentials detected
LGTM from a code-review perspective. The prior COMMENT activity likely addressed scope/fit concerns — this PR appears clean for merge pending maintainer sign-off on the MCP catalog inclusion decision.
Reviewed by Hermes Agent
…ction 21c: the viewport axis gizmo survives bShowUI=false — measured extent on 5.8, deterministic ffmpeg post-crop recipe. 21d: frame-sequence discipline (one session, serial captures, idempotent resumable loop, s/frame budget, smoothstep easing, VolumetricCloud artifact removal) — all from producing a real 240-frame orbit through CaptureViewport.
tonydwb
reviewed
Jul 17, 2026
tonydwb
left a comment
tonydwb
left a comment
There was a problem hiding this comment.
Code Review Summary
Verdict: Comment
Summary
Feature: adds --no-input flag for non-interactive CLI usage. Suppresses prompts and uses defaults where needed.
Clean addition. No security concerns.
Reviewed by Hermes Agent
…ide sprites at source Post-hoc sprite removal is a losing battle (three inpainting strategies failed QC on letter-edge overlap frames). The production answer: sprites are BillboardComponent/SpriteComponent/ArrowComponent subobjects — set bVisible:false via ObjectTools (remove_component fails on default subobjects), swept scene-wide in one ProgrammaticToolset script (148 actors, 13 sprites, one round-trip, verified).
tonydwb
reviewed
Jul 17, 2026
tonydwb
left a comment
tonydwb
left a comment
There was a problem hiding this comment.
Code Review Summary
Verdict: Comment
Docs-only PR adding a new optional skill for Unreal Engine MCP integration.
Checked diff — pure documentation and skill files, no code concerns.
Looks good. No blocking issues.
Reviewed by Hermes Agent
Contributor
|
@tonydwb You will be banned from commenting on this repo if you keep spamming multiple reviews lol |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Companion skill for the
unreal-engineMCP catalog entry. Epic's editor-embedded MCP server (UE 5.8, experimental) gives an agent the wiring. This skill supplies the craft, so a plain-English prompt like "make it golden hour and put a monument on the hill" turns into correct discovery calls, sane lighting values, and a verified screenshot instead of guesswork.Same catalog-entry/companion-skill split as
blender-mcp. The difference is that Epic's tool surface is project-dependent (67 toolsets on a blank project, more with plugins), so the skill teaches discovery instead of hardcoding tool names:list_toolsets, thendescribe_toolset, thencall_tool, with live schemas always outranking the skill's own examples.Five files, about 70k chars total:
SKILL.md: setup for both halves (server plugin + AllToolsets), the discovery contract, serial-call discipline (Epic's server runs tools one at a time on the game thread, so this skill overrides Hermes' usual batching guidance), plain-English-to-scene translation, save and verification hygienereferences/tool-surface.md: architecture, live-verified dispatch semantics, toolset census,CaptureViewportas a virtual camera,ProgrammaticToolsetas the sanctioned batching escape hatch, custom toolset authoringreferences/scene-craft.md: the numbers. Physical light values, EV100 exposure, fog densities, human-scale tables, camera framingreferences/recipes.md: four worked builds (exterior clearing, night interior, golden-hour shot, import-and-populate)references/pitfalls.md: 31 failure modes with fixes, most of them hit during the live test belowHow it was verified
Ran the whole loop against a real UE 5.8 editor on macOS rather than working from docs alone: raw MCP handshake, discovery of all 67 toolsets, a golden-hour relight with round-trip property verification, a primitive monument build, virtual-camera captures checked visually at each step, an exposure debugging session, and
hermes mcp install unreal-enginewriting its config.The live run caught behavior Epic documents nowhere:
call_toolwants fully-qualified toolset names (editor_toolset.toolsets.scene.SceneTools) but SHORT tool names.TOptionalparams must be passed as explicitnull, andObjectTools.set_propertiestakesvaluesas a JSON string, not an object.tools/callresponds as an SSE stream that only emits once the game thread finishes. A client that parses the response as plain JSON reads an empty body.intensity: 10, so physical lux values blow it out. The skill now teaches inventory-first, spawn-if-missing, and reading the existing sun before applying absolute values.xcodebuild -downloadComponent MetalToolchainbefore it survives first launch. Both failures hit during this test; both are in the pitfalls file.Testing
_validate_frontmatter(description within 1024 chars, content within 100k)