Prefab Sentinel

Servidor MCP para inspeccionar y editar con seguridad Prefabs, Scenes y Assets de proyectos Unity / VRChat.

Diagnostica con una respuesta estructurada los conflictos de override de Variant, los Broken PPtr / missing fileID y las excepciones de runtime de Udon / ClientSim, y repara sin pasar por la edición manual de YAML. Diseñado para ser operado por agentes de IA.

Las vías de solo lectura respaldadas por YAML (validate_refs / validate_materials / inspect_wiring / inspect_variant / inspect_hierarchy / find_referencing_assets, etc.) se completan sin iniciar Unity. inspect_serialized_surface / inspect_with_profile / validate_inspector_profile obtienen la superficie SerializedObject del último guardado a través del Editor Bridge residente. Las vías de escritura (patch_apply / set_property / editor_*, etc.) funcionan mediante file-IPC con el Editor Bridge residente, y las llamadas que carecen del par de auditoría confirm=True + change_reason no vacío se rechazan con CHANGE_REASON_REQUIRED.

La frontera pública de MCP solo ofrece la capability Tools. El transporte stdio es compatible con el moderno 2026-07-28 y con dos revisiones heredadas (2025-11-25 / 2025-06-18); cualquier vía HTTP ofrece solo el moderno 2026-07-28, en /mcp del loopback local. Esto no es una declaración de conformidad plena: la autoridad en cuanto a la prioridad de los errores de protocolo y las excepciones del transporte stdio es docs/api-reference.md; el ámbito cubierto por la gate estricta de CI, TESTING.md; y las desviaciones conocidas del estado de proceso, ARCHITECTURE.md. Para los métodos de request y transports correspondientes, consulta docs/tool-conventions.md y docs/execution-reference.md.

Este README es la puerta de entrada a los documentos especializados (consulta el mapa de documentos). La autoridad de la especificación son los documentos especializados; la autoridad de las reglas operativas es AGENTS.md.

Qué hacer / Qué no hacer

Qué hacer

• Proporcionar una base segura de edición a nivel de SerializedObject de Unity y hacer rastreables los valores reales de las instancias de Prefab Base / Variant / Scene.

• Exponer como API la resolución de referencias (GUID + fileID) y la validación de integridad.

• Convertir en pipeline las comprobaciones de runtime (compilación UdonSharp / smoke test de ClientSim / clasificación de logs).

• Detectar regresiones de latencia en las vías de inspección principales con workloads sintéticos deterministas y un budget fijo.

• Separar claramente los cambios que requieren la decisión humana de los que se pueden ejecutar mecánicamente.

• Incluir el conocimiento de dominio de las herramientas del ecosistema VRChat, como ModularAvatar / liltoon / VRCFury, y entregarlo como material de decisión para los agentes de IA.

• Estandarizar los flujos operativos como skills (compatible con los dos hosts, Claude Code / Codex CLI).

Qué no hacer

• No usar la sustitución directa de cadenas de YAML como medio estándar.

• No rellenar las referencias internas de Unity mediante suposiciones.

• No aplicar optimizaciones automáticas sin un motivo de cambio.

• No usar proyectos reales como timing gate, ni actualizar automáticamente la baseline desde el benchmark semanal.

• No decidir cambios de especificación que requieran juicio del usuario.

• No exponer HTTP heredado, versiones heredadas de protocolo anteriores a 2025-06-18 ni servidores HTTP remotos/compartidos.

Related MCP server: unity-asset-reference-mcp

Quickstart

Se instala como plugin. Hay dos vías según el host (Claude Code / Codex CLI), y ambas se obtienen del marketplace.

Claude Code (un slash command que se introduce dentro de Claude Code):

/plugin marketplace add tyunta/prefab-sentinel
/plugin install prefab-sentinel@tyunta-prefab-sentinel

Codex CLI (registrar el marketplace en la shell → activarlo en la TUI /plugins del Codex CLI):

codex plugin marketplace add tyunta/prefab-sentinel

Tras el registro, abre /plugins dentro de Codex CLI y elige prefab-sentinel en la lista para instalarlo (existe no hay ningún comando de shell llamado codex plugin install).

Para el uso posterior a la instalación, la skill de entrada es guide (/prefab-sentinel:guide): reúne el listado de las herramientas MCP y su invocación, el esquema de parches, la configuración del Editor Bridge y la guía del conocimiento del ecosistema. Como quien llama realmente a las herramientas MCP es el agente de IA, basta con que el agente consulte this guide para empezar a usarlo.

Para los detalles de cada vía, consulta Configuración; para el procedimiento dirigido a desarrolladores, que arrancan el servidor MCP directamente desde el repositorio, consulta CONTRIBUTING.md.

Configuración

Requisitos previos

Python 3.11 o superior (mínimo)

uv, gestor de paquetes: la instalación se detalla en la guía oficial de uv (difiere en Windows / macOS / Linux).

Unity 2022.3 + VRChat SDK 3.x (Worlds / Avatars): necesario en las vías de escritura y de verificación en tiempo de ejecución a través del Editor Bridge.

