assetcache-mcp 0.2.2

MCP server + tray app for indexing and retrieving 2D sprites, sheets, sounds, and Unity packages via natural language.

AssetCacheMCP

Unity 게임 개발 중 Claude Code가 보유 에셋(2D 스프라이트, 스프라이트 시트, 사운드)을 자연어로 요청하면 가장 적합한 후보를 돌려주는 MCP 서버 + 윈도우즈 트레이 상주 앱.

• 사용자가 library/<pack>/... 형태로 에셋 팩 폴더를 통째로 드롭하면 자동 인덱싱
• Ollama로 도는 Gemma 4(gemma4:e4b)가 이미지·오디오를 직접 보고 의미 라벨 생성
• 한 프로젝트에서 한 번 채택한 팩을 이후 검색에서 우선시해 통일성 유지
• 트레이 부팅 → 브라우저 자동 진입 (http://127.0.0.1:9874) — FastAPI + HTMX + Alpine.js 기반 웹 UI
• Unity Asset Store 로컬 캐시(.unitypackage)도 자동 임포트
• 시트 분할 + 애니메이션 프레임 추론 (suggest_animation_frames)
• PyPI 권장 설치 (pipx install assetcache-mcp) — 현재 Windows 1차 지원 (Mac/Linux 는 install 흐름이 cross-platform 호환되지만 정식 검증은 미진행)
• 한국어/영어 i18n + 다크모드 + Windows 자동 시작 + PyPI 신버전 알림

전체 설계는 DESIGN.md. 웹 UI 상세 사용법은 docs/WEB_UI_GUIDE.md.

주요 기능

기능	설명
에셋 라이브러리 검색	자연어 쿼리 + 300ms 디바운스. 의미/키워드/라벨/통일성 6채널 하이브리드 검색
라이브러리 페이지 (/library)	카드 그리드/리스트 + 사이드 패널 (B/C/D 탭) + 상세 모달 + 사운드 인라인 재생
팩 관리 페이지 (/packs)	등록된 팩 카드 그리드 + 활성/비활성 토글
라벨 admin 페이지 (/labels/admin)	24 axis 탭 + 라벨 CRUD + JSON import/export
Claude pick 인터랙션	MCP 도구 request_user_pick — Claude가 후보를 고르면 브라우저에 보라색 선택 카드 출현
통일성 가중 검색	프로젝트별 사용 이력 추적 → 같은 팩·벤더 우선 추천
MCP 20 도구	find_asset, suggest_packs, record_asset_use, request_user_pick, suggest_animation_frames, import_unity_package 등
다크 모드	OS prefers-color-scheme 자동 반영
PyPI 신버전 알림	부팅 시 PyPI JSON API 조회 → 신버전 시 웹 배너 + 트레이 메뉴 안내

진행 현황

마일스톤	상태	비고
M0 — 뼈대	✅ 완료	트레이 셸·설정·로깅·단일 인스턴스
M1 — 워처 + Pack Manager + DB	✅ 완료	watchdog, SQLite 4테이블, 부팅 풀스캔
M2 — 분석 파이프라인 + CLIP	✅ 완료	Pillow/librosa/Gemma 4/CLIP, 24 axis 라벨 시드
M2.1 — 병렬화 패치	✅ 완료	동시성 1→3, Ollama semaphore
M3 — 검색 백엔드 + 통일성 + MCP	✅ 완료	HybridSearcher, 12 MCP 도구
M4 — 검색 UX 풍부화	✅ 완료 (main 머지)	label_query AND/OR/NOT, 16 MCP 도구
M5 — 웹 GUI 전환 + Claude pick	✅ 완료 (main 머지)	FastAPI 웹 UI + Qt 폐기, 17 MCP 도구
M6 — 시트 분석 + 애니메이션	✅ 완료 (main 머지)	격자 분할, suggest_animation_frames (18 MCP)
M7 — Unity Asset Store 임포트	✅ 완료 (main 머지)	.unitypackage 파서 + 활성 프로젝트 (20 MCP)
M8 — 패키징 + i18n	✅ 완료 (main 머지)	PyInstaller --onefile + ko/en i18n + 다크모드 + autostart
M10 — PyPI + AssetCacheMCP rename	✅ 완료 (main 머지)	pipx install assetcache-mcp + PyPI 신버전 알림
v0.1.1 — yagni-clean	✅ 완료 (main 머지)	v0.0.1 마이그레이션 helper 일괄 제거, 회귀 1079, Trusted Publishing OIDC 첫 자동 publish
M11 — Multi-backend LLM Architecture	✅ 완료 (main 머지, v0.2.0 PyPI)	6 backend (Ollama/Gemini/Claude/OpenAI/OpenRouter/HF) + modality 별 chain + 자동 fallback + /settings UI
M11.1 — Gemini Batch API + /analyzing	✅ 구현 완료 (v0.2.1 PR 대기)	50% 비용 Gemini Batch API + hybrid 정책 (임계값 30) + /analyzing dashboard

마일스톤 사이클(plan → todo → 테스트 → 구현 → verification) 상세는 milestones/README.md.

설치

가장 간편한 설치는 pipx 또는 uv 도구를 사용한다.

pipx install assetcache-mcp

또는:

uv tool install assetcache-mcp

설치 후 PowerShell 어디서든 다음 명령으로 트레이 부팅:

assetcache --tray

개발 환경 셋업

Windows 10 + python.org 정식 Python 3.12 기준. Microsoft Store Python은 %APPDATA% 가상화 이슈로 권장하지 않는다.

저장소 클론:

git clone https://github.com/v0o0v/assetcache-mcp.git

cd assetcache-mcp

venv는 작업 폴더 바깥(사용자 홈)에 만든다.

python -m venv $env:USERPROFILE\.venvs\gah

& "$env:USERPROFILE\.venvs\gah\Scripts\Activate.ps1"

editable 설치:

pip install -e .[dev]

테스트:

pytest -q

→ main 기준 1252 passed, 1 skipped, 53 deselected (M11 v0.2.0 baseline). M11.1 PR 머지 후 1426 passed, 1 skipped, 56 deselected 로 갱신.

실행

python -m assetcache --tray

→ 시스템 트레이에 아이콘이 뜨고, 기본 브라우저에서 http://127.0.0.1:9874/library 가 자동으로 열린다. 트레이 우클릭 → 종료.

브라우저가 자동으로 열리지 않으면 트레이 아이콘 우클릭 → 메인 창 열기.

웹 UI 주요 페이지

URL	설명
http://127.0.0.1:9874/library	에셋 검색 · 결과 · 사이드 패널 (기본 진입점)
http://127.0.0.1:9874/packs	등록된 팩 관리
http://127.0.0.1:9874/labels/admin	라벨 어휘 관리 (24 axis)
http://127.0.0.1:9874/analyzing	분석 진행 상황 — interactive 큐 + batch jobs + 최근 실패 (5초 자동 새로고침)
http://127.0.0.1:9874/settings	백엔드 설정 + chain 우선순위 + Batch 정책 (threshold/toggle/polling interval)

포트 9874가 점유된 경우 9875~9883 사이에서 자동으로 빈 포트를 선택한다.

MCP 서버 모드:

python -m assetcache --mcp

버전 확인:

python -m assetcache --version

Claude Desktop 연동

Claude Desktop 의 설정 파일 (%APPDATA%\Claude\claude_desktop_config.json) 에 다음 추가:

{
  "mcpServers": {
    "assetcache": {
      "command": "python",
      "args": ["-m", "assetcache", "--mcp"]
    }
  }
}

PyPI 설치 환경에서는 python -m assetcache --mcp 대신 콘솔 스크립트 "command": "assetcache-mcp" 도 사용 가능.

런타임 데이터 위치

Windows 기준 (Mac/Linux 는 platformdirs 가 OS 별 표준 경로 반환):

• %APPDATA%\AssetCacheMCP\library\ — 에셋 팩(사용자가 직접 드롭)
• %APPDATA%\AssetCacheMCP\cache\ — 썸네일·스펙트로그램
• %APPDATA%\AssetCacheMCP\metadata.db — SQLite (M1부터)
• %APPDATA%\AssetCacheMCP\config.toml
• %APPDATA%\AssetCacheMCP\logs\assetcache.log

문서 맵

문서	누가 보는가
README.md	처음 들어오는 사람
docs/WEB_UI_GUIDE.md	웹 UI 사용자 — 라이브러리/팩/라벨/pick 카드 사용법
docs/MCP_USAGE_GUIDE.md	Claude Code — MCP 20 도구 사용 예시
CLAUDE.md	Claude(코드 에이전트)가 작업 시작할 때
HANDOFF.md	다음 세션으로 인계할 때의 현재 스냅샷
DESIGN.md	아키텍처·MCP 도구·데이터 스키마
milestones/	마일스톤별 plan·todo·verification

개발 규칙

• 모든 문서는 한글, 폴더·파일 이름은 영어
• 마일스톤마다 plan → todo → 테스트 먼저 → 구현 → verification 순서
• 최신 모델·API·버전은 추측 말고 1차 출처 확인 후 반영
• 자세한 건 CLAUDE.md §4

Batch 분석 (v0.2.1)

대량 에셋 드롭 시 Gemini Batch API 를 활용해 50% 비용 절감 + 24시간 이내 결과 반환 (24h SLO).

동작 방식

• 1장 드롭 → interactive (즉시 분석, Ollama/Gemini realtime)
• 30장 이상 동시 드롭 + Gemini chain 활성 → Gemini Batch API 자동 진입
• /analyzing 페이지에서 진행 상황 확인 (5초 자동 새로고침)
• batch 완료 시 결과 자동 반영 → 에셋 카드에 라벨 표시

사용 방법

1. /settings → Gemini backend 활성화 + API key 입력 + Save
2. /settings → image chain 1순위를 Gemini 로 설정 + Save
3. /settings → Batch 패널: threshold / toggle / polling interval 조정 (기본값 OK)
4. library/ 에 에셋 팩(30개 이상) 드롭
5. /analyzing 에서 batch jobs 진행 확인

사용자 설정

설정	기본값	설명
threshold	30	batch 자동 진입 최소 에셋 수
toggle	auto	auto / forced_on (강제 batch) / forced_off (강제 interactive)
polling_interval	30분	batch job 상태 확인 주기

tray 아이콘 우클릭 → Batch: auto/forced_on/forced_off 메뉴로 빠르게 전환 가능.

배포 — 단일 exe 빌드 (참고용)

PyPI 가 1차 배포 채널이지만, 폐쇄망 등 PyPI 가 닿지 않는 환경용으로 단일 .exe 빌드 가이드를 유지한다 (현재 GitHub release 에는 첨부하지 않음).

# 1. dev 의존성 설치 (Babel, pyinstaller 포함)
pip install -e .[dev]

# 2. 번역 카탈로그 컴파일 (.po → .mo)
pybabel compile -d src/assetcache/web/locale

# 3. 트레이 아이콘 ICO 생성 (런타임 QPixmap → assets/tray.ico)
python scripts/generate_tray_ico.py

# 4. exe 빌드 (10분 내외, dist/AssetCacheMCP.exe ≈ 308 MB)
pyinstaller assetcache.spec

빌드된 exe 는 단일 파일로 배포 가능. 첫 실행 시 CLIP 모델 가중치 (~600 MB) 가 %APPDATA%\AssetCacheMCP\cache\clip\ 로 자동 다운로드된다.

배포 — PyPI publish 자동화

git tag vX.Y.Z ; git push origin vX.Y.Z 로 자동 publish 되도록 GitHub Actions workflow (.github/workflows/publish.yml) 가 구성되어 있다.

인증 방식 — Trusted Publishing (OIDC):

• API token 없이 GitHub OIDC 만으로 PyPI 인증. 평문 secret 노출 위험 없음
• 사전 셋업: https://pypi.org/manage/account/publishing/ 에서 trusted publisher 등록:
  • PyPI Project Name: assetcache-mcp
  • Owner: v0o0v, Repository name: assetcache-mcp, Workflow name: publish.yml
• workflow 의 permissions.id-token: write 가 OIDC 토큰 발행 권한 부여
• v0.1.0 은 첫 publish (TestPyPI → 정식 PyPI 순) 수동 수행 완료, 이후 모든 tag push 가 자동
• skip-existing: true 설정으로 같은 version 재업로드 시 silent skip (workflow 재실행해도 안전)

수동 빌드 + 업로드 흐름 (참고):

# 1. 빌드 (dist/assetcache_mcp-*.whl + .tar.gz 생성)
python -m build

# 2. TestPyPI 업로드 (선택)
python -m twine upload --repository testpypi dist/*

# 3. 정식 PyPI 업로드
python -m twine upload dist/*

번역 추가

신규 언어 추가 시:

# 1. 소스에서 msgid 추출
pybabel extract -F babel.cfg -k _ -k _t -o src/assetcache/web/locale/messages.pot .

# 2. 새 언어 카탈로그 생성 (예: 일본어)
pybabel init -i src/assetcache/web/locale/messages.pot -d src/assetcache/web/locale -l ja

3. src/assetcache/web/locale/ja/LC_MESSAGES/messages.po 의 msgstr 채우기

# 4. 컴파일
pybabel compile -d src/assetcache/web/locale

추가로 src/assetcache/web/i18n.py 의 SUPPORTED_LOCALES 튜플 (locale_middleware.py 가 같은 값을 alias import) 과 Config 의 _VALID_UI_LANGUAGES 에 새 언어 코드를 추가.

라이선스

MIT (변경될 수 있음).