Quartermaster

이 프로젝트는 댐 프로토타입을 만들고 싶어서 시작했습니다.

대단한 건 아니었어요. 짧은 데모, 잘 되면 그 이상일 수도 있었죠. 무언가를 만들기 전에, 이미 가지고 있는 것 중에 작업을 빠르게 해줄 것이 무엇인지 확인하고 싶었습니다. 그래서 라이브러리에서 "댐"을 검색했지만 아무것도 나오지 않았습니다. 당연한 결과였죠. 어떤 에셋도 댐이라고 불리지 않으니까요. 그런데 제가 이미 소유한 네 개의 패키지에는 곡선 콘크리트 메시, 물 시스템, 바위 지형이 흩어져 있었습니다. 댐에 필요한 모든 것이었죠. 그중 대부분을 몇 년 동안 갖고 있었지만 한 번도 조각들을 연결해 본 적이 없었습니다.

두 스토어에 걸친 ~1,500개의 에셋이 사람을 그렇게 만듭니다. 거의 모두 번들과 세일로 모은 것이고, 하나도 기억되지 않습니다. 그리고 저만 그런 게 아닙니다. AI 어시스턴트도 알지 못합니다. 도움을 요청하면 처음부터 모든 것을 만들거나 쇼핑을 권할 뿐, 수백 달러어치의 딱 맞는 자산이 여러분의 디스크에 그대로 있는 동안 말이죠.

Quartermaster는 Unity Asset Store와 Fab 라이브러리 전체를 로컬에 인덱싱하고, MCP를 통해 코딩 에이전트에 제공합니다. 그날 있었으면 하고 바랐던 도구입니다. 댐에 대해 물어보면, 이미 곡선 콘크리트 메시를 소유하고 있다는 답을 얻을 수 있습니다.

you    →  "I want to build a dam — what do I have to work with?"

agent  →  search_owned_assets(...)        finds the concrete meshes, water FX, terrain
          validate_stack([...])           checks none of them fight each other
          import_asset_to_project(...)    unpacks into Assets/, demos stripped

모든 결과는 이미 비용을 지불한 것입니다. 어떤 것도 지어낸 것이 아닙니다.

이름이 아니라 설명을 입력합니다. 그 결과 중 어느 것도 검색어와 한 단어도 겹치지 않습니다.

왜 Quartermaster일까요? 병참장교(Quartermaster)의 임무는 창고에 무엇이 있는지 기억하는 것이 아니라, 출발할 때 필요한 장비를 갖추게 하는 일입니다. 이는 단순히 잊어버리는 문제보다 실제 문제에 더 가깝습니다. 저는 잃어버린 것이 없었고, 무언가를 소유하고 있다는 것을 알고 있었습니다. 문제는 "댐 프로토타입을 만들고 싶다"에서 "이 네 개 패키지를 열어라"로 가는 데 먼저 한 시간의 파고들기가 필요했다는 점입니다. 그리고 잘 되면 더는 한 시간의 파고들기를 견디지 못합니다. 그런 식으로 떠오른 아이디어는 거절당하지 않습니다. 그냥 조용히 이루어지지 않을 뿐이고, 그게 이루어졌을지 여부를 결코 알 수 없습니다.

아무도 알려주지 않는 부분

두 스토어 모두 여러분이 무엇을 소유했는지 인정하지 않습니다.

Unity는 /account/purchases를 제거했습니다(2026년 8월부터 404). Fab에는 소유권 API도, 내보내기 버튼도, 아무것도 없습니다. 구매 내역은 SSO, MFA, 봇 탐지 뒤에 있는 그들의 비공개 GraphQL 안에만 존재합니다.

그것에 접근하기까지 네 번의 시도가 필요했고, 그중 세 번은 실패였습니다.

1. Playwright가 번들한 Chromium — Epic의 캡차가 완전히 거부합니다("enable JavaScript").

2. Playwright로 실제 브라우저를 구동 — 감지 가능한 훅을 주입하며, Epic은 비밀번호 뒤에 두 번째 보안 장벽을 세웁니다.

3. 로그인 중 디버거 연결 — 같은 결과입니다. 로그인 흐름을 건드리는 모든 것이 플래그 처리됩니다.

