@uemcp/server 1.2.0 → 1.3.0

package/README.md

@@ -48,6 +48,52 @@ 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`
 
 ## Project Identity
 
@@ -228,6 +274,90 @@ 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
+
 ## 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.