# korea-shopping-mcp

Claude Code 안에서 자연어로 한국 이커머스(네이버 쇼핑) 상품을 **검색·가격비교·트렌드 조회·로컬 저장**하게 해주는 MCP 서버입니다. 네이버 쇼핑 검색 API와 DataLab 쇼핑인사이트 API만 사용하는 **검색 전용** 서버로, 안전하고 빠릅니다(장바구니/결제·크롤링은 하지 않습니다).

## 제공 도구

| 도구 | 설명 |
| --- | --- |
| `search_products` | 키워드로 상품 검색. 정렬(연관도/최신/최저가/최고가), 가격대 필터, 중고·렌탈·해외직구 제외, 네이버페이 필터. |
| `compare_products` | 검색어 2~5개를 한 번에 비교(검색어별 최저가·가격대·대표 쇼핑몰). |
| `shopping_trends` | DataLab 쇼핑인사이트로 카테고리별 **상대 트렌드 추이**(0~100). ⚠️ 실시간 인기검색어 순위가 아님. |
| `save_results` | 직전(또는 지정) 검색/비교/트렌드 결과를 마크다운/JSON 파일로 저장(위시리스트). |

## 1. 네이버 API 키 발급 (필수)

각 사용자가 **본인 키**를 발급받아 사용합니다.

1. [네이버 개발자센터](https://developers.naver.com)에 로그인합니다.
2. **Application → 애플리케이션 등록**에서 새 앱을 만듭니다.
3. **사용 API**에 다음 두 가지를 모두 추가합니다:
   - **검색** (쇼핑 검색용)
   - **데이터랩(쇼핑인사이트)** (트렌드용)
4. 등록 후 발급되는 **Client ID**와 **Client Secret**을 복사합니다.

> 호출 한도: 검색 25,000회/일, 데이터랩 1,000회/일 (Client ID 기준).

## 2. 설치 (Claude Code)

발급받은 키를 `--env`로 주입해 등록합니다. 키는 본인 PC의 환경변수에만 저장되며 외부로 전송되지 않습니다.

```bash
claude mcp add --scope user \
  --env NAVER_CLIENT_ID=발급받은ID \
  --env NAVER_CLIENT_SECRET=발급받은SECRET \
  korea-shopping-mcp -- npx -y korea-shopping-mcp
```

등록 확인:

```bash
claude mcp list
# korea-shopping-mcp  ✓ Connected  이면 정상
```

## 3. 환경변수

| 변수 | 필수 | 설명 |
| --- | --- | --- |
| `NAVER_CLIENT_ID` | ✅ | 네이버 앱 Client ID |
| `NAVER_CLIENT_SECRET` | ✅ | 네이버 앱 Client Secret |
| `SHOPPING_MCP_OUTPUT_DIR` | ❌ | 저장 파일 위치. 기본값: `~/.korea-shopping-mcp/reports` |

## 4. 사용 예시 (자연어 프롬프트)

- "샤오미 보조배터리 최저가 5개 찾아줘"
- "로지텍 MX 마스터와 애플 매직마우스 가격 비교해줘"
- "10만원대 기계식 키보드만 보여줘" (가격대 필터)
- "최근 3개월 디지털/가전과 식품 카테고리 트렌드 보여줘"
- "방금 결과를 마크다운 파일로 저장해줘"

## 한계 (범위 밖)

- 장바구니 담기·결제 등 **구매 행동**은 하지 않습니다(검색·비교 전용).
- 쿠팡·G마켓·11번가 등 **네이버 외 플랫폼**은 공식 API 제약으로 미지원.
- 트렌드는 **상대 추이**일 뿐, "실시간 인기검색어 순위"가 아닙니다.

## 개발

```bash
npm install
npm test          # 단위 테스트 (vitest)
npm run build     # dist/ 생성
```

로컬에서 빌드 산출물로 직접 등록해 개발할 때:

```bash
claude mcp add --scope user \
  --env NAVER_CLIENT_ID=... --env NAVER_CLIENT_SECRET=... \
  korea-shopping-mcp -- node "<프로젝트 경로>/dist/index.js"
```

> stdio 서버이므로 코드에서 `console.log` 사용 금지(스트림 오염). 로깅은 `console.error`만.

## 라이선스

MIT