chorned/heb-mcp.skill

heb-mcp.skill (TikTok-2-HEB) Agent Skill

Verwalte Live-H-E-B-Einkaufswagen, löse bevorzugte Haushaltsprodukte aus dem Einkaufsverlauf auf, clippe Coupons und verwandle Kochvideo-URLs in skalierte, pantry-geprüfte H-E-B-Einkaufswagen mit deterministischen Ersatzlösungen für nicht vorrätige Artikel.

---

🎯 Auslösebedingungen

Aktiviere diesen Skill immer dann, wenn:

1. Ein Benutzer bittet, bei H-E-B zu suchen, den Warenkorb zu prüfen, seinen bevorzugten Laden oder die Abholmethode (Curbside vs. Lieferung) zu wechseln, Coupons zu clippen oder Lebensmittel bei H-E-B hinzuzufügen/zu entfernen (z. B. "Füge Vollmilch und Buttertortillas zu meinem H-E-B-Warenkorb hinzu").
2. Ein autorisierter Benutzer eine Koch- oder Rezept-URL von TikTok (tiktok.com, vm.tiktok.com), Instagram Reels (instagram.com/reel/) oder YouTube Shorts (youtube.com/shorts/) teilt.
3. Ein Benutzer bittet, Zutaten für ein Rezeptvideo zu konvertieren, zu skalieren oder zu bestellen (z. B. "Bestelle die Zutaten für dieses Rezept von H-E-B", "Lege dieses TikTok-Abendessen in meinen Warenkorb").
4. Ein Benutzer auf einen bestehenden Einkaufsprüf-Thread mit Anpassungen nach der Zusammenstellung antwortet (z. B. "Sojasauce hinzufügen", "Ersetze normalen Lachs durch Wild-Sockeye", "Mach diesen Austausch dauerhaft").
5. Ein Benutzer bittet, heb-mcp.skill (TikTok-2-HEB) zum ersten Mal einzurichten oder zu konfigurieren.

---

🚀 Ersteinrichtung (Agent-geführtes Onboarding)

Wenn ein Benutzer dich bittet, dieses Projekt einzurichten, übernimm die technischen Schritte für ihn und stelle nur kurze, einfache Fragen:

1. Umgebung und Binärdateien installieren:

   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
   

2. Stelle dem Benutzer schnelle Einrichtungsfragen:
   • Bevorzugter H-E-B-Laden und Abholmethode: Frage, bei welchem H-E-B-Laden der Benutzer einkauft (aktualisiere HEB_STORE_ID in .env und store in config/household.yaml und hilf ihm, den aktiven Laden zu wechseln oder zwischen Curbside Pickup und Home Delivery umzuschalten, wann immer gewünscht).
   • Haushaltsgröße: Frage, wie viele Erwachsene/Kinder der Benutzer bekocht (aktualisiere config/household.yaml).
3. Session harvesten und vergangene Bestellungen synchronisieren: Bitte den Benutzer, sicherzustellen, dass er auf heb.com in Safari oder Chrome eingeloggt ist, und führe dann aus:

   python scripts/heb_client.py --harvest
   python scripts/cache_manager.py update-preferred-skus
   python tests/test_skill_setup.py
   

4. Automatischen täglichen Token-Erneuerungs-Cronjob einrichten: Ermutige den Benutzer nachdrücklich, dich einen wiederkehrenden 24-Stunden-Cronjob installieren zu lassen (0 9 * * * cd <REPO_PATH> && .venv/bin/python scripts/heb_client.py --harvest >/dev/null 2>&1), damit seine H-E-B-Session automatisch frisch bleibt.

---

🔒 Betriebliche Invarianten und Sicherheitsleitplanken

1. Hartes Human-in-the-Loop Checkout-Gate:
   • Der Agent stellt Artikel in den Warenkorb und clipt digitale Coupons.
   • Der Agent DARF NIEMALS Zahlungen auslösen, Liefer-/Abholfenster buchen oder den Bestellvorgang abschließen.
   • Die finale Überprüfung und der Checkout liegen immer in den Händen des Benutzers innerhalb der offiziellen My H-E-B-App.
2. Zero-Auth Extraktion:
   • Rufe scripts/extract_recipe_media.py immer ohne persönliche TikTok/Instagram-Logins oder Session-Cookies auf.
