Yango Delivery MCP

English | Русский

A1 Yango Delivery MCP подключает AI-приложение к корпоративному аккаунту Yango Delivery. Можно обычными словами рассчитать экспресс-доставку, заказать курьера, следить за маршрутом и отправить получателю ссылку для отслеживания.

Сервер работает с международным Express Claims API. Доставка на следующий день, ПВЗ и постаматы не поддерживаются.

• 13 инструментов. Семь для работы с доставкой, пять для отслеживания и связи с курьером, ещё один — для прямых запросов к API.
• Расчёт до заказа. Можно узнать текущую цену, расстояние и ETA без создания заявки.
• Создание и заказ разделены. Заявку можно подготовить и проверить до запуска поиска курьера.
• Сопровождение активной доставки. Доступны статус, положение курьера, ETA по точкам, временный телефон, код подтверждения и публичная ссылка для получателя.

Начните с запроса:

Рассчитай доставку посылки 2 кг с [адреса отправления] на [адрес получателя].

Подключить сервер · Посмотреть сценарии · Открыть техническую документацию

Увидеть работу за минуту

Вы: Рассчитай доставку посылки 2 кг с нашего склада на адрес покупателя.

Ассистент: Верну текущую цену, расстояние и ETA. Заявка на доставку не создаётся.

Вы: Создай заявку и остановись перед заказом курьера.

Ассистент: Заявка создана. Перед подтверждением покажу её id, цену, статус и версию.

Вы: Подтверди предложение.

Ассистент: Заявка подтверждена, начался поиск курьера.

Вы: Пришли ссылку для отслеживания получателю.

Ассистент: Верну публичную ссылку для точки назначения.

Цена, доступность доставки, статус и условия отмены всегда приходят из подключённого аккаунта и актуального ответа API.

Содержание

• Быстрый старт
• Что можно поручить
• Как доставка становится реальной
• Что изменится в аккаунте
• Получение доступа
• Настройка
• Данные и телеметрия
• Ограничения и фоновая работа
• Техническая документация
• Поддержка

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

Нужны Node.js 20+, корпоративный аккаунт Yango Delivery и интеграционный токен.

1. Получите интеграционный токен.

2. Добавьте сервер в своё AI-приложение по одной из инструкций ниже.

3. Начните с расчёта:

   Рассчитай доставку посылки 2 кг с [адреса отправления] на [адрес получателя].

Через интерфейс приложения:

1. Откройте Settings → Plugins → MCP servers.
2. Нажмите Add server.
3. Добавьте команду запуска npx -y mcp-yango-delivery@latest и переменную окружения YANGO_DELIVERY_TOKEN со своим токеном.

Через командную строку:

codex mcp add yango-delivery \
  --env YANGO_DELIVERY_TOKEN=ваш_токен \
  -- npx -y mcp-yango-delivery@latest

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

codex mcp list

Официальная инструкция Codex

claude mcp add \
  --env YANGO_DELIVERY_TOKEN=ваш_токен \
  --transport stdio \
  --scope user \
  yango-delivery \
  -- npx -y mcp-yango-delivery@latest

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

claude mcp list

Официальная инструкция Claude Code

1. Откройте Claude Desktop и перейдите в Settings → Developer.
2. Нажмите Edit Config.
3. Добавьте сервер в mcpServers:

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

Если кнопки Edit Config нет, откройте файл конфигурации напрямую:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Официальная инструкция Claude Desktop

Добавьте пользовательский сервер в ~/.cursor/mcp.json на macOS/Linux или в %USERPROFILE%\.cursor\mcp.json на Windows:

{
  "mcpServers": {
    "yango-delivery": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yango-delivery@latest"],
      "env": {
        "YANGO_DELIVERY_TOKEN": "ваш_токен"
      }
    }
  }
}

Официальная инструкция Cursor

Откройте палитру команд и выполните MCP: Open User Configuration, затем добавьте:

{
  "servers": {
    "yango-delivery": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yango-delivery@latest"],
      "env": {
        "YANGO_DELIVERY_TOKEN": "${input:yango_delivery_token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "yango_delivery_token",
      "description": "Интеграционный токен Yango Delivery",
      "password": true
    }
  ]
}

Проверьте сервер командой MCP: List Servers.

Официальная инструкция VS Code

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

Рассчитать экспресс-доставку

• Узнать текущую цену, расстояние и ETA без создания заявки.
• Рассчитать курьерскую, экспресс- или грузовую доставку по адресам, весу и размерам отправления.
• Проверить, может ли API построить маршрут и выполнить требования к машине или доставке.

Подготовить заявку и заказать курьера

• Создать заявку с контактами отправителя и получателя, точками маршрута, товарами и требованиями к доставке.
• Проверить полученную цену, статус и версию заявки до заказа.
• Подтвердить успешно рассчитанную заявку и запустить поиск курьера.
• Найти заявку по id, телефону, статусу, дате или внешнему номеру заказа.

Следить за доставкой и связаться с курьером

• Получить текущее положение курьера и ETA для каждой точки маршрута.
• Сформировать публичную ссылку для отслеживания получателем.
• Получить временный переадресованный номер курьера.
• Получить код подтверждения забора или вручения, если он предусмотрен для текущей заявки.

Проверить условия и отменить доставку

• Узнать, будет отмена бесплатной, платной или уже недоступной.
• Отменить заявку с её актуальной версией и режимом отмены, который вернул API.

Использовать дополнительные методы API

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

Полные схемы, поля ответов и статусы находятся в справочнике инструментов.

Как доставка становится реальной

