realms-in-ruin-dev/Documentation/Archaeology/00-MCP-Capability-Calibration.md

---
name: MCP Calibration Report
overview: Read-only Unreal MCP capability-calibration results for Realms in Ruin. No editor/project state was modified; PIE was not started. SemanticSearch failed (missing embedding API key); AssetTools and other inspect APIs succeeded.
todos:
  - id: archaeology-prep
    content: Use this calibration report as the gate checklist before the full archaeology pass (read-only tool whitelist + PIE-gated queries)
    status: pending
  - id: semantic-search-key
    content: "Optional: configure SemanticSearch embedding API key so Search/FindSimilar can be used in later passes"
    status: pending
isProject: false
---

# Unreal MCP Read-Only Capability Calibration Report

**Session constraints honored:** No ProgrammaticToolset, no create/update/set/save/delete/move/rename/compile/execute/activate/load-level/PIE/screenshot/click/type/drag, no Slate UI automation. PIE status checked only (`IsPIERunning` = false). Current level left as `/Game/_Main/Levels/Testing/Test01`.

---

## Successful Read-Only Queries

### 1. Asset location (`AssetTools.find_assets`)

| Query | Result paths |
|-------|----------------|
| Player_Paladin | `/Game/_Main/Blueprints/Characters/PlayerCharacters/PlayerCharacterClasses/Paladin/Player_Paladin` (+ meshes `SKM_Player_Paladin`, `SM_Player_Paladin`) |
| Player_Amazon | **No exact match.** Closest: `/Game/_Main/Blueprints/Characters/PlayerCharacters/PlayerCharacterClasses/Amazonian/Player_Amazonian` |
| BP_Enemy_Skeleton | `/Game/_Main/Blueprints/Characters/Enemies/Skeleton/BP_Enemy_Skeleton` |
| Test01 | `/Game/_Main/Levels/Testing/Test01` |
| Dev_Island | `/Game/_Main/Levels/Testing/Dev_Island` (+ `Dev_Island_BuiltData`) |

### 2. SemanticSearch (`SemanticSearchToolset.Search`)

**Failed.** Embedding generation returned HTTP 401 (no API key). Index/toolset present but not usable until SemanticSearch embedding credentials are configured.

### 3. Player_Paladin structural inspection

| Field | Value |
|-------|--------|
| Asset path | `/Game/_Main/Blueprints/Characters/PlayerCharacters/PlayerCharacterClasses/Paladin/Player_Paladin` |
| Object ref | `/Game/_Main/Blueprints/.../Player_Paladin.Player_Paladin` |
| Generated class | `Player_Paladin_C` → `/Game/.../Player_Paladin.Player_Paladin_C` |
| Blueprint parent | `/Game/_Main/Blueprints/Characters/PlayerCharacters/BP_PlayerCharacterBase.BP_PlayerCharacterBase_C` |
| Native parent | `/Script/REALMSINRUIN.RIRPlayerCharacter` |
| Own variables | `Ability001Montages`, `ChargeStartLoc`, `ChargeFinishLoc`, `IsCharging`, `IsBlocking` |
| Inherited DEPRECATED vars (on base) | On `BP_PlayerCharacterBase`: `DEPRECATED_CurrentHealth/MaxHealth`, `DEPRECATED_CurrentMana/MaxMana`, `DEPRECATED_CurrentStamina/MaxStamina`, `DEPRECATED_ManaRegenOverTime`, `DEPRECATED_Ability00{1-4}Damage/ManaCost` |
| Graphs | `UserConstructionScript`, `GetPlayerPaladinREF`, `PlayerHitCheck`, `EventGraph` |
| Implemented functions (local) | `UserConstructionScript`, `GetPlayerPaladinREF`, `PlayerHitCheck` |
| Key implemented events | `Charge`, `Client_Charge`, `Server_Ability_00{1-4}_*`, `UseAbility001/004`, `ReceiveBeginPlay`, `ReceiveTick`, `ReceiveActorBeginOverlap` |
| Components (via CDO `get_components`) | Native: `CollisionCylinder`, `Arrow`, `CharacterMesh0`, `CharMoveComp`, `AbilitySystemComponent`; many skeletal mesh attach comps (`Helmet`, `Sword`, `Shield`, sockets, etc.); inherited `TPSpringArm`, `ThirdPersonCamera`, footstep comps |
| Interfaces on Paladin asset tags | **Not listed** in `get_asset_tags` `ImplementedInterfaces` (empty/absent). Referencers include `/Game/_Main/Blueprints/Interfaces/BPI_PlayerCharacter` |
| DEPRECATED ability section | **Structurally inspectable.** `find_nodes(title="DEPRECATED")` + `get_node_infos` + `get_connected_subgraph` walk EventGraph nodes e.g. `GetDEPRECATED_Ability003ManaCost` → `FCanUseMana` → Branch → `Charge` / `Client_Charge` chain from `EventServer_Ability_003_Begin` |

