Prefab Sentinel

Ein MCP-Server zur sicheren Inspektion und Bearbeitung von Prefabs / Szenen / Assets in Unity-/VRChat-Projekten.

Diagnostiziert Variant-Override-Konflikte, Broken PPtr / fehlende fileIDs sowie Udon-/ClientSim-Laufzeitausnahmen mit strukturierten Antworten und repariert sie ohne manuelle YAML-Bearbeitung. Konzipiert für KI-Agenten.

Die YAML-gestützten Nur-Lese-Pfade (validate_refs / validate_materials / inspect_wiring / inspect_variant / inspect_hierarchy / find_referencing_assets usw.) funktionieren vollständig ohne Unity-Start. inspect_serialized_surface / inspect_with_profile / validate_inspector_profile beziehen die zuletzt gespeicherte SerializedObject-Oberfläche über eine residente Editor Bridge. Die Schreibpfade (patch_apply / set_property / editor_* usw.) laufen über Datei-IPC mit der residenten Editor Bridge; Aufrufe ohne das Prüfpaar confirm=True + nicht-leeres change_reason werden mit CHANGE_REASON_REQUIRED abgelehnt.

Die öffentliche MCP-Grenze bietet ausschließlich die Tools-Fähigkeit an. stdio unterstützt das moderne 2026-07-28 sowie zwei Legacy-Revisionen (2025-11-25 / 2025-06-18); jeder HTTP-Pfad bietet ausschließlich das moderne 2026-07-28 über lokalen Loopback unter /mcp an. Dies ist keine Konformitätserklärung, sondern die Priorisierung von Protokollfehlern und stdio-Transportausnahmen ist in docs/api-reference.md, der Umfang der strengen CI-Gates in TESTING.md und bekannte Abweichungen des Prozesszustands in ARCHITECTURE.md als maßgeblich dokumentiert. Die unterstützten Request-Methoden und Transporte finden sich in docs/tool-conventions.md und docs/execution-reference.md.

Diese README dient als Einstieg in die jeweiligen Fachdokumente (siehe Dokumentationsübersicht). Die Spezifikationen sind in den Fachdokumenten maßgeblich, die Betriebsregeln in AGENTS.md.

Was wir tun / was wir nicht tun

Was wir tun

• Bereitstellung einer sicheren Bearbeitungsgrundlage auf Unity-SerializedObject-Ebene, die die effektiven Werte von Prefab-Basen / Variants / Szeneninstanzen nachvollziehbar macht

• API-basierte Referenzauflösung (GUID + fileID) und Integritätsprüfung

• Pipeline für Laufzeitvalidierung (UdonSharp-Compile / ClientSim-Smoke / Logklassifizierung)

• Erkennung von Latenzregressionen in den wichtigsten Inspektionspfaden mit deterministischen synthetischen Workloads und festem Budget

• Klare Trennung zwischen Änderungen, die menschliches Urteilsvermögen erfordern, und solchen, die maschinell ausgeführt werden können

• Bündelung von Domänenwissen über VRChat-Ökosystem-Tools wie ModularAvatar / liltoon / VRCFury als Entscheidungsgrundlage für KI-Agenten

• Standardisierung von Betriebsabläufen als Skills (kompatibel mit beiden Hosts Claude Code / Codex CLI)

Was wir nicht tun

• Keine direkte String-Ersetzung in YAML als Standardmethode

• Keine Ergänzung fehlender Unity-Internreferenzen durch Vermutungen

• Keineische Optimierung ohne Änderungsbegründung

• Keine Verwendung realer Projekte für Timing-Gates und keine automatische Aktualisierung der Baseline aus wöchentlichen Benchmarks

• Keine eigenmächtige Anwendung von Spezifikationsänderungen, die Benutzerentscheidungen erfordern

• Keine Veröffentlichung von Legacy-HTTP, Legacy-Protokollversionen älter als 2025-06-18 oder Remote-/gemeinsam genutzten HTTP-Servern

