# kaspi-merchant-mcp

Первый MCP-сервер для Kaspi Marketplace в мире. 721 000 продавцов в Казахстане теперь могут управлять заказами через AI-ассистентов.

> **Kaspi.kz** — крупнейший маркетплейс Казахстана. API работает по спецификации JSON:API (`Content-Type: application/vnd.api+json`).

---

> [!WARNING]
> **Sandbox отсутствует** — все операции выполняются на **реальных данных продакшна**.
>
> Операции `accept_order`, `complete_order`, `cancel_order` **необратимы**!

---

## Инструменты (8 штук)

| Инструмент | Метод | Описание |
|---|---|---|
| `get_orders` | GET | Список заказов с фильтрацией по статусу и дате |
| `get_order` | GET | Один заказ по ID |
| `get_order_items` | GET | Позиции заказа (товары, кол-во, цена) |
| `accept_order` | PATCH | Принять заказ (ACCEPTED_BY_MERCHANT) |
| `complete_order` | PATCH | Завершить заказ (COMPLETED) |
| `cancel_order` | PATCH | Отменить заказ (CANCELLED) |
| `get_cities` | GET | Список городов Kaspi |
| `get_products` | GET | Товарные предложения продавца |

## Статусы заказов

| Статус | Описание |
|---|---|
| `NEW` | Новый заказ, ожидает обработки |
| `SIGN_REQUIRED` | Требуется подпись (для крупных покупок) |
| `PICKUP` | Готов к выдаче |
| `DELIVERY` | В доставке (курьерская) |
| `KASPI_DELIVERY` | В доставке через Kaspi Доставку |
| `ARCHIVE` | Архив (завершённые/отменённые) |

## Быстрый старт

### 1. Получите API-токен

Откройте [Kaspi Seller Cabinet](https://kaspi.kz/mc/) → Настройки → API → Скопируйте токен.

### 2. Настройте MCP-сервер

#### Claude Desktop

`claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "kaspi": {
      "command": "npx",
      "args": ["-y", "@theyahia/kaspi-merchant-mcp"],
      "env": {
        "KASPI_AUTH_TOKEN": "ваш-токен"
      }
    }
  }
}
```

#### Claude Code (CLI)

```bash
claude mcp add kaspi -- npx -y @theyahia/kaspi-merchant-mcp
# Установите переменную окружения:
export KASPI_AUTH_TOKEN="ваш-токен"
```

#### VS Code (Copilot)

`.vscode/mcp.json`:
```json
{
  "servers": {
    "kaspi": {
      "command": "npx",
      "args": ["-y", "@theyahia/kaspi-merchant-mcp"],
      "env": {
        "KASPI_AUTH_TOKEN": "ваш-токен"
      }
    }
  }
}
```

#### Cursor

`.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "kaspi": {
      "command": "npx",
      "args": ["-y", "@theyahia/kaspi-merchant-mcp"],
      "env": {
        "KASPI_AUTH_TOKEN": "ваш-токен"
      }
    }
  }
}
```

#### Windsurf

`~/.codeium/windsurf/mcp_config.json`:
```json
{
  "mcpServers": {
    "kaspi": {
      "command": "npx",
      "args": ["-y", "@theyahia/kaspi-merchant-mcp"],
      "env": {
        "KASPI_AUTH_TOKEN": "ваш-токен"
      }
    }
  }
}
```

## Примеры запросов

```
"Покажи новые заказы за сегодня"
"Прими заказ 12345678"
"Какие заказы ожидают отправки?"
"Покажи детали заказа ABC-123"
"Отмени заказ XYZ, причина: нет в наличии"
"Список городов Kaspi"
```

## Разработка

```bash
git clone https://github.com/theYahia/kaspi-merchant-mcp.git
cd kaspi-merchant-mcp
npm install
npm run build
npm test
```

## Ссылки

- [Kaspi Seller API документация](https://kaspi.kz/shop/info/merchant-api/)
- [JSON:API спецификация](https://jsonapi.org/)
- Часть серии [russian-mcp](https://github.com/theYahia) — MCP-серверы для СНГ-рынка

## Лицензия

MIT