heb-mcp.skill (TikTok-2-HEB) 에이전트 스킬
실시간 H-E-B 장바구니를 관리하고, 구매 이력에서 선호하는 가정용 제품을 찾아내며, 쿠폰을 적용하고, 요리 영상 URL을 가구 규모에 맞게 조정된 H-E-B 장바구니로 변환합니다. 품절 상품은 결정론적 방식으로 대체됩니다.
🎯 실행 조건
다음 상황에서 이 스킬을 활성화하세요:
- 사용자가 H-E-B 상품을 검색하거나, 장바구니를 확인하거나, 선호 매장이나 배송 방식(Curbside vs. Delivery)을 변경하거나, 쿠폰을 적용하거나, H-E-B 장바구니에 식료품을 추가/제거해 달라고 요청할 때 (예: "H-E-B 장바구니에 흰 우유와 버터 토르티야를 추가해줘").
- 인증된 사용자가 TikTok (
tiktok.com,vm.tiktok.com), Instagram Reels (instagram.com/reel/), 또는 YouTube Shorts (youtube.com/shorts/)의 요리 또는 레시피 URL을 공유할 때. - 사용자가 레시피 영상의 재료를 변환하거나, 분량을 조절하거나, 주문해 달라고 요청할 때 (예: "이 레시피 재료를 H-E-B에서 주문해줘", "이 TikTok 저녁 메뉴를 내 장바구니에 넣어줘").
- 사용자가 기존 장바구니 검토 스레드에 답장하여 장바구니 조정을 요청할 때 (예: "간장 추가해줘", "일반 연어를 야생 홍연어로 바꿔줘", "그 교체를 영구적으로 적용해줘").
- 사용자가
heb-mcp.skill(TikTok-2-HEB)을 처음 설정하거나 구성해 달라고 요청할 때.
🚀 최초 설정 (에이전트 주도 온보딩)
사용자가 이 프로젝트 설정을 요청하면 기술적인 단계를 대신 처리하고, 간단한 일반 언어 질문만 짧게 하세요:
- 환경 및 바이너리 설치:
uv venv --python 3.11 .venv && source .venv/bin/activate && uv pip install -r requirements.txt playwright install chromium cp -n .env.example .env cp -n config/household.example.yaml config/household.yaml cp -n config/pantry_staples.example.json config/pantry_staples.json - 간단한 설정 질문:
- 선호 H-E-B 매장 및 배송 방식: 어느 H-E-B 매장을 이용하는지 물어보고 (
.env의HEB_STORE_ID와config/household.yaml의store를 업데이트하고, 요청 시 활성 매장을 변경하거나 Curbside Pickup과 Home Delivery를 전환할 수 있도록 도와줍니다). - 가구 규모: 몇 명의 성인/아이를 위해 요리하는지 물어봅니다 (
config/household.yaml업데이트).
- 선호 H-E-B 매장 및 배송 방식: 어느 H-E-B 매장을 이용하는지 물어보고 (
- 세션 수집 및 과거 주문 동기화: 사용자에게 Safari 또는 Chrome에서
heb.com에 로그인했는지 확인하라고 요청한 후 다음 명령어를 실행합니다:python scripts/heb_client.py --harvest python scripts/cache_manager.py update-preferred-skus python tests/test_skill_setup.py - 자동 일일 토큰 갱신 크론잡 설정: 사용자가 직접 다시 로그인할 필요 없도록, 24시간마다 반복되는 크론잡(
0 9 * * * cd <REPO_PATH> && .venv/bin/python scripts/heb_client.py --harvest >/dev/null 2>&1)을 설치하도록 강력히 권장하세요.
🔒 운영 불변 조건 및 안전 장치
- 엄격한 사람 개입 결제 게이트:
- 에이전트는 장바구니에 상품을 담고 디지털 쿠폰을 적용합니다.
- 에이전트는 절대 결제를 진행하거나, 배송/픽업 시간을 예약하거나, 주문을 최종 확정해서는 안 됩니다.
- 최종 검토와 결제 실행은 항상 공식 My H-E-B 모바일 앱 내에서 사용자의 몫입니다.
- 인증 없는 추출:
- 개인 TikTok/Instagram 로그인이나 세션 쿠키 없이
scripts/extract_recipe_media.py를 항상 호출합니다.
- 개인 TikTok/Instagram 로그인이나 세션 쿠키 없이
- 캐시 오염 방지 불변 조건:
- 품절 대체 상품(티어 2/3/4)은 해당 장바구니 주문에 한해 임시로만 유지되어야 합니다.
- 사용자가 명시적으로 "그 교체를 영구적으로 적용해줘" 또는 "항상 이 브랜드를 사용해"라고 명령하지 않는 한
cache/recipes/<slug>.yaml의primary_sku를 절대 덮어쓰지 마세요.
- 어린이 친화 조리 분리:
kid_friendly_split이 활성화된 경우, 매운맛 성분(sriracha,chili flakes,cayenne,jalapeños)을 기본 팬 조리와 분리하세요. 메인 요리는 순하게 유지하고, 아이의 몫을 먼저 덜고, 성인 몫에만 양념을 더합니다.- 단백질과 질식 위험 식품은 1/2인치 크기로 잘라야 한다는 알림을 추가하세요.
- 자동 토큰 갱신 (일일 크론잡 권장):
- H-E-B의 단기 세션 액세스 토큰(
sat)은 30분마다 갱신되지만,heb_graphql.py는 장기 세션 토큰(sst)을 사용하여 필요 시 자동으로 갱신합니다. - 초기 설정 중이나 세션을 수집/갱신한 후에는 사용자에게 24시간마다 실행되는 자동 크론잡을 설정하도록 적극적으로 권장하여 H-E-B 세션과 안티봇 토큰(
reese84)이 백그라운드에서 계속 유효하게 유지되도록 하세요.
- H-E-B의 단기 세션 액세스 토큰(
🛠️ 단계별 실행 워크플로우
1단계: 사전 캐시 조회
미디어 추출이나 API 호출을 수행하기 전에, 비디오가 이미 파싱되어 캐시되었는지 확인합니다:
python scripts/cache_manager.py lookup --query "<VIDEO_URL_OR_ID>"
- HIT (캐시 적중): 캐시된 레시피 YAML을 로드합니다. 캐시된
primary_sku정의를 사용하여 4단계 (장바구니 담기) 로 바로 진행합니다. - MISS (캐시 미스): 2단계 (미디어 추출) 로 진행합니다.
2단계: 인증 없는 멀티모달 미디어 추출
3단계 추출 파이프라인을 실행합니다:
python scripts/extract_recipe_media.py "<VIDEO_URL>"
- 1단계: 비디오 제목, 설명, 업로더, 자동 자막을 캡처합니다.
- 2단계: 자막 큐를 정리하고, 타임스탬프를 제거하며, 반복되는 자막을 중복 제거합니다.
- 3단계: 대본이 너무 짧은 경우(< 3개의 요리 측정 토큰), 자동으로 오디오 스트림 또는 키프레임을 추출합니다.
3단계: 레시피 파싱, 가구 규모 조정 및 식료품 저장실 확인
- 가구 규모 조정: 원래 분량(예: 4인분)에서 목표 분량(기본값
2.5는 성인 2명 + 아이 1명)으로 재료 양을HouseholdScaler를 사용하여 조정합니다. - 식료품 저장실 중복 제거:
PantryComparator를 사용하여 재료를config/pantry_staples.json과 대조합니다. 일치하는 항목(소금, 후추, 식용유, 간장, 마늘 가루)은pantry_staples_skipped로 이동합니다. - 어린이 준비 알림: 매운 재료나 통째로 조리되는 단백질이 감지되면 어린이 친화적인 조리법을 생성합니다.
4단계: H-E-B 카탈로그 매칭 및 5단계 폴백 시스템
ingredients_to_buy의 각 재료(또는 임시 사용자 요청)에 대해 scripts/heb_client.py를 사용하여 지역 H-E-B 매장 카탈로그와 매칭합니다:
- 티어 0 (선호 SKU 확인 및 패키지 크기 조정): 과거 주문과 수동 고정에서 수집된
cache/preferred_skus.json(정식 키 및 별칭 배열)과 매칭합니다. 정수 패키지 수량을 자동으로 계산합니다(예: 레시피 용량 48oz / 패키지 32oz -> 2개 패키지). 재고가 있으면 티어 0으로 바로 담습니다. 품절이면 티어 1로 부드럽게 넘어갑니다. - 티어 1 (정확한 SKU 매칭): 재고가 있으면 기존 레시피 기본 SKU를 추가합니다.
- 티어 2 (브랜드 계층): 기본 SKU가 품절이면
brand_hierarchy(H-E-B→H-E-B Organics→Central Market→Mi Tienda→Hill Country Fare→National Brand)를 사용하여 대체합니다. - 티어 3 (유기농 ↔ 일반 전환): 매장에 한 가지만 재고가 있는 경우 유기농과 일반을 서로 전환합니다.
- 티어 4 (패키지 크기 조정 / 사람 개입 요청): 수량을 조정하거나 전체 카테고리가 품절된 경우
⚠️ OUT OF STOCK (NEEDS HUMAN CALL)로 플래그를 지정합니다.
5단계: 직접 GraphQL 장바구니 담기 및 쿠폰 적용 (느린 UI 클릭 없음)
수집된 Chrome CDP (127.0.0.1:9222) / rookiepy 세션 토큰을 사용하여 인증된 GraphQL 작업(영구 쿼리 cartEstimated, cartItemV2, CouponClip은 texas-grocery-mcp에서 가져옴)을 통해 상품을 담고 쿠폰을 적용합니다:
# 1. 라이브 세션 토큰 수집 또는 갱신
python scripts/heb_client.py --harvest
# 2. 과거 주문 및 '다시 구매'에서 선호 SKU 동기화
python scripts/cache_manager.py update-preferred-skus
# 3. 선호하는 제품을 수동으로 선호 SKU로 고정 (자동 동기화로부터 보호)
python scripts/cache_manager.py pin-preferred-sku \
--ingredient "whole milk" \
--sku "4122012345" \
--product "123456" \
--name "H-E-B Organics Whole Milk" \
--package-size "1 gal"
# 4. 임시 재료 확인 또는 패키지 크기 테스트
python scripts/heb_client.py --resolve-sku "48 oz beef broth"
# 5. 후보 상품 담기 (사람 확인 필요 --confirm)
python scripts/heb_client.py --stage-sku "48 oz beef broth" --confirm
# 또는 제품 ID로 직접:
python scripts/heb_client.py --cart-add <PRODUCT_ID> [--sku <SKU_ID>] [--qty <N>] --confirm
# 6. 현재 라이브 장바구니 확인
python scripts/heb_client.py --cart-get
# 7. 교체 시 장바구니에서 상품 제거
python scripts/heb_client.py --cart-remove <PRODUCT_ID> [--sku <SKU_ID>] --confirm
# 8. 디지털 쿠폰 적용
python scripts/heb_client.py --coupon-clip <COUPON_ID> --confirm
[!IMPORTANT] 사람 개입 결제 게이트: AGY는 결제 실행, 배송/픽업 시간 예약 관련 변형(mutation)을 절대 수행할 수 없습니다. 장바구니 담기와 디지털 쿠폰 적용만 가능합니다. 사용자(Carl)는 항상 My H-E-B 모바일 앱에서 최종 결제를 검토하고 진행합니다.
⏱️ 권장 백그라운드 크론잡 (일일 세션 갱신)
H-E-B의 단기 sat 토큰은 30분마다 갱신되며 sst를 통해 필요 시 자동 갱신되지만, 사용자에게 24시간마다 세션을 갱신하고 검증하는 일일 크론잡(macOS/Linux) 또는 예약 작업(schtasks on Windows)을 설정하도록 권장하세요. 사용자 대신 crontab에 설치를 제안하세요:
0 9 * * * cd /path/to/heb-mcp.skill && .venv/bin/python scripts/heb_client.py --harvest >/dev/null 2>&1
(Slack 알림이 필요한 경우 scripts/cron_refresh_heb_auth.py / scripts/cron_refresh_heb_auth.sh를 사용하세요.)
6단계: 레시피 캐시 저장
파싱된 레시피를 저장하여 이후 실행 시 빠른 경로(Hot Path)로 바로 접근할 수 있도록 합니다:
python scripts/cache_manager.py save --file <RECIPE_DATA_YAML>
7단계: 모바일 검토 요약 (iMessage / Slack)
모바일 화면에서 깔끔하게 읽을 수 있도록 포맷을 지정합니다 (Markdown 테이블을 피하고 깔끔한 이모지 불릿 형식을 사용합니다):
🛒 H-E-B 장바구니 준비 완료: 바삭한 꿀 마늘 연어 한입
성인 2명 + 아이 1명 기준으로 조정 (~2.5인분)
👶 아이 준비 참고:
• 메인 팬 글레이즈에 스리라차 1큰술을 넣지 마세요. 아이 몫을 먼저 덜고, 성인 몫에 스리라차를 섞으세요.
• 아이 연어는 1/2인치 크기로 잘라주세요.
✅ H-E-B 장바구니에 추가됨 (4개 항목):
• 1x H-E-B 신선 대서양 연어 필레 (~1.25 lb) — $13.74
• 1x H-E-B 순수 클로버 꿀 (12 oz) — $4.48
• 1x 신선한 파 (1단) — $0.88
• 1x H-E-B 자스민 쌀 (32 oz) — $2.74
🔄 자동 대체 (매장 품절):
• 2x H-E-B 브로콜리 플로렛 (10 oz 봉지) — $4.56
(1 lb 유기농 브로콜리는 품절; 이번 주문에 한해 10oz 봉지 2개로 대체)
🎟️ 적용된 쿠폰:
• H-E-B 신선 해산물 트레이 $1.00 할인
🏠 저장실 확인 (건너뜀 — 추가하려면 답장):
• 간장 (3큰술), 마늘 (4쪽), 옥수수 전분 (2큰술), 참기름 (1작은술)
📱 다음 단계:
저장실 항목을 추가하려면 (예: "간장 추가") 또는 브랜드를 변경하려면 답장하세요. 그렇지 않으면 My H-E-B 앱을 열어 검토하고 결제를 진행하세요!
🔄 장바구니 담기 후 답장 명령어
사용자가 준비된 장바구니 검토 스레드에 답장할 때:
- "[저장실 항목] 추가" (예: "간장이 떨어졌어, 추가해줘"):
- 티어 0 선호 SKU 엔진을 통해 확인하고 장바구니에 담습니다:
python scripts/heb_client.py --stage-sku "soy sauce" --confirm - 짧은 답장으로 확인: "H-E-B 저나트륨 간장 1개를 장바구니에 추가했습니다."
- 티어 0 선호 SKU 엔진을 통해 확인하고 장바구니에 담습니다:
- "[항목]을 [선호]로 교체" (예: "일반 연어를 야생 홍연어로 바꿔줘"):
- 장바구니에서 기존 SKU를 제거하고 선호 SKU를 추가합니다.
- 안내: "이번 주문은 야생 홍연어로 교체했습니다. 앞으로 이 레시피에 이 교체를 영구적으로 적용할까요?"
- "그 교체를 영구적으로 적용해줘":
python scripts/cache_manager.py promote-sku ...를 실행하여cache/recipes/<slug>.yaml의primary_sku를 업데이트하고source: "manual_override"로cache/preferred_skus.json에 고정합니다.- 확인: "레시피 캐시가 업데이트되었습니다: Central Market Wild Sockeye가 이 레시피의 기본 SKU이자 선호 SKU로 고정되었습니다."
- "선호 매장을 [매장명]으로 변경" / "Curbside 또는 Delivery로 전환":
.env의HEB_STORE_ID와config/household.yaml의store를 업데이트하거나, H-E-B 세션의 활성 매장/배송 모드를 업데이트하고 새 매장에서 장바구니 품목 가용성을 재확인합니다.