@uemcp/server 1.3.0 → 1.4.0

package/README.md

@@ -94,6 +94,37 @@ The MCP tool surface currently exposes:
 - `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
 
@@ -358,6 +389,89 @@ This is intended to let an MCP client resolve the canonical Unreal project ident
 - `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.