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

texas_grocery_mcp/server.py

@@ -0,0 +1,211 @@
+"""Texas Grocery MCP Server - FastMCP entry point."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+import structlog
+from fastmcp import FastMCP
+
+from texas_grocery_mcp.observability.health import health_live, health_ready
+from texas_grocery_mcp.observability.logging import configure_logging
+from texas_grocery_mcp.tools.cart import (
+    cart_add,
+    cart_add_many,
+    cart_add_with_retry,
+    cart_check_auth,
+    cart_get,
+    cart_remove,
+)
+from texas_grocery_mcp.tools.coupon import (
+    coupon_categories,
+    coupon_clip,
+    coupon_clipped,
+    coupon_list,
+    coupon_search,
+)
+from texas_grocery_mcp.tools.product import product_get, product_search, product_search_batch
+from texas_grocery_mcp.tools.session import (
+    session_clear,
+    session_clear_credentials,
+    session_refresh,
+    session_save_credentials,
+    session_save_instructions,
+    session_status,
+)
+from texas_grocery_mcp.tools.store import (
+    store_change,
+    store_get_default,
+    store_search,
+)
+from texas_grocery_mcp.utils.config import get_settings
+
+# Configure logging before anything else
+configure_logging()
+
+logger = structlog.get_logger()
+
+
+@asynccontextmanager
+async def lifespan(app: FastMCP) -> AsyncIterator[None]:
+    """Lifespan hook for startup/shutdown tasks.
+
+    On startup:
+    - Checks session status
+    - Auto-refreshes if enabled and session needs refresh
+    """
+    settings = get_settings()
+
+    # Startup: Check and refresh session if needed
+    if settings.auto_refresh_on_startup:
+        try:
+            from texas_grocery_mcp.auth.session import get_session_status
+
+            status = get_session_status()
+            logger.info(
+                "Startup session check",
+                authenticated=status["authenticated"],
+                needs_refresh=status["needs_refresh"],
+                time_remaining_hours=status["time_remaining_hours"],
+            )
+
+            # Auto-refresh if needed
+            if status["needs_refresh"] or (
+                status["time_remaining_hours"] is not None
+                and status["time_remaining_hours"] < settings.auto_refresh_threshold_hours
+            ):
+                logger.info("Startup auto-refresh triggered")
+                try:
+                    result = await session_refresh(headless=True)
+                    if result.get("success"):
+                        logger.info(
+                            "Startup session refresh successful",
+                            elapsed_seconds=result.get("elapsed_seconds"),
+                        )
+                    else:
+                        logger.warning(
+                            "Startup session refresh failed",
+                            error=result.get("error"),
+                            error_type=result.get("error_type"),
+                        )
+                except Exception as e:
+                    logger.warning("Startup session refresh error", error=str(e))
+
+        except Exception as e:
+            logger.warning("Startup session check failed", error=str(e))
+
+    yield  # Server runs here
+
+    # Shutdown: cleanup if needed
+    logger.info("MCP server shutting down")
+
+MCP_INSTRUCTIONS = """
+## Texas Grocery MCP - Session Management
+
+This MCP requires an authenticated HEB.com session for most operations.
+
+### Before using cart, coupon, or store_change tools:
+1. Call `session_status` to check authentication state
+2. If `authenticated: false` or `needs_refresh: true`, call `session_refresh`
+3. If session_refresh fails with headless mode, retry with `headless=False` for manual login
+
+### Session states:
+- `authenticated: true, needs_refresh: false` → Ready to use all tools
+- `authenticated: true, refresh_recommended: true` → Works but consider refreshing soon
+- `authenticated: false` or `needs_refresh: true` → Must refresh before cart/coupon operations
+
+### Tools that work WITHOUT authentication:
+- `store_search` - Find stores by address
+- `product_search` / `product_search_batch` - Search products (uses local store default)
+- `product_get` - Get detailed product info (ingredients, nutrition, warnings)
+- `session_status` - Check session state
+- `session_refresh` - Refresh/login
+
+### Tools that REQUIRE authentication:
+- `store_change` - Change store on HEB.com account
+- `cart_get`, `cart_add`, `cart_add_many`, `cart_remove` - Cart operations
+- `coupon_list`, `coupon_clip`, `coupon_clipped` - Coupon operations
+
+### Typical workflow:
+1. `session_status` → Check if authenticated
+2. If not authenticated: `session_refresh(headless=False)` → User logs in via browser
+3. `store_search("address")` → Find nearby stores
+4. `store_change(store_id)` → Set preferred store
+5. `product_search("query")` → Search for products
+6. `cart_add(sku)` → Add to cart
+
+### Automatic Login (Optional)
+Save your HEB credentials once for automatic login when sessions expire:
+
+1. `session_save_credentials(email, password)` → Store credentials securely
+2. Now `session_refresh` will auto-login when session expires
+3. `session_clear_credentials()` → Remove stored credentials if needed
+
+### Human Handoff (Login/CAPTCHA/2FA/WAF)
+When login requires human action (login form, CAPTCHA, 2FA, or a bot/WAF interstitial),
+`session_refresh` returns immediately with:
+- `status: "human_action_required"` - Clear indicator that human action is needed
+- `action: "login" | "captcha" | "2fa" | "waf"` - What type of action is needed
+- `screenshot_path: "/tmp/heb-login-<action>-123456.png"` - Screenshot of what's shown
+
+**Workflow when human action is required:**
+1. `session_refresh` returns with `status: "human_action_required"`
+2. Read the screenshot at `screenshot_path` to see what's shown
+3. Tell the user what's needed (log in, solve CAPTCHA, enter 2FA, or clear the WAF prompt)
+4. User completes the action in the browser window that's open
+5. User tells you "done" when finished
+6. Call `session_refresh()` again to continue the login
+7. Repeat until `status: "success"` or `status: "failed"`
+"""
+
+mcp = FastMCP(
+    name="texas-grocery-mcp",
+    version="0.1.0",
+    instructions=MCP_INSTRUCTIONS,
+    lifespan=lifespan,
+)
+
+# Register store tools
+mcp.tool(annotations={"readOnlyHint": True})(store_search)
+mcp.tool(annotations={"readOnlyHint": True})(store_get_default)
+mcp.tool()(store_change)  # Changes store on HEB.com when authenticated, or sets local default
+
+# Register product tools
+mcp.tool(annotations={"readOnlyHint": True})(product_search)
+mcp.tool(annotations={"readOnlyHint": True})(product_search_batch)
+mcp.tool(annotations={"readOnlyHint": True})(product_get)
+
+# Register coupon tools
+mcp.tool(annotations={"readOnlyHint": True})(coupon_list)
+mcp.tool(annotations={"readOnlyHint": True})(coupon_search)
+mcp.tool(annotations={"readOnlyHint": True})(coupon_categories)
+mcp.tool(annotations={"destructiveHint": True})(coupon_clip)
+mcp.tool(annotations={"readOnlyHint": True})(coupon_clipped)
+
+# Register cart tools (destructive operations require confirmation)
+mcp.tool(annotations={"readOnlyHint": True})(cart_check_auth)
+mcp.tool(annotations={"readOnlyHint": True})(cart_get)
+mcp.tool(annotations={"destructiveHint": True})(cart_add)
+mcp.tool(annotations={"destructiveHint": True})(cart_add_many)
+mcp.tool(annotations={"destructiveHint": True})(cart_add_with_retry)
+mcp.tool(annotations={"destructiveHint": True})(cart_remove)
+
+# Register session tools
+mcp.tool(annotations={"readOnlyHint": True})(session_status)
+mcp.tool(annotations={"readOnlyHint": True})(session_save_instructions)
+mcp.tool()(session_refresh)  # Uses embedded Playwright when available, falls back to commands
+mcp.tool()(session_clear)
+mcp.tool()(session_save_credentials)  # Store HEB credentials for auto-login
+mcp.tool()(session_clear_credentials)  # Remove stored credentials
+
+# Register health check tools
+mcp.tool(annotations={"readOnlyHint": True})(health_live)
+mcp.tool(annotations={"readOnlyHint": True})(health_ready)
+
+
+def main() -> None:
+    """Run the MCP server."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

