shopby-mcp — 샵바이 API 문서 검색 MCP

샵바이(Shopby) 공식 문서는 검색 기능이 없어서 "이 API 어디 있지?", "이 필터 적용돼?"를 매번 직접 찾아야 한다. 이 도구는 샵바이의 OpenAPI(YAML) 스펙을 통째로 인덱싱해서 Claude에게 자연어로 물어보면 찾아주게 한다.

• 검색은 안 되지만 데이터는 완벽히 구조화돼 있다 (OpenAPI 3.0). LLM을 새로 만들 필요 없이 스펙을 파싱해서 인덱싱하면 끝.

• 쓰는 방법 두 가지: ① MCP 서버로 Claude(Code/Desktop)에 붙이기, ② 터미널 CLI.

• 원격 인덱스(config.json)+yml을 조건부로 점검해 자동 최신화한다. 단 스펙은 월 단위로 바뀌므로 기본 하루 1회만 점검(아래 참고).

⚠️ 비공식(Unofficial) 도구. NHN커머스/샵바이 공식 제품이 아니다. 공식 클라이언트 SDK는 @shopby/shop-sdk(API 호출용)이고, 이 패키지는 그와 별개로 문서 검색/탐색을 돕는다 — 둘은 역할이 다르며 함께 쓰면 좋다.

구성

