# BuyKing MCP Server

*Read this in other languages: [English](README-en.md), [日本語](README-ja.md), [한국어](README.md)*

세일프라자(Saleplaza)의 쇼핑 지배자, 사자왕 Bㅏ이킹 페르소나를 제공하는 MCP(Model Context Protocol) 서버입니다.

> 크하하! 짐은 세일프라자의 쇼핑 지배자, 사자왕 Bㅏ이킹이다! 네 녀석이 원하는 최고의 핫딜을 찾아주마!

[![Glama.ai BuyKing MCP Server Badge](https://images.saleplaza.com/img-assets/glama-card-badge.png)](https://glama.ai/mcp/servers/accentist/buyking-mcp/score)

> 🏆 **Glama.ai 공식 MCP Registry 인증**
> License, Quality, Maintenance 3개 전 부문에서 **최고 등급(Triple A)**을 획득한 검증된 MCP 서버입니다!

## 🚀 기능

### ✨ [v1.2.1 신규] 강력해진 다국어 글로벌 검색
이제 언어의 장벽 없이 전 세계의 쇼핑 핫딜을 가장 스마트하게 찾아냅니다!
- **대규모 다국어 사전 탑재**: 1,000개 이상의 핵심 쇼핑 키워드(영어, 일본어 ↔ 한국어) 해시맵을 통해, AI의 오역(예: mouse를 쥐로 번역) 없이 정확하고 초고속으로 전 세계 상품을 매칭합니다.
- **입력 언어별 국가 최우선 정렬 (Smart Priority)**: 사용자가 입력한 언어(영어, 일본어, 한국어)를 0.1초 만에 자동 감지하여, 해당 국가의 통화(USD, JPY, KRW)를 사용하는 핫딜 상품을 1순위로 상단에 노출합니다. (예: 영문으로 `apple` 검색 시 🇺🇸US 상품 최우선 출력!)

### 제공하는 도구 (Tools) — 5개

#### 🌍 글로벌 검색
- **`search_buyking_semantic`**: 전 세계 핫딜을 국경 없이 시맨틱 검색합니다. 각 상품 앞에 배송 국가코드(🇰🇷KR/🇺🇸US/🇯🇵JP)가 표기됩니다.

#### 🇰🇷 한국 전용
- **`search_buyking_semantic_KR`**: 한국 내 직배송 가능한 핫딜만 검색합니다. KRW(₩) 가격, 한국어 결과.

#### 🇺🇸 미국 전용
- **`search_buyking_semantic_US`**: US-deliverable hot deals only. USD($) pricing, English results.

#### 🇯🇵 일본 전용
- **`search_buyking_semantic_JP`**: 日本国内配送可能なホットディールのみ検索。JPY(¥)価格、日本語結果。

#### ℹ️ 서버 정보
- **`get_server_info`**: BuyKing MCP 서버의 버전 정보와 기능 목록을 반환합니다.

### 공통 파라미터

모든 검색 도구는 동일한 파라미터를 지원합니다:

| 파라미터 | 타입 | 필수 | 설명 | 예시 |
|---------|------|------|------|------|
| `keyword` | string | ✅ | 검색할 상품명 키워드 | "무소음 마우스", "wireless earbuds" |
| `category` | string | ❌ | 카테고리 필터 | "💻 IT/가전/디지털", "👚 패션/뷰티/잡화" |
| `platform` | string | ❌ | 플랫폼 필터 | "coupang", "11st", "gmarket", "aliexpress" |
| `sort` | string | ❌ | 정렬 조건 | "newest", "price_asc", "price_desc", "click_desc" |

### 서버 엔드포인트

- **HTTP JSON-RPC**: `https://buyking.saleplaza.com/message`
- **MCP Discovery**: `https://buyking.saleplaza.com/.well-known/mcp.json`
- **LLMs.txt**: `https://buyking.saleplaza.com/llms.txt`

## 📦 설치

```bash
npm install buyking-mcp
```

## 🔧 설정

### Claude Desktop에서 사용하기

Claude Desktop의 설정 파일에 다음을 추가하세요:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "buyking-mcp": {
      "command": "npx",
      "args": ["-y", "buyking-mcp@latest"]
    }
  }
}
```

> 💡 **팁**: `@latest` 태그를 사용하면 항상 최신 버전이 설치되어 캐시 문제를 방지할 수 있습니다.

## 🎯 사용 예시

### 글로벌 검색 (GLOBAL)

```
"가성비 무소음 마우스 찾아줘" → search_buyking_semantic
"Find me the best wireless earbuds" → search_buyking_semantic
```

### 한국 배송 검색 (KR)

```
"한국 배송 가능한 제로 콜라 최저가" → search_buyking_semantic_KR
"쿠팡에서 여름 이불 추천해줘" → search_buyking_semantic_KR
```

### 미국 배송 검색 (US)

```
"Best deals on mechanical keyboards in the US" → search_buyking_semantic_US
"Amazon US wireless mouse deals" → search_buyking_semantic_US
```

### 일본 배송 검색 (JP)

```
"日本で買えるワイヤレスマウスのお得情報" → search_buyking_semantic_JP
"Amazon JP おすすめキーボード" → search_buyking_semantic_JP
```

## 🔌 API 직접 호출

### HTTP JSON-RPC 예시

```bash
# 글로벌 검색
curl -X POST https://buyking.saleplaza.com/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_buyking_semantic",
      "arguments": {
        "keyword": "무소음 마우스"
      }
    }
  }'

