mcp-yandex-kit

v1.8.0

Published

3 days ago

A1 Yandex KIT MCP server for the Yandex KIT e-commerce platform API

0High
0Medium
0Low

gistrec

yandex kit yandex-kit yandex kit yandexkit a1-yandex-kit e-commerce mcp model-context-protocol ai

`mcp-yandex-kit` — управляйте магазином через AI-ассистента

Подключите API Яндекс KIT к Claude, Cursor, Codex или другому MCP-клиенту и просто скажите, что должно получиться: показать заказы, обновить товары и остатки, опубликовать новость, создать скидку, промокод или вебхук. mcp-yandex-kit даёт ассистенту 88 готовых инструментов и доступ ко всем 166 операциям API — без ручной работы с HTTP-запросами и схемами.

Полное покрытие API. 92 операции доступны через специализированные инструменты, остальные 74 — через search_operations, get_operation_schema и kit_request.
Запуск через npx. Сервер не нужно устанавливать отдельно; понадобится Node.js 20.11+.
Проверка до отправки. Тела write-запросов валидируются по JSON Schema сохранённой OpenAPI-спецификации, если для операции задана request schema. Для multipart-загрузок источник файла проверяется отдельно.
Без слепых повторов. Автоматически повторяются только GET-запросы; POST, PATCH, PUT и DELETE после сетевой ошибки не запускаются повторно.
Бережно к лимитам KIT. Встроенный клиент по умолчанию ограничивает поток до 3 запросов в секунду и учитывает типичные ответы лимитера при повторах GET-запросов.

После подключения попробуйте:

Покажи заказы за сегодня и их статусы оплаты.

Подключить сервер · Посмотреть возможности · Добавить готовые сценарии

Содержание

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

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

В кабинете продавца Яндекс KIT откройте Настройки → API → «Сгенерировать токен». Скопируйте токен сразу: он показывается только один раз.

Токен даёт полный доступ к магазину и хранится открытым текстом в конфиге MCP-клиента. Относитесь к нему как к паролю: не добавляйте его в репозиторий, публичный файл или лог.

2. Добавьте сервер в AI-клиент

codex mcp add yandex-kit \
  --env YANDEX_KIT_TOKEN=ваш_токен \
  -- npx -y mcp-yandex-kit@latest

Начните новую задачу Codex, чтобы клиент загрузил сервер.

claude mcp add yandex-kit \
  -e YANDEX_KIT_TOKEN=ваш_токен \
  -- npx -y mcp-yandex-kit@latest

Начните новую сессию Claude Code.

Добавьте сервер в ~/.cursor/mcp.json:

{
  "mcpServers": {
    "yandex-kit": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-kit@latest"],
      "env": {
        "YANDEX_KIT_TOKEN": "ваш_токен"
      }
    }
  }
}

Перезагрузите окно Cursor.

Используйте локальный транспорт stdio и следующие параметры:

command: npx
args: -y, mcp-yandex-kit@latest
env: YANDEX_KIT_TOKEN=<токен магазина>

Формат и путь конфига зависят от клиента. Используйте официальную документацию приложения, а не вставляйте универсальный JSON-фрагмент в неизвестный файл.

3. Проверьте подключение

Спросите ассистента:

Проверь, подключился ли магазин. Покажи, сколько товаров в каталоге, и скажи, на что стоит обратить внимание в первую очередь.

Если ассистент видит магазин и каталог, сервер готов к работе.

Что можно поручить ассистенту

| Область | Примеры задач | | --- | --- | | Магазин | Показать магазин, владельца токена и доступные регионы. | | Каталог | Читать и изменять товары, варианты, цены, остатки, категории, коллекции и склады; просматривать загруженные изображения и документы (видеофайлы в этот список не входят). | | Фиды каталога | Получить постоянные ссылки на фиды ICML, YML и YML_GOODS. | | Заказы и клиенты | Смотреть заказы и дополнительные услуги, подтверждать и отменять заказы, читать и обновлять данные клиентов, получить ссылку на оплату для ручной отправки покупателю и сформировать акты приёма-передачи отправлений в PDF. | | Промо | Работать со скидками, промокодами и подарочными картами. | | Интеграции | Создавать, изменять, проверять и удалять вебхуки. | | Остальной API | Находить любую операцию Яндекс KIT, получать её схему и выполнять через универсальный kit_request. |

Полный список инструментов и карта покрытия находятся в docs/TOOLS.md.

get_order_payment_link возвращает подписанную постоянную ссылку: она не истекает и не отзывается, поэтому отправляйте её покупателю вручную и обдуманно. generate_order_waybills возвращает PDF-акты со ссылками, истекающими в expires_at; для пропущенных частей доставки указывается причина.

MCP-сервер или полный комплект

mcp-yandex-kit — это прямой доступ к API Яндекс KIT. Он предоставляет инструменты, а решение о том, какие из них и в какой последовательности вызвать, принимает AI-клиент.

