[![Docs](https://img.shields.io/badge/Docs-unity--mcp-4f46e5)](https://github.com/seokh1213/unity-my-mcp/tree/main/docs)
[![](https://img.shields.io/badge/Unity-000000?style=flat&logo=unity&logoColor=blue 'Unity')](https://unity.com/releases/editor/archive)
[![](https://badge.mcpx.dev?status=on 'MCP Enabled')](https://modelcontextprotocol.io/introduction)
[![](https://img.shields.io/badge/Node.js-339933?style=flat&logo=nodedotjs&logoColor=white 'Node.js')](https://nodejs.org/en/download/)
[![](https://img.shields.io/github/stars/seokh1213/unity-my-mcp 'Stars')](https://github.com/seokh1213/unity-my-mcp/stargazers)
[![](https://img.shields.io/github/last-commit/seokh1213/unity-my-mcp 'Last Commit')](https://github.com/seokh1213/unity-my-mcp/commits/main)

| **🇰🇷 한국어** | [🇺🇸 English](README.en.md) |
|----------------|-----------------------------|

# Seokh Unity Open MCP

## 먼저: 이 프로젝트의 기반

> 이 프로젝트는 **[AlexeyPerov/Unity-Open-MCP](https://github.com/AlexeyPerov/Unity-Open-MCP)를
> 기반으로 확장한 프로젝트**입니다. MCP 서버, Unity Bridge, Verify, Hub와 대부분의
> typed 도구 구조는 AlexeyPerov의 원본 구현에서 출발했습니다.

현재 비교 기준인 Alexey upstream 0.9.0은 267개, 이 저장소는 300개의 built-in
도구를 제공합니다. 즉
핵심 구조와 도구 대부분은 원본에서 왔고, 이 저장소는 그 위에 33개 도구와 프로젝트
확장 기능을 추가한 형태입니다.

Unity 프로젝트를 AI 에이전트로 조작하기 위한 MCP 서버입니다. 편집기 작업, 검증,
에셋 분석, 진단 및 확장 도메인을 아우르는 **300개 typed 도구**를 제공합니다.

## 공식 MCP와 Alexey 원본에 없는 추가 기능

아래 항목은 Unity 공식 MCP와 AlexeyPerov/Unity-Open-MCP 0.9.0 양쪽 모두에서 같은
내장 워크플로로 제공하지 않는 이 저장소의 추가분입니다. 범용 C# 실행으로 비슷한
동작을 직접 만드는 것과, 안정된 schema를 가진 전용 MCP 도구가 제공되는 것은
구분했습니다.

- **Input System Play Mode 자동화**
  - 입력 전송과 sequence 실행·취소
  - 입력 녹화, 목록 조회, replay 및 중단
  - 에이전트가 실제 플레이 입력을 반복 재현하는 테스트 흐름
- **고급 Shader Graph 편집**
  - 노드 삭제·복제·property 변경과 연결 해제
  - graph 저장·닫기 및 subgraph 생성
- **고급 VFX Graph 편집**
  - graph 생성·저장·닫기
  - context 추가·삭제와 flow 연결·해제
  - block 추가·삭제, property와 input 수정
- **제한형 C# snapshot query**
  - Unity 상태를 immutable DTO snapshot으로 만든 뒤 제한된 읽기 전용 쿼리만 실행
  - 임의 Editor C# 실행보다 작은 권한과 예측 가능한 결과 크기 제공
- **프로젝트 정의 MCP SDK**
  - 프로젝트 C#에서 tool뿐 아니라 resource와 prompt 등록
  - 중단 후 재개 가능한 durable job과 `get/list/cancel` lifecycle 제공
- **대용량 결과 저장소**
  - 큰 read-only 결과를 파일로 capture하고 chunk 단위로 읽은 뒤 명시적으로 삭제
- **통합 `doctor`**
  - Unity가 꺼져 있어도 설치 경로, 패키지 조합, 버전 호환성과 Bridge 상태를 함께 진단

정적 카탈로그에 추가된 33개 도구는 Input System 런타임 9개, Shader Graph 고급
편집 7개, VFX Graph 고급 편집 11개, output store 4개, 제한형 C# query와
`doctor`입니다.
Project SDK의 동적 tool/resource/prompt/job은 프로젝트별로 발견되므로 이 33개 숫자에
포함되지 않습니다.

## 공식 Unity MCP와 무엇이 다른가

대부분의 Unity 6 프로젝트에서는 먼저
[Unity 공식 MCP](https://docs.unity3d.com/Packages/com.unity.ai.assistant@latest)를
검토하는 것이 좋습니다. 설치가 간단하고 Unity가 직접 유지보수하며, 실행 중인
Editor를 다루는 일반적인 Scene·GameObject·Console 작업에는 공식 구현이 더
자연스럽습니다.

이 저장소는 공식 MCP의 대체재라기보다 다음 요구를 위한 확장형 자동화 도구입니다.

| 기술 관점 | Unity 공식 MCP | Seokh Unity Open MCP |
|---|---|---|
| 지원 환경 | Unity 6 이상, 실행 중인 Editor 중심 | Unity 2022.3 이상, live Editor + headless batch + offline 읽기 |
| 실행 구조 | Unity AI Assistant 패키지에 통합된 공식 MCP 경로 | Node stdio MCP 서버와 localhost Unity Bridge를 분리한 구조 |
| 자동화 범위 | Scene, GameObject, component, console 등 일반 Editor 작업 | 300개 typed 도구, Shader Graph/VFX/Input System/Profiler/패키지·빌드 작업 |
| 검증 방식 | Editor 권한과 Undo 중심 | `checkpoint → mutate → validate → delta`, 회귀 baseline과 표적 fix |
| Editor가 꺼진 경우 | live project context를 사용할 수 없음 | 에셋·계층·컴파일 로그 offline 조회, 지원 도구의 batch 실행 |
| CI와 반복 실행 | 공식 Unity 자동화 계층을 별도로 구성 | MCP CLI, headless 테스트, verify baseline을 저장소에 포함 |
| 확장 모델 | 공식 custom MCP tool 등록 | tool뿐 아니라 resource, prompt, durable project job을 프로젝트 C#에서 등록 |

### 어떤 것을 선택해야 하나

공식 MCP를 선택하세요:

- Unity 6 이상을 사용하고 Editor가 켜진 상태에서 주로 작업할 때
- 표준 Scene·코드·Console 자동화가 목적일 때
- 설정과 유지보수 비용을 최소화하고 Unity의 공식 지원 경로를 원할 때

이 구현을 선택할 이유가 있습니다:

- Unity 2022.3 프로젝트도 지원해야 할 때
- Unity를 열지 않고 에셋이나 최근 컴파일 오류를 읽어야 할 때
- headless batch와 CI에서 같은 도구 계약을 재사용해야 할 때
- 변경 전후의 회귀를 자동 판정하고 실패한 변경을 중단해야 할 때
- Shader Graph, VFX, Input System 런타임 입력 등 세분화된 typed 도구가 필요할 때
- 프로젝트 자체 기능을 MCP resource, prompt, 장기 실행 job으로 노출해야 할 때

위 요구가 없다면 공식 MCP가 더 단순한 선택입니다. 두 서버를 동시에 기본 도구로
노출하기보다는 프로젝트별로 하나를 주 경로로 정하는 편이 도구 중복을 줄일 수 있습니다.

이 구현은 [AlexeyPerov/Unity-Open-MCP](https://github.com/AlexeyPerov/Unity-Open-MCP)를
기술적 기반으로 사용하고, Unity 공식 MCP의 전송 및 직렬화 동작을 비교해 현재
아키텍처에 맞는 안정성 개선을 반영합니다.

## 주요 기능

- 체크포인트, 자동 검증, 변경 delta, 회귀 검사와 표적 수정을 포함한 안전한 변경
- 구조화된 에셋 검색, 검사, 재직렬화 및 참조·의존성 분석
- 제한된 Unity snapshot DTO를 대상으로 하는 읽기 전용 Roslyn 쿼리와 고급 변경용
  C# 안전 게이트
- Live Unity Bridge, 지원 도구의 batch fallback 및 Unity가 꺼진 상태의 offline 읽기
- 설치·버전·Bridge를 확인하는 `doctor`, 재사용 가능한 prompt recipe, live context
  resource 및 파일 기반 대용량 결과 저장
- 세션별 tool group으로 노출되는 typed editor 및 확장 도메인 워크플로
- 설치와 유지보수 작업을 돕는 Unity Hub Pro

### Live Bridge, batch fallback, offline 읽기

가능하면 실행 중인 Unity Editor를 사용하고, 지원되는 도구는 headless batch로
fallback합니다. Unity가 꺼져 있어도 에셋과 컴파일 오류를 디스크에서 읽을 수 있습니다.

> **예시:** “Bridge가 꺼져 있으니 Editor 로그에서 최근 컴파일 오류를 보여줘.”

### Typed editor와 확장 도메인

GameObject, Scene, Prefab, Material, Package뿐 아니라 NavMesh, Input System,
Cinemachine, Timeline, Shader Graph 등의 패키지 기반 도메인을 지원합니다.

> **예시:** “`cinemachine` 그룹을 활성화하고 Player를 따라가는 카메라를 만들어줘.”

### 에이전트 감각과 진단

테스트 러너, 스크린샷, Console, Profiler, 메모리 snapshot 및 이벤트 pull을 통해
에이전트가 실행 결과를 확인하고 다음 작업을 결정할 수 있습니다.

### 세션 도구 그룹과 Skill

기본 도구 목록은 작게 유지하고 필요한 도메인만 세션에서 활성화합니다. 프로젝트
Skill은 에이전트에게 `변경 → 검증 → 수정` 절차를 안내합니다.

### 안전 게이트가 적용된 변경

변경 작업은 `checkpoint → mutate → validate → delta` 순서로 실행됩니다. 성공으로
보이는 편집이 프로젝트를 망가뜨리기 전에 회귀를 발견하고 중단할 수 있습니다.

> **사용자:** 그 Prefab을 삭제해줘.
>
> **에이전트:** `Enemy` 삭제 영향을 확인하고 있습니다.
>
> **게이트:** 삭제하면 `Level1`과 `SpawnPoint`에 새로운 missing reference가 생깁니다.
>
> **에이전트:** 회귀가 감지되어 삭제하지 않았습니다. 참조까지 함께 수정할지 확인해 주세요.

예시 prompt는 [MCP 도구 문서](docs/api/mcp-tools.md#example-prompts), 전체 도구
계약은 [도구 카탈로그](docs/api/mcp-tools.md)에서 확인할 수 있습니다.

## 빠른 설치

**Unity 2022.3 LTS 이상**이 필요합니다.

1. **수동 설치:** [수동 설치 문서](docs/setup/manual-setup.md)에 따라 Unity 패키지와
   MCP 클라이언트를 직접 설정합니다.
2. **Unity Hub Pro:** [설치 마법사](docs/setup/wizard-setup.md)를 사용합니다.
3. **로컬 체크아웃:** [개발 환경 설정](docs/setup/development-setup.md)에 따라 저장소를
   빌드하고 실행합니다.
4. **실험적 에이전트 설치:** 다음 prompt를 AI 클라이언트에 전달합니다. 예측 가능한
   설치가 필요하다면 수동 설치나 마법사를 권장합니다.

```text
Install Unity Open MCP in this Unity project by following
https://raw.githubusercontent.com/seokh1213/unity-my-mcp/main/docs/setup/agent-setup.md
exactly. Do every agent step yourself; stop and tell me only when a human action is required.
If this monorepo is already open locally, read docs/setup/agent-setup.md from disk instead of fetching.
```

전체 절차는 [에이전트 설치 문서](docs/setup/agent-setup.md)를 참고하세요.

## 문서

사용자 문서:

- [API 색인](docs/api.md) — MCP, Bridge, resource, routing 및 자동화 계약
- [확장 기능](docs/extensions.md) — 확장 도메인, 의존성 및 tool group 활성화
- [프로젝트 정의 MCP SDK](docs/project-sdk.md) — Editor C#으로 Unity 도구, resource,
  prompt와 durable job 정의
- [문제 해결](docs/troubleshooting.md) — 연결 문제와 복구 방법
- [Dialog 정책](docs/dialog-policy.md) — 시작 modal 처리와 자동화 규칙
- [Skill](docs/skills.md) — Unity 프로젝트에 설치되는 에이전트 playbook
- [버전 호환성](docs/versioning.md) — 버전 정렬과 불일치 복구

기여자 문서:

- [아키텍처](docs/architecture.md) — 저장소 경계와 런타임 흐름
- [코드 규칙](docs/code-conventions.md) — 주요 C# 계약

다른 Unity MCP와 비교하려면 [Unity MCP 도구 비교표](docs/mcp-tools-comparison.md)를
참고하세요.

## Unity Hub Pro

Unity Open MCP의 데스크톱 보조 앱입니다. 프로젝트 관리, AI Setup 마법사 및
유지보수 작업을 하나의 UI에서 처리합니다. 자세한 내용은
[Unity Hub Pro 문서](docs/unity-hub-pro.md)를 참고하세요.

## 기여

- Issue 또는 Pull Request를 만들기 전에 [CONTRIBUTING.md](CONTRIBUTING.md)를
  확인하세요.
- [기여자 문제 해결](docs/troubleshooting-contributors.md)에서 로컬 테스트, Bridge 및
  자동화 오류 대응 방법을 확인할 수 있습니다.
- [Validation Suite](validation-suite/README.md)는 수동 검증을 위한 실행 가능한
  시나리오 앱입니다.
- [버전 및 릴리스](docs/contributing/versioning.md)에 동기화, tag 및 배포 절차가
  정리돼 있습니다.