3. Anti-Cache-Vergiftungs-Invariante:
   • Ersatz für Nicht-Vorrätiges (Stufe 2/3/4) muss strikt ephemer für diese spezifische Warenkorb-Bestellung bleiben.
   • Überschreibe NIEMALS primary_sku in cache/recipes/<slug>.yaml, es sei denn, der Benutzer befiehlt explizit: "Mach diesen Austausch dauerhaft" oder "Verwende immer diese Marke".
4. Kindgerechte Zubereitungstrennung:
   • Wenn kid_friendly_split aktiviert ist, entkopple Capsaicin/Schärfe (Sriracha, Chiliflocken, Cayenne, Jalapeños) von der Grundpfanne. Halte das Hauptgericht mild, portioniere zuerst den Kinderteller und würze die Erwachsenenportionen am Ende.
   • Füge Erinnerungen hinzu, Proteine und Erstickungsgefahren in 1,25 cm große mundgerechte Würfel zu schneiden.
5. Automatische Token-Erneuerung (Täglicher Cronjob empfohlen):
   • Obwohl H-E-Bs kurzlebiger Session-Access-Token (sat) alle 30 Minuten rotiert, erneuert heb_graphql.py ihn bei Bedarf automatisch mit dem langlebigen Session-Token (sst).
   • Während der Ersteinrichtung oder nach dem Harvesten/Erneuern einer Session ermutige den Benutzer proaktiv, dich einen automatischen 24-Stunden-Cronjob einrichten zu lassen, der die zugrunde liegende H-E-B-Session und den Anti-Bot-Token (reese84) im Hintergrund validiert, damit er sich vor dem Einkauf nicht manuell neu anmelden muss.

---

🛠️ Schritt-für-Schritt-Ausführungsworkflow

Schritt 1: Pre-Flight Cache-Suche

Bevor du Media-Extraktion oder API-Aufrufe durchführst, prüfe, ob das Video bereits analysiert und zwischengespeichert wurde:

python scripts/cache_manager.py lookup --query "<VIDEO_URL_OR_ID>"

• TREFFER: Lade das zwischengespeicherte Rezept-YAML. Fahre direkt mit Schritt 4 (Warenkorb-Zusammenstellung) unter Verwendung der zwischengespeicherten primary_sku-Definitionen fort.
• FEHLTREFFER: Fahre mit Schritt 2 (Media-Extraktion) fort.

Schritt 2: Zero-Auth Multimodale Media-Extraktion

Führe die 3-stufige Extraktionspipeline aus:

python scripts/extract_recipe_media.py "<VIDEO_URL>"

1. Durchgang 1: Erfasst Videotitel, Beschreibung, Uploader und automatische Untertitel.
2. Durchgang 2: Bereinigt Untertitel-Cues, entfernt Zeitstempel und dedupliziert sich wiederholende Untertitel.
3. Durchgang 3: Wenn das Transkript dünn ist (< 3 kulinarische Maßeinheiten), extrahiert es automatisch den Audiostream oder Keyframes.

Schritt 3: Rezeptanalyse, Haushaltsskalierung und Pantry-Prüfung

1. Haushaltsskalierung: Skaliere die Zutatenmengen von der ursprünglichen Ausbeute (z. B. 4 Portionen) auf die Zielportionen (Standard 2.5 für 2 Erwachsene + 1 Kind) mit HouseholdScaler.
2. Pantry-Deduplizierung: Prüfe Zutaten gegen config/pantry_staples.json mit PantryComparator. Verschiebe passende Artikel (Salz, Pfeffer, Speiseöl, Sojasauce, Knoblauchpulver) zu pantry_staples_skipped.
3. Kindervorbereitungs-Erinnerungen: Generiere kindgerechte Anpassungen, wenn scharfe Zutaten oder ganze Proteine erkannt werden.

Schritt 4: H-E-B-Katalogabgleich und 5-stufige Fallback-Kaskade

Für jede Zutat in ingredients_to_buy (oder Ad-hoc-Benutzeranfragen) gleiche gegen den lokalen H-E-B-Ladenkatalog mit scripts/heb_client.py ab:

