Unity MCP Efficient

독립적이고 토큰 효율적인 MCP 파사드 및 Codex 스킬로, MCP for Unity용입니다.

MCP for Unity의 전체 기능 세트를 작은 모델 지향 API 뒤에 유지합니다. 모델은 여섯 개의 안정된 도구를 보게 되고, 필요할 때 업스트림 카탈로그를 검색하고, Unity에 최적화된 컴팩트한 응답을 받으며, 모든 중간 결과를 대화창으로 가져오지 않아도 일상적인 작업을 연쇄적으로 처리할 수 있습니다.

[!IMPORTANT] 이 프로젝트는 Unity 패키지나 그 Python 서버를 대체하지 않습니다. MCP for Unity는 여전히 백엔드입니다. AI 클라이언트에는 업스트림 서버가 아니라 이 파사드를 등록하세요. 두 도구 표면을 모두 노출하면 컨텍스트 절약 효과가 대부분 사라집니다.

측정된 컨텍스트 절감

2026-08-24에 benchmarks/의 스크립트는 MCP for Unity v10.1.0 (c14de1e6)을 대상으로 다음 결과를 만들었습니다.

동적 카탈로그는 377개의 Unity 연산을 인덱싱했습니다. 작고 결정적인 영어/러시아 검색 스위트는 15개 사례 모두에서 기대 연산을 rank 1로 반환했고, 15개 사례 모두 상위 3위 안에 들었습니다. 릴리스 후보는 35개 파서드 테스트를 통과합니다. 실시간 스모크 테스트는 프로젝트를 변경하지 않았고 여섯 도구 표면, rank 1의 editor.refresh, 에디터 상태, 열려 있는 Unity Editor에 대한 두 단계 씬 검사 배치를 검증했습니다.

¹ 토큰 수는 투명한 "토큰당 4자" 추정치를 사용합니다. 이는 컨텍스트 크기를 나타내며 API 과금 기준이 아닙니다. 실제 토크나이저 인식은 모델과 페이로드에 따라 다릅니다.

² 계층 벤치마크는 250개의 오브젝트, 오브젝트당 300개의 정점 인덱스, 그리고 같은 데이터가 text와 structured payload에 있는 "잡음 있는" 응답을 모델링합니다. 이 스트레스 케이스는 모든 씬에 동일한 절감을 보장하지 않습니다. 방법과 원시 값은 BENCHMARKS.md 참조.

Related MCP server: Agent Bridge for Unity

여섯 도구가 하는 일

모델은 여전히 파사드 뒤의 377개 인덱스 연동에 접근할 수 있습니다. 그 연동은 더 이상 프롬프트 전체를 동시에 차지하지 않습니다.

경계에서 다루는 문제

아키텍처

Codex or another MCP client
        |
        | sees 6 tools
        v
Unity MCP Efficient (stdio by default)
        |-- capability search over the live upstream catalog
        |-- compact Unity-specific post-processing
        |-- bounded workflow runtime
        |-- local SQLite result and request receipts
        |
        | HTTP, default http://127.0.0.1:8080/mcp
        v
MCP for Unity server
        |
        v
Unity Editor package

단순한 스킬 하나로는 MCP 클라이언트가 이미 로드한 도구 스키마를 숨길 수 없습니다. 그래서 이 저장소에는 두 가지 구성요소가 있습니다.

• 파서드는 더 작은 API와 컴팩트한 응답을 강제합니다.

• 스킬은 Codex에 검색, 배치, 복구, 검증을 효율적으로 하는 방법을 가르칩니다.

설치

1. MCP for Unity를 HTTP 모드에서 시작

CoplayDev/MCP for Unity를 권장 업스트림 지침에 따라 설치합니다. Unity에서 Window → MCP for Unity 플러그인을 열고, 로컬 HTTP 전송을 선택한 후 서버를 시작합니다.

업스트림 기본 엔드포인트는:

http://127.0.0.1:8080/mcp

프로젝트가 다른 포트를 사용한다면 UNITY_MCP_BACKEND_URL를 통해 아래에서 전달합니다.

2. Codex에 파서등 등록

필요하면 uv를 설치하고, 다음을 실행하세요.

codex mcp add unity-efficient \
  --env UNITY_MCP_BACKEND_URL=http://127.0.0.1:8080/mcp \
  -- uvx --from git+https://github.com/Vangardo/unity-mcp-efficient.git unity-mcp-efficient

PowerShell에서는 같은 명령을 한 줄로 사용하세요.

codex mcp add unity-efficient --env UNITY_MCP_BACKEND_URL=http://127.0.0.1:8080/mcp -- uvx --from git+https://github.com/Vangardo/unity-mcp-efficient.git unity-mcp-efficient

같은 Codex 클라이언트에서 https://github.com/CoplayDev/unity-mcp 관련 직접 등록 항목을 제거하거나 비활성화하세요. 업스트림 HTTP 서버는 유지하되, 모델에 그 패키지 48개 도구 표면을 등록하지 마세요.

3. Codex 사용자 스킬을 설치

가장 쉬운 경로는 Codex에게 요청하는 것입니다.

