# shopee-mcp

MCP-сервер для поиска товаров на Shopee (Сингапур / Индонезия) и получения
affiliate-ссылок через официальный [Shopee Affiliate Open API](https://open-api.affiliate.shopee.com/).

---

## Инструменты (tools)

### `shopee_search_products`

Поиск товаров по ключевому слову в каталоге Shopee.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `keyword` | string | — | Поисковый запрос, напр. `"wireless earbuds"` |
| `country` | `"SG"` / `"ID"` | `"SG"` | Маркетплейс: Сингапур или Индонезия |
| `page` | int 1–100 | `1` | Номер страницы |
| `limit` | int 1–50 | `20` | Результатов на странице |
| `sort_type` | int 1–5 | `2` | Сортировка (см. ниже) |
| `response_format` | `"markdown"` / `"json"` | `"markdown"` | Формат ответа |

**`sort_type`:**
- `1` — по релевантности / новинки
- `2` — по продажам (убывание)
- `3` — по цене (возрастание)
- `4` — по цене (убывание)
- `5` — по ставке комиссии (убывание)

**Ответ (`markdown`)** — карточки товаров: название, картинка, цена, скидка, рейтинг, число продаж, магазин, ссылка.

**Ответ (`json`):**
```json
{
  "keyword": "wireless earbuds",
  "count": 20,
  "page_info": { "page": 1, "limit": 20, "hasNextPage": true },
  "products": [
    {
      "itemId": 123456,
      "productName": "Earbuds Pro X",
      "productLink": "https://shopee.sg/product/123456",
      "offerLink": "https://shope.ee/affiliate-link",
      "imageUrl": "https://...",
      "priceMin": 29.9,
      "priceMax": 39.9,
      "priceDiscountRate": 15,
      "sales": 4821,
      "ratingStar": 4.8,
      "commissionRate": "0.03",
      "shopId": 200001,
      "shopName": "TechStore SG"
    }
  ]
}
```

---

### `shopee_get_buy_link`

Генерирует трекаемую affiliate-ссылку для конкретного товара.
Покупку пользователь совершает **сам**, открыв ссылку — сервер ничего не заказывает и не оплачивает.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `product_url` | string | — | URL товара Shopee (из `productLink` результатов поиска или любой `shopee.sg` / `shopee.co.id` ссылки) |
| `country` | `"SG"` / `"ID"` | `"SG"` | Маркетплейс, которому принадлежит ссылка |
| `sub_ids` | list[string] | `[]` | До 5 произвольных меток для трекинга конверсий |
| `response_format` | `"markdown"` / `"json"` | `"markdown"` | Формат ответа |

**Ответ (`json`):**
```json
{
  "origin_url": "https://shopee.sg/product/123456",
  "short_link": "https://shope.ee/abc123"
}
```

---

## Mock-режим

Если переменные `SHOPEE_APP_ID` / `SHOPEE_APP_SECRET` не заданы, сервер
**автоматически** возвращает детерминированные тестовые данные.
В markdown-ответе появится предупреждение `⚠️ Mock data`, в JSON — поле `"note"`.

Это позволяет разрабатывать и тестировать сервер без реального доступа к API.

---

## Установка

```bash
git clone https://github.com/TatarchenkovAndrey/shopee-mcp
cd shopee-mcp
python3 -m venv venv
./venv/bin/pip install -e .
cp .env.example .env
```

Если есть ключи — впишите их в `.env`:

```
SHOPEE_APP_ID=your_app_id
SHOPEE_APP_SECRET=your_app_secret
```

---

## Получение ключей Shopee Affiliate API

1. Подайте заявку на партнёрской странице Shopee:
   - Сингапур: [affiliate.shopee.sg](https://affiliate.shopee.sg)
   - Индонезия: портал Shopee ID
   
   Заявки проверяются вручную — обычно 5–15 дней.

2. После одобрения откройте раздел **Open API** в личном кабинете партнёра и скопируйте **App ID** и **App Secret**.

3. Без ключей сервер работает в mock-режиме.

> ⚠️ Перед первым реальным вызовом сверьте точный домен эндпоинта и GraphQL-схему с документацией из личного кабинета — они могут незначительно отличаться по стране.

---

## Как устроена аутентификация

Каждый запрос к Shopee API подписывается по схеме:

```
signature = SHA256(appId + timestamp + payload + appSecret)
```

Заголовок запроса:
```
Authorization: SHA256 Credential=<appId>,Timestamp=<ts>,Signature=<sig>
```

Реализация: [`src/shopee_mcp/client.py`](src/shopee_mcp/client.py) — функция `_sign()`.

---

## Запуск и тест

```bash
# Прогнать оба инструмента на mock-данных
PYTHONPATH=src ./venv/bin/python smoke_test.py
```

---

## Добавление в Claude Code

### Локально (stdio)

```bash
claude mcp add shopee_mcp -- /полный/путь/к/venv/bin/python -m shopee_mcp.server
```

Claude Code запустит сервер как дочерний процесс. Работает только на вашей машине.

### Удалённо (Streamable HTTP)

Чтобы сервером мог пользоваться **любой** пользователь Claude Code:

1. Запустите сервер в HTTP-режиме:
   ```bash
   MCP_TRANSPORT=streamable-http PORT=8000 ./venv/bin/python -m shopee_mcp.server
   ```

2. Разверните за публичным HTTPS (Fly.io, Render, Railway, VPS + nginx/TLS).
   Для разработки — `ngrok http 8000`.

3. Пользователи подключают сервер командой:
   ```bash
   claude mcp add --transport http shopee_mcp https://your-domain/mcp
   ```

---

## Переменные окружения

| Переменная | По умолчанию | Описание |
|---|---|---|
| `SHOPEE_APP_ID` | — | App ID из Shopee Affiliate Open API |
| `SHOPEE_APP_SECRET` | — | App Secret из Shopee Affiliate Open API |
| `MCP_TRANSPORT` | `stdio` | `stdio` для локального запуска, `streamable-http` для удалённого |
| `PORT` | `8000` | Порт HTTP-сервера (только при `streamable-http`) |
| `MCP_HOST` | `127.0.0.1` | Адрес биндинга HTTP-сервера |

---

## Структура проекта

```
shopee-mcp/
├── pyproject.toml              # зависимости, точка входа
├── .env.example                # шаблон переменных окружения
├── smoke_test.py               # быстрый тест обоих инструментов
└── src/shopee_mcp/
    ├── __init__.py
    ├── client.py               # подпись запросов, GraphQL API, mock-данные
    ├── formatting.py           # форматирование ответов (markdown / json)
    └── server.py               # FastMCP сервер, Pydantic-схемы, регистрация tools
```

---

## Важно

Этот сервер **не выполняет покупки** и не вводит платёжные данные.
Он только ищет товары и генерирует affiliate-ссылку — оплату пользователь всегда совершает сам в браузере или приложении Shopee.