눈치 키오스크 주문/메뉴/결제 MCP 도구 모음. 메뉴 조회, 추천, 장바구니, 주문, 결제 관련 Tool을 제공하는 FastMCP 기반 서버.
Server has 20 tools with consistent verb-noun naming (create_, get_, update_, add_, remove_, confirm_, pay_, filter_, search_). All tools have descriptions in Korean, ranging 20 - 200 chars. Input schemas are present with type definitions for all parameters. However, descriptions lack English translations, making them inaccessible to non-Korean-speaking developers. Parameter descriptions are minimal (often just field names in Korean). Output schemas are not documented in the tool definitions, responses are inferred from domain models (CartResponse, MenuDetail, etc.) but not explicitly declared to the LLM. Error handling is present in code (SpringApiError, ValidationError) but not surfaced in tool descriptions. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels (WRITE, DESTRUCTIVE, IRREVERSIBLE). Composition is strong, tools chain well (create_session → add_cart_item → confirm_order → request_payment). Idempotency is addressed in code comments (e.g., cart lock retry logic) but not documented in tool descriptions.
장바구니에 메뉴를 담는다. 옵션 없으면 option_ids는 빈 배열로 전달한다.
장바구니 전체를 초기화한다.
주문 세션을 종료한다.
주문을 확정한다.
결제 성공을 처리한다. IC_CARD / VEIN_AUTH 단말기 승인 완료 후 호출한다. PENDING 상태인 paymentId에만 동작하며, 이미 처리된 결제는 400 반환.
대화 세션을 시작한다. 반드시 대화 첫 번째로 호출해야 한다. session_id를 반환한다. order_type은 DINE_IN(매장) 또는 TAKEOUT(포장).
All tool descriptions are in Korean only. Non-Korean developers cannot understand tool purpose, parameters, or when to invoke them. LLMs trained primarily on English will struggle to reason about Korean descriptions.
Output schemas are not documented in tool definitions. Responses are inferred from domain models (CartResponse, MenuDetail, etc.) but LLMs cannot see what fields to expect. This breaks downstream tool chaining and forces agents to guess field names.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 58 | <=2025-11-25 | v2 |
결제 실패를 처리한다. 단말기 승인 실패 또는 사용자 취소 시 호출한다. PENDING 상태인 paymentId에만 동작하며, 이미 처리된 결제는 400 반환.
조건에 맞는 메뉴를 필터링해 반환한다. 파라미터는 모두 Optional. - max_calorie / min_calorie: 칼로리 범위 (kcal) - min_protein: 단백질 하한 (g) - max_sodium: 나트륨 상한 (mg) - max_spicy_level / min_spicy_level: 매운맛 범위 0~5 - min_price / max_price: 가격 범위 (원) - temperature_type: HOT | COLD - vegetarian_type: VEGAN | VEGETARIAN | NONE - season: SPRING | SUMMER | FALL | WINTER | ALL - category_id: 카테고리 ID - exclude_allergies: 제외할 알레르기 콤마 구분 영문 enum (MILK, EGG, WHEAT, SOY, PEANUT, WALNUT, PINE, SHRIMP, CRAB, SQUID, CLAM, BEEF, PORK, CHICKEN, PEACH, TOMATO, BUCKWHEAT) - limit: 반환할 최대 메뉴 수 (추천은 보통 3~5 권장) - restaurant_name: 식당명 필터. 지정 시 해당 식당 + 공용 메뉴(null) 포함 - floor: 층 필터. 지정 시 해당 층 + 공용 메뉴(null) 포함
현재 장바구니 전체를 조회한다.
카테고리 목록을 조회한다.
메뉴 상세 정보와 옵션을 조회한다. 장바구니 담기 전 반드시 호출해야 한다.
메뉴 목록을 조회한다. category_id를 주면 해당 카테고리만 반환한다.
오늘 판매량 기준 인기 메뉴 목록을 반환한다. limit으로 개수를 조절한다.
바코드 결제를 요청한다. 선행 조건: confirm_order로 주문 확정이 완료된 상태여야 한다.
장바구니에서 아이템을 제거한다.
결제를 요청한다.
대화 메시지를 저장한다. role은 USER 또는 ASSISTANT 중 하나다.
메뉴명으로 검색한다. 발화에서 추출한 메뉴명을 넣으면 menuId를 포함한 목록을 반환한다.
장바구니 아이템 수량을 수정한다. item_id는 장바구니 조회 결과의 item_id(UUID)다.
주문 단계를 이동한다. step 값: BROWSE / SELECT / CONFIGURE / CHECKOUT
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels marked in metadata (READ_ONLY, WRITE, DESTRUCTIVE, IRREVERSIBLE). Agents cannot distinguish safe reads from destructive writes without explicit hints.
Parameter descriptions are minimal, often just field names in Korean with no guidance on valid ranges, formats, or dependencies. E.g., 'option_ids' has no description of what constitutes a valid option ID or how to obtain one.
Error handling is implemented in code (SpringApiError, ValidationError, retry logic) but not surfaced in tool descriptions. Agents have no guidance on what errors to expect, whether to retry, or how to recover.