$skill-installer Install the skill from https://github.com/Vangardo/unity-mcp-efficient/tree/main/skills/unity-mcp-efficient

수동 사용자 수준 설치를 원하면 저장소를 클론하고 skills/unity-mcp-efficient를 다음 위치로 복사하세요.

$HOME/.agents/skills/unity-mcp-efficient

Codex는 스킬 변경을 자동으로 감지합니다. 스킬이 목록에 안 나타나면 Codex를 다시 시작하세요.

다른 MCP 클라이언트

stdio 구성은 다음과 같은 형태입니다.

{
  "mcpServers": {
    "unity-efficient": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Vangardo/unity-mcp-efficient.git",
        "unity-mcp-efficient"
      ],
      "env": {
        "UNITY_MCP_BACKEND_URL": "http://127.0.0.1:8080/mcp"
      }
    }
  }
}

클라이언트가 Agent Skills 형식을 지원하면 패키징된 스킬을 설치하세요. 파사이드 없이도 동작하지만, 스킬은 도구 선택과 복구 동작을 개선합니다.

권장 에이전트 루프

1. Unity의 낮은 세부 상태를 먼저 검사합니다.

2. 하나의 구체적인 작업 문구로 검색합니다.

3. 인자가 불분명하면 선택한 스키마를 요청합니다.

4. 알려진 종속 작업은 순차적으로 일괄 처리합니다. 독립 읽기는 병렬화하고 Unity 변경 작업은 절대 병렬화하지 않습니다.

5. 컴팩트한 출력을 유지하고, 저장된 결과는 경로 또는 페이지 단위로 확장합니다.

6. 정의적 결과를 검증하되, 모든 원시 중간 오브젝트를 전부 확인하지는 않습니다.

이 루프는 이미 skills/unity-mcp-efficient/SKILL.md에 반영되어 있습니다.

구성

기본 stdio 전송을 유지하세요, 파서드를 네트워크에 공개할 이유가 없다면. HTTP 또는 SSE를 사용하기 전에 SECURITY.md를 읽으세요.

개발과 검증

git clone https://github.com/Vangardo/unity-mcp-efficient.git
cd unity-mcp-efficient
uv sync --extra dev
uv run pytest -q

업스트림 HTTP 서버가 실행 중일 때:

uv run python benchmarks/evaluate_facade.py
uv run python benchmarks/measure_surface.py
uv run python benchmarks/live_smoke.py

evaluate_facade.py와 measure_surface.py는 실행 중인 업스트림 카탈로그를 읽습니다. live_smoke.py는 변경을 만들지 않지만, 열려 있고 게임 실행 중인 Unity Editor를 요구합니다.

알려진 경계

• 컴팩트한 출력은 의도적으로 손실이 있습니다. 원본의 손상되지 않은 raw 결과는 유한한 시간 동안 get_result로 얻을 수 있습니다.

• 파서드가 임의의 Unity 변경 작업을 안전하게 만든는 건 아닙니다. 권한과 단계를 MCP 클라이언트와 사용자가 여전히 확인해야 합니다.

• 병렬 모드는 보수적입니다. Unity는 내부에서 에디터 작업을 직렬화할 수 있습니다.

• 검출되어 선택할 수 있는 옵션 기능(예: Roslyn 지원)이 특정 Unity 프로젝트에 없을 수 있습니다.

• Scene·Game 뷰 캡처는 IMGUI 일부나 에디터 오버레이를 빼먹을 수 있습니다.

• 호환성 테스트는 MCP for Unity v10.1.0 기준입니다. 카탈로그는 동적으로 늘어나므로, 이후의 업스트림 버전에서는 우선 벤치마크를 실행하고 호환한다고 볼 것.

디자인 계보

우리는 Vangardo/mcp_hub 작업에서 온 프로gressive-disclosure 아이디어를 가져왔습니다. MCP_hub는 큰 통합 카탈로그를 작은 검색-호출 API 뒤로 보내는 넓은 MCP 게이트웨이입니다. Unity MCP Efficient는 그 컨텍스트 운영 방식을 Unity에 적용하고, 여기에 Unity 특화 압축, 리비전 체크, 변경 작업 복구, 스크린샷, 그리고 짧은 로컬 워크플로우까지 추가했습니다.

Slack, Teamwork, Telegram, 메모리, 자동화, 교차 서비스 에이전트에 이런 패턴이 필요하다면 MCP Hub를 참고하세요.

Unity 호환 백엔드는 CoplayDev/MCP for Unity이며, MIT License로 배포됩니다. 이 저장소는 독립적인 프로젝트로 그 소스 코드를 포함하지 않습니다. NOTICE.md와 THIRD_PARTY_NOTICES.md를 확인하세요.

사용 허가와 상표

이 저장소의 원본 코드는 MIT 라이선스로 제공됩니다.

Unity는 미국 및 기타 국가에서 Unity Technologies 또는 그 계열사의 상표 또는 등록 상표입니다. 이 프로젝트는 Unity Technologies 또는 CoplayDev와 제휴하거나 보증한 것이 아닙니다. 그 외 이름과 브랜드의 소유권은 각 해당 소유자에게 있습니다.