1. Расчёт. Сервер возвращает текущую цену, расстояние и ETA, ничего не создавая.
2. Создание. В аккаунте появляется заявка и начинается её оценка. По умолчанию курьер ещё не заказан.
3. Проверка. Сервер читает актуальный статус, цену и версию заявки. Успешная заявка переходит в состояние готовности к подтверждению.
4. Подтверждение. Начинается поиск курьера. С этого момента доставка заказана и может привести к списанию.
5. Отслеживание. После назначения курьера можно получать его положение, ETA, контактные данные и ссылку для получателя.

Рассчитанное предложение обычно действует около десяти минут. Если при создании заявки передать auto_accept: true, отдельные шаги проверки и подтверждения пропускаются, а курьер может быть заказан автоматически.

Что изменится в аккаунте

Сервер передаёт AI-клиенту MCP-аннотации чтения, записи и разрушительных действий. Когда и как запрашивать подтверждение, решает само AI-приложение.

| Действие | Результат | Изменяет аккаунт | |---|---|---:| | Расчёт цены | Возвращает текущую цену, расстояние и ETA | Нет | | Чтение, поиск и отслеживание | Возвращает данные заявки, курьера и условия отмены | Нет | | Создание заявки | Добавляет реальную заявку, но по умолчанию ещё не заказывает курьера | Да | | Подтверждение заявки | Запускает поиск курьера и может привести к списанию | Да | | Отмена заявки | Отменяет доставку; может взиматься комиссия | Да | | raw_request | Вызывает другой метод API, включая возможную запись | Зависит от метода |

При создании используется уникальный request_id: повтор с тем же id вернёт ту же заявку. Подтверждение и отмена не повторяются автоматически после сетевой ошибки или ответа 5xx, потому что операция могла уже выполниться. Перед новой попыткой прочитайте актуальное состояние заявки.

Получение доступа

1. Зарегистрируйтесь как корпоративный клиент Yango Delivery и заключите договор на доставку.
2. Откройте раздел Integration в личном кабинете.
3. Нажмите Get token.
4. Добавьте токен в AI-клиент как YANGO_DELIVERY_TOKEN.

Токен привязан к корпоративному аккаунту. Он не истекает сам по себе, но сбрасывается при изменении пароля аккаунта.

Интеграционный токен хранится открытым текстом в локальной конфигурации AI-клиента. Относитесь к нему как к паролю и не добавляйте конфигурацию с реальным токеном в Git.

Настройка

| Переменная | Обязательна | По умолчанию | Что задаёт | |---|---:|---|---| | YANGO_DELIVERY_TOKEN | да | — | Bearer-токен из кабинета доставки | | YANGO_DELIVERY_BASE_URL | нет | https://b2b.taxi.yandex.net | Другой корневой адрес API | | YANGO_DELIVERY_LANG | нет | en | Значение заголовка Accept-Language | | YANGO_DELIVERY_TIMEOUT_MS | нет | 60000 | Таймаут одного запроса, мс | | YANGO_DELIVERY_MAX_RETRIES | нет | 3 | Максимальное число повторов при временных ошибках; операции записи не повторяются, кроме идемпотентных | | ASKADS_TELEMETRY | нет | включена | 0, false, off или no отключает анонимную телеметрию |

Данные и телеметрия

Запросы к Yango Delivery

Сервер запускается на вашей машине и передаёт данные заявки напрямую на b2b.taxi.yandex.net. Интеграционный токен добавляется только к запросам на настроенный хост API. Даже raw_request принимает относительный путь и блокирует переход на другой хост.

Анонимная телеметрия

По умолчанию сервер отправляет на usage.gistrec.cloud технические события: запуск сервера, имя вызванного инструмента и фиксированный код причины неудачного запуска.

В события входят случайный идентификатор установки, версия пакета, имя и версия AI-клиента, версия Node.js и операционная система. Интеграционный токен, данные заявки, аргументы инструментов и тексты запросов не читаются и не отправляются. Телеметрия ограничена таймаутом в две секунды и не блокирует вызов инструмента.

Чтобы отключить телеметрию, добавьте:

ASKADS_TELEMETRY=0

Реализация находится в src/telemetry.ts.

Ограничения и фоновая работа

• Песочница не описана. Считайте создание и подтверждение заявки операциями в реальном аккаунте.
• Предложение ограничено по времени. Рассчитанная цена обычно действует около десяти минут; перед подтверждением прочитайте актуальное состояние заявки.
• Отслеживание работает для активной заявки. Положение, ETA, контактные данные и ссылки могут быть недоступны до назначения курьера или после завершения доставки.
• Числовые квоты API не опубликованы. При ответе 429 сервер учитывает Retry-After, если он передан, и делает не больше числа повторов из YANGO_DELIVERY_MAX_RETRIES.
• Фонового наблюдения нет. Сервер работает только во время вызова из AI-приложения. Если приложение поддерживает задания по расписанию, оно может периодически проверять активную доставку.
• Автоматического отката нет. После неопределённого результата подтверждения или отмены прочитайте заявку перед повторной операцией.

Техническая документация

• Каталог MCP-возможностей — страницы по пользовательским задачам для каждого инструмента.
• Все инструменты — входные схемы, ответы, статусы и ошибки.
• Разработка — локальная настройка и проверки проекта.
• Публикация — выпуск пакета и публикация в каталогах MCP.
• npm-пакет — опубликованная версия mcp-yango-delivery.
• API Yango/Yandex Delivery — исходная документация методов.

Поддержка

Нашли ошибку или не хватает сценария? Создайте issue или напишите в Telegram.