@uemcp/server 1.2.0 → 1.4.0

package/README.md

@@ -48,6 +48,83 @@ The MCP tool surface currently exposes:
 - `refresh_source_control_status`
 - `checkout_assets`
 - `get_source_control_job_status`
+- `list_asset_factories`
+- `create_asset`
+- `duplicate_asset`
+- `rename_asset`
+- `move_asset`
+- `delete_asset`
+- `save_asset`
+- `create_folder`
+- `get_asset_metadata`
+- `list_graph_nodes`
+- `add_graph_node`
+- `remove_graph_node`
+- `connect_pins`
+- `disconnect_pins`
+- `set_pin_default`
+- `list_available_nodes`
+- `set_viewport_camera`
+- `focus_actors`
+- `set_view_mode`
+- `toggle_show_flags`
+- `high_res_screenshot`
+- `duplicate_actor`
+- `attach_actor`
+- `add_actor_component`
+- `set_actor_tags`
+- `move_to_folder`
+- `place_asset`
+- `replace_actors`
+- `build_lighting`
+- `build_navigation`
+- `build_hlod`
+- `build_reflection_captures`
+- `build_geometry`
+- `build_texture_streaming`
+- `build_virtual_textures`
+- `precompute_visibility`
+- `get_build_job_status`
+- `create_gameplay_tag`
+- `list_gameplay_tags`
+- `create_landscape`
+- `sculpt_landscape`
+- `paint_landscape_layer`
+- `run_geometry_script`
+- `list_data_layers`
+- `set_data_layer_state`
+- `load_wp_region`
+- `get_asset_property`
+- `set_asset_property`
+- `array_property_op`
+- `create_struct`
+- `create_enum`
+- `create_blueprint`
+- `add_bp_variable`
+- `add_bp_function`
+- `add_bp_event`
+- `add_bp_component`
+- `add_bp_interface`
+- `set_bp_default`
+- `batch_edit`
+- `import_asset`
+- `reimport_asset`
+- `set_import_settings`
+- `get_import_job_status`
+- `create_blackboard`
+- `set_blackboard_keys`
+- `create_eqs_query`
+- `create_state_tree`
+- `add_state_tree_state`
+- `create_level_sequence`
+- `add_sequence_binding`
+- `add_sequence_track`
+- `add_sequence_keys`
+- `add_foliage_type`
+- `paint_foliage`
+- `create_sound_cue`
+- `create_metasound`
+- `set_metasound_graph`
 
 ## Project Identity
 
@@ -228,6 +305,173 @@ This is intended to let an MCP client resolve the canonical Unreal project ident
 - `rename_data_table_row` keeps the row's position and values, which an upsert-under-the-new-name plus a delete-of-the-old does not: that pair costs two transactions and moves the row to the end. It refuses a missing row (`row_not_found`) and a name already taken (`row_already_exists`), since renaming onto an existing row would discard that row's values. **Row names are how other assets address rows**, so a rename breaks any `FDataTableRowHandle` pointing at the old name — nothing fixes those up
 - Rename and delete both need referencer data, which is only trustworthy once the Asset Registry's initial gather has finished — mid-scan `GetReferencers` returns a short list that reads as "nothing depends on this". Both drive the scan to completion first (starting it when a headless editor never did), and report `asset_registry_scanning` only if it is still incomplete afterwards. On a large project that wait can be long enough to hit the bridge read timeout
 
