texas-grocery-mcp 0.1.0__py3-none-any.whl

texas_grocery_mcp/models/__init__.py

@@ -0,0 +1,54 @@
+"""Data models for Texas Grocery MCP."""
+
+from texas_grocery_mcp.models.cart import AppliedCoupon, Cart, CartItem
+from texas_grocery_mcp.models.coupon import Coupon, CouponCategory, CouponSearchResult
+from texas_grocery_mcp.models.errors import AuthRequiredResponse, ErrorResponse
+from texas_grocery_mcp.models.health import (
+    CircuitBreakerStatus,
+    ComponentHealth,
+    HealthResponse,
+)
+from texas_grocery_mcp.models.product import (
+    ExtendedNutrition,
+    NutrientInfo,
+    Product,
+    ProductCoupon,
+    ProductDetails,
+    ProductNutrition,
+    ProductSearchAttempt,
+    ProductSearchResult,
+)
+from texas_grocery_mcp.models.store import (
+    GeocodedLocation,
+    SearchAttempt,
+    Store,
+    StoreHours,
+    StoreSearchResult,
+)
+
+__all__ = [
+    "AppliedCoupon",
+    "AuthRequiredResponse",
+    "Cart",
+    "CartItem",
+    "CircuitBreakerStatus",
+    "ComponentHealth",
+    "Coupon",
+    "CouponCategory",
+    "CouponSearchResult",
+    "ErrorResponse",
+    "ExtendedNutrition",
+    "GeocodedLocation",
+    "HealthResponse",
+    "NutrientInfo",
+    "Product",
+    "ProductCoupon",
+    "ProductDetails",
+    "ProductNutrition",
+    "ProductSearchAttempt",
+    "ProductSearchResult",
+    "SearchAttempt",
+    "Store",
+    "StoreHours",
+    "StoreSearchResult",
+]

texas_grocery_mcp/models/cart.py

@@ -0,0 +1,60 @@
+"""Cart data models."""
+
+from pydantic import BaseModel, Field, computed_field
+
+
+class CartItem(BaseModel):
+    """Item in shopping cart."""
+
+    sku: str = Field(description="Product SKU")
+    name: str = Field(description="Product name")
+    price: float = Field(description="Unit price")
+    quantity: int = Field(ge=1, description="Quantity in cart")
+    image_url: str | None = Field(default=None, description="Product image")
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def subtotal(self) -> float:
+        """Calculate item subtotal."""
+        return round(self.price * self.quantity, 2)
+
+
+class AppliedCoupon(BaseModel):
+    """Coupon applied to cart."""
+
+    code: str = Field(description="Coupon code")
+    discount: float = Field(description="Discount amount")
+    description: str | None = Field(default=None, description="Coupon description")
+
+
+class Cart(BaseModel):
+    """Shopping cart."""
+
+    items: list[CartItem] = Field(default_factory=list, description="Cart items")
+    coupons_applied: list[AppliedCoupon] = Field(
+        default_factory=list, description="Applied coupons"
+    )
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def subtotal(self) -> float:
+        """Calculate cart subtotal before coupons."""
+        return round(sum(item.subtotal for item in self.items), 2)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def total_discount(self) -> float:
+        """Calculate total coupon discount."""
+        return round(sum(c.discount for c in self.coupons_applied), 2)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def estimated_total(self) -> float:
+        """Calculate estimated total after discounts."""
+        return round(self.subtotal - self.total_discount, 2)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def item_count(self) -> int:
+        """Total number of items in cart."""
+        return sum(item.quantity for item in self.items)

texas_grocery_mcp/models/coupon.py

