# WB Readonly MCP

ИИ-помощник для своего кабинета Wildberries: товары, реклама, заказы, остатки, воронка, отзывы, тарифы и финансовые документы. Сервер получает данные WB, а ChatGPT, Cursor или другой MCP-клиент помогают их разбирать.

**Изменять WB через этот проект нельзя.** Доступны 12 инструментов MCP и 181 разрешённая операция API из 13 разделов. Для редких задач есть поиск по каталогу и точные схемы параметров. Новые методы автоматически не включаются.

**[Начать установку → DEPLOY.md](DEPLOY.md)** · [Примеры запросов](USAGE.md) · [Инструкция для любой ИИ](AI_GUIDE.md) · [Полный каталог](CAPABILITIES.md)

## Что полезного менеджеру

| Направление | Что можно читать и анализировать |
|---|---|
| Товары | Карточки, артикулы, размеры, штрихкоды, категории, предметы, характеристики, цены, скидки, карантин цен и ошибки карточек |
| Реклама | Кампании, бюджеты, баланс, расходы, показы, клики, атрибутированные заказы, поисковые кластеры, ставки и минус-фразы; расчёт CTR, CPC и ДРР |
| Продажи | Заказы, продажи и возвраты; воронка по товарам и дням; сравнение периодов и группировка выгрузок |
| Остатки | Склады WB и продавца, размеры, доступные отчёты; оценка запаса в днях и сценарий пополнения |
| Заказы и поставки | FBS, DBS, DBW, самовывоз; статусы, история, доставка, состав поставок; сведения о поставках FBW и приёмке |
| Финансы | Отчёты реализации, детализации, эквайринг, баланс, документы; сценарная экономика товара с вашей себестоимостью |
| Покупатели | Отзывы, вопросы, чаты, заявки на возврат; поиск повторяющихся причин недовольства |
| Дополнительно | Акции, комиссии и тарифы, удержания, замеры, география продаж, рейтинг продавца и доступные подписки |

Доступность зависит от категорий и типа токена, модели работы продавца, подписок WB и текущей версии API. «Есть в каталоге» не означает, что WB предоставит метод каждому кабинету.

## Как это устроено

```text
ChatGPT / Cursor / совместимый MCP-клиент
                  ↓ HTTPS + OAuth
     Cloudflare: постоянный домен или workers.dev
                  ↓ Tunnel
       Ваш VPS → WB Readonly MCP → API WB
                       ↓
            локальные результаты и расчёты
```

Токен WB хранится на VPS и используется только сервером для запросов к API Wildberries. ChatGPT подключается к MCP через OAuth 2.0 (Authorization Code + PKCE): на странице входа вводятся логин и пароль MCP, не токен WB. Для локального Cursor доступен запуск через stdio. Это один кабинет и общая доверенная команда: разграничения товаров и финансов между сотрудниками нет.

Cloudflare даёт внешний HTTPS-адрес. Если нужен адрес вне зоны `.ru`, предусмотрен вход через `*.workers.dev`. С сервера должен работать доступ к API WB; Cloudflare не меняет этот исходящий маршрут.

## Поиск товара без лишних вопросов

«Разбери товар 123456789» → сервер получает карточку, определяет `subjectId`, название предмета и родительскую категорию, читает характеристики и цены. Вручную указывать категорию при известном артикуле обычно не нужно.

«Найди белые носки» → поиск по своему каталогу. При нескольких совпадениях ИИ показывает варианты. Для большого каталога возвращаются признак неполной выборки и курсор продолжения.

## Почему запись недоступна

