ubeats-bo-mcp

Servidor MCP para el UBEats Backoffice (office.ubeats.mn, host de API https://ubeats-bo-api.ubcabtech.com). Construido con el mismo patrón que ubcab-bo-mcp: un api/index.ts autónomo que se ejecuta a través de stdio (local / Claude Desktop) o como un endpoint HTTP Streamable protegido por bearer token en Vercel.

Autenticación

Keycloak SSO — verificado el 18-08-2026 contra una sesión activa del BO:

Los tokens de acceso duran ~5 minutos; el servidor los almacena en caché hasta ~30 segundos antes de su vencimiento y se reautentica silenciosamente (primero refresh_token, luego concesión de contraseña).

Herramientas (21)

Reportes (8)

Los siete endpoints de reportes comparten una misma estructura de cuerpo:

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

Tres cosas que son fáciles de equivocar (todas confirmadas mediante pruebas en vivo):

1. page / limit están al nivel superior, no dentro de pagination. Enviar pagination: {page, limit} se ignora silenciosamente y se obtienen las 20 filas predeterminadas.

2. endDate es exclusivo. Para un solo día, pasa el día siguiente. beginDate === endDate devuelve 996 "¡La fecha de inicio o la fecha de fin es incorrecta!".

3. Las fechas deben estar en formato YYYY-MM-DD. Las fechas ISO o "YYYY-MM-DD HH:mm:ss" devuelven 996.

Las claves filter desconocidas se ignoran silenciosamente — sin error, sin filtrado. Siempre verifica los totales.

Enumerado de filter.city (códigos de aimag/ciudad de Mongolia, 11 = Улаанбаатар): 11 21 22 23 41 42 43 44 45 46 48 61 62 63 64 65 67 81 82 83 84 85

Pedidos (6)

Los pedidos de Cloud Kitchen y de comercios viven en colecciones separadas — un número de teléfono puede tener pedidos en ambas, así que busca en ambas.

ubeats_order_search / _get / _state_histories, ubeats_merchant_order_search / _get / _state_histories

Catálogo (6)

ubeats_provider_search, ubeats_branch_search (filtros: name, status), ubeats_merchant_search, ubeats_kitchen_search, ubeats_menu_search, ubeats_notification_search (filtros: beginDate, endDate, sender, senderRole, receiverPhoneNumber)

Vía de escape (1)

ubeats_bo_request — método/ruta arbitrarios contra la API del BO, con autenticación y encabezados gestionados. Úsalo para sondear endpoints no documentados antes de agregar una herramienta real.

Ejecución local

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

Despliegue en Vercel

Configuración cero: api/index.ts es la función, vercel.json reescribe todo hacia ella. Tres reglas heredadas de ubcab-bo-mcp (aprendidas por las malas):

1. Sin builds + routes heredados en vercel.json en un proyecto importado por git — cada ruta devuelve 404. Usa solo rewrites.

2. Sin script build en package.json — Vercel entonces busca public/ y el despliegue falla. La compilación local es npm run compile.

3. Sin importaciones desde src/ — el resolvedor Node16 de esbuild no mapeará .js → .ts y obtendrás un 500. Todo vive en el único archivo.

Despliega enviando a main (integración con git), no desde la CLI.

Variables de entorno a configurar en Vercel: UBEATS_BO_USERNAME, UBEATS_BO_PASSWORD, UBEATS_BO_MCP_AUTH_TOKEN (openssl rand -hex 32).

Verificación de estado: GET /health → {"status":"ok","server":"ubeats-bo-mcp"}

Brechas conocidas

• El meta?action=list de order-duration devuelve 998 permission_denied para algunos roles aunque /list funciona. Lee las columnas de la respuesta en su lugar.

• includeCancelled de financial-report se asigna a filter.state; el BO lo renderiza como una casilla de verificación pero el efecto en el backend no se confirmó en vivo.

• /v1/api/categories/list devuelve 998 para la cuenta probada.

• No hay rutas de listado products, delivery-tariffs, delivery-zones, feedbacks o lots bajo /v1/api/ — esas pantallas del BO usan rutas diferentes.