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, 그 다음 password grant).

도구 (21개)

보고서 (8개)

7개의 보고서 엔드포인트는 모두 동일한 본문 형식을 공유합니다:

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. 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는 /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 화면은 다른 경로를 사용합니다.