• Stufe 0 (Bevorzugte SKU-Auflösung und Paketgrößenskalierung): Gleiche gegen cache/preferred_skus.json (kanonische Schlüssel und Alias-Arrays) ab, die aus vergangenen Bestellungen und manuellen Pins befüllt wird. Berechne automatisch ganzzahlige Paketmengen (z. B. 48 oz Rezeptvolumen / 32 oz Paket -> 2 Pakete). Wenn auf Lager, stelle direkt als Stufe 0 bereit. Wenn nicht vorrätig, falle sanft auf Stufe 1 zurück.
• Stufe 1 (Exakter SKU-Abgleich): Füge die vorhandene Rezept-Primär-SKU hinzu, wenn auf Lager.
• Stufe 2 (Markenhierarchie): Wenn Primär-SKU nicht vorrätig ist, ersetze mit brand_hierarchy (H-E-B → H-E-B Organics → Central Market → Mi Tienda → Hill Country Fare → National Brand).
• Stufe 3 (Organic ↔ Conventional Tausch): Tausche Bio gegen konventionell (oder umgekehrt), wenn der Laden nur eines davon auf Lager hat.
• Stufe 4 (Paketgrößenanpassung / Eskalation an Menschen): Passe Mengen an oder markiere Kategorie-Ausfall als ⚠️ NICHT VORRÄTIG (BRAUCHT MENSCHLICHEN ANRUF).

Schritt 5: Direktes GraphQL-Warenkorb-Staging und Coupon-Clipping (Kein langsames UI-Klicken)

Stelle Artikel bereit und clippe Coupons direkt über authentifizierte GraphQL-Operationen (persistierte Abfragen cartEstimated, cartItemV2, CouponClip aus texas-grocery-mcp vendored) unter Verwendung von geharvesteten Chrome-CDP-Tokens (127.0.0.1:9222) / rookiepy-Session-Tokens:

# 1. Harveste oder erneuere Live-Session-Tokens
python scripts/heb_client.py --harvest

# 2. Synchronisiere bevorzugte SKUs aus vergangenen Bestellungen & "Buy It Again"
python scripts/cache_manager.py update-preferred-skus

# 3. Pinne manuell ein Lieblingsprodukt als bevorzugte SKU (vor automatischer Synchronisation geschützt)
python scripts/cache_manager.py pin-preferred-sku \
  --ingredient "Vollmilch" \
  --sku "4122012345" \
  --product "123456" \
  --name "H-E-B Organics Vollmilch" \
  --package-size "1 gal"

# 4. Löse eine Ad-hoc-Zutat auf oder teste die Paketgröße
python scripts/heb_client.py --resolve-sku "48 oz Rinderbrühe"

# 5. Stelle Kandidaten-Artikel bereit (erfordert Human-in-the-Loop --confirm)
python scripts/heb_client.py --stage-sku "48 oz Rinderbrühe" --confirm
# oder direkt per Produkt-ID:
python scripts/heb_client.py --cart-add <PRODUCT_ID> [--sku <SKU_ID>] [--qty <N>] --confirm

# 6. Überprüfe den aktuellen Live-Warenkorb
python scripts/heb_client.py --cart-get

# 7. Entferne einen Artikel aus dem Warenkorb, falls ausgetauscht
python scripts/heb_client.py --cart-remove <PRODUCT_ID> [--sku <SKU_ID>] --confirm

# 8. Clippe digitale Coupons
python scripts/heb_client.py --coupon-clip <COUPON_ID> --confirm

[!IMPORTANT] Human-in-the-Loop Checkout-Gate: AGY ist strengstens untersagt, Checkout-, Zahlungs- oder Liefer-/Abholfenster-Buchungsmutationen auszuführen. Nur Warenkorb-Zusammenstellung und digitales Coupon-Clipping; Carl überprüft immer und tippt den finalen Checkout in der My H-E-B-App.

⏱️ Empfohlener Hintergrund-Cronjob (Tägliche Session-Erneuerung)

Obwohl H-E-Bs kurzlebiger sat-Token alle 30 Minuten rotiert und bei Bedarf automatisch über sst erneuert wird, ermutige den Benutzer, einen täglichen Cronjob (macOS/Linux) oder eine geplante Aufgabe (schtasks unter Windows) einzurichten, der die Session einmal alle 24 Stunden erneuert und validiert. Biete an, ihn für den Benutzer in seine crontab zu installieren:

0 9 * * * cd /pfad/zu/heb-mcp.skill && .venv/bin/python scripts/heb_client.py --harvest >/dev/null 2>&1

(Oder verwende scripts/cron_refresh_heb_auth.py / scripts/cron_refresh_heb_auth.sh, wenn Slack-Benachrichtigungen gewünscht sind.)

