ubeats-bo-mcp

MCPサーバー for the UBEats Backoffice (office.ubeats.mn, API host https://ubeats-bo-api.ubcabtech.com)。ubcab-bo-mcp と同じパターンで構築: 自己完結型の api/index.ts が stdio (ローカル / Claude Desktop) または Vercel 上の Bearer 認証付き Streamable HTTP エンドポイントとして動作します。

認証

Keycloak SSO — 2026-08-18に実際のBOセッションで確認済み:

アクセストークンの有効期限は約5分。サーバーは期限切れの約30秒前までキャッシュし、サイレントに再認証します（最初にrefresh_token、次にpassword grant）。

ツール (21)

レポート (8)

All seven report endpoints share one body shape:

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

間違いやすい3つのポイント（すべて実際のテストで確認済み）:

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 から引き継いだ3つのルール（苦労して学びました）:

1. gitインポートしたプロジェクトの vercel.json にレガシーな builds + routes を入れない — すべてのパスが404になります。rewrites のみを使用してください。

2. package.json に build スクリプトを入れない — Vercelが public/ を探してデプロイに失敗します。ローカルコンパイルは npm run compile です。

3. src/ からのインポートをしない — esbuildのNode16リゾルバーが .js → .ts をマッピングできず、500エラーになります。すべては1つのファイルにあります。

CLIからではなく、main ブランチへのプッシュ（git連携）でデプロイします。

Vercelで設定する環境変数: 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"}

既知のギャップ

• order-duration の meta?action=list は、一部のロールで /list が動作するにもかかわらず 998 permission_denied を返します。代わりにレスポンスから列を読み取ってください。

• financial-report の includeCancelled は filter.state にマッピングされます。BOではチェックボックスとして表示されますが、バックエンドの効果は実際には確認されていません。

• テストしたアカウントでは /v1/api/categories/list が 998 を返します。

• /v1/api/ 以下に products、delivery-tariffs、delivery-zones、feedbacks、lots のリストルートはありません — これらのBO画面は異なるパスを使用しています。