ubeats-bo-mcp

面向 UBEats Backoffice（office.ubeats.mn，API 主机 https://ubeats-bo-api.ubcabtech.com）的 MCP 服务器。它遵循与 ubcab-bo-mcp 相同的模式：一个自包含的 api/index.ts，可在 stdio （本地 / Claude Desktop）上运行，也可作为 Vercel 上受 bearer 保护的 Streamable HTTP 端点运行。

认证

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 枚举（蒙古 aimag/城市代码，11 = Улаанбаатар）： 11 21 22 23 41 42 43 44 45 46 48 61 62 63 64 65 67 81 82 83 84 85

订单（6）

云厨房和商户订单位于独立的集合中——一个电话号码 可能在两者中都有订单，因此请同时搜索两者。

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. 在通过 git 导入的项目中，vercel.json 里不要用旧的 builds + routes —— 否则每个路径都会 404。只能使用 rewrites。

2. package.json 中不要有 build 脚本 —— 否则 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 的 meta?action=list 对某些角色返回 998 permission_denied， 即使 /list 可以正常工作。请改为从响应中读取列信息。

• financial-report 的 includeCancelled 映射到 filter.state；BO 将其 渲染为复选框，但后端效果未经过实时确认。

• /v1/api/categories/list 对测试的账户返回 998。

• 在 /v1/api/ 下没有 products、delivery-tariffs、delivery-zones、 feedbacks 或 lots 列表路由——那些 BO 界面使用不同的路径。