@@ -0,0 +1,44 @@
+"""Coupon data models."""
+
+from pydantic import BaseModel, Field
+
+
+class CouponCategory(BaseModel):
+    """Coupon category/department."""
+
+    id: int = Field(description="Category ID")
+    name: str = Field(description="Category display name")
+    count: int = Field(description="Number of coupons in this category")
+
+
+class Coupon(BaseModel):
+    """HEB digital coupon."""
+
+    coupon_id: int = Field(description="Unique coupon identifier")
+    headline: str = Field(description="Short discount headline (e.g., '25% off', '$2 off')")
+    description: str = Field(description="Full description of eligible products")
+    expires: str | None = Field(default=None, description="Expiration date (YYYY-MM-DD)")
+    expires_display: str | None = Field(default=None, description="Human-readable expiration")
+    image_url: str | None = Field(default=None, description="Coupon image URL")
+
+    # Coupon type and status
+    coupon_type: str = Field(default="NORMAL", description="Type: NORMAL, COMBO_LOCO, MEAL_DEAL")
+    clipped: bool = Field(default=False, description="Whether user has clipped this coupon")
+    redeemable: bool = Field(default=True, description="Whether coupon can be redeemed")
+
+    # Usage info
+    usage_limit: str | None = Field(default=None, description="Usage limit (e.g., 'Limit 1')")
+    digital_only: bool = Field(default=False, description="Exclusive digital coupon")
+
+
+class CouponSearchResult(BaseModel):
+    """Result from coupon list/search."""
+
+    coupons: list[Coupon] = Field(default_factory=list)
+    count: int = Field(description="Number of coupons returned")
+    total: int = Field(description="Total coupons available")
+    page: int = Field(default=1, description="Current page number")
+    categories: list[CouponCategory] = Field(
+        default_factory=list,
+        description="Available categories",
+    )

texas_grocery_mcp/models/errors.py