Related MCP server: unity-asset-reference-mcp

Quickstart

Als Plugin installieren. Je nach Host (Claude Code / Codex CLI) gibt es zwei Wege, beide über den Marketplace.

Claude Code (Slash-Befehl, der in Claude Code eingegeben wird):

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

Codex CLI (Marketplace in der Shell registrieren → in der /plugins-TUI von Codex CLI aktivieren):

codex plugin marketplace add tyunta/prefab-sentinel

Nach der Registrierung in Codex CLI /plugins öffnen, prefab-sentinel aus der Liste auswählen und Installieren (einen Shell-Befehl codex plugin install gibt es nicht).

Einstieg in die Nutzung nach der Installation ist der guide-Skill (/prefab-sentinel:guide) – er enthält die Liste der MCP-Tools und deren Aufrufweise, das Patch-Schema, die Einrichtung der Editor Bridge und Hinweise zum Ökosystem-Wissen. Da die MCP-Tools tatsächlich von der KI-Agentenseite aufgerufen werden, genügt es, den Agenten auf diesen guide verweisen zu lassen.

Details zu den einzelnen Wegen finden sich unter Einrichtung, die Entwickleranleitung zum direkten Start des MCP-Servers aus dem Repository unter CONTRIBUTING.md.

Einrichtung

Voraussetzungen

• Python 3.11 oder höher

• uv (Paketmanager) – Installationsanleitung siehe offizieller uv-Leitfaden (unterschiedlich für Windows / macOS / Linux)

• Unity 2022.3 + VRChat SDK 3.x (Worlds / Avatars) – erforderlich für Schreib- und Laufzeitvalidierungspfade über die Editor Bridge

Da der MCP-Server innerhalb des Plugins lokal über uv / uvx gestartet wird, sind Python / uv auch beim Plugin-Installationsweg erforderlich. Host (Claude Code / Codex CLI) und dieses Tool funktionieren unter Windows / macOS / Linux.

Claude Code Plugin

Mit den 2 Befehlen aus Quickstart installieren. Nach der Installation werden MCP-Server, 6 Skills und das knowledge/-Verzeichnis auf einmal entpackt, und Skills wie /prefab-sentinel:guide können direkt aus Claude Code aufgerufen werden. Die Befehle in den einzelnen Skills werden über die Template-Variable ${CLAUDE_PLUGIN_ROOT} lokal ausgeführt.

Codex CLI Plugin

Gemäß den Schritten in Quickstart installieren (in der Shell codex plugin marketplace add → in der /plugins-TUI von Codex CLI prefab-sentinel installieren). Der MCP-Server wird über die Plugin-Definition (.codex-plugin/mcp.json, auf die mcpServers in .codex-plugin/plugin.json verweist) registriert; die gepackte MCP-Definition liefert auch die erforderlichen modernen Protokollmarker. Das Skill-Bundle wird ebenfalls entpackt. Da der Codex-MCP-Server die Hauptkomponente per uvx von GitHub bezieht und startet, ist beim Start eine Netzwerkverbindung erforderlich (der Claude-Code-Pfad startet aus der lokalen Installation). Nach einem Plugin-Update die Codex-CLI-Sitzung neu starten. Deaktivieren und Abmelden erfolgt über die /plugins-TUI.

Skills

Unity Bridge

Die Schreibpfade wie tatsächliche Patch-Anwendung und Laufzeitvalidierung sowie die Inspector-Profile-Pfade, die die zuletzt gespeicherte SerializedObject-Oberfläche verwenden, laufen über Datei-IPC mit einer im Unity-Editor residenten Editor Bridge. Die Einrichtungsanleitung für die Bridge steht im Skill /prefab-sentinel:guide, die Umgebungsvariable UNITYTOOL_BRIDGE_WATCH_DIR zur Angabe des Watch-Verzeichnisses in CONFIGURATION.md. Wenn Schreibwerkzeuge ohne Konfiguration aufgerufen werden, stoppt das System fail-fast mit BRIDGE_WATCH_DIR_MISSING; bei Inspector-Profile-Werkzeugen mit INSPECTOR_SURFACE_UNAVAILABLE. Für YAML-gestützte Nur-Lese-Inspektionen ist keine Bridge-Konfiguration erforderlich.

