myhotlunchbox-mcp

My Hot Lunchbox용 MCP 서버 — 학교 급식 달력을 읽고, 학생을 관리하고, 주문을 넣고 변경하며, 학부모 계정에서 배송 및 결제를 추적합니다.

AI(Claude Code)가 개발 및 유지 관리합니다. 사용에 따른 책임은 본인에게 있습니다.

설치

npx myhotlunchbox-mcp

또는 Claude Code 플러그인으로:

/plugin marketplace add chrischall/myhotlunchbox-mcp
/plugin install myhotlunchbox-mcp

Related MCP server: Corben MCP Server

구성

MYHOTLUNCHBOX_USERNAME=you@example.com
MYHOTLUNCHBOX_PASSWORD=…

이것이 전체 설정입니다. 서버는 ordernow.myhotlunchbox.com에 대해 실제 서버 측 로그인(OAuth2 password grant)을 수행하고 수신한 refresh token으로 세션을 갱신합니다 — 브라우저 확장 프로그램도, 로그인된 탭도, 캡처된 쿠키도 필요 없습니다. 디스크에 아무것도 기록되지 않습니다.

MYHOTLUNCHBOX_BASE_URL은 앱 오리진이 이동하는 경우 이를 재정의합니다.

서버는 자격 증명 없이 부팅되므로 호스트의 설치 시 tools/list 프로브가 계속 작동합니다. 구성 오류는 첫 번째 도구 호출 시 표면화됩니다.

도구

34개의 도구, 모두 mhlb_ 접두사가 붙습니다. 20개의 읽기 도구는 모두 실제 학부모 계정에 대해 실시간으로 검증되었습니다(node scripts/verify-reads.mjs). 14개의 쓰기 도구는 검증되지 않았습니다 — 아래 참조.

계정 — mhlb_whoami, mhlb_session_reset

학생 — mhlb_list_students, mhlb_get_student_form, mhlb_new_student_form, mhlb_create_student, mhlb_update_student, mhlb_delete_student

달력 — mhlb_get_calendar, mhlb_get_day

주문 — mhlb_get_cart, mhlb_get_cart_tabs, mhlb_get_menu, mhlb_get_order_form, mhlb_get_order, mhlb_create_order, mhlb_update_order, mhlb_delete_order

결제 — mhlb_list_transactions, mhlb_get_transaction, mhlb_list_subscriptions, mhlb_get_subscription_settings, mhlb_set_subscription_enabled, mhlb_unsubscribe_order, mhlb_list_gift_cards, mhlb_apply_gift_card, mhlb_get_coupon, mhlb_apply_coupon, mhlb_remove_coupon

체크아웃 — mhlb_init_checkout, mhlb_checkout

보고서 — mhlb_print_calendar, mhlb_print_orders, mhlb_print_transaction. 이들은 실제 PDF를 반환합니다. 각각 파일을 작성하고 해당 경로를 반환하거나, inline: true로 바이트를 인라인으로 반환합니다. MYHOTLUNCHBOX_OUTPUT_DIR을 설정하여 저장 위치를 선택할 수 있습니다(기본값은 작업 디렉터리). 기존 파일은 절대 덮어쓰지 않습니다.

쓰기는 확인 게이트가 적용됩니다

모든 변경 도구는 confirm을 받습니다. confirm: true가 없으면 네트워크 호출을 전혀 하지 않고 정확히 무엇을 보낼지에 대한 dry-run 미리보기를 반환합니다.

mhlb_checkout은 실제 결제 수단에 청구합니다. 서버는 orderIds에서 청구 금액을 산정하므로 클라이언트 측에서 금액을 바인딩할 수 없습니다 — 확인할 요청에 총액이 없습니다. 따라서 expectedTotal은 귀속(attribution)이지 보호 장치가 아닙니다: 예상한 금액을 명시하면 dry-run과 결과에 기록되어 예상치 못한 청구가 발생한 호출을 추적할 수 있습니다. 도구가 명백히 거부하는 것은 orderIds 없이 0이 아닌 총액을 결제하는 경우뿐입니다.

쓰기: 형태는 캡처됨, 수락 여부는 미검증

npm run capture:writes는 모든 변경 도구를 로컬 프록시에 대해 실행합니다. 이 프록시는 읽기를 실제 서비스로 전달하지만 쓰기는 자체적으로 응답하므로, 페이로드는 실제 서버 모델에서 구성되고 업스트림에서는 아무 일도 일어나지 않습니다. 또한 13개 모두가 confirm: true 없이는 아무것도 보내지 않는다는 것을 증명합니다.

이를 통해 확립되고 수정된 사항: mhlb_delete_order와 mhlb_unsubscribe_order는 주문 모델이 아닌 {orderId, eventDate, studentId, isRepeated, isSubscribed}를 받으며, 체크아웃은 {orderIds, checkoutType, couponCode, giftCardCode, schoolDonations}를 받습니다.

여전히 검증되지 않은 것은 서버가 이러한 본문을 수락하는지 여부입니다. 형태는 수락을 의미하지 않습니다. 실제 쓰기만이 그것을 보여주며, 지금까지 어떤 쓰기도 이루어지지 않았습니다. 확인 전에 dry-run 미리보기를 검토하고, 확인 후에 다시 읽어보세요 — 200은 쓰기가 영구적으로 반영되었음을 증명하지 않습니다.

mhlb_checkout에 대한 두 가지 제한 사항:

• 계정에 이미 저장된 카드로만 결제할 수 있습니다. 새 카드로 결제하려면 브라우저에서 Stripe.js가 생성한 Stripe 토큰이 필요하며, 서버 측 클라이언트는 이를 생성할 수 없습니다.

• 멱등성 키를 생성하여 반환합니다. 체크아웃이 모호하게 실패하면 새 호출 대신 동일한 idempotencyKey로 재시도하세요 — 이것이 재시도가 두 번째 청구가 되는 것을 막는 방법입니다.

주문은 읽기-수정-쓰기 방식입니다

"항목 X 추가" 호출은 없습니다. 모델을 가져와서 편집하고 전체를 다시 보내세요:

1. mhlb_get_menu — 특정 날짜에 학생이 주문 가능한 항목

2. mhlb_get_order_form — 작성할 주문 모델

3. mhlb_create_order — 다시 보내기(confirm: true 포함)

4. mhlb_init_checkout → mhlb_checkout — 가격 산정 후 결제

페이로드에서 생략된 필드는 보존되지 않고 삭제됩니다.

셸 스킬

skills/myhotlunchbox는 MCP 프로세스 없이 curl을 사용하여 셸에서 동일한 계정을 다룹니다. 스크립트에서 또는 이 서버가 설치되지 않은 머신에서 유용합니다.

참고 사항

• /deliveryInfo/* 및 /calendar/viewMatchedVendors는 컴파일된 클라이언트에서 학부모용으로 보이지만 학부모 계정에 대해서는 403을 반환합니다 — 이들은 학교/공급업체 대시보드에 속합니다. 이를 감싸는 도구는 없습니다.

• 학부모 역할만 연결되어 있습니다. 동일한 API는 학교 관리자 및 공급업체 역할도 제공합니다. 해당 엔드포인트는 403을 반환하며, 클라이언트는 이를 세션 오류가 아닌 역할 불일치로 보고합니다.

• docs/MYHOTLUNCHBOX-API.md는 API가 어떻게 매핑되었고 정확히 무엇이 검증되었는지 기록합니다. docs/api-surface.txt는 전체 359개 엔드포인트 추출본입니다.

라이선스

MIT