+### `list_asset_factories` / `create_asset`
+
+- Everything in the Content Browser's Add menu is backed by a `UFactory`, so one discovery tool plus one creation tool cover the whole menu rather than a tool per asset type
+- `list_asset_factories` enumerates every factory that can create new assets (`CanCreateNew()` and `ShouldShowInNewMenu()`), reporting the factory class, the asset class it produces, its menu category, and the **required options** — the object or class properties a factory would otherwise pop a modal picker for. Filter with `nameFilter`; results page by `nextCursor`
+- `create_asset` goes through `IAssetTools::CreateAsset`, never the Content Browser's `CreateAssetWithDialog`, and never calls `UFactory::ConfigureProperties`. A modal window opened from a bridge request would block the editor with nobody to answer it
+- A factory that needs configuring is configured from `options` instead: each key is a reflected property on the factory (`ParentClass` for a Blueprint, for example) set on a **fresh factory instance**, never on the CDO. A factory whose required options were not supplied is refused with their names rather than producing something the caller did not ask for
+- The new asset is dirty and **unsaved** — compose with `save_asset`
+
+### `duplicate_asset` / `rename_asset` / `move_asset` / `delete_asset` / `save_asset` / `create_folder` / `get_asset_metadata`
+
+- File-level content management. `find_assets` locates assets and `get_asset_dependencies` describes them; these are what reorganize them
+- Rename and move both go through `IAssetTools::RenameAssets` rather than moving packages by hand: that is what fixes up referencers and leaves the redirector the engine expects, so existing hard references keep resolving
+- Writes are refused outside `/Game`. Engine and plugin content is not the project's to reorganize, and a rename there silently breaks every project sharing the engine install
+- `delete_asset` queries referencers first and refuses with their names rather than leaving them pointing at nothing; `force` deletes anyway. There is no transaction behind it — asset deletion is not undoable
+- `save_asset` saves without prompting (the prompting variants can open a modal). A package that was already clean reports `saved: false` as a **success**, not a no-op error
+- `create_folder` reports `state: 'exists'` rather than failing when the folder is already there, since that is the state the caller wanted. A content folder is an Asset Registry entry until something is saved into it, so an empty one does not survive an editor restart — the response says so
+- `get_asset_metadata` answers from the Asset Registry's `FAssetData` and **never loads the package**: class, package name and path, on-disk size, and the registry tag map — which carries a Blueprint's parent class, a texture's dimensions, a DataTable's row struct. `loaded` reports whether it happens to be in memory already; `false` is normal
+
+### `list_graph_nodes` / `add_graph_node` / `remove_graph_node` / `connect_pins` / `disconnect_pins` / `set_pin_default` / `list_available_nodes`
+
+- Blueprint graph authoring. `get_blueprint_graph` reads a graph; these write to one, and they work on any `UEdGraph` — an event graph or function, an Animation Blueprint AnimGraph, a Material graph
+- **Nodes are addressed by GUID, never by index.** A graph's node array reorders on every edit and recompile, so an index read a moment ago can name a different node by the time it is written back. `nodeId` from `list_graph_nodes` is what every other tool here takes. `list_graph_nodes` is the only read here, so it is the only one that takes `loadIfNeeded`; the write tools need the asset in memory regardless
+- `add_graph_node` builds the node through `FGraphNodeCreator`, so it allocates its own pins and gets the schema's default wiring. `kind` picks how it is addressed: `class` by node class, `function` by member name and parent class, `variable_get` / `variable_set` by variable. It returns the placed node **with its pins**, so the caller can wire it without a follow-up read
+- `connect_pins` asks the schema's `CanCreateConnection` before connecting, so an illegal wire comes back with **the schema's own refusal text** rather than a generic failure after the fact
+- `set_pin_default` refuses an output pin and a pin that is already connected — a connected pin takes its value from the wire, so a literal there would be stored and then ignored. The stored value is validated after the write and the previous literal restored if the schema rejects it
+- `list_available_nodes` answers from `FBlueprintActionDatabase` filtered by this graph's context, so what it lists is what the graph would actually accept rather than every node class the editor knows about
+- Every edit marks the Blueprint structurally modified and leaves it **dirty and uncompiled** — compose with `compile_blueprint` and `save_asset`
+
+### `set_viewport_camera` / `focus_actors` / `set_view_mode` / `toggle_show_flags` / `high_res_screenshot`
+
+- Level viewport control, all targeting the active level editing viewport — the one a human would be looking at
+- `set_viewport_camera` takes every field optionally, so a caller can change the rotation without restating a location it does not want moved. `orthoWidth` is only meaningful for an orthographic projection, and a perspective viewport reports it **absent** rather than as a zero that reads like a width
+- `focus_actors` frames the given actors in the active viewport only, so focusing does not yank every open viewport to the same place
+- `toggle_show_flags` reads each flag back after setting it rather than echoing the request: a flag the renderer forces cannot be turned off, and the caller should see that. A name that does not resolve comes back with **near matches** — the engine's flag names are CamelCase and easy to guess wrong
+- `high_res_screenshot` **queues** the capture for the next rendered frame, so the reported `filePath` is where the file will be, not proof that it is there. `includeUi` cannot be combined with a multiplier above 1: the high-resolution path renders the scene alone. `fileName` is a name and not a path — the capture always lands under the project’s `Saved/Screenshots`, and a separator or `..` in the name is refused rather than followed
+
+### `duplicate_actor` / `attach_actor` / `add_actor_component` / `set_actor_tags` / `move_to_folder` / `place_asset` / `replace_actors`
+
+- The level authoring surface beyond spawn and destroy. Each opens a single `FScopedTransaction` around the whole batch, so Ctrl+Z reverses the call as one Undo History step, and a per-item failure is reported in the result without aborting the rest
+- `attach_actor` with an empty `parentActorPath` **detaches**; the location, rotation and scale rules map onto `EAttachmentRule` so a caller gets the same choice the editor offers rather than one hard-coded behaviour
+- `place_asset` goes through the actor factory the engine picks for the asset, which is what turns a Static Mesh into an `AStaticMeshActor` and a Blueprint into an instance of its generated class
+- `replace_actors` preserves each actor's transform, label and attachment, which spawn-then-destroy does not
+- `dryRun: true` validates every entry and reports `state: 'validated'` without opening a transaction
+- Every one of these dirties the level **without saving** — compose with `save_dirty_packages`
+
+### `build_lighting` / `build_navigation` / `build_hlod` / `build_reflection_captures` / `build_geometry` / `build_texture_streaming` / `build_virtual_textures` / `precompute_visibility` / `get_build_job_status`
+
+- The editor's Build menu. A build runs for minutes to hours and blocks the game thread while it does, so none of these run inline: each returns `state: 'accepted'` with a `buildJobId`. Poll it with `get_build_job_status`, or wait with `wait_for_job` using `kind: 'build'`
+- One build at a time. A second request while one is running reports `state: 'busy'` with the running job's id rather than racing two builders over the same level's build data
+- **Failures are reported faithfully.** Lightmass and Swarm log the reason nothing was built and still return success, so the job captures the editor log for the duration and reports those errors verbatim — a failed build ends as `failed` with its own error text, never as succeeded-with-warnings
+- A build interrupted by the bridge shutting down reports `cancelled`, not a `running` state that never resolves
+- `build_hlod` takes an `hlodAction` because clusters and proxy meshes are separate passes in the editor and a caller usually wants one of them
+
+### `create_gameplay_tag` / `list_gameplay_tags`
+
+- Gameplay tags live in `.ini` files rather than in an asset, so declaring one is a config write
+- `create_gameplay_tag` goes through the GameplayTags editor module rather than writing the ini directly, which is what registers the tag with the running manager as well as persisting it — a hand-written ini would need an editor restart to take effect. It reports **which config file** the declaration landed in, so it can be put under source control
+- A tag that already exists reports `state: 'exists'` and writes nothing
+- `list_gameplay_tags` reports **declared** tags rather than every parent a declaration implies, so `Ability.Fire.Bolt` does not also list `Ability` and `Ability.Fire`. Filter with `prefix`; results page by `nextCursor`
+
+### `create_landscape` / `sculpt_landscape` / `paint_landscape_layer`
+
+- **Height and weight data never travels over the wire.** A 505×505 landscape is a quarter of a million samples, which no 64 KiB bridge frame can carry, so sculpting is either described procedurally (`flatten`, `ramp`, `noise`) or pointed at a heightmap file the editor host can already read
+- `create_landscape` reports the **vertex resolution**, which is the coordinate space the sculpt and paint regions are expressed in
+- Heights are world-space centimetres, so a caller can ask for a 20 m ramp without knowing about the landscape's raw `uint16` encoding or its 32768 midpoint
+- `heightmap_file` mode reads raw 16-bit little-endian data — what the landscape import dialog reads and what every terrain tool exports. A file whose size does not match the region is refused with both sizes rather than producing garbage terrain
+- `noise` takes a seed, so the same request twice produces the same terrain and a caller can raise the amplitude without the shape moving underneath them
+- `paint_landscape_layer` names the layers the landscape actually has when the requested one is missing, since a layer is only paintable once its material assigns it
+
+### `run_geometry_script`
+
+- Procedural mesh authoring: a box minus a cylinder in **one call**. Each operation carries its own primitive rather than referring to a mesh stack, so a boolean does not need three calls to set up
+- Built on the engine's own GeometryCore and DynamicMesh modules rather than on the Geometry Script plugin's Blueprint library — the same operations that plugin wraps — so it works whether or not that plugin is enabled
+- `output: 'static_mesh'` creates a `UStaticMesh` asset (dirty and unsaved, like every other asset write here); `output: 'dynamic_mesh_actor'` spawns an `ADynamicMeshActor` that lives in the level and in no asset. Supply `label` with a static mesh output to also place it
+- A boolean that produces a non-manifold result is reported as a **geometric failure with the operation index**, not swallowed: overlapping or open input geometry is the usual cause
+
+### `list_data_layers` / `set_data_layer_state` / `load_wp_region`
+
+- World Partition. On a partitioned map most actors are unloaded most of the time, which is why `list_actors` there answers about what is **in memory** rather than about what the level contains
+- `list_data_layers` reports `isWorldPartition`, so an empty list on an ordinary map reads as "there are none" rather than "none are loaded"
+- `set_data_layer_state` changes runtime state, editor loading and editor visibility independently, since they are three separate things in the editor. An editor-only data layer asked for a runtime state is refused rather than silently ignored
+- `load_wp_region` pins a bounding box into the editor through a loader adapter — the same mechanism the World Partition window uses when a human drags a loading region — and reports how many actors that brought into memory. The load is synchronous, so a box covering a large part of a big partitioned map blocks the editor while it runs: pin the area being worked on, not the whole world
+- Pins are held by the bridge and released on `unpin_all`, and every pin is released when the bridge shuts down, so a session cannot silently accumulate loaded actors nobody can name any more
+
+### `get_asset_property` / `set_asset_property` / `array_property_op`
+
+- The asset-side counterpart to `get_actor_details` / `set_actor_property`: reflected reads and writes against an asset on disk rather than an actor in a level
+- Values cross the wire as **ExportText**, the exact spelling the reader reports and the writer takes back, so a value read from one asset can be written straight into another without translation
+- `propertyPath` walks structs, array elements and object references (`Modifiers[1].Magnitude`), and an `FPostProcessSettings`-style field also sets its `bOverride_` sibling — a write that skipped it would report success and change nothing anyone can see
+- A Blueprint asset resolves to its **class defaults**, which is what the Class Defaults panel edits, rather than to the `UBlueprint` bookkeeping object that carries none of the user's properties
+- `array_property_op` exists because an array cannot be written as one exported string without knowing the whole array. It reports `elementCount` after the operation, and an out-of-range index is refused **before** the transaction opens so a rejected request leaves no undo entry behind
+- Every write leaves the package dirty rather than saving it, so a run of edits is one `save_asset`
+
+### `create_struct` / `create_enum`
+
+- User-defined types, authored through the engine's own `FStructureEditorUtils` / `FEnumEditorUtils` rather than by writing the asset — those utilities are what recompile every Blueprint that already referenced the type
+- Field and variable types share **one type grammar** with the Blueprint tools: a `kind`, an optional `container` (`array`, `set`, `map`) and a `subtype` naming what the kind points at. A kind that names something in the project without a subtype is refused, because UE would otherwise produce a wildcard pin
+- A fresh struct or enum arrives with one placeholder member so the asset is valid on disk; the requested members are added first and the placeholder removed afterwards, since neither utility will remove the last one
+- `rebuiltAssets` reports what the editor recompiled because the type changed underneath it — empty for a brand-new type, which has no dependents yet
+
+### `create_blueprint` / `add_bp_variable` / `add_bp_function` / `add_bp_event` / `add_bp_component` / `add_bp_interface` / `set_bp_default`
+
+- Blueprint **authoring**, the write side of `get_blueprint_summary` / `get_blueprint_graph`. Every call leaves the Blueprint compiled and its package dirty: an uncompiled Blueprint reports the old member list to every reader, which makes the next tool call wrong
+- `create_blueprint` reports the **generated class path** (`/Game/BP/BP_Foo.BP_Foo_C`), which is what `spawn_actor` and every class reference take — not the asset path
+- `add_bp_variable` carries replication: `rep_notify` also authors the `OnRep_` handler graph, because a `CPF_RepNotify` variable whose handler does not exist fails to compile
+- `add_bp_event` distinguishes `override` from `custom`. An override takes its signature from the parent, so declaring `inputs` on one is refused rather than silently discarded
+- Batched calls report **per entry**: one variable that fails to resolve its type does not abort the other thirty-one
+- `set_bp_default` writes the same reflected values `set_asset_property` does, against the generated class's CDO
+
+### `batch_edit`
+
+- The one level tool that is **all-or-nothing**. Every other batch reports per-item failures and keeps going; this one cancels its transaction on the first failure and leaves the level exactly as it was
+- That is the point: ops address actors earlier ops created. A `spawn` binds a caller-supplied `handle`, and a later op addresses it as `handle:<name>` — a half-applied batch would leave the level in a state nobody described
+- Ordered and heterogeneous: spawn, place, transform, set a property, attach, tag and destroy in one call, inside **one** `FScopedTransaction`, so a human presses Ctrl+Z once
+- `handles` reports what each handle bound to, so the new actors are addressable afterwards. A rollback reports `failedIndex` and `failedError` and no handles, because none of them exist any more
+- `dryRun` validates the shape of the batch only. An op addressing a handle can only be checked once the spawn that binds it has run, so anything further is a promise this call cannot keep
+
+### `import_asset` / `reimport_asset` / `set_import_settings` / `get_import_job_status`
+
+- Source asset import. An FBX of any real size runs far past the game thread budget, so both mutating requests return `state: 'accepted'` with an `importJobId`. Poll it with `get_import_job_status`, or wait with `wait_for_job` using `kind: 'import'`
+- `pipeline: 'auto'` lets the editor route the file — **Interchange first, legacy factory where there is no translator**, which is the engine's own behaviour. `'interchange'` is refused up front for a file no translator claims, rather than quietly running the legacy factory instead; `'legacy_factory'` names the factory explicitly so Interchange cannot take over behind the caller's back
+- Job results are **per source file**, and each one lists **every** asset it produced: a skeletal mesh import yields a mesh, a skeleton and a physics asset, and a caller that only heard about the mesh would leave the rest unreferenced
+- `set_import_settings` stores a named preset. It is applied to the import factory that claims each source file, so a key that factory does not have is a **request error** rather than something dropped on the floor
+- `get_import_job_status` is exposed as its own tool because the accept-then-poll shape needs somewhere to poll; it is not one of the tools the issues named, and it exists only to serve them
+
+### `create_blackboard` / `set_blackboard_keys`
+
+- Blackboard assets, the data half of a Behavior Tree
+- An `object`, `class` or `enum` key **must** name its base type. Without it the key still appears in the editor and never matches anything at runtime, which is the failure these tools exist to prevent
+- Inherited keys are counted and reported **separately** from local ones: a key that comes from the parent blackboard is not one this asset owns, and adding a local copy of it is exactly the mistake the split prevents
+- `set_blackboard_keys` with `mode: 'replace'` drops the **local** keys only — an inherited key belongs to the parent asset and is not this request's to remove
+
+### `create_eqs_query`
+
+- Environment queries: one generator plus its tests, each with its own `purpose` (`filter`, `score`, or both), since a failing test either removes an item or merely scores it down
+- Generator and test classes are resolved and their parameters written by reflection **before** the asset exists, so a typo leaves nothing behind in the content browser
+- `eqsEnabled` reports whether the Environment Query editor is switched on. With it off the asset is still valid and still runs, but nothing in the editor will open it — reported rather than failed, and the response names where to turn it on (Editor Preferences → Experimental → AI → Environment Query Editor)
+
+### `create_state_tree` / `add_state_tree_state`
+
+- StateTree assets and their states. `supportedVersions` is reported on every answer, so an editor this plugin build cannot author StateTrees for says so instead of failing somewhere inside the compiler
+- The schema decides which tasks and conditions the tree may hold at all, so an unresolvable one is refused before the asset exists
+- Tasks and enter conditions are **script structs**, not classes, and are addressed as such; their parameters are written into the instanced struct's own memory by reflection
+- `add_state_tree_state` compiles by default and reports `compiled` separately from the per-state results: a tree that was authored but not compiled reports `false` with no messages, which is a different thing from one that failed to compile
+
+### `create_level_sequence` / `add_sequence_binding` / `add_sequence_track` / `add_sequence_keys`
+
+- Sequencer authoring. **Every time on this surface is explicit**, because a sequence authored at the wrong rate is silently wrong rather than broken
+- Frame rates cross the wire as the exact rationals Sequencer stores — 30000/1001 is not 29.97 — and `create_level_sequence` reports back both `displayRate` and `tickResolution`, since every frame number in `add_sequence_keys` resolves through them
+- `add_sequence_keys` requires `timeUnit`: `'frames'` resolves through the display rate and `'seconds'` through the tick resolution. It reports `resolvedFrames`, which is the number that proves a seconds-based request converted correctly on a non-default rate
+- A `possessable` binding names an actor in the level; a `spawnable` one needs a template, so it takes an actor to copy or a class to instance
+- A `camera_cut` track belongs to the sequence itself; every other kind belongs to a binding, so `bindingId` is required for them. A `property` track is typed by the property it drives — bool, float and double properties are animatable, and anything else is refused rather than animated as the wrong type
+
+### `add_foliage_type` / `paint_foliage`
+
+- Foliage types and instance placement
+- `mode: 'explicit'` places the transforms the caller supplies. `mode: 'region'` is a **rule the editor evaluates against the ground** — density over an area, traced downward, filtered by slope — which is the only shape that scales to the tens of thousands of instances a real pass produces
+- A region takes a `randomSeed`, so the same call twice produces the same scatter and a painted region is reviewable rather than a one-off
+- `attemptedCount`, `placedCount` and `skippedCount` are reported separately: a placement whose downward trace hit nothing, or hit ground outside the slope limits, is skipped rather than placed floating. `instanceCount` is the foliage actor's **total** for that type afterwards, so density can be checked against something absolute
+
+### `create_sound_cue` / `create_metasound` / `set_metasound_graph`
+
+- Audio authoring. Sound Cue nodes are addressed by **caller-supplied ids**, so connections can name nodes before the editor has created them
+- `rootNodeId` must name one of the nodes in the same request, and a `wave_player` must name the wave it plays — both are refused up front rather than producing a cue that plays silence
+- MetaSound documents are **never written directly**. The document format is versioned and migrated by the engine, so everything goes through `UMetaSoundBuilderSubsystem`, which is the only supported way to author one from code
+- `set_metasound_graph` declares interface members, adds nodes by their registered class name and connects them. A connection whose data types do not match is reported with the builder's own refusal rather than left as a silently dead edge
+
 ## MCP Resources
 
 Resources carry context a client can attach without spending a tool call and a model turn. Every one of them is served from in-memory state or the local filesystem: **a resource read never opens a bridge socket and never waits on the editor**, so an unreachable or absent editor produces a structured payload rather than a timeout.