Como el servidor MCP se inicia localmente dentro del plugin mediante uv / uvx, también en la vía de instalación del plugin se necesitan Python / uv. El host (Claude Code / Codex CLI) y esta herramienta funcionan en Windows / macOS / Linux.

Claude Code Plugin

Se instala con los 2 comandos de la Introducción rápida. Al instalar se despliegan el servidor MCP, las 6 skills y el directorio knowledge/, y desde Claude Code se puede llamar directamente a skills como /prefir-sentinel:guide. Los comandos de cada skill se ejecutan localmente mediante la variable de plantilla ${CLAUDE_PLUGIN_ROOT}.

Codex CLI Plugin

Se instala con el procedimiento del Quickstart (codex plugin marketplace add en la shell → Install de prefir-sentinel en la TUI /plugins de Codex CLI). El servidor MCP se registra desde la definición de plugin en .codex-plugin/mcp.json, al que apunta mcpServersde.codex-plugin/plugin.json; la definición MCP empaquetada aporta también los marcajones de protocolo moderno necesarios. La agrupación de skills se despliega al mismo tiempo. El servidor MCP de Codex es que uvxobtiene el ejecutable desde GitHub y lo lanza, por lo que necesita conexión de red en el arranque (la vía de Claude Code se sirve desde una instalación local). Si actualizas el plugin, reinicia la sesión de Codex CLI. La desactivación o anulación del registro se hace desde la TUI/plugins`.

Skills

Bridge de Unity

Las vías de escritura (aplicación real de parches, validación de tiempo de ejecución) y la vía de Inspector profile, que se ocupa de la superficie SerializedObject del último guardado, funcionan mediante file-IPC con el Editor Bridge que se mantiene residente dentro de Unity Editor. Los pasos de configuración del Bridge están en la skill /prefab-sentinel:guide; la variable de entorno que define el directorio watch, UNITYTOOL_BRIDGE_WATCH_DIR, está documentada en CONFIGURATION.md. Si no está definida, llamar a las herramientas de escritura detiene la ejecución con BRIDGE_WATCH_DIR_MISSING, y llamar a las herramientas de Inspector profile, con INSPECTOR_SURFACE_UNAVAILABLE (fail-fast). Las inspecciones de solo lectura respaldadas por YAML no requieren del Bridge ninguna configuración.

La wheel de Python solo hace mapping en el paquete de los objetos de distribución de tools/unity/ y knowledge/; no incluye metadata local de workspace, como por ejemplo .serena anidados.

Herramientas MCP principales

El catálogo de referencia de todas las herramientas MCP está en docs/tools.md; la envelope de respuesta (success / severity / code / message / data / diagnostics) y los códigos de error tienen la autoridad en docs/api-reference.md. La tabla siguiente solo incluye las herramientas más representativas.

En la validación rutinaria de CI / agente, usar validate_runtime(profile="compile_only") o validate_runtime(profile="editor_console_only"). ClientSim es un opt-in explícito para escenas de envío, y solo se ejecuta cuando profile="clientsim" + par de auditoría están presentes y la escena solicitada es la única escena activa cargada. El contrato detallado de cleanup/restore/efectos secundarios se rige por docs/api-reference.md y docs/execution-reference.md.

Las inspecciones de solo lectura basadas en YAML (validate_refs / validate_materials / inspect_wiring / inspect_variant / inspect_hierarchy / find_referencing_assets, etc.) no requieren Unity. Las 3 herramientas del perfil de Inspector son de solo lectura, pero presuponen un Bridge de Editor residente, y las herramientas de la familia editor_* y la aplicación con confirmación de patch_apply usan el mismo Bridge.

validate_refs / inspect_wiring / validate_all_wiring / validate_structure / validate_materials leen config/diagnostics_baseline.json de la raíz del proyecto para clasificar los diagnostics en new / known / resolved. El baseline no se genera automáticamente ni se actualiza implícitamente; solo update_diagnostics_baseline explícito se encarga de la escritura con vista previa y control de auditoría. La fuente autoritativa del formato del archivo de baseline es CONFIGURATION.md, la de las formas de respuesta y el contrato de la herramienta de actualización es docs/api-reference.md, y la del listado de herramientas públicas es docs/tools.md.

Flujo recomendado: detección temprana de referencias rotas con validate_refs → visualización de conflictos de override como valores efectivos con inspect_variant → dry-run de patch_apply → al aplicar, usar confirm=True + change_reason, y en una transacción de Prefab exactamente abierta, especificar además out_report para aplicar con registro de auditoría.

Conocimiento del ecosistema VRChat

En el directorio knowledge/ se acumulan y se incluyen con el plugin conocimientos de dominio sobre ModularAvatar / liltoon / VRCFury / AvatarOptimizer, etc., en 3 niveles (L1 conceptos / L2 patrones de operación / L3 SerializedProperty). La habilidad guide orienta sobre las referencias, y el agente de IA lee el conocimiento correspondiente desde knowledge/ según la tarea. La investigación y expansión del conocimiento se realiza con la habilidad knowledge-acquisition. Las normas de edición están en knowledge/STYLE_GUIDE.md.

Mapa de documentación

Las especificaciones están distribuidas en documentos especializados. La siguiente tabla muestra los puntos de entrada según el propósito.