@style-room/mcp

Model Context Protocol 서버 — Claude / Cursor / VS Code / Claude Code 등 모든 MCP client 에서 자연어로 style-room 의 AI 패션 플랫폼을 조작.

버전: v1.0.0 · 22 tools · 5 MCP Apps UI iframes · npm public · Node 16+

핵심 흐름 두 가지:

1. 스타일샷 만들기 — 저장된 피팅샷 + 배경 → AI 합성 사진
2. 뮤직 클립 만들기 — 사진 10~30장 → BGM 입힌 짧은 영상

그 외 도구는 모두 읽기/보조 — 카탈로그 탐색 (배경 / 테마 / 포즈), 내 갤러리 조회, 크레딧 잔액, 작업 폴링, 미디어 업로드.

사전 조건 (Prerequisites)

• Node.js 16 이상 (node -v 로 확인 — 16/18/20/22 모두 OK)
• MCP client 중 하나: Claude Desktop / Claude Code / Cursor / VS Code / Windsurf / Cline / Goose / Kiro / Codex / Copilot CLI
• STYLE_ROOM_API_KEY — style-room.ai 마이페이지에서 발급 (sr_... prefix)

설치 (Installation)

Standard config — 모든 client 공통

{
  "mcpServers": {
    "style-room": {
      "command": "npx",
      "args": ["-y", "@style-room/mcp@latest"],
      "env": {
        "STYLE_ROOM_API_KEY": "<여기에_본인_API_key>"
      }
    }
  }
}

각 client 별로 위 config 를 어디에 넣는지만 다름. 아래 참고:

Claude Desktop

config 파일 위치 (OS 별):

| OS | 경로 | |---|---| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

위 파일 열고 mcpServers 안에 standard config 병합 (파일 없으면 새로 만들기) → Cmd+Q (또는 Alt+F4) 종료 후 재시작.

Claude Code

# 사용자 단위 등록
claude mcp add style-room -e STYLE_ROOM_API_KEY=<your_key> -- npx -y @style-room/mcp@latest

# 또는 프로젝트 공유 (.mcp.json 생성, git commit 가능)
claude mcp add style-room -s project -e STYLE_ROOM_API_KEY=<your_key> -- npx -y @style-room/mcp@latest

⚠️ 옵션 순서 중요: <name> (style-room) 을 -e 보다 먼저, 그리고 npx 명령 앞에 -- 로 separator (claude 가 -y 를 가로채지 않도록).

Cursor

• Cursor Settings → MCP → Add new MCP Server → command type → npx -y @style-room/mcp@latest
• 또는 ~/.cursor/mcp.json 에 standard config 직접 병합

VS Code

code --add-mcp '{"name":"style-room","command":"npx","args":["-y","@style-room/mcp@latest"],"env":{"STYLE_ROOM_API_KEY":"<your_key>"}}'

Windsurf / Cline / Goose / Kiro / Codex / Copilot CLI 등

Standard config 그대로 각 client 의 mcpServers 자리에 병합. 위치는 client 별 docs 참고. 모든 표준 MCP client 에서 작동.

🤖 LLM 한테 자동 설치 시키기 (Cowork / Claude Code / Cursor / Codex 등)

답변 본문에 fs/bash 도구가 있는 agent 에게 한 줄 prompt 로 끝:

아래 prompt 를 그대로 던지면 끝 (외부 fetch 없이 self-contained):

@style-room/mcp (npm public 패키지) 를 내 MCP client 에 설치해줘.

설치 방법:
1. Node.js 16+ 설치 확인 (없으면 안내)
2. Claude Desktop 의 claude_desktop_config.json 의 mcpServers 에 아래 블록 병합:
   {
     "style-room": {
       "command": "npx",
       "args": ["-y", "@style-room/mcp@latest"],
       "env": { "STYLE_ROOM_API_KEY": "<여기에_본인_key>" }
     }
   }
   - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   - Windows: %APPDATA%\Claude\claude_desktop_config.json
   - Linux: ~/.config/Claude/claude_desktop_config.json
3. API key 는 내가 줄게 — 'STYLE_ROOM_API_KEY 값 알려줘' 물어보면 멈추고 기다려.
4. Cmd+Q 종료 후 재시작 안내.

다른 client 면:
- Claude Code:  claude mcp add style-room -e STYLE_ROOM_API_KEY=<key> -- npx -y @style-room/mcp@latest
- Claude Code (프로젝트 공유 .mcp.json):  claude mcp add style-room -s project -e STYLE_ROOM_API_KEY=<key> -- npx -y @style-room/mcp@latest
- Cursor:       Settings → MCP → Add new MCP Server → command: npx -y @style-room/mcp@latest
- VS Code:      code --add-mcp '{"name":"style-room","command":"npx","args":["-y","@style-room/mcp@latest"],"env":{"STYLE_ROOM_API_KEY":"<key>"}}'
- 그 외:        standard config 를 client 의 mcpServers 자리에 병합

→ LLM 이 npm 페이지 / GitHub repo fetch 없이 위 정보만으로 install 진행. 사용자는 API key 값만 직접 제공.

동작 확인

설치 + 재시작 후 대화창에:

get_capabilities 호출해서 지금 몇 개 툴 로드됐는지 알려줘