@@ -0,0 +1,43 @@
+"""Error response models."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class ErrorResponse(BaseModel):
+    """Structured error response."""
+
+    error: bool = Field(default=True, description="Always true for errors")
+    code: str = Field(description="Error code (e.g., HEB_API_TIMEOUT)")
+    category: Literal["client", "server", "external"] = Field(
+        description="Error category for handling"
+    )
+    message: str = Field(description="Human-readable error message")
+    retry_after_seconds: int | None = Field(
+        default=None, description="Seconds to wait before retry"
+    )
+    fallback_used: bool = Field(
+        default=False, description="Whether fallback data source was used"
+    )
+    fallback_source: str | None = Field(
+        default=None, description="Which fallback was used (cache, scraper)"
+    )
+    suggestions: list[str] = Field(
+        default_factory=list, description="Actionable suggestions"
+    )
+
+
+class AuthRequiredResponse(BaseModel):
+    """Response when authentication is required."""
+
+    auth_required: bool = Field(default=True)
+    message: str = Field(default="Login required for this operation")
+    instructions: list[str] = Field(
+        default_factory=lambda: [
+            "1. Use Playwright MCP: browser_navigate to 'https://www.heb.com/my-account/login'",
+            "2. Complete login in the browser",
+            "3. Use Playwright MCP: browser_run_code to save storage state",
+            "4. Retry this operation",
+        ]
+    )

texas_grocery_mcp/models/health.py

@@ -0,0 +1,41 @@
+"""Health check response models."""
+
+from datetime import UTC, datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class ComponentHealth(BaseModel):
+    """Health status of a single component."""
+
+    status: Literal["up", "down", "degraded"] = Field(description="Component status")
+    latency_ms: float | None = Field(default=None, description="Response latency")
+    message: str | None = Field(default=None, description="Status message")
+
+
+class CircuitBreakerStatus(BaseModel):
+    """Status of a circuit breaker."""
+
+    state: Literal["closed", "open", "half_open"] = Field(
+        description="Circuit state"
+    )
+    failures: int = Field(default=0, description="Current failure count")
+
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+
+    status: Literal["healthy", "degraded", "unhealthy"] = Field(
+        description="Overall health status"
+    )
+    timestamp: str = Field(
+        default_factory=lambda: datetime.now(UTC).isoformat(),
+        description="Check timestamp",
+    )
+    components: dict[str, ComponentHealth] = Field(
+        default_factory=dict, description="Component health statuses"
+    )
+    circuit_breakers: dict[str, CircuitBreakerStatus] = Field(
+        default_factory=dict, description="Circuit breaker statuses"
+    )

texas_grocery_mcp/models/product.py

@@ -0,0 +1,274 @@
+"""Product data models."""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class ProductNutrition(BaseModel):
+    """Nutritional information."""
+
+    calories: int | None = None
+    protein: str | None = None
+    carbohydrates: str | None = None
+    fat: str | None = None
+    fiber: str | None = None
+    sodium: str | None = None
+
+
+class ProductCoupon(BaseModel):
+    """Coupon applicable to product."""
+
+    code: str
+    discount: str
+    expires: str | None = None
+
+
+# ============================================================================
+# Product Details Models (for product_get tool)
+# ============================================================================
+
+
+class NutrientInfo(BaseModel):
+    """Individual nutrient from FDA nutrition facts panel.
+
+    Supports nested sub_items for nutrients like:
+    - Total Fat -> Saturated Fat, Trans Fat, etc.
+    - Total Carbohydrate -> Dietary Fiber, Total Sugars, etc.
+    """
+
+    title: str = Field(description="Nutrient name (e.g., 'Total Fat')")
+    unit: str = Field(description="Amount with unit (e.g., '14g')")
+    percentage: str | None = Field(default=None, description="% Daily Value (e.g., '18%')")
+    font_modifier: str | None = Field(
+        default=None, description="Display style: BOLD, PLAIN, ITALIC"
+    )
+    sub_items: list["NutrientInfo"] | None = Field(
+        default=None, description="Nested nutrients (e.g., Saturated Fat under Total Fat)"
+    )
+
+
+class ExtendedNutrition(BaseModel):
+    """Complete FDA-style nutrition facts panel.
+
+    Matches the structure returned by HEB's nutritionLabels API field.
+    """
+
+    serving_size: str | None = Field(default=None, description="e.g., '1 Tbsp (15mL)'")
+    servings_per_container: str | None = Field(default=None, description="e.g., 'about 34'")
+    calories: str | None = Field(default=None, description="Calories per serving")
+    label_modifier: str | None = Field(default=None, description="e.g., '15 mL'")
+    nutrients: list[NutrientInfo] = Field(
+        default_factory=list,
+        description="Main nutrients (fat, cholesterol, sodium, carbs, protein)",
+    )
+    vitamins_and_minerals: list[NutrientInfo] = Field(
+        default_factory=list, description="Vitamins and minerals section"
+    )
+
+
+class ProductDetails(BaseModel):
+    """Comprehensive product information from HEB product detail page.
+
+    Returned by the product_get tool. Contains all available details
+    including ingredients, nutrition facts, warnings, and instructions.
+
+    Note: Many fields are optional as availability varies by product type:
+    - Food items: Have nutrition, ingredients, may have warnings
+    - Produce: Have ingredients, dietary attributes, no nutrition panel
+    - Non-food: Have chemical ingredients, extensive warnings, no nutrition
+    """
+
+    # === Identifiers ===
+    product_id: str = Field(description="Product ID (e.g., '127074')")
+    sku: str = Field(description="SKU ID (e.g., '4122071073')")
+    upc: str | None = Field(default=None, description="12-digit UPC barcode")
+
+    # === Basic Info ===
+    name: str = Field(description="Full product display name")
+    description: str | None = Field(
+        default=None, description="Product description (may contain HTML)"
+    )
+    brand: str | None = Field(default=None, description="Brand name")
+    is_own_brand: bool = Field(default=False, description="True if HEB own brand")
+
+    # === Pricing & Availability ===
+    price: float = Field(description="Curbside/delivery price")
+    price_online: float | None = Field(default=None, description="In-store/online price")
+    on_sale: bool = Field(default=False, description="Currently on sale")
+    is_price_cut: bool = Field(default=False, description="Price cut active")
+    available: bool = Field(description="In stock at store")
+    price_per_unit: str | None = Field(default=None, description="e.g., '$0.41 / fl oz'")
+
+    # === Size ===
+    size: str | None = Field(default=None, description="Package size (e.g., '17 oz')")
+
+    # === Ingredients ===
+    ingredients: str | None = Field(
+        default=None,
+        description="Full ingredients text (string, not list)"
+    )
+
+    # === Safety Warning ===
+    safety_warning: str | None = Field(
+        default=None,
+        description="Safety/allergen warnings (may include allergen info for food)"
+    )
+
+    # === Instructions ===
+    instructions: str | None = Field(
+        default=None,
+        description="Preparation, storage, or usage instructions"
+    )
+
+    # === Dietary Attributes ===
+    dietary_attributes: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Dietary info from lifestyles (e.g., 'Gluten free verified', "
+            "'Organic', 'Vegan')"
+        ),
+    )
+
+    # === Nutrition (only for packaged food) ===
+    nutrition: ExtendedNutrition | None = Field(
+        default=None,
+        description="Full FDA nutrition panel (null for produce/non-food)"
+    )
+
+    # === Category ===
+    category_path: list[str] = Field(
+        default_factory=list,
+        description="Category breadcrumb (e.g., ['Shop', 'Pantry', 'Oils'])"
+    )
+
+    # === Media ===
+    image_url: str | None = Field(default=None, description="Primary product image URL")
+    images: list[str] = Field(default_factory=list, description="All product image URLs")
+
+    # === Store Location ===
+    location: str | None = Field(
+        default=None,
+        description="Store location (e.g., 'Aisle 5' or 'In Produce')"
+    )
+    store_id: int | None = Field(default=None, description="Store ID for this data")
+
+    # === Availability Channels ===
+    availability_channels: list[str] = Field(
+        default_factory=list,
+        description="How product can be purchased (e.g., ['IN_STORE', 'CURBSIDE_PICKUP'])"
+    )
+
+    # === SNAP/EBT ===
+    is_snap_eligible: bool = Field(default=False, description="SNAP EBT eligible")
+
+    # === URL ===
+    product_url: str | None = Field(default=None, description="Full URL to product page")
+
+
+class Product(BaseModel):
+    """HEB product information.
+
+    IMPORTANT FOR CART OPERATIONS:
+    - Use `product_id` as the first argument to cart_add
+    - Use `sku` as the second argument (sku_id) to cart_add
+
+    Example:
+        cart_add(product_id=product.product_id, sku_id=product.sku, quantity=1)
+    """
+
+    # SKU - the longer identifier needed for cart operations
+    sku: str = Field(description="SKU ID (longer numeric ID) - use as sku_id in cart_add")
+    name: str = Field(description="Product name")
+    price: float = Field(description="Current price")
+    available: bool = Field(description="In stock at store")
+
+    # Product ID - the shorter identifier needed for cart operations
+    product_id: str | None = Field(
+        default=None,
+        description="Product ID (shorter numeric ID) - use as product_id in cart_add"
+    )
+
+    # Standard fields (optional)
+    brand: str | None = Field(default=None, description="Brand name")
+    size: str | None = Field(default=None, description="Package size")
+    price_per_unit: str | None = Field(default=None, description="Unit price display")
+    image_url: str | None = Field(default=None, description="Product image URL")
+    aisle: str | None = Field(default=None, description="Store aisle number")
+    section: str | None = Field(default=None, description="Store section")
+    has_coupon: bool = Field(default=False, description="Coupon available for this product")
+
+    # Extended fields (optional)
+    nutrition: ProductNutrition | None = Field(default=None, description="Nutrition facts")
+    ingredients: list[str] | None = Field(default=None, description="Ingredient list")
+    on_sale: bool = Field(default=False, description="Currently on sale")
+    original_price: float | None = Field(default=None, description="Price before sale")
+    rating: float | None = Field(default=None, ge=0, le=5, description="Customer rating")
+    coupons: list[ProductCoupon] = Field(
+        default_factory=list, description="Applicable coupons"
+    )
+
+
+class ProductSearchAttempt(BaseModel):
+    """Record of a product search attempt for diagnostics."""
+
+    query: str = Field(description="Query string used")
+    method: Literal["ssr", "typeahead_as_ssr", "typeahead"] = Field(
+        description="Search method attempted"
+    )
+    result: Literal["success", "empty", "security_challenge", "error"] = Field(
+        description="Result of the attempt"
+    )
+    error_detail: str | None = Field(default=None, description="Error details if failed")
+
+
+class ProductSearchResult(BaseModel):
+    """Result of a product search with diagnostic metadata.
+
+    Provides transparency about the search process, including which methods
+    were tried and why fallbacks were used.
+    """
+
+    # Core results
+    products: list[Product] = Field(default_factory=list, description="Found products")
+    count: int = Field(description="Number of products found")
+    query: str = Field(description="Original search query")
+    store_id: str = Field(description="Store ID used for search")
+
+    # Data source tracking
+    data_source: Literal["ssr", "playwright", "typeahead_suggestions"] = Field(
+        description="Source of the product data"
+    )
+    authenticated: bool = Field(
+        default=False, description="Whether authenticated search was attempted"
+    )
+
+    # Diagnostic fields
+    fallback_reason: str | None = Field(
+        default=None, description="Human-readable reason fallback was used"
+    )
+    security_challenge_detected: bool = Field(
+        default=False, description="Whether WAF/captcha was detected"
+    )
+    attempts: list[ProductSearchAttempt] = Field(
+        default_factory=list, description="Query attempts made during search"
+    )
+
+    # Actionable guidance
+    search_url: str | None = Field(
+        default=None, description="Direct URL to search results on heb.com"
+    )
+    playwright_fallback_available: bool = Field(
+        default=False, description="Whether Playwright can be used as fallback"
+    )
+    playwright_instructions: list[str] | None = Field(
+        default=None, description="Instructions for using Playwright MCP fallback"
+    )
+
+    # Session status fields (for proactive refresh guidance)
+    session_needs_refresh: bool = Field(
+        default=False, description="Whether session needs refresh before searching"
+    )
+    session_freshness: dict[str, Any] | None = Field(
+        default=None, description="Session freshness details from check_session_freshness()"
+    )

texas_grocery_mcp/models/store.py

@@ -0,0 +1,77 @@
+"""Store data models."""
+
+from pydantic import BaseModel, Field
+
+
+class StoreHours(BaseModel):
+    """Store operating hours."""
+
+    monday: str = Field(alias="mon", default="6am-11pm")
+    tuesday: str = Field(alias="tue", default="6am-11pm")
+    wednesday: str = Field(alias="wed", default="6am-11pm")
+    thursday: str = Field(alias="thu", default="6am-11pm")
+    friday: str = Field(alias="fri", default="6am-11pm")
+    saturday: str = Field(alias="sat", default="6am-11pm")
+    sunday: str = Field(alias="sun", default="6am-11pm")
+
+    model_config = {"populate_by_name": True}
+
+
+class Store(BaseModel):
+    """HEB store information."""
+
+    store_id: str = Field(description="Unique store identifier")
+    name: str = Field(description="Store display name")
+    address: str = Field(description="Full street address")
+    phone: str | None = Field(default=None, description="Store phone number")
+    distance_miles: float | None = Field(
+        default=None, description="Distance from search location"
+    )
+    hours: StoreHours | None = Field(default=None, description="Operating hours")
+    services: list[str] = Field(
+        default_factory=list,
+        description="Available services (curbside, delivery, pharmacy)",
+    )
+    latitude: float | None = Field(default=None, description="Store latitude")
+    longitude: float | None = Field(default=None, description="Store longitude")
+    supports_curbside: bool = Field(
+        default=True,
+        description="Whether store supports curbside pickup for online orders",
+    )
+    supports_delivery: bool = Field(
+        default=False,
+        description="Whether store supports home delivery",
+    )
+
+
+class GeocodedLocation(BaseModel):
+    """Geocoded location information."""
+
+    latitude: float = Field(description="Latitude of geocoded location")
+    longitude: float = Field(description="Longitude of geocoded location")
+    display_name: str = Field(description="Human-readable location name")
+
+
+class SearchAttempt(BaseModel):
+    """Record of a store search attempt."""
+
+    query: str = Field(description="Query string used")
+    result: str = Field(description="Result: 'success', 'no_stores', 'error'")
+
+
+class StoreSearchResult(BaseModel):
+    """Result of a store search including metadata."""
+
+    stores: list[Store] = Field(default_factory=list, description="Found stores")
+    count: int = Field(description="Number of stores found")
+    search_address: str = Field(description="Original search address")
+    geocoded: GeocodedLocation | None = Field(
+        default=None, description="Geocoded location if available"
+    )
+    attempts: list[SearchAttempt] = Field(
+        default_factory=list, description="Query attempts made"
+    )
+    error: str | None = Field(default=None, description="Error message if search failed")
+    suggestions: list[str] = Field(
+        default_factory=list, description="Suggestions for improving search"
+    )

texas_grocery_mcp/observability/__init__.py

@@ -0,0 +1,6 @@
+"""Observability: logging, metrics, and health checks."""
+
+from texas_grocery_mcp.observability.health import health_live, health_ready
+from texas_grocery_mcp.observability.logging import configure_logging, get_logger
+
+__all__ = ["configure_logging", "get_logger", "health_live", "health_ready"]