UI Toolkit MCP

Unity Editor가 열려 있는 동안 AI 에이전트가 UI Toolkit 화면을 검사할 수 있게 해주는 MCP 서버입니다. Play Mode에 진입하거나 Player를 빌드하지 않고도 UXML/USS 파일의 구조와 모양을 검사하고 스크린샷을 캡처할 수 있습니다.

주요 기능:

• UXML 파일을 나열하고 UI Toolkit 창을 엽니다

• 요소 트리, 텍스트, 값, 위치, 크기, 해석된 스타일을 검사합니다

• 전체 화면 또는 선택한 요소를 PNG 이미지로 캡처합니다

• 긴 화면을 자동으로 타일로 분할합니다(이미지당 최대 8192px, 총 100MP)

• UXML/USS 파일을 다시 가져옵니다

• Unity 2022.3 LTS 및 Unity 6.3과의 호환성 테스트 완료

설정

1. Unity 패키지 추가

Unity Editor에서 Window > Package Manager를 열고 왼쪽 상단의 + 버튼을 클릭한 다음 Add package from git URL...을 선택합니다.

다음 URL을 입력합니다:

https://github.com/adzukyat/ui-toolkit-mcp.git?path=/unity-package

Unity가 스크립트 컴파일을 마치면 미리보기 서버가 자동으로 시작됩니다. 사용하는 동안 Unity Editor를 열어 두세요.

2. MCP 서버 등록

Node.js 20 이상이 필요합니다. Codex용 구성 예시:

[mcp_servers.ui_toolkit_mcp]
command = "npx"
args = [
  "-y",
  "ui-toolkit-mcp-server@latest",
  "mcp"
]

Related MCP server: Unity MCP Server

MCP 도구

ui_list_projects로 프로젝트를 찾은 다음 ui_select_project로 선택합니다. 그런 다음 ui_list_targets로 검사할 화면을 찾고 ui_inspect 또는 ui_screenshot을 사용합니다.

미리보기 구성(선택 사항)

프로젝트 루트에 .ui-toolkit-mcp-preview.json 파일을 배치하여 안정적인 별칭, 추가 USS 파일, 테마, 뷰포트를 정의할 수 있습니다. 다음 예시를 복사하여 수정하세요:

{
  "$schema": "./Packages/me.adzuki.ui-toolkit-mcp.preview-server/Schemas/ui-toolkit-mcp-preview.schema.json",
  "schemaVersion": 1,
  "previews": [
    {
      "alias": "settings",
      "document": "Assets/UI/Settings.uxml",
      "stylesheets": ["Assets/UI/Settings.uss"],
      "theme": "editor-dark",
      "selector": "#settings-root",
      "viewport": { "width": 480, "height": "full" }
    }
  ]
}

지원되는 테마는 editor-dark, editor-light, runtime입니다. 런타임 테마에는 panelSettings 에셋 경로도 지정할 수 있습니다.

개발 및 검증

npm test
npm run typecheck
npm run build
node scripts/mcp-smoke.mjs [project-id]

Unity EditMode 테스트는 test-projects/2022.3 및 test-projects/6000.3에 있습니다. 픽셀 단위 정확도 검증에는 그래픽 장치가 필요합니다. 트리 검사는 -nographics로 작동하지만 PNG 렌더링은 작동하지 않으므로, 정상적으로 시작된 Unity Editor에서 최종 검증을 수행하세요.

현재 제한 사항

• 서버는 주로 정적 UI 상태를 대상으로 합니다. C#에서 나중에 구성되는 화면의 경우 실제 EditorWindow를 열거나 미리보기 UXML 파일에 필요한 상태를 준비하세요.

• Editor 오프스크린 렌더러는 리플렉션을 통해 내부 UI Toolkit API를 호출합니다. ui_status는 지원되지 않는 Unity 버전에 대해 경고를 보고합니다.

• 열린 창 ID는 현재 Unity 세션에서만 유효합니다.

• 호버 및 포커스와 같은 의사 상태 주입, 포인터/키보드 상호 작용, 고정 애니메이션 시간은 아직 지원되지 않습니다.

• 글꼴, 아이콘, 사용자 지정 컨트롤, 데이터 바인딩은 대상 프로젝트에서 해석할 수 있을 때만 렌더링됩니다.