4. 실제로 작동하는 방법: 로그인 자동화를 완전히 중단하는 것입니다. 디버그 포트도 없고, 스토어와 여러분 사이에 아무것도 없는 일반 브라우저 창으로 로그인합니다. 자동화 자체가 위험 시스템을 작동시킨 원인이었기 때문입니다. 로그인이 끝난 후에만, 여러분이 직접 세운 세션에서 Quartermaster가 디버거를 연결하고 스토어 자체의 페이지네이션 쿼리를 재생합니다. 자체 CSRF 헤더, 자체 청킹(요청당 42개 ID — Unity 클라이언트가 보내는 방식)과 함께요.

그 방법이 이 프로젝트의 대부분입니다. 나머지(검색, 린팅, 언패킹)는 솔직히 비교하면 단순합니다.

이 프로젝트를 직접 수정하려 할 때 설계에 녹아 있는 두 가지 값진 규칙이 있습니다.

• 브라우저는 정상적으로 닫혀야 합니다(/F 없는 taskkill). 갑작스러운 종료는 Unity의 장치 신뢰 쿠키를 잃게 하며, 이후 모든 세션에서 MFA 인증이 요구됩니다.

• 라이브러리 가져오기를 헤드리스로 실행하지 마세요. 유효한 쿠키가 있어도 헤드리스는 Unity의 위험 시스템을 작동시킵니다.

Related MCP server: Unity API Communicator MCP Server

얻을 수 있는 것

의도와 시각을 이해하는 검색. 이것이 댐 문제입니다.

• 정확한 키워드 — SQLite FTS5 기반.

• 자연어 의도 — 로컬 ONNX 텍스트 임베딩(BAAI/bge-small-en-v1.5) — "물을 가두기 위한 콘크리트 구조물" 검색 시 목록에 댐을 언급하지 않는 메시와 셰이더를 찾아냅니다.

• 교차 양식 시각 이해 — ONNX CLIP 임베딩(Qdrant/clip-ViT-B-32) — *"고딕 대성당"*을 검색하면 말 그대로 스크린샷과 프로모 렌더를 점수화하여, 텍스트 설명이 전혀 없는 에셋도 찾아냅니다. 세 신호는 모두 CPU에서 **3-way Reciprocal Rank Fusion (RRF)**으로 융합됩니다. GPU도, 벡터 데이터베이스 프로세스도, 클라우드 API도 없습니다. ONNX Runtime과 numpy 행렬이 다른 모든 것과 같은 프로세스 안에서 동작합니다.

~1,800개 에셋 보관함을 기준으로 측정: 두 모델이 상주한 상태에서 ~480 MB의 최대 RAM, 첫 쿼리에 ~1.5 s(BGE와 CLIP 로딩), 이후 ~110 ms의 웜 상태가 소요됩니다. 모델은 지연 로딩되므로, 검색을 전혀 하지 않는 에이전트는 그 비용을 지불하지 않습니다.

디스크에 대한 실측 정보. %APPDATA%/Unity/Asset Store-5.x/와 Epic의 VaultCache를 스캔하여 모든 결과가 이미 다운로드되었는지 클라우드에만 있는지 알 수 있습니다. 에이전트는 로컬에 있는 것을 선호합니다. 다운로드 없는 임포트가 4GB 임포트보다 낫습니다.

스택용 린터. 식물 렌더러 두 개가 충돌합니다. 코어 MicroSplat 없이 MicroSplat 모듈만 있으면 조용히 아무 일도 하지 않습니다. HDRP 프로젝트의 URP 전용 셰이더는 분홍색으로 렌더링됩니다. Quartermaster는 이런 문제를 한나절을 쓰기 전에 잡아냅니다.

직접 언패킹. 캐시된 .unitypackage 파일을 Assets/로 직접 추출하면서 /Demo/, /Samples/, /Documentation/ 및 PDF는 제외합니다. 일반적으로 패키지당 60–80%의 불필요한 용량이 줄어듭니다. 선언된 모든 경로는 <project>/Assets/ 안에서 정규화되고 검증됩니다. 이스케이프는 단순히 필터링되는 수준이 아니라 구조적으로 불가능합니다.

설치

독립 실행 번들 — Releases에서 Quartermaster-windows-x64.zip을 다운로드하여 아무 곳에나 압축을 풉니다. Python이 필요 없습니다.

• Quartermaster.exe — Win+Alt+V 스포트라이트 검색, 스토어 하베스팅, 라이브러리 탐색, 직접 언패킹을 지원하는 데스크톱 GUI.

