artel-mcp

MCP-сервер Wildberries для Claude Desktop — клиентская часть продукта Artel AI. Селлер вводит локальный WB API-токен и может обычным языком работать с заказами, продажами, остатками, ценами, рекламой, финансами, отзывами, поставками и аналитикой.

Для полной работы Artel нужен персональный токен WB, созданный через ручную интеграцию. Базовый токен видит только ограниченный набор данных, поэтому отдельные методы могут отклонить его; тестовый токен не видит реальный магазин, а сервисный привязан к конкретному облачному сервису. Коннектор определяет тип JWT локально и при отказе WB возвращает понятную инструкцию без раскрытия токена.

Актуальный production-релиз: .mcpb [email protected] · 103 инструмента при активном полном доступе (44 общих + 59 полного доступа) · MCP Prompts не объявляются.

Версия 1.1.13: 103 инструмента (44 общих + 59 полного доступа). update_advert_bid переведён на актуальный пакетный контракт WB. Добавлен полный контур товарной рекламы: общая и дневная статистика, рекомендации и текущие ставки, кластеры и минус-фразы, бюджет и история операций, создание кампаний, переименование, запуск/пауза/завершение/удаление, размещения, состав товаров и пополнение бюджета. WB Media не входит. Также добавлен update_content_card для названия, описания и характеристик одной карточки. Все write-инструменты сначала перечитывают состояние, возвращают точный diff с previewId и применяют изменение только с тем же previewId и confirm:true. Сетевые write-запросы не повторяются автоматически.

Кандидат 1.1.10: лицензия обновляется во время работы: перед отказом Pro-инструмент обязательно перепроверяет ключ, поэтому переход Free → paid Pro подхватывается без перезапуска Claude. Локальная Pro-база подключается лениво. MCP Prompts и рекламные TXT-инструкции удалены; вместо них зарегистрированы составные инструменты diagnose_sales, analyze_product_seo и существующий build_growth_action_plan. Всего 69 инструментов (30 общих + 39 полного доступа), включая отдельную безопасную проверку refresh_artel_access.

В версии 1.1.12 лицензия не активируется и магазин не привязывается, пока WB seller-info не подтвердит идентичность магазина или пока нет ранее сохранённого настоящего хэша. Это исключает повреждение привязки значением unknown. FBS остаётся расширен до полного операционного контура маркировки и поставок. Добавлены получение и безопасная запись метаданных заданий, повторная отгрузка, отмена продавцом, удаление пустой поставки, короба и их QR-стикеры. Лимит проверки статусов исправлен со 100 до 1000 ID. Итого 79 инструментов (30 общих + 49 полного доступа). Все новые write-действия используют preview и требуют confirm:true; значения маркировки скрыты из preview и не попадают в локальный кэш.

В версии 1.1.9 устранена двусмысленность тарифа в MCP-ответах. requiredTier описывает требование инструмента, licenseTier — фактический класс лицензии, а licenseAccess различает оплаченный доступ, триал и старый базовый ключ. Внутреннее поле tier, которое Claude мог ошибочно назвать тарифом пользователя, больше не сериализуется во внешний ответ.

В версии 1.1.8 большой FBS-каталог больше не загружается целиком в один ответ: текущие остатки возвращаются компактными страницами с cursor, а полная выгрузка строится в фоне в локальный UTF-8 CSV. Явный нулевой остаток отделён от позиции, не заведённой на складе; каждый HTTP-запрос WB ограничен таймаутом.

В версии 1.1.7 исправлена standalone-загрузка встроенного node:sqlite, а карточки, товарная воронка и список рекламных кампаний получили компактные LLM-safe режимы, фильтры и явную пагинацию. receivedIds остатков больше не содержит дубли, а ответы явно различают требуемый и активный тарифы. Все write-методы требуют полного доступа и выполняются только после confirm:true. Новые пользователи получают 5 дней полного триала; старые WB Free-ключи сохраняют базовый read-доступ.

В версии 1.1.4 пользовательские отчёты переведены на деловой язык без имён внутренних методов и кодов ошибок, «Расследование продаж» переименовано в «Диагностику продаж», а крупные сценарии завершаются скачиваемым артефактом и маршрутом из трёх действий. Ошибки ключа теперь различают истёкший срок, неверный ключ, другой магазин и лимит устройств. Также включена более устойчивая постраничная загрузка финансовых отчётов из зафиксированного коммита f017d64.

В версии 1.1.3 добавлен отдельный Pro-контур FBS: склады продавца FBS, реальные остатки по chrtId, новые и архивные сборочные задания, статусы и стикеры, состав и QR поставки, а также сводный отчёт по FBS-остаткам с карточками, фотографиями и размерами. Изменение остатков, добавление заказов в поставку и передача поставки в доставку выполняются только после явного confirm: true. Универсальный Pro-отчёт FBO + FBS объединяет фотографию, артикул WB, название, размер/SKU и оба вида остатков в готовые строки для Excel, HTML или дальнейшего анализа.