Если вы хотите не набор инструментов, а готового оператора магазина, установите A1 Yandex KIT Skills. Навыки добавляют поверх MCP-сервера рабочие сценарии и правила: обзорные запросы ничего не меняют, бизнес-значения не придумываются, а результат разрешённого изменения читается повторно и проверяется.

npx skills@latest add ztemerbekov/a1-yandex-kit-skills -y

После установки явно вызовите навык a1-yandex-kit-setup. В Codex вызов выглядит так:

$a1-yandex-kit-setup

В другом приложении явно выберите навык с этим именем в списке команд. Setup выбирает способ, который поддерживает приложение и окружение. Если приложение поддерживает локальную одноразовую страницу, токен можно ввести туда и не помещать в чат. Для удалённой сессии setup сначала предлагает задать токен в secrets/env; если они недоступны, токен можно передать в чате. Чатовый маршрут доступен и в локальном native CLI; переданный в чат токен останется в истории чата. Затем setup проверяет подключение.

Готовые сценарии включают операционный разбор магазина, аудит и исправление каталога, запуск промо и проверку готовности к открытию.

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

Как устроено покрытие API

Сервер предоставляет 88 MCP-инструментов. У повседневных задач есть специализированные инструменты с понятными аргументами; вместе они покрывают 92 из 166 операций сохранённой спецификации Яндекс KIT.

Для остальных 74 операций используется мета-трио:

search_operations — находит операцию по ключевому слову, operationId, пути, тегу или русскому описанию.
get_operation_schema — возвращает HTTP-метод, путь, параметры, content type и развёрнутые схемы запроса и ответа.
kit_request — выполняет выбранную операцию по operationId.

Так ассистент получает удобные инструменты для частых задач, но не упирается в их фиксированный список, когда нужна редкая операция API.

Ответы списковых инструментов могут содержать машинно-читаемую информацию о покрытии: coverage, received, total_count (если его возвращает API) и pages_read. Значение coverage: "partial" означает, что список неполный, поэтому его нельзя описывать как полный. При all:true включается автопагинация с ограничением до 500 элементов за один вызов; если элементов больше, продолжайте чтение страниц. Для совместимости сохраняются поля pages и truncated.

Экспорт списков и защита персональных данных

В списковых инструментах с поддержкой CSV можно указать format: "csv". Параметр fields принимает имена полей верхнего уровня схемы элемента, например fields: ["id", "name"]; без него используются скалярные столбцы по умолчанию. Запрошенные вложенные поля попадают в ячейки как JSON и не раскладывают pricing или stocks на отдельные столбцы. Нативный XLSX не поддерживается. Первая строка CSV — комментарий # coverage: с метаданными покрытия.

Например: «Выгрузи заказы за май в CSV с датой, суммой и статусом».

В list_orders, get_order, list_customers, get_customer, list_gift_cards и get_gift_card доступен необязательный redact: true (по умолчанию false). Он маскирует в ответе имя, телефон, email, адрес и примечания. Маскирование применяется только к ответу: данные магазина и тела write-запросов не меняются, а автоматически для всех инструментов оно не включается.

Настройка

| Переменная | Обязательна | По умолчанию | Назначение | | --- | :---: | --- | --- | | YANDEX_KIT_TOKEN | да | — | API-токен магазина. | | YANDEX_KIT_BASE_URL | нет | https://api.kit.yandex.net | Базовый URL API. | | YANDEX_KIT_RPS | нет | 3 | Лимит исходящих запросов в секунду. | | YANDEX_KIT_TIMEOUT_MS | нет | 30000 | Таймаут одной попытки HTTP-запроса, мс. |

Технически сервер работает через stdio и использует Bearer-токен. Для каждого запроса применяется content type из спецификации, включая application/merge-patch+json и multipart/form-data.

Обратите внимание

Все вызовы идут в рабочий магазин. Собственной песочницы у проекта нет.
Токен хранится открытым текстом. Не передавайте конфиг другим людям и не публикуйте его.
kit_request может изменять данные. Безопасность зависит от операции, выбранной ассистентом.
Write-запросы не повторяются автоматически. После таймаута изменение могло уже примениться; слепой повтор создал бы дубликат или вторую мутацию.
Лимит API — 3 запроса в секунду на магазин. При превышении live-лимитер обычно отвечает HTTP 429 текстом limited, без Retry-After; иногда приходит HTTP 400 с кодом LIMIT_EXCEEDED. Оба ответа учитываются при автоматических повторах только GET-запросов; write-запросы не повторяются.
API Яндекс KIT находится в статусе беты. Контракт может меняться.

Документация

Установка и подключение — поддерживаемые клиенты, setup-сценарий и устранение ошибок.
Полный список MCP-инструментов — аргументы инструментов и карта всех 166 операций.
Техническое устройство — архитектура, валидация, повторы и генерация из OpenAPI.
Официальная документация Яндекс KIT — авторизация, лимиты, ошибки и OpenAPI-справочник.
Исходный код и задачи — репозиторий проекта и issue tracker.

Лицензия

MIT — см. LICENSE.