• Quartermaster-mcp.exe — Claude Desktop, Cursor, Antigravity, Windsurf용 독립 실행 MCP stdio 서버.

라이브러리 데이터는 %LOCALAPPDATA%\Quartermaster에 안전하게 저장되므로 업그레이드는 데이터 손실 없이 폴더를 교체하는 것만으로 충분합니다.

소스에서 — **Python 3.10+**가 필요합니다.

git clone https://github.com/Tanshaydar/Quartermaster.git
cd Quartermaster
pip install -r requirements.txt

라이브러리를 시드하세요:

1. 로그인. 참여가 필요한 유일한 단계입니다. 일반 브라우저 창이 열리며, 2FA와 캡차는 평소와 똑같이 동작합니다. 작업을 마치고 창을 닫으면 세션이 로컬에 유지됩니다.

python -m src.store_client login unity
python -m src.store_client login fab

2. 하베스트 및 보강. 오래 걸리는 작업이며, 재개 가능하고, 다시 실행해도 안전합니다. 각각 중단된 지점부터 이어서 진행합니다.

python -m src.store_client fetch unity
python -m src.store_client fetch fab
python -m src.store_client enrich            # descriptions and cover art, politely batched
python -m src.store_client fab-deep-media    # Fab only: plain HTTP is 403'd, galleries need the authed browser

3. 로컬 인덱스를 구축한 다음 디스크를 스캔하세요.

python -m src.semantic build     # text embeddings
python -m src.vision build       # screenshot embeddings + concept tagging
python -m src.local_scan         # which of them are already downloaded here

semantic build와 vision build는 "물을 가두기 위한 콘크리트 구조물" 같은 자연어 쿼리와 시각적 개념 쿼리가 여러분의 에셋을 찾게 만드는 명령입니다. 이 단계를 건너뛰어도 검색은 여전히 작동하지만, 정확한 키워드로만 검색됩니다.

local_scan은 카탈로그를 만든 후에 실행하세요. 빈 보관함을 스캔하면 파일 이름을 대조할 대상이 없으므로 캐시된 모든 패키지를 각각 단독 항목으로 분류합니다. 무해합니다. 다음 스캔에서 실제 카탈로그와 대조하여 정리되지만, 그때까지는 중복이 보일 것입니다.

이미 스토어에서 CSV 내보내기가 있으신가요? 브라우저를 완전히 건너뛰세요:

python -m src.ingest             # eats any CSVs in data/seed/
python -m src.semantic build     # still needed — see the note above
python -m src.local_scan         # then find what's already on disk

에이전트를 연결하세요:

옵션 A: 자동 등록(명령 하나로)

# Standalone binary users:
Quartermaster-mcp.exe --register --all

# Source users:
python -m src.register --all             # Claude Desktop, Cursor, Windsurf, Antigravity
python -m src.register --all --dry-run   # look before you leap

등록은 기존 클라이언트 설정에 병합되며, 먼저 .quartermaster-backup을 만듭니다. 다른 서버를 덮어쓰지 않습니다.

옵션 B: 수동 설정 서버 블록을 클라이언트 설정에 붙여넣으세요:

독립 실행 바이너리:

{
  "mcpServers": {
    "quartermaster": {
      "command": "C:/path/to/Quartermaster/Quartermaster-mcp.exe",
      "args": []
    }
  }
}

소스에서:

{
  "mcpServers": {
    "quartermaster": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "C:/path/to/Quartermaster"
    }
  }
}

Claude Desktop은 %APPDATA%/Claude/claude_desktop_config.json, Cursor는 ~/.cursor/mcp.json, Windsurf는 ~/.codeium/windsurf/mcp_config.json을 읽습니다.

[!NOTE] 최초 실행 모델 워밍업: 처음 자연어 또는 시각 검색을 실행하면 ONNX Runtime이 임베딩 모델(BAAI/bge-small-en-v1.5 및 clip-ViT-B-32)을 다운로드하여 로컬에 캐시합니다(~150 MB). 첫 쿼리는 메모리에 로딩하는 동안 3–5초가 걸릴 수 있으며, 이후 모든 쿼리는 ~100 ms 안에 실행됩니다.

에이전트 도구

두 개의 파일로 코드 변경 없이 Quartermaster에 고유한 어휘를 가르칠 수 있습니다:

