Prefab Sentinel

MCP-сервер для безопасной проверки и редактирования Prefab / Scene / Asset в проектах Unity / VRChat.

Диагностирует конфликты override в Variant, Broken PPtr / отсутствующие fileID, исключения времени выполнения Udon / ClientSim с помощью структурированных ответов и исправляет их без ручного редактирования YAML. Проектирование рассчитано на AI-агентов.

Пути только для чтения на основе YAML (validate_refs / validate_materials / inspect_wiring / inspect_variant / inspect_hierarchy / find_referencing_assets и т. д.) выполняются без запуска Unity. inspect_serialized_surface / inspect_with_profile / validate_inspector_profile получают поверхность последнего сохранённого SerializedObject через резидентный Editor Bridge. Пути записи (patch_apply / set_property / editor_* и т. д.) работают через file-IPC с резидентным Editor Bridge; вызовы без пары аудита confirm=True + непустой change_reason отклоняются с CHANGE_REASON_REQUIRED.

Публичная граница MCP предоставляет только capability Tools. stdio поддерживает современную версию 2026-07-28 и две legacy-ревизии (2025-11-25 / 2025-06-18); любой HTTP-путь предоставляет только современную 2026-07-28 через локальный loopback на /mcp. Это не заявление о полном соответствии, а первоисточник по приоритетам protocol error и исключениям stdio transport — docs/api-reference.md, по охвату строгих CI-гейтов — TESTING.md, по известным отклонениям process-state — ARCHITECTURE.md. Соответствующие request method и transport см. в docs/tool-conventions.md и docs/execution-reference.md.

Данный README — точка входа в специализированные документы (см. карту документов). Первоисточник спецификаций — специализированные документы, первоисточник операционных правил — AGENTS.md.

Что делаем / чего не делаем

Делаем

• Предоставляем безопасную основу редактирования на уровне Unity SerializedObject, позволяющую отслеживать фактические значения Prefab Base / Variant / Scene instance

• Предоставляем API для разрешения ссылок (GUID + fileID) и проверки целостности

• Конвейеризуем проверки времени выполнения (UdonSharp compile / ClientSim smoke / классификация логов)

• Обнаруживаем регрессии задержки основных inspection-путей с помощью детерминированных synthetic workload и фиксированного бюджета

• Чётко разделяем изменения, требующие человеческого решения, и изменения, которые можно выполнить механически

• Включаем доменные знания инструментов экосистемы VRChat, таких как ModularAvatar / liltoon / VRCFury, и предоставляем их как материал для принятия решений AI-агентам

• Стандартизируем операционные процессы как Skills (поддержка обоих хостов: Claude Code / Codex CLI)

Не делаем

• Не используем прямую замену YAML-строк как стандартный метод

• Не дополняем внутренние ссылки Unity догадками

• Не выполняем автоматическую оптимизацию без обоснования изменений

• Не используем реальные проекты для timing gate и не обновляем baseline автоматически из weekly benchmark

• Не применяем самовольно изменения спецификаций, требующие решения пользователя

• Не публикуем legacy HTTP, legacy protocol version старше 2025-06-18, а также remote / shared HTTP server

Related MCP server: unity-asset-reference-mcp

Quickstart

Устанавливается как плагин. В зависимости от хоста (Claude Code / Codex CLI) есть два пути, оба получаются из marketplace.

Claude Code (слэш-команда, вводимая внутри Claude Code):

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

Codex CLI (регистрация marketplace в shell → активация в TUI /plugins внутри Codex CLI):

codex plugin marketplace add tyunta/prefab-sentinel

После регистрации откройте /plugins внутри Codex CLI, выберите prefab-sentinel из списка и установите (shell-команды codex plugin install не существует).

Точка входа после установки — скилл guide (/prefab-sentinel:guide) — в нём собраны список MCP-инструментов и способы их вызова, схема патчей, настройка Editor Bridge и навигация по знаниям экосистемы. MCP-инструменты фактически вызывает AI-агент, поэтому достаточно указать агенту на этот guide.

Подробности каждого пути см. в Настройка, процедуру для разработчиков, запускающих MCP-сервер напрямую из репозитория, — в CONTRIBUTING.md.

Настройка

Предварительные требования

• Python 3.11 или выше

• uv (менеджер пакетов) — инструкции по установке см. в официальном руководстве uv (различаются для Windows / macOS / Linux)

• Unity 2022.3 + VRChat SDK 3.x (Worlds / Avatars) — требуется для путей записи и проверки времени выполнения через Editor Bridge

MCP-сервер запускается локально внутри плагина через uv / uvx, поэтому Python / uv требуются и при установке через плагин. Хост (Claude Code / Codex CLI) и данный инструмент работают на Windows / macOS / Linux.