Schritt 6: Rezept-Cache-Persistenz

Speichere das analysierte Rezept, um sicherzustellen, dass zukünftige Durchläufe den schnellen Pfad (Hot Path) nehmen:

python scripts/cache_manager.py save --file <RECIPE_DATA_YAML>

Schritt 7: Mobile Prüfzusammenfassung (iMessage / Slack)

Formatiere die Prüfung für eine saubere Lesbarkeit auf mobilen Bildschirmen (vermeide Markdown-Tabellen, verwende saubere Emoji-Aufzählungsformatierung):

🛒 H-E-B Warenkorb bereitgestellt: Knusprige Honig-Knoblauch-Lachshäppchen
Skaliert für 2 Erwachsene + 1 Kind (~2,5 Portionen)

👶 Kinder-Vorbereitungshinweis:
• Halte die 1 EL Sriracha aus der Hauptpfannen-Glasur heraus. Portioniere zuerst den Kinderteller, dann mische die Erwachsenenportionen mit Sriracha.
• Schneide den Lachs für das Kind in 1,25 cm große mundgerechte Würfel.

✅ Zum H-E-B-Warenkorb hinzugefügt (4 Artikel):
• 1x H-E-B Frisches Atlantiklachsfilet (~1,25 lb) — 13,74 €
• 1x H-E-B Reiner Kleehonig (12 oz) — 4,48 €
• 1x Frische Frühlingszwiebeln (1 Bund) — 0,88 €
• 1x H-E-B Jasminreis (32 oz) — 2,74 €

🔄 Automatisch ersetzt (nicht vorrätig im Laden):
• 2x H-E-B Brokkoliröschen (10 oz Beutel) — 4,56 €
  (1 lb Bio-Kronen waren nicht vorrätig; für diese Bestellung durch 2x 10-oz-Beutel ersetzt)

🎟️ Geclippte Coupons:
• 1,00 € Rabatt auf H-E-B Frische Meeresfrüchteplatte

🏠 Pantry-Check (Übersprungen – antworte, um hinzuzufügen):
• Sojasauce (3 EL), Knoblauch (4 Zehen), Maisstärke (2 EL), Sesamöl (1 TL)

📱 Nächster Schritt:
Antworte, wenn du einen Pantry-Artikel hinzufügen möchtest (z. B. "Sojasauce hinzufügen") oder eine Marke tauschen möchtest. Öffne andernfalls die My H-E-B-App, um zu überprüfen und den Checkout zu tätigen!

---

🔄 Befehle nach der Warenkorb-Zusammenstellung

Wenn der Benutzer auf den Thread mit der zusammengestellten Prüfung antwortet:

1. "[Pantry-Artikel] hinzufügen" (z. B. "unsere Sojasauce ist alle, füge sie hinzu"):
   • Löse über die bevorzugte SKU-Engine der Stufe 0 auf und stelle in den Warenkorb: python scripts/heb_client.py --stage-sku "Sojasauce" --confirm
   • Bestätige mit einer kurzen Antwort: "1x H-E-B Reduzierte Natrium-Sojasauce wurde deinem Warenkorb hinzugefügt."
2. "[Artikel] durch [Präferenz] ersetzen" (z. B. "ersetze normalen Lachs durch Wild-Sockeye"):
   • Entferne die alte SKU aus dem Warenkorb und füge die bevorzugte SKU hinzu.
   • Frage: "Für diese Bestellung gegen Wild-Sockeye getauscht. Soll ich diesen Austausch für zukünftige Bestellungen dieses Rezepts dauerhaft machen?"
3. "Mach diesen Austausch dauerhaft":
   • Führe python scripts/cache_manager.py promote-sku ... aus, um primary_sku in cache/recipes/<slug>.yaml zu aktualisieren und in cache/preferred_skus.json mit source: "manual_override" zu pinnen.
   • Bestätige: "Rezept-Cache aktualisiert: Central Market Wild-Sockeye ist jetzt deine primäre SKU für dieses Rezept und als bevorzugte SKU gepinnt."
4. "Bevorzugten Laden zu [Laden] wechseln" / "Auf Curbside oder Lieferung umstellen":
   • Aktualisiere HEB_STORE_ID in .env und store in config/household.yaml oder aktualisiere den aktiven Laden/die Abholmethode in der H-E-B-Session und überprüfe die Verfügbarkeit der Warenkorb-Artikel im neuen Laden erneut.