Prefab Sentinel

Unity / VRChat 프로젝트의 Prefab / Scene / Asset을 안전하게 검사·편집하는 MCP 서버.

Variant의 override 충돌, Broken PPtr / missing fileID, Udon / ClientSim 런타임 예외를 구조화된 응답으로 진단하고, 수작업 YAML 편집을 거치지 않고 복구한다. AI 에이전트 전제 설계.

YAML 기반 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 스킬에, watch 디렉토리를 지정하는 환경 변수 UNITYTOOL_BRIDGE_WATCH_DIR는 CONFIGURATION.md에 기재. 미설정 상태로 쓰기계 도구를 호출하면 BRIDGE_WATCH_DIR_MISSING, Inspector profile 도구를 호출하면 INSPECTOR_SURFACE_UNAVAILABLE로 fail-fast 정지한다. YAML 기반 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 검증에서는 validate_runtime(profile="compile_only") 또는 validate_runtime(profile="editor_console_only")를 사용한다. ClientSim은 submission scene용 명시적 opt-in으로, profile="clientsim" + audit pair가 갖춰지고 requested scene이 sole loaded active scene인 경우에만 실행한다. 상세한 cleanup/restore/side-effect 계약은 docs/api-reference.md와 docs/execution-reference.md를 정본으로 한다.

YAML 기반 읽기 전용 검사(validate_refs / validate_materials / inspect_wiring / inspect_variant / inspect_hierarchy / find_referencing_assets 등)는 Unity가 필요 없다. Inspector profile의 3개 도구는 읽기 전용이지만, 상주 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, 정확히 하나의 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.

문서 맵

사양은 전문 문서로 나뉘어 배치되어 있다. 목적별 진입점은 아래 표와 같다.