claude-code-arcane 2.3.0 → 2.5.0

package/profiles/testing.yaml

@@ -1,6 +1,6 @@
 name: testing
 description: "Testing avanzado — contract, performance, regression, flakiness"
-type: addon
+category: platform
 
 skills:
   - contract-testing

package/profiles/unity-design.yaml

@@ -1,6 +1,6 @@
 name: unity-design
 description: "Game Designer — GDDs, balance, art bible, playtesting, UX de juego"
-type: base
+category: gamedev
 
 skills:
   - user-persona

package/profiles/unity-dev.yaml

@@ -1,6 +1,6 @@
 name: unity-dev
 description: "Programador Unity — C#, arquitectura, performance, builds"
-type: base
+category: gamedev
 
 skills:
   - test-setup

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"
+category: gamedev
+
+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/profiles/visual-novel.yaml

@@ -1,6 +1,6 @@
 name: visual-novel
 description: "Visual Novel Developer — Ren"
-type: base
+category: gamedev
 
 skills:
   - vn-renpy-setup

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/arcane-list/SKILL.md

@@ -15,24 +15,23 @@ List all profiles and skills available in the Arcane source repo, so you can see
 1. Read `.claude/arcane-manifest.json` to find the `source` path (Arcane repo location)
 2. If no manifest, ask the user for the Arcane repo path
 3. From the source repo, list:
-   - **Base profiles** from `profiles/*.yaml` where type = base
-   - **Addon profiles** from `profiles/*.yaml` where type = addon
+   - **Profiles** from `profiles/*.yaml`, grouped by their `category` field (backend, frontend, mobile, gamedev, platform, management, business, personal, utilities)
    - **All skills** in `skills/` directory, grouped by category from SKILL.md frontmatter
 4. Mark skills that are already installed in the current project with `[installed]`
+5. Close with a one-line summary (`COMPLETE — N profiles, M skills, K installed`)
 
 ## Output format
 
 ```
 === Available Profiles ===
-Base:
+Backend:
   backend-ts     Backend TypeScript — Fastify, Prisma, Zod
   backend-go     Backend Go — scaffold, DB, auth, API design
-  frontend       Frontend React + Vite + TypeScript
   ...
 
-Addons:
-  +agile         Gestión de proyecto — sprints, standups
-  +testing       Testing avanzado — contract, performance
+Project Management:
+  agile          Gestión de proyecto — sprints, standups
+  jira           Jira via curl/REST API — issues, sprints, boards
   ...
 
 === Skills by Category ===
@@ -43,4 +42,10 @@ workflow (12):
 testing (4):
   skill-test [installed], check [installed], ...
 ...
+
+COMPLETE — 37 profiles, 427 skills, 52 installed
 ```
+
+## Next steps
+
+If the user wants something from the list, suggest `/arcane-add <skill>` or `/arcane-add +<profile>` to install it.

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.