• data/recipes.json — 역할, 전제 조건, 큐레이션된 스택. 충돌 린터가 추론하는 기준입니다. 어떤 에셋이 같은 작업을 두고 경쟁하는지, 무엇이 무엇을 필요로 하는지, 어떤 스택을 검증된 좋은 스택으로 간주하는지.

• data/concepts.json — CLIP이 스크린샷을 점수화할 때 사용하는 시각적 어휘. 기본 제공 목록은 게임 중심으로 구성되어 있습니다. archviz 또는 previs 작업을 한다면 교체하고 다시 빌드하세요.

둘 다 런타임에 읽히는 일반 JSON이며, 둘 다 docs/ 아래에 참조 페이지가 있습니다.

다른 사용 방법

• 데스크톱 앱(run_desktop.bat) — 트레이 아이콘이 있는 PySide6 스포트라이트 검색. Windows 어디서든 Win+Alt+V를 누르세요. 에이전트와 나란히 실행되며 방해하지 않습니다. 데이터베이스가 WAL 모드로 실행되므로, 에이전트가 검색하는 동안 GUI가 쓰기를 해도 어느 쪽도 블로킹되지 않습니다.

• 웹 UI(run_ui.bat) — http://localhost:7890의 다크 모드 대시보드.

• Unity에서 — editor_bridge/Quartermaster-Bridge.unitypackage를 임포트한 후 Window > Quartermaster를 선택하세요. 에디터를 떠나지 않고 검색하고 임포트할 수 있습니다. 작은 참고: 이 브리지 패키지는 src/build_bridge.py로 생성되며, 이 스크립트는 unpacker.py가 읽는 것과 동일한 tar 형식을 작성합니다. 의도적인 도그푸딩입니다.

보안

이 도구는 스토어 세션을 보유하고 프로젝트에 쓰기를 수행하므로 로컬 API를 진지하게 다룹니다:

• 상태를 변경하는 모든 엔드포인트는 토큰을 요구합니다(최초 실행 시 생성되며 data/.auth_token에 저장되고 Unity 브리지용으로 미러링됩니다). X-Quartermaster-Token 또는 Authorization: Bearer로 전송하세요. 웹 UI는 SameSite=Strict 쿠키를 자동으로 받습니다.

• 유효한 토큰이 있어도 교차 출처(cross-origin) 요청은 거부됩니다.

• 언패커 샌드박스는 .. 세그먼트를 접고, 드라이브 문자와 제어 문자를 제거하며, Assets/ 밖의 모든 것을 Assets/_Quartermaster_Imported/ 아래로 옮기고, 최종 경로가 프로젝트 안에 있는지 확인합니다 — 감정이 아닌 테스트로 강제됩니다 (python run_tests.py -v).

• 이미지 프록시는 도메인 허용 목록을 사용하고, 사설 대역과 메타데이터 엔드포인트를 차단하며, 모든 리다이렉트 홉을 다시 검증하고, 크기를 제한하며, 캐시가 파일 상한을 초과하면 가장 오래된 항목을 정리합니다.

아무것도 외부로 전송되지 않습니다. 라이브러리, 임베딩, 디스크 경로, 스토어 세션은 이 머신에만 남습니다.

설정

config.json의 선택적 키(최초 실행 시 생성됨):

솔직한 한계

• Windows 우선. 캐시 스캔은 Windows 경로를 가정합니다. MCP 검색은 어디서나 작동하지만 로컬 가져오기 감지는 그렇지 않습니다.

• 한 대의 머신, 한 명의 사용자. 동기화나 서버 모드가 없습니다. 의도적인 선택입니다.

• 하베스팅은 스크래핑입니다. Unity와 Fab는 원할 때마다 내부 구조를 바꾸며 실제로 바꿔 왔습니다 — 여기의 청크 크기, 엔드포인트, GraphQL 형식은 내가 배포한 날 기준으로 정확하며 영원히 정확한 것이 아닙니다. 가져오기가 빈 결과로 돌아오면 data/store_harvest.log에 본 모든 JSON 응답이 기록됩니다. 그곳이 조사를 시작할 곳입니다.