→ toolCount: 22, authenticated: true 면 성공.

안 되면 §트러블슈팅 참고.

업데이트

새 버전 publish 시 client 만 재시작 — npx 가 자동으로 latest fetch. 캐시 꼬이면:

npm cache clean --force

✨ 뭐가 되나요

1. 자연어로 카탈로그 탐색

👤 "모던&미니멀 느낌 배경 5개 보여줘"
🤖 [답변 본문에 3:4 배경 카드 그리드 iframe]
   → 카드 다중 선택 → 하단 큰 버튼 "5개 배경 선택" → 클릭 시 입력창에
     "배경 1, 2, 3, 4, 5 에 스타일샷을 요청합니다" 자동 채움

2. 저장된 피팅샷 → 스타일샷

👤 "내 저장된 피팅샷 보여줘"
🤖 [9:16 피팅샷 갤러리]
   → 카드 클릭 → "피팅샷 82567 로 스타일샷 만들고 싶어요" 자동 input
🤖 "어떤 배경으로?"  → 배경 갤러리 추가 흐름 → 합성 → 결과 갤러리

3. 뮤직 클립 (릴스) — 통합 composer iframe

👤 "뮤직 클립 만들어줘"
🤖 [composer iframe — 갤러리 multi-select + drag-drop 업로드 통합]
   → 갤러리 N장 + 내 PC 미디어 M장 (10≤N+M≤30) 선택
   → [뮤직 클립 생성] 클릭
   → server jobCode 받아 입력창에 polling prompt 자동 채움
   → 사용자 send → LLM 이 5초 폴링 → completed 시 영상 링크

📚 툴 목록 (22개)

| 분류 | 도구 | |---|---| | 배경 | list_backgrounds_for_user ★ UI · recommended_backgrounds | | 합성 요청 | list_my_synthesis_requests · get_synthesis_request_status | | 빌링 | get_my_credits · list_plans | | 스타일샷 | list_saved_garments · estimate_style_shot_credits · list_background_tags · create_style_shot_from_saved_garment ⚠️ · fetch_saved_garment_thumbnails ★ UI · fetch_synthesis_result_thumbnails ★ UI | | 릴스 (뮤직 클립) | list_my_style_shots_for_reels · estimate_reel_credits · fetch_reel_source_thumbnails ★ UI · create_reel ⚠️ · list_my_reels · get_reel_status | | 업로드 + Composer | upload_user_media · open_reel_composer 🎬 ★ UI | | 유틸 | health_check · get_capabilities |

★ = 답변 본문에 iframe 갤러리 자동 렌더 (MCP Apps extension). ⚠️ = 크레딧 차감. 🎬 = v1.5 메인 흐름 통합 iframe.

⚠️ 크레딧 사용 툴 주의

create_style_shot_from_saved_garment — 호출 즉시 크레딧 차감 + 비동기 합성 잡 큐잉.

• 재시도 절대 금지 (NFR-9): 5xx 받아도 재시도하면 이중 차감
• expectedCredits 는 반드시 estimate_style_shot_credits 결과 그대로 (서버 strict equality)
• 권장 5장 — 5장까지 base 6 credits, 5장 초과부터 +1/장
• API key 는 발급된 사용자 권한 그대로 — 공유 Mac 에서 실행 금지

create_reel — 호출 즉시 1 크레딧 차감 + 비동기 잡 큐잉.

• 재시도 절대 금지 (NFR-9): 5xx 시 잡 큐잉됐을 가능성 → 5분 뒤 list_my_reels 로 확인 후 재호출
• BGM 은 server-random
• sources 는 10~30장 (server 강제), 1 크레딧 고정

🧯 트러블슈팅

| 증상 | 조치 | |---|---| | MCP server 가 client 목록에 없음 | config 의 JSON 문법 오류 / 재시작 (Cmd+Q 후) 안 함 | | get_capabilities 의 authenticated: false | STYLE_ROOM_API_KEY 미설정 / 오탈자 | | auth-required 툴이 401 | API key 만료 또는 권한 — 어드민에서 재발급 | | create_style_shot_from_saved_garment 의 400 "Credit mismatch" | 반드시 estimate_style_shot_credits 결과 그대로 expectedCredits 전달 | | composer 업로드 카드가 빨간 (failed) | API base 와 client config 의 STYLE_ROOM_API_BASE 가 일치하는지 확인. 동적 CSP 가 그 도메인만 허용 | | 배경 썸네일이 엑박 | client 버전 오래됨 — 업데이트 | | 업데이트했는데 여전히 구 버전 | npm cache clean --force → 재시작 |

로그 (Claude Desktop): ~/Library/Logs/Claude/mcp-server-style-room.log

🚧 제약 / 알려진 이슈

• iframe 갤러리는 Claude Desktop 의 MCP Apps extension 지원 client 에서만 정상 렌더. 다른 client 는 type:"image" content block fallback
• multipart 업로드 (POST /ai-studio/upload/single-file) 의 10MB cap — 사이트 정책 동일
• 배경 갤러리 다중 선택 후 input 발동은 LLM 응답 자동 — Cowork mode / Claude Code 가 가장 자연스러움

라이선스

MIT