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.

주요 기능

진행 현황

마일스톤 사이클(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 주요 페이지

포트 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

문서 맵

개발 규칙

• 모든 문서는 한글, 폴더·파일 이름은 영어
• 마일스톤마다 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 진행 확인

사용자 설정

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

1. 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 (변경될 수 있음).