### 4. Selected `BP_Enemy_Skeleton` instance

| Field | Value |
|-------|--------|
| Selected actor | `/Game/_Main/Levels/Testing/Test01.Test01:PersistentLevel.BP_Enemy_Skeleton_C_1` |
| Blueprint asset | `/Game/_Main/Blueprints/Characters/Enemies/Skeleton/BP_Enemy_Skeleton` |
| Class | `/Game/.../BP_Enemy_Skeleton.BP_Enemy_Skeleton_C` |
| Blueprint parent | `/Game/_Main/Blueprints/Characters/Enemies/BP_EnemyCharacterBase.BP_EnemyCharacterBase_C` |
| Native parent | `/Script/REALMSINRUIN.RIRBaseEnemyCharacter` |
| Implemented interface | `BPI_EnemyCharacter` → `/Game/_Main/Blueprints/Interfaces/BPI_EnemyCharacter.BPI_EnemyCharacter_C` (graph `GetEnemyREF`) |
| AI Controller class | `/Script/AIModule.AIController` (stock engine class) |
| AutoPossessAI | `PlacedInWorld` |
| Components | `CollisionCylinder`, `Arrow`, `CharMoveComp`, `CharacterMesh0`, `AbilitySystemComponent` (+ `AttributeSet` property → `...BP_Enemy_Skeleton_C_1.AttributeSet`) |
| ASC editor state | `defaultStartingData=[]`, `activatableAbilities.items=[]` |
| Dependencies | `SKM_Skeleton_Guard_Body`, `BPI_EnemyCharacter`, `BP_EnemyCharacterBase`, `/Script/REALMSINRUIN`, `/Game/_Main/Animations/Enemies/Skeleton/ABP_Skeleton` |
| Perception / BT / Blackboard props on instance | **Not present** as dedicated properties on the actor instance beyond stock pawn AI fields |

### 5. BehaviorTreeTools vs project content

- `AssetTools.find_assets` with `asset_type=/Script/AIModule.BehaviorTree` over `/Game` → **[]**
- No `BT_*`, `Blackboard`, `AIC_*`, or `Perception` assets under `/Game/_Main`
- `ObjectTools.search_subclasses(AIController, "RIR")` → **[]**
- **Conclusion:** BehaviorTreeTools APIs (`list_nodes`, `get_blackboard`, etc.) are available, but **no Behavior Tree asset is associated with `BP_Enemy_Skeleton` in this project** — nothing to inspect.

### 6. AttributeSetToolset

`FindAttributeSetClasses` returned:

- **`RIRAttributeSet`** (native, empty `assetPath`) — Realms in Ruin set: `Health`, `MaxHealth`, `Mana`, `MaxMana`, `Stamina`, `MaxStamina`
- `AbilitySystemTestAttributeSet` (engine/test)
- `GASToolsetsTestAttributeSet` (toolset test)

### 7. GameplayTagsToolset (read-only `ListTags` / `GetTagInfo`)