В версии 1.1.2 добавлена диагностика новых типов токенов WB, последовательная очередь запросов и корректная обработка 429: лимит отдельного метода не блокирует остальные, а global limiter останавливает весь сценарий до времени из заголовков WB. Сценарии больше не умножают ошибку резервными запросами.

В версии 1.1.1 SEO/Джем-сценарий приведён к официальной инструкции WB от 25.06.2026: частотный запрос больше не переносится в название автоматически, а пол, возраст, бренд, сезон, состав, материал, синонимы и лишние подробности отсекаются обязательной проверкой. Корректное наименование не меняется ради SEO.

В версии 1.1.0 Pro-сценарии сначала уточняют область анализа: магазин, категория или конкретные артикулы. План роста возвращает не более трёх доказательных действий, а SEO-разбор соблюдает правила WB: естественное название, полезное покупателю описание, проверенные характеристики и никакой цепочки ключевых слов.

Добавлены build_store_pulse и локальный SQLite Data Layer. «Пульс магазина» возвращает единый набор данных для Live Artifact: сравнение периодов, дневную воронку, состояние источников и три действия с контрольными метриками. Продажи, заказы, дневная воронка и остатки кэшируются и накапливаются локально по магазину; WB-токен и данные не отправляются на сервер Artel. При отсутствии поддержки node:sqlite коннектор продолжает работать без локальной истории.

Все живые запросы WB одного коннектора выполняются последовательно. При ответе 429 Artel учитывает Retry-After/rate-limit headers и включает cooldown отдельного метода, а при сообщении global limiter — всего магазина. Сценарии не запускают резервные методы после такого отказа. При наличии локальной копии временно используется она с явной отметкой local_cache.

В npm попадает минифицированный dist, а в .mcpb — manifest.json, package.json и автономный dist/index.js со встроенными runtime-зависимостями. Исходники и .env в пакеты не входят. Сервер запускается встроенным Node.js Claude Desktop — интернет и npx для запуска не нужны. Автообновления нет: пользователь устанавливает новый .mcpb вручную.

• Текущее состояние и релиз: ../HANDOFF.md
• План развития: ../artel-development-plan.md
• Реестр методов WB: ../artel-wb-api-registry.md

Возможности

• 30 общих инструментов для активного доступа, включая безопасную проверку лицензии.
• 49 инструментов полного доступа: все write-операции, FBS, диагностика, «Пульс магазина», локальная история, комплексный план роста, Джем-аналитика и write-действия.
• MCP Prompts не объявляются; диагностика, SEO-разбор и план роста работают как обычные составные MCP-инструменты.
• Все write-действия относятся к полному доступу, сначала возвращают предпросмотр «было → стало» и выполняются только с confirm: true.
• Каждый метод сообщает freshness, completeness и provenance.
• Кэшированные ответы помечаются dataSource: local_cache, смешанные — dataSource: mixed; refresh: true принудительно запрашивает WB.

Стек

TypeScript · @modelcontextprotocol/sdk · tsup · vitest. Node ≥ 18.

Скрипты

• npm run build — сборка минифицированного бандла для npm и .mcpb
• npm run dev — запуск исходников через tsx
• npm run typecheck — проверка типов
• npm test — тесты vitest

Дополнительные интеграционные и smoke-проверки находятся в scripts/.

Структура

• src/contract/ — envelope: данные, provenance, свежесть, полнота и типизированные ID.
• src/registry/ — реестр возможностей с тарифом Free/Pro.
• src/methods/ — атомарные методы WB, write-действия и расследования.
• src/methods/workflows/ — большие комплексные сценарии принятия решений.
• src/data/ — локальный SQLite Data Layer, кэш, история и provenance.
• src/mcp/tools.ts — 102 доменных инструмента плюс refresh_artel_access в кандидате 1.1.13; MCP Prompts не объявляются.
• src/license/ — динамический гейтинг, повторная проверка перед отказом и офлайн-грейс только для старого Free и оплаченного Pro (не для trial).
• src/store/identity.ts — локальное определение и кэш хэша магазина.

Приватность и секреты

Никогда не коммитить .env. WB-токен и лицензионный ключ хранятся локально у клиента. На сервер лицензий уходят только sha256(ИНН) и хэш устройства; WB-токен и данные магазина устройство клиента не покидают.

Статус: production WB 1.1.13 содержит 103 инструмента и расширенный FBS-контур. Версия 1.1.13 добавляет полный контур товарной рекламы, пакетные ставки и редактирование карточек; typecheck и 122 теста в 31 файле проходят. В standalone отдельно проверяются состав пакета и обязательный Pro-гейтинг всех write-инструментов.