# 미국 전용 검색
curl -X POST https://buyking.saleplaza.com/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_buyking_semantic_US",
      "arguments": {
        "keyword": "wireless mouse"
      }
    }
  }'
```

**카테고리 허용값:**
- `all` - 전체
- `💻 IT/가전/디지털`
- `👚 패션/뷰티/잡화`
- `🍎 식품/생활/리빙`
- `📚 도서/여행/취미`
- `🛒 종합몰/기획전`
- `📦 기타`

**플랫폼 허용값:**
- `all_rank` - 전체
- `coupang` - 쿠팡
- `11st` - 11번가
- `gmarket` - G마켓
- `auction` - 옥션
- `aliexpress` - 알리익스프레스

## 📸 실제 사용 예시

### LMStudio에서의 사용 예시

![LMStudio에서 BuyKing MCP를 활용한 마우스 검색 예시](https://images.saleplaza.com/img-assets/buyking-using-llm.png)

*LMStudio에서 BuyKing MCP를 활용하여 "마우스"를 검색한 결과입니다. AI가 자동으로 최적의 핫딜을 찾아 추천해주는 것을 확인할 수 있습니다.*

## 🏗️ 개발

### 의존성

- Node.js
- TypeScript
- @modelcontextprotocol/sdk

### 빌드

```bash
npm run build
```

### 로컬 테스트

```bash
npm run dev
```

### Cloudflare Workers 배포

```bash
npm run deploy
```

## 📝 라이선스

ISC

## 🤝 기여

이 프로젝트는 Saleplaza 팀에서 관리합니다. 버그 리포트나 기능 요청은 이슈를 통해 제출해 주세요.

## 🌐 관련 링크

- [세일프라자](https://saleplaza.com)
- [MCP Install Guide](https://saleplaza.com/mcp)
- [MCP Registry](https://registry.modelcontextprotocol.io)
- [MCP 공식 문서](https://modelcontextprotocol.io)

## 📋 MCP Registry

BuyKing MCP Server는 공식 MCP Registry에 등록되어 있습니다.

### Registry 정보
- **서버 이름**: `io.github.accentist/buyking-mcp`
- **버전**: 1.2.1
- **레지스트리**: [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)

### Registry에서 검색
```bash
# API로 서버 정보 조회
curl "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.accentist%2Fbuyking-mcp/versions/latest"

# 웹에서 검색
https://registry.modelcontextprotocol.io/?q=buyking-mcp
```

---

> 크하하! 짐의 보물창고에서 최고의 전리품을 찾아가라!