# MCP-сервер для RetailCRM — заказы, клиенты и товары интернет-магазина через ИИ

Если вы искали, как подключить RetailCRM к нейросети, поднять заказ или карточку клиента и не собирать отчёты руками — это оно. 39 инструментов и 2 навыка поверх API v5: заказы, клиенты, товары, складские остатки, оплаты, задачи, справочники и аналитика. Спрашиваете «что с заказом 12345» — получаете статус, состав и оплату одним ответом.

> Промышленный MCP-сервер для e-commerce CRM **RetailCRM**. 39 инструментов + 2 навыка-промпта для работы с заказами, клиентами, товарами, остатками, оплатами, задачами, справочниками и аналитикой через API v5.

[![npm](https://img.shields.io/npm/v/@theyahia/retailcrm-mcp)](https://www.npmjs.com/package/@theyahia/retailcrm-mcp)
[![Smithery](https://smithery.ai/badge/@theyahia/retailcrm-mcp)](https://smithery.ai/server/@theyahia/retailcrm-mcp)

## Ответы экономят токены по умолчанию

Читающие инструменты возвращают **компактную структурированную сводку** только из тех полей, которые нужны агенту, а не весь ответ RetailCRM. Подробность настраивается на каждый вызов:

| Параметр | Что делает |
|-------|--------|
| _(по умолчанию)_ | `detail:"summary"` — ключевые поля + блок `pagination` |
| `detail:"full"` | Все структурированные поля (позиции, доставка, оплаты, адрес…) |
| `raw:true` | Нетронутый ответ RetailCRM (для отладки) |

> ⚠️ **v3 ломает совместимость** с v2: по умолчанию отдаётся структурированная сводка, а не сырой JSON. Передайте `raw:true`, чтобы вернуть прежний формат.

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

### Заказы
| Инструмент | Описание |
|------|-------------|
| `list_orders` | Список заказов по статусу, клиенту, номеру, периоду |
| `get_order` | Один заказ по ID или externalId |
| `create_order` | Создать заказ; привязать существующего клиента (`customer_id`/`customer_external_id`) или завести нового прямо в вызове |
| `update_order` | Изменить статус, клиента, доставку, комментарии |
| `orders_history` | История изменений заказов, включая смены статусов (инкрементальная синхронизация) |

### Клиенты
| Инструмент | Описание |
|------|-------------|
| `list_customers` | Поиск клиентов по имени, e-mail, телефону, дате |
| `get_customer` | Один клиент по ID или externalId |
| `create_customer` | Создать клиента |
| `update_customer` | Изменить существующего клиента |
| `merge_customers` | Объединить дубли (разрушающая операция) |
| `customers_history` | Лог изменений клиентов (прирост/отток, инкрементальная синхронизация) |

### Товары и остатки
| Инструмент | Описание |
|------|-------------|
| `list_products` | Товары каталога по названию, группе, активности, цене |
| `list_product_groups` | Дерево товарных категорий |
| `store_inventories` | Остатки и себестоимость по торговым предложениям и складам |

### Оплаты
| Инструмент | Описание |
|------|-------------|
| `order_payment_create` | Зафиксировать оплату по заказу |
| `order_payment_edit` | Изменить оплату |
| `order_payment_delete` | Удалить оплату (разрушающая операция) |

### Заметки и задачи
| Инструмент | Описание |
|------|-------------|
| `customer_notes_list` / `customer_notes_create` / `customer_notes_delete` | Произвольные заметки по клиенту |
| `tasks_list` / `tasks_create` / `tasks_edit` | Задачи и напоминания |

### Маркетинг и финансы
| Инструмент | Описание |
|------|-------------|
| `list_segments` | Сегменты клиентов (RFM и маркетинговые когорты) |
| `list_costs` / `create_cost` | Записи расходов для аналитики маржи |

### Файлы
| Инструмент | Описание |
|------|-------------|
| `files_list` / `files_get` / `files_upload` | Прикрепление и получение файлов (загрузка сырым octet-stream) |

### Справочники
| Инструмент | Описание |
|------|-------------|
| `list_statuses` / `list_delivery_types` / `list_payment_types` / `list_stores` | Справочники статусов, доставок, оплат и магазинов |
| `list_sites` | Сайты, доступные ключу API (для заполнения параметра `site`) |
| `list_countries` / `list_order_types` / `list_order_methods` | Справочники адресов и заказов |

### Аналитика
| Инструмент | Описание |
|------|-------------|
| `get_orders_summary` | Статистика заказов за период: точное количество и выручка, средний чек, распределение по статусам |
| `get_customers_summary` | Количество новых клиентов за период |

## Навыки-промпты (2)

| Навык | Описание |
|-------|-------------|
| `new-orders` | Быстрый ежедневный обзор сегодняшних заказов |
| `customer-search` | Найти клиента по имени, e-mail или телефону |

## Настройка

1. В RetailCRM откройте **Настройки → Интеграция → Ключи API**.
2. Создайте ключ API с нужными правами (заказы, клиенты, склад, справочники). Для **мультисайтового** ключа передавайте код `site` в инструментах создания и изменения (см. `list_sites`).
3. Запомните свой домен (часть `yourstore` из `yourstore.retailcrm.ru`).

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

| Переменная | Обяз. | Описание |
|----------|----------|-------------|
| `RETAILCRM_DOMAIN` | да | Домен вашего RetailCRM (например, `yourstore.retailcrm.ru`) |
| `RETAILCRM_API_KEY` | да | Ключ API (передаётся в заголовке `X-API-KEY`) |
| `RETAILCRM_READONLY` | нет | `1` — оставить только читающие инструменты (скрыть create/update/merge/delete) |
| `RETAILCRM_RATE_LIMIT` | нет | Клиентское ограничение запросов в секунду (RetailCRM допускает ~10/с) |
| `PORT` / `HOST` | нет | Привязка HTTP-сервера (по умолчанию `3000` / `127.0.0.1`, только в режиме `--http`) |
| `RETAILCRM_HTTP_ALLOWED_HOSTS` | нет | Разрешённые значения `Host` через запятую для защиты от DNS-rebinding |
| `RETAILCRM_DNS_PROTECTION` | нет | `off` — отключить защиту от DNS-rebinding (HTTP-режим) |

> `RETAILCRM_URL` по-прежнему принимается как запасной вариант для `RETAILCRM_DOMAIN`.

## Подключение к Claude Desktop

```json
{
  "mcpServers": {
    "retailcrm": {
      "command": "npx",
      "args": ["-y", "@theyahia/retailcrm-mcp"],
      "env": {
        "RETAILCRM_DOMAIN": "yourstore.retailcrm.ru",
        "RETAILCRM_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Режим Streamable HTTP

Запуск в виде HTTP-сервера вместо stdio:

```bash
RETAILCRM_DOMAIN=yourstore.retailcrm.ru \
RETAILCRM_API_KEY=your-key \
npx @theyahia/retailcrm-mcp --http
```

- `POST /mcp` — эндпоинт MCP Streamable HTTP (stateless: на каждый запрос создаётся новый сервер)
- `GET /health` — проверка состояния (JSON с версией и числом инструментов)
- `GET`/`DELETE /mcp` — `405` (в stateless-режиме не используются)
- Привязка по умолчанию: `127.0.0.1:3000`. Защита от DNS-rebinding для локальных привязок включена по умолчанию.

## Smithery

```bash
npx @smithery/cli install @theyahia/retailcrm-mcp
```

## Демо-промпты

**1. Обзор заказов за день:** «Покажи все заказы, созданные сегодня, в статусе „новый“. Дай итоговое количество и выручку.»

**2. Клиент и его история заказов:** «Найди клиента с почтой anna@example.com. Покажи полный профиль и последние заказы.»

**3. Проверка остатков:** «Есть ли товар с externalId SKU-42 в наличии и на каком складе?»

## Вебхуки и триггеры

RetailCRM не умеет создавать вебхуки через API. Используйте **Триггеры** в админке (Настройки → Триггеры), чтобы отправлять HTTP-запросы на внешние эндпоинты по событиям заказов и клиентов.

## Обработка ошибок

- **Лимиты запросов и 5xx:** автоматический повтор с экспоненциальной задержкой и джиттером (до 3 попыток).
- **Ошибки API:** детали ошибки RetailCRM разбираются и возвращаются модели как результат инструмента с `isError: true`, чтобы агент мог исправиться сам (например, повторить с `by:"externalId"`).
- **Таймауты:** 15 секунд на запрос с повтором.

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

```bash
npm install
npm test          # vitest (на моках; живой ключ API не нужен)
npm run lint      # eslint
npm run typecheck # tsc --noEmit
npm run dev       # dev-режим stdio (tsx)
npm run build     # очистка + сборка в dist/
```

## Лицензия

MIT

---

Часть [WWmcp](https://github.com/theYahia/WWmcp) · Telegram: [@vhodvai](https://t.me/vhodvai)