- `ListTags(parentTag="")` returned full manager list (project + engine/plugin tags).
- Sample project tags from `DefaultGameplayTags.ini`: `State.Dead`, `Disable.Ability`, plus `Disable.*`, `Effect.*`, `State.*`, etc.
- Also listed engine/plugin tags (`EnhancedInput.*`, `Niagara.*`, `UI.Action.*`, `Tests.*`, …).
- Mutators (`AddTag`/`RemoveTag`/`RenameTag`) **not used**.

### 8. Domain capability probes (read-only)

| Domain | Tooling that worked | Sample / note |
|--------|---------------------|---------------|
| Gameplay Effects | `AssetTools` + `ObjectTools` on CDO | e.g. `/Game/_Main/Blueprints/Game/GameSystems/GAS/GameplayEffects/PlayerCharacters/Paladin/GE_Paladin_DefaultAttributes` — Instant GE, overrides `RIRAttributeSet:Health/Mana` to 100 |
| Gameplay Abilities | Class filter `/Script/GameplayAbilities.GameplayAbility` → **[]**; `GA_*` name search → **[]**; `search_subclasses` → **[]** | No discrete GA assets found; abilities appear BP-event driven (`Server_Ability_*`, `UseAbility*`) |
| Anim Blueprints | `AssetTools` + `BlueprintTools.list_graphs` | `/Game/_Main/Animations/PlayerCharacters/Human/CharacterClasses/Paladin/ABP_Paladin` — AnimGraph states Idle/WalkRun/Charge/Block/Death |
| Anim Montages | `AssetTools` + `get_asset_tags` | e.g. `Paladin_Ability004_Montage` — Skeleton `SKEL_Hu_M`, length `1.866667` |
| UMG | `AssetTools` + `BlueprintTools` + UMG read helpers | Widgets under `/Game/_Main/UI/Widgets/...`; UMGToolSet has `ListWidgetBlueprints`, `GetWidgets`, `GetWidgetTreeDepth`, etc. (mutating UMG ops exist but were not used) |
| Advanced Sessions | `PluginToolset` + `AssetTools` + `BlueprintTools` | Plugin **enabled**; path `.../Plugins/AdvancedSessions`; example BP `/Game/_Main/Blueprints/Examples/ExampleAdvancedSessionsFunctionsChar` contains many `K2Node_LatentOnlineCall` / Session nodes |

---

## Information Available

- Asset registry search by name/type/folder; deps/refs; asset class; asset registry tags; metadata tags; load soft refs
- Blueprint parent chain (BP + native); graphs; functions; events (incl. `bIsImplemented`); variables (per-Blueprint, not auto-merged inheritance in one call)
- Graph structure: find nodes by title, node infos (pins/connections/positions), connected subgraphs, `read_graph_dsl`
- Actor/instance: selection query, class, components, property list/get (AIControllerClass, ASC, AttributeSet, etc.)
- AttributeSet discovery + attribute names
- Gameplay tag list + per-tag comment/source/children
- Plugin enablement + descriptor/path for Advanced Sessions
- AnimBP graph/state machine listing via BlueprintTools
- GE CDO modifiers/duration via ObjectTools
- Current level path; PIE running flag

---

## Information Not Exposed

- **SemanticSearch** without embedding API key
- **Dedicated GameplayAbility asset inspector** (no GA assets + no GA-specific toolset beyond runtime `AbilitySystemInspectorToolset`)
- **Behavior Trees / Blackboards / custom AIControllers / AI Perception assets** for enemies in this project (tools exist; content absent)
- **ImplementedInterfaces** as a reliable ObjectTools property on BP/CDO (failed property reads); available via **asset registry tags** when populated (worked for Skeleton, not Paladin tags)
- **Inherited Blueprint variables** not returned by child `list_variables` alone (must query each parent BP)
- **Comment-box / graph-section / “DEPRECATED ability section” as a named region** — only discoverable via node title search + subgraph walk
- **Montage notify/timeline deep structure** beyond asset registry tags (`AnimNotifyList` was empty `;` in sample)
- **Runtime ASC state** (granted abilities, active effects, live attribute values) without PIE
- **Online session runtime** (Advanced Sessions latent results) without PIE/network
- Full UMG visual tree layout details without loading widget into UMGToolSet/`GetWidgets` (read APIs exist; not fully exercised for every widget)