• 분류 체계는 휴리스틱입니다. 카테고리는 단어 경계 토큰, 스토어 태그, 스크린샷의 제로샷 CLIP 시각 개념 마이닝을 다중 모달로 혼합하여 추론됩니다. 스크린샷이 없는 고도로 양식화된 제목은 Tools & Utilities로 기본 설정되지만, 의미 벡터 검색과 하이브리드 검색은 지정된 카테고리와 관계없이 항상 전체 볼트를 포괄합니다. 시각 어휘를 조정하는 방법은 docs/concepts.md에 문서화되어 있습니다.

• 인덱싱은 패키지 경계에서 멈추며 스토어 메타데이터는 노이즈가 많습니다. 검색은 제목, 설명, 태그, 갤러리 스크린샷의 전체 이미지 CLIP 임베딩에 걸쳐 작동합니다. 여기에는 두 가지 구조적 한계가 있습니다.

  1. 내부 에셋 인덱싱 없음: 아카이브 내용을 풀어 개별 하위 메시, 프리팹 또는 내부 파일명을 인덱싱하지 않습니다(예: 모듈형 환경 팩 안에 있는 "판와"나 "곡선 콘크리트 계단참" 같은 특정 건축 하위 요소를 검색해도 목록 텍스트에 선언되어 있거나 갤러리 렌더링에서 두드러지지 않으면 검색되지 않습니다).

  2. 실질 내용이 없는 스토어 상용구: 상당한 비율의 스토어 목록(특히 Unity의 템플릿화된 og:description)에는 기술 정보가 전혀 없는 순수 마케팅 상용구("Elevate your workflow with...")가 포함되어 있습니다. 시각적 CLIP 임베딩은 바로 이 간극을 메우기 위해 존재하지만, 전체 이미지 벡터가 항상 세분화된 하위 요소를 해결할 수는 없습니다.

• 언패킹은 Unity 전용입니다. Fab 에셋은 인덱싱되고 검색 가능하지만, .unitypackage 추출은 당연히 적용되지 않습니다.

문제 발생 시

이슈를 열어 주세요. 혼자 하는 프로젝트라 응답 시간을 약속할 수는 없지만, 이슈는 읽습니다.

증상별로 도움이 되는 정보:

• 가져오기가 비어 있거나 일부만 돌아왔습니다. 스토어가 예고 없이 내부 구조를 바꾸기 때문에 가장 고장나기 쉬운 부분입니다. data/store_harvest.log는 하베스트가 본 모든 JSON 응답을 기록합니다 — 그 파일의 끝부분이 전체 진단입니다. 그것을 포함해 주세요.

• 검색이 의미 있는 결과를 반환하지 않습니다. 먼저 python -m src.vision status를 확인하세요. 인덱스가 구축되지 않으면 조용히 키워드 전용으로 저하되며, 이것이 대부분의 "검색이 고장났다"는 보고의 원인입니다.

• 잘못된 카테고리 또는 실제가 아닌 충돌. 그것은 대개 코드가 아니라 지식 베이스 문제입니다 — docs/recipes.md와 docs/concepts.md에서 직접 고치는 방법을 다루며, 테스트할 에셋을 제가 소유하지 않은 규칙을 담은 data/recipes.json에 대한 PR은 진심으로 환영합니다.

• 독립 실행형이 시작되지 않습니다. --windowed 모드라서 조용히 실패합니다. %LOCALAPPDATA%\Quartermaster\data\crash.log에 기록됩니다.

이 도구로 멋진 무언가를 만들었다면 정말로 듣고 싶습니다.

스토어에 관한 참고 사항

Quartermaster는 여러분이 직접 로그인한 브라우저에서, 여러분 자신의 머신으로, 여러분 자신의 계정을 읽습니다. 자격 증명을 보관하지 않으며, 제 어떤 서버로도 아무것도 보내지 않고, 텔레메트리가 없습니다 — 세션은 로컬 브라우저 프로필에, 라이브러리는 로컬 SQLite 파일에 존재합니다. 유출될 공유 백엔드가 없습니다.

이 도구는 Unity Technologies나 Epic Games와 제휴, 보증, 또는 연결되어 있지 않습니다. Unity, Unity Asset Store, Fab, Unreal Engine은 각 소유주의 상표입니다. 어떤 서비스에 대한 접근 자동화는 해당 서비스 약관에 비추어 여러분이 결정할 일이며, 이 도구가 대신 결정하지 않습니다.

라이선스

MIT. LICENSE를 참조하세요.