Prefab Sentinel

An MCP server for safely inspecting and editing Prefab / Scene / Asset files in Unity / VRChat projects.

It diagnoses Variant override conflicts, Broken PPtr / missing fileID, and Udon / ClientSim runtime exceptions with structured responses, and repairs them without manual YAML editing. Designed for AI-agent-first usage.

The YAML-backed read-only paths (validate_refs / validate_materials / inspect_wiring / inspect_variant / inspect_hierarchy / find_referencing_assets, etc.) complete without launching Unity. inspect_serialized_surface / inspect_with_profile / validate_inspector_profile retrieve the last-saved SerializedObject surface via a resident Editor Bridge. The write paths (patch_apply / set_property / editor_*, etc.) operate through file-IPC with the resident Editor Bridge, and any call that lacks the confirm=True + non-empty change_reason audit pair is rejected with CHANGE_REASON_REQUIRED.

The public MCP boundary exposes only the Tools capability. stdio supports the modern 2026-07-28 revision and two legacy revisions (2025-11-25 / 2025-06-18); any HTTP route is served only for the modern 2026-07-28 revision on local loopback at /mcp. This is not a declaration of full conformance — the priority order of protocol errors and stdio transport exceptions are governed by docs/api-reference.md, the scope covered by strict CI gates is in TESTING.md, and known deviations in process state are governed by ARCHITECTURE.md. See docs/tool-conventions.md and docs/execution-reference.md for the corresponding request methods and transports.

This README is the entry point to each specialized document (see Document Map). The authoritative specification lives in the specialized documents, and the authoritative operational rules live in AGENTS.md.

What it does / What it doesn't do

What it does

• Provides a safe editing foundation at the Unity SerializedObject level, making the effective values of Prefab Base / Variant / Scene instances traceable

• Exposes reference resolution (GUID + fileID) and integrity validation as an API

• Pipelines runtime validation (UdonSharp compile / ClientSim smoke / log classification)

• Detects latency regressions in the main inspection paths using deterministic synthetic workloads and fixed budgets

• Clearly separates changes that require human judgment from changes that can be executed mechanically

• Bundles domain knowledge of VRChat ecosystem tools such as ModularAvatar / liltoon / VRCFury, and supplies it as material for AI-agent judgment

• Standardizes operational flows as Skills (compatible with both Claude Code and Codex CLI hosts)

What it doesn't do

• Does not use direct YAML string replacement as a standard means

• Does not fill in Unity internal references by guesswork

• Does not perform automatic optimization without a basis for the change

• Does not use real projects as timing gates, and does not auto-update baselines from weekly benchmarks

• Does not apply specification changes that require user judgment without asking

• Does not expose legacy HTTP, legacy protocol versions older than 2025-06-18, or remote / shared HTTP servers

Related MCP server: unity-asset-reference-mcp

Quickstart

Install it as a plugin. There are two paths depending on the host (Claude Code / Codex CLI), and both are obtained from the marketplace.

Claude Code (a slash command entered inside Claude Code):

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

Codex CLI (register the marketplace in the shell → enable it in the /plugins TUI inside Codex CLI):

codex plugin marketplace add tyunta/prefab-sentinel

After registration, open /plugins inside Codex CLI, select prefab-sentinel from the list, and install it (there is no shell command called codex plugin install).

After installation, the guide skill (/prefab-sentinel:guide) is the entry point — it covers the MCP tool list and how to call them, the patch schema, Editor Bridge setup, and ecosystem knowledge. Since the AI agent is the one that actually calls the MCP tools, you can get started by having the agent reference this guide.

For details on each path, see Setup; for developer instructions on launching the MCP server directly from the repository, see CONTRIBUTING.md.

Setup

Prerequisites

• Python 3.11 or later

• uv (package manager) — see the uv official guide for installation steps (differs on Windows / macOS / Linux)

• Unity 2022.3 + VRChat SDK 3.x (Worlds / Avatars) — required for the write and runtime-validation paths via the Editor Bridge

The MCP server is launched locally via uv / uvx inside the plugin, so Python / uv are also required on the plugin installation path. The host (Claude Code / Codex CLI) and this tool run on Windows / macOS / Linux.