shopby-api-bot/
├─ cache-paths.mjs      # 캐시/번들 경로·호스트 매핑 (공유)
├─ specs-index.json     # 카테고리 인덱스 — 오프라인/첫실행용 번들 폴백(원본은 원격 config.json)
├─ download-specs.mjs   # 인덱스+yml 조건부 최신화 (refreshAll) + CLI 진입점
├─ shopby-index.mjs     # 핵심: yml 로드 + 평탄화 + 검색 + $ref 해석
├─ shopby-cli.mjs       # 터미널 검색/상세조회
├─ shopby-mcp.mjs       # MCP 서버 (Claude 연동, 시작 시 자동 최신화)
├─ spec/                # 번들 폴백 seed (*.yml) — 런타임 캐시는 ~/.cache/shopby-mcp/
└─ (런타임) ~/.cache/shopby-mcp/{spec/*.yml, specs-index.json, .etags.json}

Related MCP server: Apidog MCP Server

설치 — Claude Code (권장: npx, 클론 불필요)

claude mcp add shopby-docs -- npx -y shopby-mcp

끝. npx가 패키지를 받아 실행하고, 서버가 첫 실행 시 스펙을 ~/.cache/shopby-mcp/로 자동 다운로드한다. 이후 Claude에게 그냥 물어보면 된다:

• "샵바이 장바구니 리스트 api 찾아줘"

• "브랜드 리스트 api에 필터 뭐 있어?"

• "주문 취소 관련 api 다 보여줘"

Claude가 search_apis → get_api_detail 툴을 알아서 호출해서 답한다.

팀 공유: 저장소 루트에 .mcp.json을 두면 팀원이 클론만 해도 동일 설정이 잡힌다.

{ "mcpServers": { "shopby-docs": { "command": "npx", "args": ["-y", "shopby-mcp"] } } }

설치 — Claude Desktop

claude_desktop_config.json의 mcpServers에 추가:

{
  "mcpServers": {
    "shopby-docs": { "command": "npx", "args": ["-y", "shopby-mcp"] }
  }
}

CLI로도 쓰기 (Claude 없이 터미널에서)

npx -p shopby-mcp shopby-cli "장바구니 리스트"     # API 검색
npx -p shopby-mcp shopby-cli --detail get-cart    # 특정 API 상세

# 자주 쓰면 전역 설치:
npm i -g shopby-mcp
shopby-cli "브랜드 목록 필터"

상세조회(--detail <operationId>)는 필터(쿼리 파라미터)의 이름·타입·필수여부·enum·설명까지 보여준다. (첫 실행 시 캐시가 비어 있으면 스펙을 자동으로 받아온다.)

로컬 개발 (소스에서 직접)

npm install
node shopby-cli.mjs "장바구니 리스트"
claude mcp add shopby-docs-dev -- node "$(pwd)/shopby-mcp.mjs"

Claude Desktop 연동

claude_desktop_config.json의 mcpServers에 위 JSON과 동일하게 추가.

노출되는 MCP 툴

필드 기반 검색

응답/요청 바디의 필드명·필드설명까지 색인하므로 **"특정 필드가 들어있는 API 찾기"**가 된다:

• "회원 등급(couponAutoSupplying/적립률) 정보 들어있는 API" → 회원등급 API를 잡아냄

• "슬러그 필드 쓰는 응답 어디야" → 필드명으로 후보가 좁혀짐

정밀하게는 실제 필드명(camelCase)으로, 막연하면 한국어 필드설명으로 검색하면 된다.

동작 원리 (요약)

1. spec/*.yml 을 전부 파싱 → 오퍼레이션 1개 = 레코드 1개로 평탄화. 각 레코드에 method·path·operationId·tags·summary·description·parameters(필터)·응답/요청 필드명 포함.

2. 검색은 한국어 summary/태그설명/operationId/path/파라미터/스키마 필드명을 가중치로 스코어링하는 키워드 매칭. 샵바이 스펙의 summary·description이 한국어라서 "장바구니" 같은 한국어 질의가 그대로 먹힌다. (가중치: summary·태그설명 5 > operationId 4 > path·태그 3 > description·필드명 2 > 파라미터 1)

3. 검색·상세조회 모두 $ref(#/components/schemas/...)를 재귀적으로 해석한다. 상세조회는 응답 구조까지 펼쳐 보여주고, 색인은 필드명을 평탄화해 담는다.

자동 최신화 (스펙 갱신 대응)

샵바이는 매달/상시로 API를 업데이트한다. 인덱스(config.json)와 yml URL은 항상 최신본을 서빙하고 서버가 ETag/Last-Modified를 주므로, MCP 서버는 시작할 때 자동으로 최신 여부를 점검한다.

시작 시퀀스:

1. 인덱스 갱신 — https://docs.shopby.co.kr/config.json 을 조건부로 받아 최신 파일 목록 확보

2. yml 갱신 — 그 최신 인덱스 기준으로 각 yml 을 조건부로 점검 → 바뀐 파일만 받음

3. 캐시의 yml 로 검색 인덱스 빌드 → MCP 서버 기동

• MCP는 세션마다 새로 켜지므로, 새 Claude 세션을 열면 자동 반영된다(실행 중 세션 도중엔 안 바뀜).

• 새 모듈(새 yml 파일) 추가도 자동 발견된다 — 인덱스를 함께 갱신하므로 새 파일명이 생기면 그 yml까지 자동으로 받는다.

• 대부분 304라 빠르다. 변경/신규/실패 내역은 stderr에 로그된다.

• 오프라인/장애 시엔 캐시 → (캐시도 없으면) 패키지 동봉 seed 로 조용히 폴백한다.

점검 주기(TTL): 샵바이 스펙은 보통 몇 주~한 달 간격으로 바뀌므로, 세션마다 네트워크 점검하는 건 낭비다. 그래서 기본 TTL이 24시간이다 — 마지막 점검이 24h 안이면 네트워크 0회로 즉시 시작하고, 24h이 지났을 때만 한 번 조건부 점검한다. "지금 당장 최신"이 필요하면 --refresh(또는 SHOPBY_MCP_MAX_AGE=0)로 강제, 더 늦춰도 되면 SHOPBY_MCP_MAX_AGE=604800(7일) 식으로 키우면 된다.

캐시 위치: ~/.cache/shopby-mcp/ (spec/*.yml, specs-index.json, ETag 저장 .etags.json). 패키지 디렉터리가 아니라 사용자 캐시에 두어 npx/전역 설치(읽기전용)에서도 동작한다.

플래그 / 환경변수:

수동 갱신도 가능: npm run download (인덱스+yml 조건부 점검).

ℹ️ admin/internal 영역은 의도적으로 제외한다(관리자/내부용이라 봇 대상이 아님). 인덱스에는 들어 있어도 cache-paths.mjs 의 HOST_BY_CATEGORY 에 호스트가 없어 받지 않는다. 즉 shop+server만 인덱싱.

확장 아이디어

• 의미 검색: 키워드로 부족하면 각 오퍼레이션 요약을 임베딩해 벡터검색 추가(코퍼스가 작아 굳이 없어도 잘 된다).

• 사내 슬랙봇: shopby-index.mjs의 search/getApi를 그대로 import 해서 슬랙 슬래시커맨드로 노출.