claude-code-arcane 2.3.0 → 2.4.0

package/hooks/detect-unreal.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# SessionStart hook: inject a short note identifying the session as operating inside
+# an Unreal Engine project, so Claude defaults to UE conventions and reaches for the
+# ue-* skills. Walks upward from $PWD so sessions started in a subdirectory
+# (Source/, Content/, Plugins/, ...) are still detected.
+#
+# Adapted from EpicGames/unreal-engine-skills-for-claude-code-plugin (MIT).
+# Opt-in debug logging: set CLAUDE_UE_HOOK_DEBUG to any non-empty value.
+set +e
+
+debug() {
+  [[ -n "$CLAUDE_UE_HOOK_DEBUG" ]] && echo "detect-unreal.sh: $*" >&2
+}
+
+is_project_root() {
+  # Reliable top-level markers only. A bare `Engine` directory is NOT a marker: the
+  # Unreal source tree contains an `Engine` module at Engine/Source/Runtime/Engine,
+  # so walking up from a Runtime module would otherwise short-circuit at
+  # Source/Runtime and mis-identify it as the root.
+  local directory="$1"
+  [[ -f "$directory/GenerateProjectFiles.bat" ]] && return 0
+  [[ -f "$directory/GenerateProjectFiles.sh" ]] && return 0
+  [[ -f "$directory/GenerateProjectFiles.command" ]] && return 0
+  for candidate in "$directory"/*.uproject; do
+    [[ -e "$candidate" ]] && return 0
+  done
+  return 1
+}
+
+find_project_root() {
+  local directory="$1"
+  while [[ -n "$directory" ]]; do
+    if is_project_root "$directory"; then
+      echo "$directory"
+      return 0
+    fi
+    local parent
+    parent="$(dirname "$directory")"
+    [[ "$parent" == "$directory" ]] && break
+    directory="$parent"
+  done
+  return 1
+}
+
+main() {
+  local project_root
+  project_root="$(find_project_root "$PWD")"
+  if [[ -z "$project_root" ]]; then
+    debug "no Unreal Engine project marker found walking up from $PWD"
+    return 0
+  fi
+
+  local project_type="game"
+  [[ -d "$project_root/Engine" ]] && project_type="engine"
+
+  local uproject_filename=""
+  for candidate in "$project_root"/*.uproject; do
+    if [[ -e "$candidate" ]]; then
+      uproject_filename="$(basename "$candidate")"
+      break
+    fi
+  done
+
+  debug "project root: $project_root (type=$project_type, uproject=$uproject_filename)"
+
+  local context="This working directory is an Unreal Engine project."
+  if [[ "$project_type" == "engine" ]]; then
+    context="$context It is an Engine source tree."
+  elif [[ -n "$uproject_filename" ]]; then
+    context="$context The project is \`$uproject_filename\`."
+  fi
+  context="$context Prefer Unreal Engine conventions (C++/UObject patterns, Slate, UHT reflection) when suggesting code."
+  context="$context Arcane ships ue-* skills for this stack; run /ue-project-context first if docs/unreal/project-context.md does not exist yet."
+  context="$context Unreal ships its own MCP server as engine plugins; run /install-mcp to enable and connect it."
+
+  if [[ -f "$project_root/.mcp.json" ]]; then
+    context="$context An \`.mcp.json\` is already present at the project root."
+  else
+    context="$context No \`.mcp.json\` is present yet. Run \`ModelContextProtocol.GenerateClientConfig ClaudeCode\` in the editor console to generate one."
+  fi
+
+  # JSON-escape the dynamic content: backslash first, then double quote.
+  local escaped="${context//\\/\\\\}"
+  escaped="${escaped//\"/\\\"}"
+
+  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$escaped"
+}
+
+main 2>/dev/null
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx claude-code-arcane",
   "type": "module",
   "bin": {

package/profiles/unreal-dev.yaml

@@ -0,0 +1,97 @@
+name: unreal-dev
+description: "Programador Unreal Engine 5 — C++, Blueprints, GAS, replication, rendering, naming conventions, build y editor MCP"
+type: base
+
+skills:
+  # Foundation — read this first, every other ue-* skill depends on it
+  - ue-project-context
+  - ue-naming-conventions
+  # C++ & architecture
+  - ue-cpp-foundations
+  - ue-actor-component-architecture
+  - ue-gameplay-framework
+  - ue-module-build-system
+  - ue-async-threading
+  # Blueprints
+  - ue-blueprints
+  # Gameplay systems
+  - ue-gameplay-abilities
+  - ue-character-movement
+  - ue-animation-system
+  - ue-physics-collision
+  - ue-game-features
+  - ue-networking-replication
+  # AI & behaviour
+  - ue-ai-navigation
+  - ue-state-trees
+  - ue-mass-entity
+  # Rendering & VFX
+  - ue-materials-rendering
+  - ue-niagara-effects
+  # Audio & cinematics
+  - ue-audio-system
+  - ue-sequencer-cinematics
+  # World & data
+  - ue-world-level-streaming
+  - ue-procedural-generation
+  - ue-data-assets-tables
+  - ue-serialization-savegames
+  # UI & input
+  - ue-ui-umg-slate
+  - ue-input-system
+  # Tooling, build & QA
+  - ue-editor-tools
+  - ue-testing-debugging
+  - ue-packaging
+  # Cross-engine, reused from the shared library
+  # Unreal ships its own MCP as engine plugins; install-mcp only enables and connects it.
+  - install-mcp
+  - test-setup
+  - perf-profile
+  - optimize
+  - deps-audit
+  - env-sync
+  - security-audit
+  - release-checklist
+  - patch-notes
+  - onboard
+  - map-systems
+  - game-audit
+  - audit-game
+  - asset-audit
+  - accessibility
+  - balance-check
+  - consistency-check
+  - doc-gdd
+  - playtest-report
+
+rules:
+  universal:
+    []
+  gamedev:
+    - unreal-code
+    - gameplay-code
+    - engine-code
+    - shader-code
+    - network-code
+    - ui-code
+    - ai-code
+
+agents:
+  - game
+
+permissions:
+  allow:
+    - "Bash(*RunUAT*)"
+    - "Bash(*UnrealBuildTool*)"
+    - "Bash(*UnrealEditor-Cmd*)"
+    - "Bash(*GenerateProjectFiles*)"
+    - "Glob(Source/**)"
+    - "Glob(Plugins/**)"
+    - "Grep(Source/**)"
+  deny:
+    - "Write(Content/**)"
+    - "Edit(Content/**)"
+    - "Write(Binaries/**)"
+    - "Write(Intermediate/**)"
+    - "Write(DerivedDataCache/**)"

package/rules/gamedev/unreal-code.md

@@ -0,0 +1,125 @@
+---
+paths:
+  - "Source/**"
+  - "Plugins/**/Source/**"
+---
+
+# Unreal Engine C++ Rules
+
+- Every UObject reference held by another UObject must be a `TObjectPtr<>` marked `UPROPERTY()` — an unmarked pointer is invisible to the GC and becomes a dangling pointer
+- Never `new`/`delete` a UObject — use `NewObject<>()` or `CreateDefaultSubobject<>()`; use `TSharedPtr`/`TUniquePtr`/`TWeakPtr` only for non-UObject types
+- Follow engine naming: `U` for UObject, `A` for AActor, `F` for structs, `E` for enums, `I` for interfaces, `T` for templates
+- Restrict every identifier to `[A-Za-z0-9_]` — no whitespace, no symbols, no Unicode. This applies to type names, asset references and paths alike; non-ASCII identifiers break cooking, batch tools and source control in ways that surface far from the cause
+- Use `FName` for identifiers and lookups, `FText` for anything shown to a player, `FString` only for manipulation — never build display strings by concatenating `FString` for localized UI
+- Use `TArray`/`TMap`/`TSet`, not STL containers, in any reflected or engine-facing code
+- `Tick` is opt-in, not default: disable it (`PrimaryActorTick.bCanEverTick = false`) and use timers, delegates or events instead. Ticking work multiplied across instances is a measured cost, not an assumption
+- ZERO allocations in hot paths (tick, animation, physics, rendering) — pre-allocate, pool and reuse
+- Always call `Super::` in overridden engine functions (`BeginPlay`, `EndPlay`, `Tick`, `GetLifetimeReplicatedProps`, `PostInitializeComponents`)
+- Every replicated `UPROPERTY(Replicated)` must appear in `GetLifetimeReplicatedProps` with a `DOREPLIFETIME` entry, and every Server RPC must validate its input — never trust the client
+- Use soft references (`TSoftObjectPtr`, `TSoftClassPtr`) plus the Asset Manager for assets that are not always needed; a hard reference pulls the whole asset tree into memory
+- No synchronous load of large assets on the game thread during gameplay — use `StreamableManager` / async loading
+- UObject access happens on the game thread only; async completion paths must handle their owner being destroyed mid-flight
+- Editor-only code lives in an editor module or behind `WITH_EDITOR`, and never ships in a runtime target
+- Profile with Unreal Insights and `stat` commands before AND after every optimization — document the measured numbers
+- Blueprint Nativization was removed in UE5; never propose it as an optimization
+
+## Examples
+
+**Correct** (GC-visible reference, no tick, validated RPC):
+
+```cpp
+UCLASS()
+class AGate : public AActor
+{
+    GENERATED_BODY()
+
+public:
+    AGate()
+    {
+        PrimaryActorTick.bCanEverTick = false;  // event-driven, nothing to tick
+    }
+
+protected:
+    virtual void BeginPlay() override
+    {
+        Super::BeginPlay();  // never skip Super
+        OnActorBeginOverlap.AddDynamic(this, &AGate::HandleOverlap);
+    }
+
+    UFUNCTION(Server, Reliable, WithValidation)
+    void ServerRequestOpen();
+
+private:
+    // TObjectPtr + UPROPERTY: the GC can see and keep this alive.
+    UPROPERTY(VisibleAnywhere)
+    TObjectPtr<UStaticMeshComponent> Frame;
+
+    // Soft reference: the VFX only loads when the gate actually opens.
+    UPROPERTY(EditDefaultsOnly)
+    TSoftObjectPtr<UNiagaraSystem> OpenEffect;
+};
+
+bool AGate::ServerRequestOpen_Validate()
+{
+    return true;
+}
+
+void AGate::ServerRequestOpen_Implementation()
+{
+    // Server re-checks authority and state; the client's word is not enough.
+    if (!HasAuthority() || bIsLocked)
+    {
+        return;
+    }
+    OpenInternal();
+}
+```
+
+**Incorrect** (invisible to GC, needless tick, trusted client, hot-path allocation):
+
+```cpp
+UCLASS()
+class AGate : public AActor
+{
+    GENERATED_BODY()
+
+    // VIOLATION: raw pointer with no UPROPERTY — GC cannot see it, this will dangle
+    UStaticMeshComponent* Frame;
+
+    // VIOLATION: hard reference, loads the VFX and its dependencies with this actor
+    UPROPERTY()
+    UNiagaraSystem* OpenEffect;
+
+    virtual void BeginPlay() override
+    {
+        // VIOLATION: missing Super::BeginPlay()
+        Frame = new UStaticMeshComponent();  // VIOLATION: never new a UObject
+    }
+
+    virtual void Tick(float DeltaTime) override
+    {
+        // VIOLATION: allocates every frame
+        TArray<AActor*> Nearby;
+        UGameplayStatics::GetAllActorsOfClass(GetWorld(), APawn::StaticClass(), Nearby);
+
+        // VIOLATION: string comparison in a hot path — use FName or a tag
+        for (AActor* A : Nearby)
+        {
+            if (A->GetName() == TEXT("BP_Player_C_0"))
+            {
+                OpenInternal();
+            }
+        }
+    }
+
+    UFUNCTION(Server, Unreliable)
+    void ServerRequestOpen(bool bClientSaysUnlocked)
+    {
+        // VIOLATION: trusts a client-supplied authority decision
+        if (bClientSaysUnlocked)
+        {
+            OpenInternal();
+        }
+    }
+};
+```

package/skills/install-mcp/SKILL.md

@@ -1,45 +1,60 @@
 ---
 name: install-mcp
-description: "Instala y registra el MCP de Unity (CoplayDev MCP for Unity) en un proyecto Unity + Claude Code: agrega el package UPM, registra el server MCP y verifica la conexion. Usar para: instalar mcp unity, conectar Claude con Unity, setup MCP Unity."
+description: "Conecta Claude Code con el MCP del engine: Unity (package UPM CoplayDev) o Unreal (plugins del engine). Detecta, registra y verifica. Usar para: mcp unity, mcp unreal, setup MCP del editor."
 category: "gamedev"
-argument-hint: "[--secondary] [project-path]"
+argument-hint: "[unity | unreal] [--secondary] [project-path]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, Write, Edit
 ---
-# install-mcp — Unity MCP Setup
+# install-mcp — Engine MCP Setup
 
-Instala el package MCP del lado Unity y registra el server MCP en Claude Code, replicando el setup usado en los proyectos de tesis (TesisUade).
+Conecta Claude Code con el editor del engine via MCP. Los dos engines difieren en algo importante:
 
-- **Package primario:** `com.coplaydev.unity-mcp` (CoplayDev "MCP for Unity"). Server Python vía `uv`/`uvx`, transport HTTP en `127.0.0.1:8080`. El server se levanta y auto-configura desde Unity en `Window → MCP for Unity`.
-- **Package secundario (opcional, flag `--secondary`):** `com.gamelovers.mcp-unity` (CoderGamester). Server Node.
+| | Unity | Unreal |
+|---|---|---|
+| **De donde viene el MCP** | Package de terceros (CoplayDev) | **Plugins propios del engine** (`ModelContextProtocol` + `AllToolsets`) |
+| **Se suma algo al proyecto** | Si — package UPM en `Packages/manifest.json` | **No** — ya viene con el engine, solo se habilita |
+| **Que hace este skill** | Instalar + registrar + verificar | Habilitar + conectar + verificar |
 
-> El flujo de Unity (`Window → MCP for Unity`) requiere la GUI del Editor — Claude no puede manejarla. La skill automatiza lo que sí puede (editar `manifest.json`, registrar el cliente MCP, verificar) y **guía** el paso del Editor.
+> En Unreal **no hay nada que instalar**. El server y los toolsets son plugins del engine; el trabajo es habilitarlos en el `.uproject`, prender auto-start y generar el `.mcp.json`. No agregues packages ni plugins de terceros.
 
 ## Input
 
-- `project-path` (opcional): raíz del proyecto Unity. Default: directorio actual.
-- `--secondary` (opcional): además del primario, instala el package CoderGamester.
+- `unity` | `unreal` (opcional): fuerza el engine. Sin argumento, se autodetecta.
+- `project-path` (opcional): raiz del proyecto. Default: directorio actual.
+- `--secondary` (opcional, **solo Unity**): ademas del primario, instala el package CoderGamester.
 
 ---
 
-## Workflow
+## Phase 1: Detectar el engine
 
-### 1. Detectar proyecto Unity
+Desde `project-path` (o cwd), buscar marcadores:
 
-Desde `project-path` (o cwd), confirmar que existen:
-- `Packages/manifest.json`
-- `ProjectSettings/ProjectVersion.txt`
+| Marcador | Engine |
+|---|---|
+| `Packages/manifest.json` + `ProjectSettings/ProjectVersion.txt` | Unity |
+| `*.uproject` (o `GenerateProjectFiles.*` en un source tree) | Unreal |
 
-Si falta alguno, **abortar** con: "No parece un proyecto Unity (falta Packages/manifest.json o ProjectSettings/ProjectVersion.txt). Pasá la ruta del proyecto con `/install-mcp <project-path>`."
+- Si el argumento explicito contradice los marcadores, **avisar y preguntar** antes de seguir.
+- Si no hay marcadores, **abortar**: "No parece un proyecto Unity ni Unreal. Pasa la ruta con `/install-mcp [unity|unreal] <project-path>`."
+- Si aparecen ambos, preguntar cual.
 
-### 2. Verificar prerrequisitos
+Confirmar el engine detectado y la ruta antes de tocar archivos.
 
-- `uv --version` y `uvx --version` (server del primario). Si falta `uv`, **no abortar**: avisar y dar el comando de install y seguir editando el manifest:
-  - Windows: `winget install astral-sh.uv`
-  - alternativa: `pipx install uv`
-- Solo con `--secondary`: `node --version`. Si falta, avisar (el server CoderGamester no podrá correr).
+---
+
+## Phase 2A: Unity — instalar y registrar
+
+### 1. Verificar prerrequisitos
+
+`uv --version` y `uvx --version` (server del primario). Si falta `uv`, **no abortar**: avisar, dar el comando y seguir editando el manifest.
+
+- Windows: `winget install astral-sh.uv`
+- alternativa: `pipx install uv`
+
+Solo con `--secondary`: `node --version`. Si falta, avisar (el server CoderGamester no podra correr).
 
-### 3. Agregar el package UPM (lado Unity)
+### 2. Agregar el package UPM
 
 Leer `Packages/manifest.json`. Dentro de `"dependencies"`, agregar **solo si la key no existe** (idempotente — nunca duplicar):
 
@@ -47,61 +62,135 @@ Leer `Packages/manifest.json`. Dentro de `"dependencies"`, agregar **solo si la
 "com.coplaydev.unity-mcp": "https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main"
 ```
 
-Con `--secondary`, agregar también:
+Con `--secondary`, agregar tambien:
 
 ```json
 "com.gamelovers.mcp-unity": "https://github.com/CoderGamester/mcp-unity.git"
 ```
 
-Usar `Edit` puntual sobre el bloque `dependencies` preservando el JSON válido (indentación, comas). Si la key ya estaba, reportar "ya presente, sin cambios".
+Usar `Edit` puntual sobre el bloque `dependencies` preservando el JSON valido (indentacion, comas). Si la key ya estaba, reportar "ya presente, sin cambios".
 
-> **Antes de escribir**, mostrar el diff propuesto sobre `manifest.json` (y el `.mcp.json` del paso 4B si aplica) y pedir aprobación al usuario. No editar sin confirmación.
+> **Antes de escribir**, mostrar el diff propuesto sobre `manifest.json` (y el `.mcp.json` del paso 3B si aplica) y pedir aprobacion al usuario. No editar sin confirmacion.
 
-### 4. Registrar el server MCP en Claude Code
-
-Dos caminos, en orden de preferencia:
+### 3. Registrar el server en Claude Code
 
 **A. Recomendado (auto-config desde Unity).** Instruir al usuario:
-1. Abrir el proyecto en Unity (Unity importará el package nuevo).
+1. Abrir el proyecto en Unity (importara el package nuevo).
 2. `Window → MCP for Unity`.
-3. En esa ventana, usar el botón de auto-configuración para **Claude Code** — instala el server `uv` y registra el cliente MCP automáticamente.
+3. Usar el boton de auto-configuracion para **Claude Code** — instala el server `uv` y registra el cliente.
 
-**B. Fallback manual.** Si el usuario no puede usar el Editor ahora, registrar el transport HTTP que usa CoplayDev:
+**B. Fallback manual.** Registrar el transport HTTP de CoplayDev:
 
 ```bash
 claude mcp add --transport http unity-mcp http://127.0.0.1:8080
 ```
 
-(equivalente: escribir un `.mcp.json` de proyecto con
-`{"mcpServers":{"unity-mcp":{"type":"http","url":"http://127.0.0.1:8080"}}}`).
+> El server solo responde con Unity abierto y `MCP for Unity` activo. Registrar el cliente no levanta el server.
+
+---
+
+## Phase 2B: Unreal — habilitar y conectar
+
+Nada se instala. Tres pasos, en orden. **No edites el `.uproject` sin confirmar la ruta con el usuario.**
+
+### 1. Habilitar los plugins del engine en el `.uproject`
+
+Dos plugins, ambos requeridos. `ModelContextProtocol` es el server y el transport; `AllToolsets` provee las tools. Con solo `ModelContextProtocol` el server arranca pero **no expone ninguna tool**.
+
+En el array `Plugins` del `.uproject`, asegurar las dos entradas:
+
+```json
+{ "Name": "ModelContextProtocol", "Enabled": true },
+{ "Name": "AllToolsets", "Enabled": true }
+```
+
+Si el array no existe, crearlo. Si alguna entrada esta en `"Enabled": false`, pasarla a `true`. Mostrar el diff y pedir aprobacion antes de escribir.
+
+`AllToolsets` es un agregador editor-only con `EnabledByDefault` apagado, asi que hay que habilitarlo explicitamente. Para exponer solo un subconjunto, habilitar los plugins de toolset puntuales en lugar de `AllToolsets`.
+
+### 2. Prender auto-start
 
-> El server solo responde cuando Unity está abierto con `MCP for Unity` activo. Registrar el cliente no levanta el server.
+Por default el server queda detenido. Para arrancarlo a mano en una sesion: `ModelContextProtocol.StartServer` desde la consola del editor.
 
-### 5. Verificar
+Para que arranque en cada launch, agregar al config per-user del editor:
 
-Correr:
+`<Project>/Saved/Config/<Platform>Editor/EditorPerProjectUserSettings.ini`
+
+```ini
+[/Script/ModelContextProtocolEngine.ModelContextProtocolSettings]
+bAutoStartServer=True
+```
+
+Es per-user y no va a source control. Overrides opcionales si el default choca con otro servicio local:
+
+```ini
+ServerPortNumber=8000
+ServerUrlPath=/mcp
+```
+
+Alternativa por command line: `-ModelContextProtocolStartServer` (y `-ModelContextProtocolPort=<port>`). Preferir el `.ini` porque persiste.
+
+### 3. Generar el `.mcp.json`
+
+El editor no lo escribe solo.
+
+**Con el editor corriendo (preferido):** `ModelContextProtocol.GenerateClientConfig ClaudeCode` en la consola (o `All` para todos los clientes soportados). Re-correrlo mergea sobre el JSON existente, asi que es seguro despues de cambiar puerto o path.
+
+El destino depende del tipo de build:
+- **Source build** (el repo contiene `Engine/`): se escribe en la raiz del workspace, al lado de `Engine/` — **no** junto al `.uproject`.
+- **Installed/launcher build**: se escribe junto al `.uproject`.
+
+**Sin lanzar el editor**, escribir a mano en la ubicacion que corresponda:
+
+```json
+{
+  "mcpServers": {
+    "unreal-mcp": {
+      "type": "http",
+      "url": "http://127.0.0.1:8000/mcp"
+    }
+  }
+}
+```
+
+Ajustar la URL si se override el puerto o el path en el paso 2.
+
+---
+
+## Phase 3: Verificar
 
 ```bash
 claude mcp list
 ```
 
-Reportar si `unity-mcp` aparece **conectado**. Seguir la guía de TesisUade: **si NO está conectado, avisar explícitamente** y aclarar que las operaciones de engine (scenes, SOs, prefabs, UI wiring) NO se aplicaron — no asumir éxito.
+Reportar si el server aparece **conectado** (`unity-mcp` o `unreal-mcp` segun el engine). En Unreal, dos senales extra: el Output Log muestra mensajes de arranque del MCP, y `list_toolsets` responde.
 
-### 6. Resumen
+**Si NO esta conectado, avisar explicitamente** y aclarar que las operaciones de engine (scenes, assets, blueprints, prefabs, UI wiring) NO se aplicaron — no asumir exito.
+
+---
+
+## Phase 4: Resumen
 
 Reportar:
-- Qué keys se agregaron a `manifest.json` (o si ya estaban).
-- Estado del registro MCP (auto-config pendiente en Unity vs. fallback aplicado).
-- Resultado de `claude mcp list`.
-- Próximo paso manual: abrir Unity → `Window → MCP for Unity`.
+- Engine detectado y ruta del proyecto.
+- **Unity:** que keys se agregaron a `manifest.json` (o si ya estaban).
+- **Unreal:** que plugins se habilitaron en el `.uproject`, si se prendio auto-start, y donde quedo el `.mcp.json`.
+- Estado del registro y resultado de `claude mcp list`.
+- Proximo paso manual, si queda alguno.
 
 **Verdict:**
-- **READY** — package en `manifest.json` + cliente registrado + `unity-mcp` conectado en `claude mcp list`.
-- **PENDING** — package y cliente listos, pero falta abrir Unity (`Window → MCP for Unity`) para que el server conecte. Avisar que las operaciones de engine aún NO están disponibles.
-- **BLOCKED** — falta un prerrequisito (`uv` ausente) o no es un proyecto Unity válido. Indicar el fix.
+- **READY** — server registrado y conectado en `claude mcp list`.
+- **PENDING** — config lista, pero falta abrir el editor para que el server conecte (Unity: `Window → MCP for Unity`; Unreal: lanzar el editor con auto-start, o `ModelContextProtocol.StartServer`). Avisar que las operaciones de engine aun NO estan disponibles.
+- **BLOCKED** — falta un prerrequisito (`uv` ausente en Unity), el `.uproject` no se pudo editar, o no es un proyecto valido. Indicar el fix.
 
-Tras conectar, seguir con `/unity-game-architecture` o `/scaffold-unity` para trabajar el proyecto.
+## Next Steps
+
+- **Unity:** `/unity-game-architecture` o `/scaffold-unity` para trabajar el proyecto
+- **Unreal:** `/ue-project-context` primero (el resto de los `ue-*` lo leen), despues `/ue-cpp-foundations` o `/ue-blueprints`
+- Si el server no conecta, ver el troubleshooting de la referencia del engine que corresponda
 
 ---
 
-> → Read references/manual-setup.md for [pasos detallados del flujo Window → MCP for Unity, troubleshooting (uv no encontrado, puerto 8080 ocupado, MCP no conecta) y la variante secundaria CoderGamester]
+> → Read references/manual-setup.md for el flujo manual de Unity (`Window → MCP for Unity`), troubleshooting (uv no encontrado, puerto 8080 ocupado, MCP no conecta) y la variante secundaria CoderGamester
+
+> → Read references/unreal-operations.md for los console commands de Unreal (`StartServer`, `StopServer`, `RefreshTools`, `GenerateClientConfig`), el modo tool-search y la matriz de troubleshooting (puerto ocupado, toolset faltante, tool calls que cuelgan)

package/skills/install-mcp/references/unreal-operations.md

@@ -0,0 +1,55 @@
+# Unreal MCP — Console Commands, Settings, Recovery
+
+> Adapted from the `unreal-mcp` skill in [EpicGames/unreal-engine-skills-for-claude-code-plugin](https://github.com/EpicGames/unreal-engine-skills-for-claude-code-plugin) (MIT). References to the upstream `setup.md` were remapped to Phase 2B of this skill.
+
+Read this when something is misbehaving with the Unreal MCP server (tools missing, port collision, stale tool registry), or when you need a non-default configuration.
+
+Remember: the server and toolsets are **engine plugins**. Nothing here installs anything into the project — it enables, restarts and reconfigures what the engine already ships.
+
+## Console commands
+
+Run these from the Unreal Editor console (`~`).
+
+| Command | Use it for |
+|---------|------------|
+| `ModelContextProtocol.StartServer [port]` | Start the MCP server. Pass a port to override the default (e.g. when 8000 is in use). |
+| `ModelContextProtocol.StopServer` | Stop the server. Useful if the registry is in a bad state and you want a clean restart. |
+| `ModelContextProtocol.RefreshTools` | Re-register every toolset. Run this after enabling a new toolset plugin. |
+| `ModelContextProtocol.GenerateClientConfig <client>` | Regenerate the per-client config file. Args: `ClaudeCode`, `Cursor`, `VSCode`, `Gemini`, `Codex`, `All`. |
+
+Codex is the exception for config generation: it uses TOML and the writer refuses to overwrite an existing `.codex/config.toml`. Edit that one by hand if it already exists.
+
+## Tool-search mode
+
+`tools/list` has two modes, controlled by the `bEnableToolSearch` UPROPERTY on `UModelContextProtocolSettings` (default `true`):
+
+- **`True`** (default): `tools/list` returns only `list_toolsets`, `describe_toolset`, `call_tool`. Toolset tools are dispatched server-side through `call_tool` and stay out of the prompt; the catalog never changes mid-session, so the prompt cache stays warm.
+- **`False`**: every toolset tool is registered as a native MCP tool at startup, with schemas visible upfront.
+
+Override in the same `.ini` used for `bAutoStartServer` (see Phase 2B):
+
+```ini
+[/Script/ModelContextProtocolEngine.ModelContextProtocolSettings]
+bEnableToolSearch=False
+```
+
+## Troubleshooting matrix
+
+| Symptom | What to do |
+|---------|------------|
+| `unreal-mcp` not in `claude mcp list` / `/mcp`, or `list_toolsets` errors | The editor isn't running, or the server isn't started. Launch the editor and run `ModelContextProtocol.StartServer`, or enable `bAutoStartServer` per Phase 2B. Then check the Output Log for startup errors. |
+| Editor logs "Failed to listen on port" | Another process holds the default port. Change `ServerPortNumber` in the per-user `EditorPerProjectUserSettings.ini`, or pass `-ModelContextProtocolPort=<port>` on the next launch. Restart the editor, then re-run `ModelContextProtocol.GenerateClientConfig ClaudeCode` to refresh `.mcp.json`. |
+| A toolset you expect (e.g. `NiagaraTools`) is missing | Run `ModelContextProtocol.RefreshTools`. If still missing, that toolset's plugin may not be enabled in the `.uproject` — check there. Remember `AllToolsets` is the aggregator and is off by default. |
+| Tool calls hang or return errors | The editor may be busy compiling, loading a level, or in PIE. Wait and retry. For long compiles, prefer `LiveCodingToolset.CompileLiveCoding`, which returns when the compile actually finishes. |
+| `AIAssistantToolset.GetDockedContext` returns empty | The Claude Code tab must be docked inside an asset editor (Blueprint, Material, etc.) to provide docked context. Undocked, that tool has nothing to report. |
+| Sequential tool calls collide | Tool calls execute on the game thread. Don't issue them in parallel, even when they look independent. Serialize them. |
+
+## Safety notes when driving the editor
+
+These matter because every MCP call mutates live editor state on the game thread:
+
+- **Save before and after** any bulk change. MCP edits are not always undoable, especially across compilation boundaries.
+- **Wait for compilation** to finish before issuing further calls.
+- **Never parallelize** tool calls.
+- **Read every result.** Many tools return a status that flips between success and failure without raising. Treat anything that isn't an explicit success as a stop.
+- **Mind PIE.** Editor-only tools, asset creation in particular, behave differently while Play-in-Editor is active.