Claude Code Plugin

Install with the two commands in Quickstart. Once installed, the MCP server, six skills, and the knowledge/ directory are deployed together, and skills such as /prefab-sentinel:guide can be called directly from Claude Code. Commands inside each skill are executed locally using the ${CLAUDE_PLUGIN_ROOT} template variable.

Codex CLI Plugin

Install using the steps in Quickstart (run codex plugin marketplace add in the shell, then install prefab-sentinel in the /plugins TUI inside Codex CLI). The MCP server is registered from the plugin definition (the mcpServers in .codex-plugin/plugin.json points to .codex-plugin/mcp.json), and the packaged MCP definition also supplies the required modern protocol marker. The skill bundle is also deployed at the same time. Since Codex's MCP server is launched by uvx fetching the main package from GitHub, a network connection is required at startup (the Claude Code path launches from the local installation). After updating the plugin, restart the Codex CLI session. Disable or unregister from the /plugins TUI.

Skills

Unity Bridge

The write paths (such as applying patches and runtime validation) and the Inspector profile paths that handle the last-saved SerializedObject surface operate through file-IPC with an Editor Bridge resident in the Unity Editor. The Bridge setup steps are in the /prefab-sentinel:guide skill, and the environment variable UNITYTOOL_BRIDGE_WATCH_DIR that specifies the watch directory is documented in CONFIGURATION.md. If it is not set, calling write-path tools fails fast with BRIDGE_WATCH_DIR_MISSING, and calling Inspector profile tools fails fast with INSPECTOR_SURFACE_UNAVAILABLE. No Bridge setup is required for YAML-backed read-only inspection.

The Python wheel maps only the distribution targets under tools/unity/ and knowledge/ into the package, and does not bundle workspace-local metadata such as nested .serena files.

Representative MCP tools

The authoritative catalog of all MCP tools is in docs/tools.md; the authoritative response envelope (success / severity / code / message / data / diagnostics) and error codes are in docs/api-reference.md. The table below lists only representative tools.

For routine CI / agent validation, use validate_runtime(profile="compile_only") or validate_runtime(profile="editor_console_only"). ClientSim is an explicit opt-in for submission scenes and runs only when profile="clientsim" + an audit pair are present and the requested scene is the sole loaded active scene. Detailed cleanup / restore / side-effect contracts are governed by docs/api-reference.md and docs/execution-reference.md.

YAML-backed read-only inspections (validate_refs / validate_materials / inspect_wiring / inspect_variant / inspect_hierarchy / find_referencing_assets, etc.) do not require Unity. The three Inspector profile tools are read-only but assume a resident Editor Bridge; the editor_* family and the confirm application of patch_apply also use the same Bridge.

validate_refs / inspect_wiring / validate_all_wiring / validate_structure / validate_materials read config/diagnostics_baseline.json at the project root and classify diagnostics into new / known / resolved. The baseline is not auto-generated or implicitly updated; only the explicit update_diagnostics_baseline performs preview / audit-gated writes. The authoritative sources are CONFIGURATION.md for the baseline file format, docs/api-reference.md for the response shape and update tool contract, and docs/tools.md for the public tool list.

Recommended flow: detect reference corruption early with validate_refs → visualize override conflicts as effective values with inspect_variant → dry-run patch_apply → when applying, use confirm=True + change_reason; in an exactly one open Prefab transaction, additionally specify out_report to apply with an audit log.

VRChat Ecosystem Knowledge

Domain knowledge for ModularAvatar / liltoon / VRCFury / AvatarOptimizer, etc. is accumulated in the knowledge/ directory at three levels (L1 concepts / L2 operation patterns / L3 SerializedProperty) and bundled with the plugin. The guide skill points to the relevant references, and the AI agent reads the applicable knowledge from knowledge/ according to the task. Knowledge research and expansion are performed with the knowledge-acquisition skill. Editing conventions are in knowledge/STYLE_GUIDE.md.

Document Map

Specifications are split across specialized documents. The entry points by purpose are as shown in the table below.