- Допускаются токены с правами «Только чтение» и «Чтение и запись». Права токена не расширяют набор методов MCP: сервер разрешает только операции чтения из фиксированного списка. Формат и срок токена проверяются локально; подлинность и доступ к данным окончательно проверяет WB.
- Вызов разрешён только для точного сочетания операции, метода, пути и домена из `catalog/allowlist.json`.
- ИИ не может задать произвольный URL, заголовки, другой токен или HTTP-метод. Перенаправления API не выполняются.
- Изменяющие операции исключены даже при использовании GET. POST для получения данных допускается только по списку.
- Создание и повторный запуск фоновых отчётов WB исключены. Можно читать уже готовые отчёты при наличии их ID и доступа.
- Все инструменты объявлены в MCP как read-only; реальное ограничение действует в коде, а не только в подсказке ИИ.
- Встроенная инструкция прямо запрещает назначать или переносить отгрузки, бронировать слоты, менять цены, остатки, рекламу и отправлять сообщения. На такие просьбы ИИ помогает с анализом и ручными действиями, не заявляя об их выполнении.

Сохранение ответов и OAuth-подключений на собственном сервере не изменяет кабинет WB.

## Инструменты MCP

| Инструмент | Назначение |
|---|---|
| `wb_status` | Проверка настройки и доступного каталога без запроса к WB |
| `wb_catalog` | Поиск операций по задаче или разделу |
| `wb_schema` | Параметры, ограничения и источник выбранной операции |
| `wb_read` | Чтение одной страницы API WB по разрешённой операции |
| `wb_result` | Просмотр сохранённого результата частями, включая вложенные поля и длинный текст |
| `wb_find_product` | Поиск по артикулу WB, артикулу продавца, штрихкоду или названию |
| `wb_product_profile` | Карточка, категория, характеристики и цены товара |
| `wb_sales_funnel` | Воронка за выбранный период |
| `wb_ads_audit` | Рекламная статистика и расчёт CTR, CPC, ДРР |
| `wb_aggregate` | Локальные суммы, средние, группировки и фильтры по выгрузке |
| `wb_stock_plan` | Сценарий пополнения из заданных остатков и спроса |
| `wb_unit_economics` | Экономика одной выкупленной единицы из введённых затрат |

Есть встроенная инструкция `wb://guide` и шаблон `wb_daily_review`. Шаблон запускается по запросу, автоматического ежедневного расписания нет.

## Быстрый старт разработчика

Нужен Node.js 22 или новее.

```bash
git clone https://github.com/zimuspro156-lab/mcp-wb-readonly.git
cd mcp-wb-readonly
npm ci
npm test
npm run check
npm run setup
```

Настройте `.env`, добавьте персональный токен WB с нужными категориями API в `WB_READ_ONLY_TOKEN` (допускаются оба режима прав), затем `npm run start:http`. Для сервера с автозапуском используйте [полную инструкцию](DEPLOY.md). Для локального Cursor — раздел «Локальный Cursor» в ней.

## Границы текущей версии

- Реализованы и проверены локально MCP, ограничения запросов, OAuth и аналитические расчёты. Тесты используют подставные ответы WB; проверка реальным токеном вашего кабинета ещё нужна.
- Каталог основан на датированном снимке API от 19.08.2026 с дополнением полных схем. Прямое получение части документации WB во время разработки было недоступно. Происхождение и ограничения описаны в [PROVENANCE.md](PROVENANCE.md).
- Одна операция с неполной схемой отключена. Это настройки автовозвратов FBS для конкретных товаров. Все 104 исключённые операции перечислены отдельно.
- Получение готового ZIP/PDF возвращает сохранённое содержимое/base64. Автоматической распаковки и распознавания PDF нет. Для аналитики удобнее выбирать JSON-детализации.
- Нет доступа к закрытым данным конкурентов, автоматического обхода платных подписок или гарантированной «чистой прибыли» без ваших затрат.
- Docker-конфигурация подготовлена, но сборка Docker и установка на Linux VPS в среде разработки не выполнялись. Основной путь установки — отдельные службы systemd.
- Входящий доступ ChatGPT → MCP — только OAuth 2.0 Authorization Code + PKCE. Статический Bearer MCP больше не принимается. Токен WB по-прежнему только для исходящих запросов сервера к API WB.

Исходный код — [MIT](LICENSE). Проект не является официальным продуктом Wildberries.