@uemcp/server 0.3.0 → 1.0.0

package/README.md

@@ -32,6 +32,18 @@ The MCP tool surface currently exposes:
 - `set_config_value`
 - `list_config_section`
 - `run_clang_tidy`
+- `list_actors`
+- `get_actor_details`
+- `get_current_level`
+- `spawn_actor`
+- `destroy_actor`
+- `set_actor_transform`
+- `set_actor_property`
+- `select_actors`
+- `undo`
+- `redo`
+- `open_level`
+- `get_open_level_status`
 
 ## Project Identity
 
@@ -137,6 +149,69 @@ This is intended to let an MCP client resolve the canonical Unreal project ident
 - Spawns `clang-tidy` (server-configured via `CLANG_TIDY_PATH`, else `PATH`) over the translation units and returns structured findings (file, line, column, check, severity, message)
 - Report only — does not apply fixes
 
+### `list_actors` / `get_actor_details` / `get_current_level`
+
+- The read half of the level surface. All three answer about actors instantiated in the **editor world** — not the PIE world, and not assets on disk (`find_assets` remains the tool for those)
+- Every actor is identified by `actorPath` — `AActor::GetPathName()`, e.g. `/Game/Maps/Test.Test:PersistentLevel.StaticMeshActor_3` — carried alongside the display `label`. The path is the only stable, unique, resolvable identifier; labels are neither unique nor resolvable, so never address an actor by one. The same `actorPath` round-trips through `get_editor_state`, `list_actors`, and `select_actors`
+- `list_actors` filters by class and by name substring, and pages with `nextCursor` / `totalCount` / `truncated`. Pages are trimmed by encoded bytes as well as by entry count, because actor paths vary wildly in length — `totalCount` stays authoritative when a page truncates
+- `get_actor_details` reports the actor's class, transform, folder, tags, components, and reflected properties, paging components and properties independently. Property values are `ExportText`, the same format `get_cdo_defaults` emits and `set_actor_property` accepts
+- `get_current_level` reports the loaded map's package name plus its streaming levels and World Partition state
+
+### `spawn_actor` / `destroy_actor` / `set_actor_transform` / `set_actor_property` / `select_actors`
+
+- The mutating half. **Every one of these runs inside a single `FScopedTransaction` on the game thread, so one Ctrl+Z in the editor reverses the whole call** — a batch of 64 spawns undoes as one step, not 64. The response reports the `transactionTitle` the batch collapsed into
+- All five take **arrays** and return per-item results (`{ index, ok, actorPath?, error? }`) with `successCount` / `failureCount`. One bad entry fails its own item and neither aborts the batch nor rolls back the transaction. The batch bound is 64 (`BRIDGE_LEVEL_EDIT_MAX_BATCH`), sized so the request also stays under the 64 KiB payload cap
+- `dryRun: true` validates everything the real call validates — class resolves, actor exists, property path resolves and the value coerces — and reports what *would* change with `state: 'validated'`, opening no transaction and touching no world state
+- Mutations `Modify()` the objects they touch and dirty their packages, so `save_dirty_packages` subsequently reports and persists them
+- `set_actor_transform` treats each of `location` / `rotation` / `scale` as optional: an omitted component keeps its current value, so a move need not restate the rest. An entry naming none of the three is rejected rather than silently doing nothing
+- `set_actor_property` addresses a property on the actor (`bHidden`) or on one of its components (`StaticMeshComponent.RelativeScale3D`), and writes via `ImportText_InContainer` — the exact inverse of the reader, so a value read from `get_actor_details` or `get_cdo_defaults` can be edited and written back with no format translation. `EditConst` and non-editable properties are rejected with an explicit error rather than silently no-op'ing
+- `select_actors` sets the editor selection; an empty `actorPaths` clears it, and `addToSelection` adds rather than replaces. It reports the resulting `selectedActorCount`
+- In a non-editor plugin build every one of these returns `state: 'unsupported'` rather than failing
+
+### `undo` / `redo`
+
+- Act on the editor's own transaction buffer — the same buffer Ctrl+Z and Ctrl+Y drive — and report the `transactionTitle` they acted on, or `state: 'nothing_to_undo'` / `'nothing_to_redo'`
+- The head of that buffer may be a **human's** edit rather than the agent's, so check the returned `transactionTitle` before assuming what was reversed
+
+### `open_level` / `get_open_level_status`
+
+- Loading a map tears down and rebuilds the world, which runs far past the plugin's 5 s game-thread budget, so `open_level` does not load inline: it validates the request, schedules the load onto the next editor tick, and returns `state: 'opening'` with an `openLevelJobId`. Poll it with `get_open_level_status` (or `wait_for_job`) until the state leaves `opening`
+- `dryRun: true` checks that the level package exists and reports `state: 'validated'` with no job — nothing was scheduled, so nothing is pollable
+- Unsaved changes in the current world are **discarded** unless `saveDirtyPackages: true`, which saves before the teardown. There is no user in front of a bridge request to answer the editor's usual "save these?" prompt
+- **Not undoable.** Loading a map clears the transaction buffer, so `undo` cannot bring the previous level back
+- Actor paths do not survive a load: re-run `list_actors` against the new world rather than reusing paths from the old one
+- One load at a time per editor; a second request while one is running is refused with `open_level_in_progress` rather than queued
+
+## 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.
+
+All resources use the `uemcp://` URI scheme, are `application/json`, and are capped at 64 KB (`MAX_RESOURCE_PAYLOAD_BYTES`). A read that hits the cap drops entries from the end of the list and sets `truncated: true` while `totalCount` stays authoritative — the same convention the paged tools use. The authority segment (`registry`, `engines`, `workspace`) is the type discriminator.
+
+| URI | Contents |
+| --- | --- |
+| `uemcp://registry` | Every registered Unreal Editor: `projectId`, `projectName`, `projectPath`, `port`, `pid`, `registeredAt`, `lastSeenAt`, plus `totalCount` and `truncated` |
+| `uemcp://registry/{projectId}` | One registration, addressed by canonical ProjectID. Enumerable — the template's `list` callback returns the current registry, and `projectId` offers completions from it |
+| `uemcp://engines` | Unreal installs found under `UE_INSTALLS_DIR`, ascending by version, each with `engineVersion`, `engineRoot`, and `unrealBuildToolResolved`. Source builds and GUID engine associations are excluded, matching `resolveEngine` |
+| `uemcp://workspace/project` | The Unreal project identity of the server's working directory, resolved from `Config/DefaultGame.ini` |
+
+`uemcp://registry/{projectId}` reports `found: false` with a `reason` for an unknown or malformed ProjectID, and `uemcp://engines` / `uemcp://workspace/project` report a `reason` when `UE_INSTALLS_DIR` is unset or the directory is not an Unreal project — none of them fail the read.
+
+Registering or deregistering an editor over the HTTP API emits `notifications/resources/list_changed`. There is no `resources/subscribe`: the MCP SDK's `McpServer` does not implement it, so the list-changed notification is the only change signal.
+
+## MCP Prompts
+
+Prompts ship the workflows this server knows about as discoverable entry points for any MCP client, not just ones that can read the repo's `.agents/skills/` runbooks. They are compiled into the bundle, reference only tools this server registers, and assume no shell, no checkout, and no particular client.
+
+| Prompt | Arguments | What it drives |
+| --- | --- | --- |
+| `diagnose_crash` | `projectId` | Registration check, `get_crash_callstack`, `get_editor_state`, then the output log around the crash |
+| `diagnose_bridge_disconnect` | `projectPath` (optional) | Which leg of the bridge is broken: registry state, `get_project_id` cross-check, `ping_project`, plugin-side log evidence |
+| `smoke_test_bridge` | `projectId` | Green-path proof: registration, `ping_project`, `get_editor_state`, and a full log subscribe-emit-drain cycle |
+| `add_gameplay_feature` | `projectId`, `className`, `parentClass`, `moduleName` (optional) | `create_cpp_class` → `wait_for_job` → implement → `trigger_live_compile` → `run_automation_tests` → `save_dirty_packages` |
+
+`diagnose_bridge_disconnect` and `smoke_test_bridge` are distilled from the same-named skills in `.agents/skills/`. Those files stay separate on purpose: they are maintainer runbooks that reference `just` recipes, `registry.json` paths, and pino module loggers, and the published package ships `dist` only, so they cannot be read at runtime. Each skill carries a pointer to its prompt counterpart so the two do not silently diverge.
+
 ## Configuration
 
 - Engine toolchain (`build_target`, `generate_project_files`, `clean_build`):