texas_grocery_mcp/services/__init__.py

@@ -0,0 +1,5 @@
+"""Services for Texas Grocery MCP."""
+
+from texas_grocery_mcp.services.geocoding import GeocodingResult, GeocodingService
+
+__all__ = ["GeocodingResult", "GeocodingService"]

texas_grocery_mcp/services/geocoding.py

@@ -0,0 +1,227 @@
+"""Geocoding service using Nominatim (OpenStreetMap)."""
+
+import math
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+import structlog
+
+logger = structlog.get_logger()
+
+# Nominatim API endpoint
+NOMINATIM_URL = "https://nominatim.openstreetmap.org/search"
+
+# Nominatim requires a valid User-Agent. They block custom app names
+# without real contact info. Using curl format as a pragmatic workaround.
+USER_AGENT = "curl/8.7.1"
+
+
+@dataclass
+class GeocodingResult:
+    """Result from geocoding an address."""
+
+    latitude: float
+    longitude: float
+    city: str | None
+    state: str | None
+    postcode: str | None
+    display_name: str
+
+    def get_query_variations(self, original_query: str) -> list[str]:
+        """Generate query variations to try against HEB's API.
+
+        Returns queries in priority order:
+        1. Zip code (most reliable)
+        2. City, State format
+        3. Original query
+        """
+        variations = []
+
+        # Priority 1: Zip code
+        if self.postcode:
+            # Extract just the 5-digit zip if it has extension
+            zip_code = self.postcode.split("-")[0].strip()
+            if zip_code:
+                variations.append(zip_code)
+
+        # Priority 2: City, State
+        if self.city and self.state:
+            variations.append(f"{self.city}, {self.state}")
+
+        # Priority 3: Original query (if not already covered)
+        original_lower = original_query.lower().strip()
+        if not any(v.lower() == original_lower for v in variations):
+            variations.append(original_query)
+
+        return variations
+
+
+class GeocodingService:
+    """Geocoding via Nominatim (OpenStreetMap).
+
+    Converts addresses, neighborhoods, and landmarks to coordinates
+    and structured address components.
+    """
+
+    def __init__(self, timeout: float = 15.0):
+        """Initialize geocoding service.
+
+        Args:
+            timeout: Request timeout in seconds (default 15s for Nominatim)
+        """
+        self.timeout = timeout
+        self._client: httpx.AsyncClient | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create HTTP client."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                timeout=httpx.Timeout(self.timeout),
+                headers={"User-Agent": USER_AGENT},
+                http2=False,  # Nominatim doesn't handle HTTP/2 well
+            )
+        return self._client
+
+    async def close(self) -> None:
+        """Close HTTP client."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    async def geocode(self, address: str) -> GeocodingResult | None:
+        """Convert address to coordinates and structured components.
+
+        Args:
+            address: Address, zip code, neighborhood, or landmark to geocode
+
+        Returns:
+            GeocodingResult with coordinates and address components,
+            or None if geocoding failed
+        """
+        if not address or not address.strip():
+            return None
+
+        client = await self._get_client()
+
+        params = {
+            "q": address.strip(),
+            "format": "json",
+            "addressdetails": "1",
+            "limit": "1",
+            "countrycodes": "us",
+        }
+
+        try:
+            logger.debug("Geocoding address", address=address)
+            response = await client.get(NOMINATIM_URL, params=params)
+            response.raise_for_status()
+
+            results = response.json()
+            if not results:
+                logger.info("Geocoding returned no results", address=address)
+                return None
+
+            return self._parse_result(results[0])
+
+        except httpx.TimeoutException:
+            logger.warning("Geocoding timeout", address=address)
+            return None
+        except httpx.HTTPError as e:
+            logger.warning("Geocoding HTTP error", address=address, error=str(e))
+            return None
+        except Exception as e:
+            logger.error("Geocoding unexpected error", address=address, error=str(e))
+            return None
+
+    def _parse_result(self, result: dict[str, Any]) -> GeocodingResult:
+        """Parse Nominatim API result into GeocodingResult.
+
+        Args:
+            result: Single result from Nominatim API
+
+        Returns:
+            GeocodingResult with extracted data
+        """
+        address_details = result.get("address", {})
+
+        # Extract city - Nominatim uses various fields
+        city = (
+            address_details.get("city")
+            or address_details.get("town")
+            or address_details.get("village")
+            or address_details.get("municipality")
+            or address_details.get("county")
+        )
+
+        # Extract state
+        state = address_details.get("state")
+        # Convert full state name to abbreviation if needed
+        state = self._abbreviate_state(state) if state else None
+
+        return GeocodingResult(
+            latitude=float(result["lat"]),
+            longitude=float(result["lon"]),
+            city=city,
+            state=state,
+            postcode=address_details.get("postcode"),
+            display_name=result.get("display_name", ""),
+        )
+
+    def _abbreviate_state(self, state: str) -> str:
+        """Convert state name to abbreviation.
+
+        Args:
+            state: Full state name or abbreviation
+
+        Returns:
+            Two-letter state abbreviation
+        """
+        # If already abbreviated, return as-is
+        if len(state) == 2:
+            return state.upper()
+
+        state_abbrevs = {
+            "texas": "TX",
+            "california": "CA",
+            "new york": "NY",
+            "florida": "FL",
+            "louisiana": "LA",
+            "oklahoma": "OK",
+            "new mexico": "NM",
+            "arkansas": "AR",
+            "arizona": "AZ",
+            "colorado": "CO",
+            # Add more as needed
+        }
+
+        return state_abbrevs.get(state.lower(), state)
+
+    @staticmethod
+    def haversine_miles(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+        """Calculate distance between two points using Haversine formula.
+
+        Args:
+            lat1, lon1: First point coordinates (degrees)
+            lat2, lon2: Second point coordinates (degrees)
+
+        Returns:
+            Distance in miles
+        """
+        # Earth radius in miles
+        earth_radius_miles = 3959
+
+        # Convert to radians
+        lat1_rad = math.radians(lat1)
+        lat2_rad = math.radians(lat2)
+        delta_lat = math.radians(lat2 - lat1)
+        delta_lon = math.radians(lon2 - lon1)
+
+        # Haversine formula
+        a = (
+            math.sin(delta_lat / 2) ** 2
+            + math.cos(lat1_rad) * math.cos(lat2_rad) * math.sin(delta_lon / 2) ** 2
+        )
+        c = 2 * math.atan2(math.sqrt(a), math.sqrt(1 - a))
+
+        return earth_radius_miles * c

texas_grocery_mcp/state.py

@@ -0,0 +1,166 @@
+"""Thread-safe state management for MCP tools.
+
+Uses contextvars for request-scoped state and locks for shared resources.
+"""
+
+import asyncio
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any, cast
+
+import structlog
+
+logger = structlog.get_logger()
+
+if TYPE_CHECKING:
+    from texas_grocery_mcp.clients.graphql import HEBGraphQLClient
+
+# Request-scoped state using contextvars
+_request_store_id: ContextVar[str | None] = ContextVar("request_store_id", default=None)
+
+# Shared state with proper locking
+_state_lock = asyncio.Lock()
+_shared_state: dict[str, Any] = {
+    "default_store_id": None,
+    "found_stores": {},
+    "graphql_client": None,
+    "pending_login": None,
+}
+
+
+class StateManager:
+    """Thread-safe state manager for MCP tools.
+
+    Provides:
+    - Request-scoped store ID via contextvars
+    - Shared GraphQL client with lazy initialization
+    - Thread-safe store cache
+    - Login state management with locking
+    """
+
+    # --- GraphQL Client (singleton, thread-safe) ---
+
+    @staticmethod
+    async def get_graphql_client() -> "HEBGraphQLClient":
+        """Get or create the shared GraphQL client.
+
+        Thread-safe lazy initialization.
+        """
+        from texas_grocery_mcp.clients.graphql import HEBGraphQLClient
+
+        async with _state_lock:
+            if _shared_state["graphql_client"] is None:
+                _shared_state["graphql_client"] = HEBGraphQLClient()
+            return cast(HEBGraphQLClient, _shared_state["graphql_client"])
+
+    @staticmethod
+    def get_graphql_client_sync() -> "HEBGraphQLClient":
+        """Get or create GraphQL client (sync version for non-async contexts).
+
+        Note: Initialization is not fully thread-safe, but acceptable for
+        MCP's primarily single-threaded execution model.
+        """
+        from texas_grocery_mcp.clients.graphql import HEBGraphQLClient
+
+        if _shared_state["graphql_client"] is None:
+            _shared_state["graphql_client"] = HEBGraphQLClient()
+        return cast(HEBGraphQLClient, _shared_state["graphql_client"])
+
+    # --- Default Store ID ---
+
+    @staticmethod
+    def get_default_store_id() -> str | None:
+        """Get the current default store ID."""
+        # Check request-scoped override first
+        request_store = _request_store_id.get()
+        if request_store is not None:
+            return request_store
+        return cast(str | None, _shared_state["default_store_id"])
+
+    @staticmethod
+    async def set_default_store_id(store_id: str | None) -> None:
+        """Set the default store ID (thread-safe)."""
+        async with _state_lock:
+            _shared_state["default_store_id"] = store_id
+
+    @staticmethod
+    def set_default_store_id_sync(store_id: str | None) -> None:
+        """Set default store ID (sync version)."""
+        _shared_state["default_store_id"] = store_id
+
+    @staticmethod
+    def set_request_store_id(store_id: str | None) -> None:
+        """Set store ID for the current request only."""
+        _request_store_id.set(store_id)
+
+    # --- Found Stores Cache ---
+
+    @staticmethod
+    async def cache_stores(stores: dict[str, Any]) -> None:
+        """Cache stores found via search (thread-safe)."""
+        async with _state_lock:
+            _shared_state["found_stores"].update(stores)
+
+    @staticmethod
+    def cache_stores_sync(stores: dict[str, Any]) -> None:
+        """Cache stores found via search (sync version)."""
+        _shared_state["found_stores"].update(stores)
+
+    @staticmethod
+    def get_cached_store(store_id: str) -> Any | None:
+        """Get a cached store by ID."""
+        return _shared_state["found_stores"].get(store_id)
+
+    @staticmethod
+    def get_all_cached_stores() -> dict[str, Any]:
+        """Get all cached stores (returns a copy for safety)."""
+        return dict(cast(dict[str, Any], _shared_state["found_stores"]))
+
+    @staticmethod
+    def get_cached_stores_values() -> Any:
+        """Get cached stores values (for iteration)."""
+        return _shared_state["found_stores"].values()
+
+    # --- Pending Login State ---
+
+    @staticmethod
+    async def get_pending_login() -> dict[str, Any] | None:
+        """Get pending login state (thread-safe)."""
+        async with _state_lock:
+            return cast(dict[str, Any] | None, _shared_state["pending_login"])
+
+    @staticmethod
+    def get_pending_login_sync() -> dict[str, Any] | None:
+        """Get pending login state (sync version)."""
+        return cast(dict[str, Any] | None, _shared_state["pending_login"])
+
+    @staticmethod
+    async def set_pending_login(state: dict[str, Any] | None) -> None:
+        """Set pending login state (thread-safe)."""
+        async with _state_lock:
+            _shared_state["pending_login"] = state
+
+    @staticmethod
+    def set_pending_login_sync(state: dict[str, Any] | None) -> None:
+        """Set pending login state (sync version)."""
+        _shared_state["pending_login"] = state
+
+    # --- Reset (for testing) ---
+
+    @staticmethod
+    async def reset() -> None:
+        """Reset all state. For testing only."""
+        async with _state_lock:
+            _shared_state["default_store_id"] = None
+            _shared_state["found_stores"] = {}
+            _shared_state["graphql_client"] = None
+            _shared_state["pending_login"] = None
+        _request_store_id.set(None)
+
+    @staticmethod
+    def reset_sync() -> None:
+        """Reset all state synchronously. For testing only."""
+        _shared_state["default_store_id"] = None
+        _shared_state["found_stores"] = {}
+        _shared_state["graphql_client"] = None
+        _shared_state["pending_login"] = None
+        _request_store_id.set(None)

texas_grocery_mcp/tools/__init__.py

@@ -0,0 +1,5 @@
+"""MCP tool definitions."""
+
+from texas_grocery_mcp.tools import cart, coupon, product, session, store
+
+__all__ = ["cart", "coupon", "product", "session", "store"]