Das Python-Wheel mappt nur die Verteilungsziele von tools/unity/ und knowledge/ in das Paket; Workspace-lokale Metadaten wie verschachtelte .serena werden nicht mitgeliefert.

Repräsentative MCP-Tools

Der maßgebliche Katalog aller MCP-Tools befindet sich in docs/tools.md, der maßgebliche Antwort-Envelope (success / severity / code / message / data / diagnostics) und die Fehlercodes in docs/api-reference.md. Die folgende Tabelle zeigt nur repräsentative Tools.

Verwenden Sie für Routine-CI-/Agentenvalidierung validate_runtime(profile="compile_only") oder validate_runtime(profile="editor_console_only"). ClientSim ist ein explizites Opt-in für Einreichungsszenen und wird nur ausgeführt, wenn profile="clientsim" + Audit-Paar vorhanden ist und die angeforderte Szene die einzige geladene aktive Szene ist. Maßgeblich für die detaillierten Cleanup-/Wiederherstellungs-/Nebenwirkungsverträge sind docs/api-reference.md und docs/execution-reference.md.

YAML-gestützte schreibgeschützte Prüfungen (validate_refs / validate_materials / inspect_wiring / inspect_variant / inspect_hierarchy / find_referencing_assets usw.) benötigen kein Unity. Die 3 Tools des Inspector-Profils sind schreibgeschützt, setzen jedoch einen residenten Editor Bridge voraus, und die editor_*-Familie sowie die Bestätigungsanwendung von patch_apply verwenden dieselbe Bridge.

validate_refs / inspect_wiring / validate_all_wiring / validate_structure / validate_materials lesen config/diagnostics_baseline.json im Projektstammverzeichnis und klassifizieren Diagnosen in new / known / resolved. Die Baseline wird nicht automatisch generiert oder implizit aktualisiert; nur das explizite update_diagnostics_baseline übernimmt preview-/audit-gated Schreibvorgänge. Das Baseline-Dateiformat ist in CONFIGURATION.md, die Antwortform und der Update-Tool-Vertrag in docs/api-reference.md und die öffentliche Tool-Liste in docs/tools.md als maßgebliche Quelle festgelegt.

Empfohlener Ablauf: Referenzschäden frühzeitig mit validate_refs erkennen → Override-Konflikte mit inspect_variant als effektive Werte visualisieren → Dry-Run von patch_apply → bei der Anwendung confirm=True + change_reason angeben, bei genau einer offenen Prefab-Transaktion zusätzlich out_report angeben und mit Audit-Protokoll anwenden.

VRChat-Ökosystem-Wissen

Im Verzeichnis knowledge/ werden Domänenkenntnisse zu ModularAvatar / liltoon / VRCFury / AvatarOptimizer usw. auf 3 Ebenen (L1-Konzepte / L2-Operationsmuster / L3-SerializedProperty) gesammelt und im Plugin mitgeliefert. Die guide-Fähigkeit leitet Referenzen an, und der KI-Agent liest je nach Aufgabe das entsprechende Wissen aus knowledge/. Die Recherche und Erweiterung des Wissens erfolgt über die knowledge-acquisition-Fähigkeit. Die Bearbeitungsregeln sind in knowledge/STYLE_GUIDE.md festgelegt.

Dokumentationsübersicht

Die Spezifikationen sind auf Fachdokumente verteilt. Die Einstiegspunkte nach Zweck sind in der folgenden Tabelle aufgeführt.