---

## Queries Requiring PIE

Mark as **Requires Runtime Inspection**:

- `GASToolsets.AbilitySystemInspectorToolset.*` (`GetGrantedAbilities`, `GetAttributeValues`, `GetActiveTags`, `GetActiveEffects`) — needs live ASC
- Runtime AI possession / Behavior Tree tick / Blackboard values (even if BTs existed)
- Advanced Sessions create/find/join session outcomes
- Montage playback, ability activation success, damage application, death/respawn flows
- `GameplayCueToolset.ExecuteCueOnSelectedActor` (executes cue; docs note PIE/manager for visible results) — also mutating/execute, excluded here

---

## Queries Requiring Manual Editor Inspection

- SemanticSearch captions/similarity until API key configured
- Visual layout of DEPRECATED comment regions / collapsed graph sections in EventGraph
- Confirm whether enemy AI logic lives entirely in native `RIRBaseEnemyCharacter` C++ (no BT assets found)
- Exact BPI_PlayerCharacter implementation chain on Paladin vs base (tags vs interface editor UI)
- AnimMontage notify tracks / section names when registry tags are empty
- Any content outside `/Game` that uses non-standard naming (e.g. undocumented AI assets)

---

## Recommended Toolsets for the Full Archaeology Pass

**Primary (read-only):**

1. `editor_toolset.toolsets.asset.AssetTools` — locate, classify, deps/refs, tags
2. `editor_toolset.toolsets.blueprint.BlueprintTools` — graphs/functions/events/variables/nodes/DSL
3. `editor_toolset.toolsets.object.ObjectTools` — CDO/instance properties, subclass search
4. `editor_toolset.toolsets.actor.ActorTools` — component trees on CDO/instances
5. `EditorToolset.EditorAppToolset` — selection, open assets, PIE status only
6. `editor_toolset.toolsets.scene.SceneTools` — `get_current_level`, `find_actors` (avoid `load_level`)
7. `GASToolsets.AttributeSetToolset` — attribute inventory
8. `GameplayTagsToolset.GameplayTagsToolset` — `ListTags` / `GetTagInfo` / `FindReferencersByTag` only
9. `GASToolsets.GameplayCueToolset` — `ListCues` / `GetCueInfo` / `FindCueNotifyAssets` only
10. `PluginToolset.PluginToolset` — `ListEnabledPlugins` / `GetPluginInfo` / `IsEnabled`
11. `UMGToolSet.UMGToolSet` — `ListWidgetBlueprints`, `GetWidgets`, `GetWidgetTreeDepth`, `GetWidgetDescription` only
12. `aimodule_toolset.toolsets.behavior_tree.BehaviorTreeTools` — only if BT assets appear later

**Deferred / gated:**

- `SemanticSearchToolset` — after API key
- `GASToolsets.AbilitySystemInspectorToolset` — **Requires Runtime Inspection** (PIE)
- Avoid: ProgrammaticToolset, SlateInspector, mutating Asset/Blueprint/Object/Scene/UMG/GameplayTags ops

**Suggested archaeology order:** AttributeSets + Tags → Character BP hierarchy (native → base → class) → GE CDOs → AnimBP/Montages → UI widgets → Plugin/session examples → level-placed enemy instances → (optional PIE) ASC runtime.

---

## Calibration verdict

Unreal MCP read-only tooling is **sufficient for structural archaeology** of Blueprints, levels, GEs, AnimBPs, montages, tags, AttributeSets, plugins, and UMG widget discovery. Gaps: SemanticSearch credentials, absence of GA/BT project assets, and any live GAS/AI/session behavior (**Requires Runtime Inspection**).