ubeats-bo-mcp

MCP-сервер для UBEats Backoffice (office.ubeats.mn, хост API https://ubeats-bo-api.ubcabtech.com). Построен по тому же принципу, что и ubcab-bo-mcp: один самодостаточный api/index.ts, который работает либо через stdio (локально / Claude Desktop), либо как защищённый Bearer-токеном Streamable HTTP-эндпоинт на Vercel.

Аутентификация

Keycloak SSO — проверено 2026-08-18 на живой сессии BO:

Токены доступа живут ~5 минут; сервер кэширует их до ~30 секунд до истечения и переаутентифицируется незаметно (сначала refresh_token, затем парольная выдача).

Инструменты (21)

Отчёты (8)

Все семь эндпоинтов отчётов используют одну форму тела:

POST /v1/api/reports/{report}/list
{ "filter": { "beginDate": "2026-08-17", "endDate": "2026-08-18", "city": "11" },
  "page": 1, "limit": 20 }

Три вещи, которые легко сделать неправильно (все подтверждены тестированием на живых данных):

1. page / limit находятся на верхнем уровне, а не внутри pagination. Отправка pagination: {page, limit} молча игнорируется, и вы получаете 20 строк по умолчанию.

2. endDate является исключающим. Для одного дня передавайте следующий день. beginDate === endDate возвращает 996 "Begin date or end date is wrong!".

3. Даты должны быть в формате YYYY-MM-DD. ISO-даты или "YYYY-MM-DD HH:mm:ss" возвращают 996.

Неизвестные ключи filter молча игнорируются — ни ошибки, ни фильтрации. Всегда проверяйте итоги.

Перечисление filter.city (монгольские коды аймаков/городов, 11 = Улаанбаатар): 11 21 22 23 41 42 43 44 45 46 48 61 62 63 64 65 67 81 82 83 84 85

Заказы (6)

Заказы Cloud Kitchen и Merchant находятся в разных коллекциях — номер телефона может иметь заказы в обеих, поэтому ищите в обоих.

ubeats_order_search / _get / _state_histories, ubeats_merchant_order_search / _get / _state_histories

Каталог (6)

ubeats_provider_search, ubeats_branch_search (фильтры: name, status), ubeats_merchant_search, ubeats_kitchen_search, ubeats_menu_search, ubeats_notification_search (фильтры: beginDate, endDate, sender, senderRole, receiverPhoneNumber)

Запасной выход (1)

ubeats_bo_request — произвольный метод/путь к BO API, с аутентификацией и заголовками, обрабатываемыми автоматически. Используйте для изучения недокументированных эндпоинтов перед добавлением реального инструмента.

Локальный запуск

npm install
npm run typecheck
cp .env.example .env      # fill in creds
npm run test:login        # live smoke test: auth + one driver-revenue page
npm run compile && npm start   # stdio MCP server

Развёртывание на Vercel

Нулевая конфигурация: api/index.ts — это функция, vercel.json перенаправляет всё на неё. Три правила, перенесённые из ubcab-bo-mcp (выученные на собственном опыте):

1. Без устаревших builds + routes в vercel.json на проекте, импортированном через git — каждый путь выдаёт 404. Используйте только rewrites.

2. Без скрипта build в package.json — Vercel затем ищет public/ и развёртывание завершается ошибкой. Локальная компиляция — npm run compile.

3. Без импортов из src/ — резолвер esbuild для Node16 не отобразит .js → .ts и вы получите 500. Всё находится в одном файле.

Развёртывайте путём отправки в main (интеграция с git), а не из CLI.

Переменные окружения, которые нужно установить в Vercel: UBEATS_BO_USERNAME, UBEATS_BO_PASSWORD, UBEATS_BO_MCP_AUTH_TOKEN (openssl rand -hex 32).

Проверка работоспособности: GET /health → {"status":"ok","server":"ubeats-bo-mcp"}

Известные пробелы

• order-duration's meta?action=list возвращает 998 permission_denied для некоторых ролей, хотя /list работает. Вместо этого читайте столбцы из ответа.

• financial-report's includeCancelled отображается на filter.state; BO показывает его как флажок, но эффект на бэкенде не был подтверждён на живых данных.

• /v1/api/categories/list возвращает 998 для протестированной учётной записи.

• Нет маршрутов списка products, delivery-tariffs, delivery-zones, feedbacks или lots в /v1/api/ — эти экраны BO используют другие пути.