Claude Code Plugin

Устанавливается двумя командами из Quickstart. После установки разворачиваются MCP-сервер, 6 скиллов и каталог knowledge/, а скиллы, такие как /prefab-sentinel:guide, можно вызывать напрямую из Claude Code. Команды внутри каждого скилла выполняются локально с шаблонной переменной ${CLAUDE_PLUGIN_ROOT}.

Codex CLI Plugin

Устанавливается по процедуре из Quickstart (в shell: codex plugin marketplace add → в TUI /plugins внутри Codex CLI: Install prefab-sentinel). MCP-сервер регистрируется из определения плагина (.codex-plugin/mcp.json, на который указывает mcpServers в .codex-plugin/plugin.json); packaged MCP definition также предоставляет необходимые modern protocol marker. Одновременно разворачивается и skill bundle. MCP-сервер Codex запускается через uvx, который получает основную часть из GitHub, поэтому при запуске требуется сетевое соединение (путь Claude Code запускается из локально установленного пакета). После обновления плагина перезапустите сессию Codex CLI. Отключение и удаление регистрации выполняется через TUI /plugins.

Скиллы

Unity Bridge

Пути записи, такие как фактическое применение патчей и проверка времени выполнения, а также путь Inspector profile, работающий с поверхностью последнего сохранённого SerializedObject, работают через file-IPC с Editor Bridge, резидентным внутри Unity Editor. Процедура настройки Bridge описана в скилле /prefab-sentinel:guide, переменная окружения UNITYTOOL_BRIDGE_WATCH_DIR, задающая watch-каталог, — в CONFIGURATION.md. Если она не задана, вызов инструментов записи завершается fail-fast с BRIDGE_WATCH_DIR_MISSING, а инструментов Inspector profile — с INSPECTOR_SURFACE_UNAVAILABLE. Для проверок только для чтения на основе YAML настройка Bridge не требуется.

Python wheel сопоставляет в package только объекты распространения из tools/unity/ и knowledge/; workspace-local метаданные, такие как вложенный .serena, не включаются.

Типовые MCP-инструменты

Полный каталог всех MCP-инструментов — docs/tools.md, первоисточник по конверту ответа (success / severity / code / message / data / diagnostics) и кодам ошибок — docs/api-reference.md. В таблице ниже — только типовые инструменты.

В рутинной CI / агентной валидации используйте validate_runtime(profile="compile_only") или validate_runtime(profile="editor_console_only"). ClientSim — явный opt-in для submission-сцены: выполняется только при наличии profile="clientsim" + audit pair и когда запрошенная сцена является единственной загруженной активной сценой. Подробные контракты cleanup/restore/side-effect — в docs/api-reference.md и docs/execution-reference.md как канонических источниках.

YAML-основанные read-only проверки (validate_refs / validate_materials / inspect_wiring / inspect_variant / inspect_hierarchy / find_referencing_assets и т.д.) не требуют Unity. Три инструмента Inspector profile являются read-only, но предполагают постоянно работающий Editor Bridge; инструменты серии editor_* и подтверждённое применение patch_apply также используют тот же Bridge.

validate_refs / inspect_wiring / validate_all_wiring / validate_structure / validate_materials читают config/diagnostics_baseline.json в корне проекта и классифицируют диагностики как new / known / resolved. Baseline не создаётся автоматически и не обновляется неявно; только явный update_diagnostics_baseline отвечает за запись с preview и аудит-гейтом. Формат файла baseline задаётся в CONFIGURATION.md, форма ответа и контракт инструмента обновления — в docs/api-reference.md, список публичных инструментов — в docs/tools.md.

Рекомендуемый поток: раннее обнаружение повреждённых ссылок через validate_refs → визуализация конфликтов override как фактических значений через inspect_variant → dry-run patch_apply → при применении указывайте confirm=True + change_reason; при ровно одной открытой транзакции Prefab дополнительно укажите out_report для применения с аудит-логом.

Знания экосистемы VRChat

В каталоге knowledge/ накапливаются доменные знания о ModularAvatar / liltoon / VRChat / AvatarOptimizer и т.д. на трёх уровнях (L1 концепции / L2 паттерны операций / L3 SerializedProperty) и поставляются вместе с плагином. Навык guide направляет к справочным материалам, а AI-агент в зависимости от задачи читает соответствующие знания из knowledge/. Исследование и расширение знаний выполняется навыком knowledge-acquisition. Правила редактирования — knowledge/STYLE_GUIDE.md.

Карта документации

Спецификации разделены по профильным документам. Точки входа по целям приведены в таблице ниже.