Metadata-Version: 2.4
Name: marketplaces-mcp-ru
Version: 0.3.2
Summary: MCP servers for Wildberries and Ozon Seller APIs (schema-driven, safety-gated)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.2.0
Requires-Dist: httpx>=0.27
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pre-commit>=3.5; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Requires-Dist: detect-secrets>=1.5; extra == "dev"
Dynamic: license-file

# marketplaces-mcp-ru: Wildberries и Ozon в вашем ИИ-ассистенте

<!-- mcp-name: io.github.ilyautov/marketplaces-mcp-ru -->

> 🇬🇧 [English version](README.en.md)

Подключает ИИ-ассистента (Claude, Cursor, Codex, Cowork и др.) напрямую к вашим кабинетам Wildberries и Ozon. Вы спрашиваете обычными словами, агент берёт продажи, остатки, цены, финансы и отзывы прямо из API маркетплейса, а не выдумывает цифры.

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Версия](https://img.shields.io/badge/%D0%B2%D0%B5%D1%80%D1%81%D0%B8%D1%8F-0.3.2-B5491F)](https://github.com/ilyautov/marketplaces-mcp-ru/commits/main)
[![Методов](https://img.shields.io/badge/%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D0%BE%D0%B2-793-2D7D4F)](#как-это-устроено)
[![Клиентов](https://img.shields.io/badge/%D0%BA%D0%BB%D0%B8%D0%B5%D0%BD%D1%82%D0%BE%D0%B2-4-D97757)](#установка)

<!-- social preview: assets/social-preview.png → Settings → Social preview.
     TODO: сайт marketplaces-mcp-ru.aifrontier.tech (как у humanizer-ru / small-business-ru) -->

## Зачем

Вы продаёте на двух площадках, а данные лежат в двух разных кабинетах. Продажи, остатки, цены, финансы, отзывы: всё руками, по очереди, через два браузера. Обычный ИИ-ассистент тут мало помогает. Либо ходит через браузер и спотыкается о капчу, либо называет цифры, которые звучат уверенно, но взяты из воздуха.

Этот проект решает задачу иначе. Он даёт ассистенту прямой доступ к Seller API обоих кабинетов:

- Цифры приходят из ответа Wildberries и Ozon, с указанием источника и полей. Не пересказ, не догадка.
- Перед тем как менять цену или остаток, агент просит подтверждение. Случайно «уронить цену в три раза» не получится.
- Никакого браузера и капчи: обращение идёт по токену кабинета напрямую.

Спросите обычными словами: «покажи продажи за неделю на обоих», «что пора дозаказать», «сравни мои цены с рынком». Агент подберёт нужный метод или готовый сценарий и проведёт по шагам.

> ⚠️ Версия alpha. Помогает с операционкой продавца, но это инструмент, а не замена аналитику. Проверенное вручную ядро (продажи, остатки, цены, финансы, отзывы) выверено на реальных кабинетах. Остальные методы импортированы из спецификаций и служат картой для разведки. Подробности в разделе [Оговорки](#оговорки).

## Что можно спросить

Просто пишите агенту в чат по-русски:

```
покажи продажи за неделю на WB и Ozon и сравни
что пора дозаказать, посчитай дни покрытия по остаткам и продажам
вытащи финотчёт реализации WB за прошлый месяц
какие товары на Ozon с красным индексом цены
собери отзывы ниже 4 звёзд за неделю и сгруппируй жалобы по товару
сделай ABC-анализ по выручке и покажи товары-хвост
```

Не знаете, с чего начать, скажите «что ты умеешь по моему кабинету». Агент покажет готовые сценарии: для Wildberries это пульс продаж, здоровье остатков, аудит цен, планировщик дозаказа, ABC-анализ, сводка отзывов; для Ozon: риск out-of-stock, анализ цен, юнит-экономика, синхронизация каталога, аудит контента и те же ABC и отзывы. Каждый сценарий это пошаговый рецепт с трактовкой результата и типичными ошибками.

## Установка

Подробный гайд под любую аудиторию лежит в [QUICKSTART.md](QUICKSTART.md). Несколько способов, результат один.

1. **Claude Desktop в один клик (`.mcpb`).** Возьмите `marketplaces-mcp-ru-v<версия>.mcpb` из [GitHub Releases](https://github.com/ilyautov/marketplaces-mcp-ru/releases) и дважды кликните — Claude Desktop сам поставит расширение и спросит ключи в окне настроек. Без терминала и без Gatekeeper. Один бандл поднимает WB + Ozon + Ozon Performance сразу.
2. **Попросить своего ИИ (без терминала).** Откройте Claude или Cowork и скажите: «установи WB + Ozon MCP». Агент проведёт по встроенному скиллу `install-skill/`. В песочнице Cowork финальный клик остаётся за вами; в Claude Code установка проходит полностью сама.
3. **Скачать и кликнуть.** Возьмите `marketplaces-mcp-ru-v<версия>.zip` из [GitHub Releases](https://github.com/ilyautov/marketplaces-mcp-ru/releases), распакуйте, дважды кликните `install.command` (macOS) или `install.bat` (Windows), вставьте ключи. На macOS при первом запуске: правый клик → «Открыть» → «Открыть» (так обходится Gatekeeper для скачанного файла).
4. **Через терминал.** `git clone https://github.com/ilyautov/marketplaces-mcp-ru`, затем `python3 install.py --client <ваш-клиент>`.
5. **Для разработчиков (`uvx`).** `uvx marketplaces-mcp-ru` запускает объединённый сервер прямо из PyPI; отдельные серверы — консольными командами `wb-mcp` / `ozon-mcp` / `ozon-perf-mcp`. Ключи — через переменные окружения или те же `*_add_cabinet` из чата.

Установщик копирует приложение в стабильную папку (`~/.marketplace-mcp/app`) и привязывает конфиг туда, так что исходную папку потом можно перемещать или удалять, ничего не сломается. Ни `pip install`, ни ручной правки JSON: зависимости ставятся сами при первом запуске. От вас нужны только ключи. Поддерживается 4 клиента через `--client`: `claude-desktop` и `opencode` получают готовый конфиг, `claude-code` и `codex` получают готовые команды `mcp add`.

**Где взять ключи.** Wildberries: seller.wildberries.ru → Настройки → Доступ к API. Ozon: seller.ozon.ru → Настройки → API-ключи. Ключи хранятся в `~/.marketplace-mcp/cabinets.json` локально (`chmod 600`), в репозиторий и в чат не попадают. Можно подключить несколько магазинов и переключаться между ними прямо из чата (`*_add_cabinet` / `*_use_cabinet`).

**Проверка после установки:**

```bash
python3 serve.py ozon --selfcheck
```

## Безопасность

Ключ кабинета двигает цены, остатки и деньги, поэтому каждый метод заранее размечен по уровню риска:

- `read`: чтение, выполняется сразу;
- `write`: изменение, требует `confirm_write=true`;
- `destructive`: удаление, требует `confirm_write=true` и `i_understand_this_modifies_data=true`.

Проверка работает локально, наружу без подтверждения ничего не уходит. Что метод-мутация случайно не пометится как `read`, проверяет тест в CI (`test_safety_catalog.py`): сборка падает, если в каталог попадёт PUT, PATCH или DELETE с уровнем `read`. Дополнительно `call_method` подстраховывается на лету: даже устаревшая пометка `read` на мутирующем запросе не опустит проверку ниже `write`.

Подробнее в [SECURITY.md](SECURITY.md). О найденной уязвимости пишите на ilyautov@gmail.com с темой `SECURITY: marketplaces-mcp-ru`, без публичного issue.

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

Под капотом два MCP-сервера (Wildberries и Ozon) на общем ядре. Вместо «один инструмент на каждый эндпоинт» (это 300+ инструментов, в которых агент теряется) сделано иначе: 8 универсальных мета-инструментов поверх каталога методов. Полное покрытие API при компактной поверхности.

```
ваш ИИ-агент
      │
      ▼
 8 мета-инструментов  ──►  каталог (endpoints.yaml)  ──►  общее ядро
 search / describe /                                      клиент · safety · ошибки
 call / call_raw /                                        пагинация · реестр
 fetch_all / ...                                                │
 + типизированные инструменты (wb_get_sales, …)                 ▼
                                            Wildberries / Ozon HTTPS API
```

Мета-инструменты одинаковы на обоих серверах (префикс `wb_` или `ozon_`):

| Инструмент | Что делает |
|---|---|
| `*_check_auth` | Проверяет наличие ключей (секреты не печатает) |
| `*_search_methods` | Ищет метод по-русски или по-английски |
| `*_describe_method` | Полное описание: метод, хост, путь, scope, уровень риска, лимит, ссылка на доку |
| `*_call_method` | Вызывает любой метод каталога через проверку безопасности |
| `*_call_raw` | Вызывает любой путь, даже которого ещё нет в каталоге (полное покрытие) |
| `*_fetch_all` | Авто-пагинация (offset / last_id / cursor / date-курсор WB) |

Плюс типизированные инструменты для частых задач (`wb_get_sales`, `wb_get_stocks`, `ozon_get_products`, `ozon_get_prices` и др.) и инструменты управления кабинетами.

Каталог собран schema-driven из официальных OpenAPI-спецификаций:

| Каталог | Файл | Методов | Секций |
|---|---|---:|---|
| Wildberries | `wb_mcp/endpoints.yaml` | 307 | 70 |
| Ozon Seller | `ozon_mcp/endpoints.yaml` | 441 | 67 |
| Ozon Performance (реклама) | `ozon_mcp/perf_endpoints.yaml` | 45 | 6 |

Ядро (продажи, остатки, цены, финансы, отзывы) выверено вживую; остальное импортировано из спецификаций, а `call_raw` достаёт то, чего ещё нет в каталоге. Что покрыто по бизнес-областям:

| Область | Wildberries | Ozon |
|---|---|---|
| Продажи и заказы | продажи, заказы, сборочные задания FBS / DBS / DBW / Самовывоз | заказы FBO / FBS, отправления, возвраты |
| Остатки и склады | остатки, склады продавца, поставки FBS | остатки по складам, FBO / FBS, аналитика остатков |
| Цены и скидки | цены и скидки, календарь акций | цены, стратегии ценообразования, акции |
| Финансы | финотчёт реализации, баланс | транзакции, начисления, реализация, компенсации |
| Контент и карточки | карточки, категории, характеристики, медиа | товары, атрибуты, категории, сертификаты |
| Отзывы и вопросы | отзывы, вопросы | отзывы (нужен Premium Plus), вопросы и ответы |
| Реклама | управление кампаниями, статистика | Performance API (отдельный сервер) |
| Аналитика | воронка продаж, отчёты | аналитические отчёты, оборачиваемость |

Полный список секций покажет `*_list_sections` прямо в чате, точечный поиск делает `wb_search_methods("остатки")`.

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

Раздел для тех, кто хочет покопаться в коде, выверить методы боем или прислать PR.

**Структура.** Вся общая логика живёт в `core/`, серверы это тонкие обёртки над ней:

```
core/                общее ядро обоих серверов
  client.py          HTTPS-клиент (хосты, заголовки, ретраи)
  credentials.py     загрузка ключей из cabinets.json / env
  safety.py          гейт read / write / destructive
  registry.py        загрузка и индексация каталога endpoints.yaml
  paginate.py        авто-пагинация (offset / last_id / cursor / date)
  entities.py        нормализация сущностей (товары, заказы и т.д.)
  workflows.py       движок пошаговых сценариев
  tools.py           регистрация мета-инструментов в MCP
  errors.py          единый формат ошибок
wb_mcp/              сервер WB: server.py + endpoints.yaml + workflows.yaml
ozon_mcp/            сервер Ozon: server.py + endpoints.yaml + perf_endpoints.yaml + workflows.yaml
scripts/             сборка каталогов, валидация, релиз
tests/               офлайн-тесты (токены не нужны)
```

**Локальный запуск и тесты.** Нужен Python 3.10+. Зависимости (`mcp`, `httpx`, `pyyaml`) `serve.py` ставит сам в локальный `.venv` при первом запуске.

```bash
git clone https://github.com/ilyautov/marketplaces-mcp-ru.git
cd marketplaces-mcp-ru

# офлайн-тесты, ключи не нужны — все офлайн-тесты зелёные
env -u OZON_CLIENT_ID -u OZON_API_KEY -u WB_API_TOKEN python3 -m pytest tests/ -q

# selfcheck серверов: отдаёт 19 тулов для wb, 19 для ozon, 14 для ozon-perf
python3 serve.py wb --selfcheck
python3 serve.py ozon --selfcheck
python3 serve.py ozon-perf --selfcheck
```

**Как устроен и растёт каталог.** `endpoints.yaml` собирается schema-driven из официальных OpenAPI-спеков: `ingest_specs.py` (WB) и `ingest_ozon.py` (Ozon) тянут пути, `derive_pagination.py` и `fix_items_path_from_examples.py` настраивают пагинацию и `items_path`, `sync_swagger.py` подтягивает свежие спеки. Запись каждого метода описывает `operation_id`, метод, хост, путь, scope, уровень риска и пагинацию. Импорт идемпотентный и аддитивный: курированные уровни риска и описания не перетираются. `validate_items_path.py` это live-валидатор (гонять локально на своих ключах), `package_release.py` собирает чистый версионный zip, `smoke_mcp.py` это дымовой тест.

**Что особенно полезно прислать:**

- Боевую выверку HTTP-глаголов. Пути у импортированных методов надёжны, а глаголы нет: live-проба находила «GET», которые на деле POST (405). Поправьте `*/endpoints.yaml` и приложите доказательство: код ответа или ссылку на доку.
- Новые сценарии в `*/workflows.yaml`: пошаговые рецепты с трактовкой и типичными ошибками, каждый шаг сверяется с каталогом.
- Уточнение safety-классификации, если метод размечен слишком мягко или строго.

Полностью правила в [CONTRIBUTING.md](CONTRIBUTING.md). Перед PR прогоните офлайн-тесты и `--selfcheck` всех серверов; изменили число методов или тулов, поправьте цифры в README.

**Безопасность репозитория.** Гайдлайны для людей и агентов лежат в [AGENTS.md](AGENTS.md). Секреты живут только локально: `.env`, `cabinets.json`, ключи и сертификаты закрыты `.gitignore`, а pre-commit прогоняет `scripts/security/forbid_sensitive_files.py` и `scan_mcp_config.py`. Что мутирующий метод не попадёт в каталог с уровнем `read`, держит тест `test_safety_catalog.py`: сборка падает на PUT, PATCH или DELETE с пометкой `read`. Файл `.mcp.json` отслеживается намеренно, это манифест плагина без секретов.

## Частые вопросы

**Нужно ли уметь программировать?** Нет. Есть установка «попроси своего ИИ» и установка двойным кликом. `pip install` и правка JSON не нужны, зависимости ставятся сами, от вас только API-ключ.

**Это безопасно? Куда уходят ключи?** Сервер работает там же, где ваш агент, локально. Ключи лежат в `~/.marketplace-mcp/cabinets.json` (`chmod 600`), в репозиторий и в чат не попадают. Любое изменение в кабинете (цена, остаток) происходит только с вашим подтверждением.

**Чем это лучше парсеров и браузерных ботов?** Это прямой Seller API по токену, а не разбор веб-страниц: нет капчи, нет блокировок, данные приходят структурированными. Плюс защита от случайного изменения цены или остатка.

**Это бесплатно?** Да, открытый код под лицензией MIT. Берите, форкайте, дорабатывайте.

## Оговорки

Сверяйте с живой документацией маркетплейсов:

- **WB `Authorization`**: сервер шлёт raw-токен без префикса `Bearer` (подтверждено на практике). Если авторизация падает, проверьте это в первую очередь.
- **Импортированные из спецификаций методы: пути надёжны, HTTP-глаголы не всегда.** Live-проба находила методы, помеченные GET, которые на деле POST (ответ 405). Считайте такие записи картой для разведки: подтверждайте глагол и тело по докам или вызывайте через `call_raw`. Курированное ядро (7 категорий WB, 4 секции Ozon) и live-выверенный набор надёжны.
- **Ozon дрейфует по версиям** (list v3, attributes v4, prices v5). При 404 проверьте версию; `ingest_ozon.py` пере-выравнивает пути.
- **Ozon Performance**: пока каталог-артефакт плюс OAuth-обвязка по докам. Контракт токен-эндпоинта вживую не выверен, нужны рекламные креды.
- **Кабинет затеняет переменные окружения.** Активный кабинет в `cabinets.json` имеет приоритет над env. Необъяснимый 401 или «Client-Id should be positive integer»: первым делом проверьте этот файл.

## Чем это не является

Это инструмент для ИИ-агента, а не онлайн-сервис «в один клик» и не замена аналитику. Решение, которое меняет цены, остатки или деньги, всегда остаётся за вами, защита лишь не даёт сделать это случайно. Проект на стадии alpha: ставьте, проверяйте на своих данных, экспериментируйте. Нашли проблему, заведите [issue](https://github.com/ilyautov/marketplaces-mcp-ru/issues) (без реальных ключей и данных кабинета).

Архитектура взяла сильные идеи зрелых marketplace-MCP (schema-driven каталог, проверка безопасности, единый формат ошибок, авто-пагинация), но реализована своим кодом, без зависимости от чужих библиотек.

## Лицензия

MIT.
