ubeats-bo-mcp

MCP-Server für das UBEats Backoffice (office.ubeats.mn, API-Host https://ubeats-bo-api.ubcabtech.com). Basierend auf dem gleichen Muster wie ubcab-bo-mcp: eine eigenständige api/index.ts, die entweder über stdio (lokal / Claude Desktop) oder als bearer-geschützter Streamable-HTTP-Endpunkt auf Vercel läuft.

Authentifizierung

Keycloak SSO — verifiziert am 18.08.2026 gegen eine Live-BO-Sitzung:

Access-Tokens leben ca. 5 Minuten; der Server cacht bis ca. 30 Sekunden vor Ablauf und führt eine erneute Authentifizierung durch (zuerst refresh_token, dann Passwort-Grant).

Tools (21)

Berichte (8)

Alle sieben Berichts-Endpunkte teilen sich eine Körperform:

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

Drei Dinge, die leicht falsch gemacht werden können (alle durch Live-Tests bestätigt):

1. page / limit sind auf oberster Ebene, nicht innerhalb von pagination. Das Senden von pagination: {page, limit} wird stillschweigend ignoriert und Sie erhalten die Standardeinstellung von 20 Zeilen.

2. endDate ist exklusiv. Für einen einzelnen Tag übergeben Sie den nächsten Tag. beginDate === endDate gibt 996 "Begin date or end date is wrong!" zurück.

3. Daten müssen YYYY-MM-DD sein. ISO-Datumsangaben oder "YYYY-MM-DD HH:mm:ss" geben 996 zurück.

Unbekannte filter-Schlüssel werden stillschweigend ignoriert — kein Fehler, keine Filterung. Überprüfen Sie immer stichprobenartig die Summen.

filter.city-Enum (Mongolische Aimag/Stadt-Codes, 11 = Улаанбаатар): 11 21 22 23 41 42 43 44 45 46 48 61 62 63 64 65 67 81 82 83 84 85

Bestellungen (6)

Cloud-Kitchen- und Merchant-Bestellungen leben in separaten Sammlungen — eine Telefonnummer kann Bestellungen in beiden haben, also suchen Sie in beiden.

ubeats_order_search / _get / _state_histories, ubeats_merchant_order_search / _get / _state_histories

Katalog (6)

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

Notausstieg (1)

ubeats_bo_request — beliebige Methode/Pfad gegen die BO-API, mit Authentifizierung und Headern. Verwenden Sie es, um undokumentierte Endpunkte zu testen, bevor Sie ein echtes Tool hinzufügen.

Lokale Ausführung

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-Bereitstellung

Null-Konfiguration: api/index.ts ist die Funktion, vercel.json leitet alles auf sie um. Drei Regeln, die von ubcab-bo-mcp übernommen wurden (auf die harte Tour gelernt):

1. Keine veralteten builds + routes in vercel.json bei einem per Git importierten Projekt — jeder Pfad gibt 404. Verwenden Sie nur rewrites.

2. Kein build-Skript in package.json — Vercel sucht dann nach public/ und die Bereitstellung schlägt fehl. Die lokale Kompilierung erfolgt mit npm run compile.

3. Keine Importe aus src/ — esbuilds Node16-Resolver kann .js nicht auf .ts abbilden und Sie erhalten einen 500. Alles lebt in der einen Datei.

Bereitstellung durch Pushen auf main (Git-Integration), nicht über die CLI.

Umgebungsvariablen, die in Vercel gesetzt werden müssen: UBEATS_BO_USERNAME, UBEATS_BO_PASSWORD, UBEATS_BO_MCP_AUTH_TOKEN (openssl rand -hex 32).

Health-Check: GET /health → {"status":"ok","server":"ubeats-bo-mcp"}

Bekannte Lücken

• order-duration's meta?action=list gibt 998 permission_denied für einige Rollen zurück, obwohl /list funktioniert. Lesen Sie stattdessen die Spalten aus der Antwort ab.

• financial-report's includeCancelled wird auf filter.state abgebildet; das BO rendert es als Kontrollkästchen, aber der Backend-Effekt wurde nicht live bestätigt.

• /v1/api/categories/list gibt 998 für das getestete Konto zurück.

• Keine products-, delivery-tariffs-, delivery-zones-, feedbacks- oder lots- Listenroute unter /v1/api/ — diese BO-Bildschirme verwenden andere Pfade.