Prefab Sentinel

Unity / VRChat プロジェクトの Prefab / Scene / Asset を安全に検査・編集する MCP サーバー。

Variant の override 衝突、Broken PPtr / missing fileID、Udon / ClientSim ランタイム例外を構造化された応答で診断し、手作業 YAML 編集を経由せずに修復する。AI エージェント前提の設計。

YAML-backed read-only 経路（validate_refs / validate_materials / inspect_wiring / inspect_variant / inspect_hierarchy / find_referencing_assets 等）は Unity を起動せずに完結する。inspect_serialized_surface / inspect_with_profile / validate_inspector_profile は、last-saved SerializedObject surface を常駐 Editor Bridge 経由で取得する。書き込み経路（patch_apply / set_property / editor_* 等）は常駐 Editor Bridge との file-IPC で動き、confirm=True + 非空 change_reason の監査ペアを欠く呼び出しは CHANGE_REASON_REQUIRED で拒否される。

公開 MCP 境界は Tools capability のみを提供する。stdio は modern 2026-07-28 と、二つの legacy revision（2025-11-25 / 2025-06-18）から成る二世代に対応し、任意の HTTP 経路は modern 2026-07-28 のみをローカル loopback の /mcp で提供する。これは full conformance の合格宣言ではなく、protocol error の優先順位と stdio transport 例外は docs/api-reference.md、厳格 CI gate の対象範囲は 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 インスタンスの実効値を追跡可能にする

• 参照解決（GUID + fileID）と整合性検証を API 化する

• 実行時検証（UdonSharp compile / ClientSim smoke / ログ分類）をパイプライン化する

• 決定的な synthetic workload と固定 budget で主要 inspection path の latency regression を検出する

• 人間の判断が要る変更と、機械的に実行できる変更を明確に分離する

• ModularAvatar / liltoon / VRCFury 等の VRChat エコシステムツールのドメイン知識を同梱し、AI エージェントの判断材料として供給する

• Skills として運用フローを標準化する（Claude Code / Codex CLI の両ホストに対応）

やらないこと

• YAML 文字列の直接置換を標準手段にしない

• Unity 内部参照を推測で補完しない

• 変更根拠のない自動最適化をしない

• 実プロジェクトを timing gate に使わず、weekly benchmark から baseline を自動更新しない

• ユーザー判断が要る仕様変更を勝手に適用しない

• legacy HTTP、2025-06-18 より古い legacy protocol version、remote / shared HTTP server は公開しない

Related MCP server: unity-asset-reference-mcp

Quickstart

プラグインとして導入する。ホスト（Claude Code / Codex CLI）に応じて 2 つの経路があり、いずれも marketplace から取得する。

Claude Code（Claude Code 内に入力するスラッシュコマンド）:

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

Codex CLI（シェルで marketplace を登録 → Codex CLI 内の /plugins TUI で有効化）:

codex plugin marketplace add tyunta/prefab-sentinel

登録後、Codex CLI 内で /plugins を開き、一覧から prefab-sentinel を選んで Install する（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 サーバーは Plugin 内部で uv / uvx 経由でローカル起動されるため、Plugin 導入経路でも Python / uv は必要。ホスト（Claude Code / Codex CLI）と本ツールは Windows / macOS / Linux で動作する。

Claude Code Plugin

Quickstart の 2 コマンドで導入する。インストールすると MCP サーバー・6 つのスキル・knowledge/ ディレクトリが一括展開され、/prefab-sentinel:guide 等のスキルを Claude Code から直接呼び出せる。各スキル内のコマンドは ${CLAUDE_PLUGIN_ROOT} テンプレート変数でローカルから実行される。

Codex CLI Plugin

Quickstart の手順で導入する（シェルで codex plugin marketplace add → Codex CLI 内の /plugins TUI で prefab-sentinel を Install）。MCP サーバーは Plugin 定義（.codex-plugin/plugin.json の mcpServers が指す .codex-plugin/mcp.json）から登録され、packaged MCP definition は必要な modern protocol marker も供給する。skill bundle も同時に展開される。Codex の MCP サーバーは uvx が GitHub から本体を取得して起動するため、起動時にネットワーク接続が必要（Claude Code 経路はローカル導入物から起動する）。Plugin を更新したら Codex CLI セッションを再起動する。無効化・登録解除は /plugins TUI から行う。

スキル

Unity Bridge

パッチ実適用・ランタイム検証などの書き込み経路と、last-saved SerializedObject surface を扱う Inspector profile 経路は、Unity Editor 内に常駐する Editor Bridge との file-IPC で動く。Bridge のセットアップ手順は /prefab-sentinel:guide スキルに、project-scoped Watch Directory、生成済み instance ID の copy control、接続環境変数は CONFIGURATION.md の「Editor Bridge の接続設定」に記載。未設定で書き込み系ツールを呼ぶと BRIDGE_WATCH_DIR_MISSING、Inspector profile ツールを呼ぶと INSPECTOR_SURFACE_UNAVAILABLE で fail-fast 停止する。YAML-backed read-only 検査には Bridge 設定は不要。

Python wheel は tools/unity/ と knowledge/ の配布対象だけを package 内へ mapping し、nested .serena など workspace-local metadata は同梱しない。

代表的な MCP ツール

全 MCP ツールの正本カタログは docs/tools.md、応答エンベロープ（success / severity / code / message / data / diagnostics）とエラーコードの正本は docs/api-reference.md。下表は代表ツールのみ。

Routine CI / agent validation では validate_runtime に明示 profile を渡す。editor_console_only は read-only、compile_only / clientsim は conditional/write profile である。引数、audit、report、Scene 条件、実行順序は docs/tools.md、docs/tool-conventions.md、docs/api-reference.md、docs/execution-reference.md、TESTING.md を正本とする。

YAML-backed read-only 検査（validate_refs / validate_materials / inspect_wiring / inspect_variant / inspect_hierarchy / find_referencing_assets 等）は Unity 不要。Inspector profile の 3 ツールは read-only だが、常駐 Editor Bridge が前提で、editor_* 系と patch_apply の confirm 適用も同じ Bridge を使う。

validate_refs / inspect_wiring / validate_all_wiring / validate_structure / validate_materials は project root の config/diagnostics_baseline.json を読むと diagnostics を new / known / resolved に分類する。baseline は自動生成・暗黙更新せず、明示的な update_diagnostics_baseline だけが preview / audit-gated write を担う。baseline file 形式は CONFIGURATION.md、応答形状と update tool 契約は docs/api-reference.md、公開 tool 一覧は docs/tools.md を正本とする。

推奨フロー: validate_refs で参照破損を早期検出 → inspect_variant で override 衝突を実効値として可視化 → patch_apply の dry-run → 適用時は confirm=True + change_reason、exactly one open Prefab transaction ではさらに out_report を指定して監査ログ付きで適用。

VRChat エコシステムナレッジ

knowledge/ ディレクトリに ModularAvatar / liltoon / VRCFury / AvatarOptimizer 等のドメイン知識を 3 レベル（L1 概念 / L2 操作パターン / L3 SerializedProperty）で蓄積し、プラグインに同梱する。guide スキルが参照を案内し、AI エージェントが作業に応じて該当ナレッジを knowledge/ から読む。ナレッジの調査・拡充は knowledge-acquisition スキルで行う。編集規約は knowledge/STYLE_GUIDE.md。

ドキュメントマップ

仕様は専門ドキュメントに分かれて置かれている。目的別の入口は下表のとおり。