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

texas_grocery_mcp/tools/store.py

@@ -0,0 +1,353 @@
+"""Store-related MCP tools."""
+
+from typing import TYPE_CHECKING, Annotated, Any
+
+from pydantic import Field
+
+from texas_grocery_mcp.auth.session import ensure_session
+from texas_grocery_mcp.clients.graphql import KNOWN_STORES
+from texas_grocery_mcp.state import StateManager
+
+if TYPE_CHECKING:
+    from texas_grocery_mcp.clients.graphql import HEBGraphQLClient
+
+
+def _get_client() -> "HEBGraphQLClient":
+    """Get or create GraphQL client."""
+    return StateManager.get_graphql_client_sync()
+
+
+async def store_search(
+    address: Annotated[str, Field(description="Address or zip code to search near")],
+    radius_miles: Annotated[
+        int, Field(description="Search radius in miles", ge=1, le=100)
+    ] = 25,
+) -> dict[str, Any]:
+    """Search for HEB stores near an address.
+
+    Returns stores sorted by distance, including store ID, name,
+    address, and distance from the search location.
+    """
+    client = _get_client()
+    result = await client.search_stores(address=address, radius_miles=radius_miles)
+
+    # Cache found stores for later use in store_change
+    stores_dict = {s.store_id: s for s in result.stores}
+    StateManager.cache_stores_sync(stores_dict)
+
+    # Build response with geocoding metadata
+    response: dict[str, Any] = {
+        "stores": [
+            {
+                "store_id": s.store_id,
+                "name": s.name,
+                "address": s.address,
+                "distance_miles": round(s.distance_miles, 2) if s.distance_miles else None,
+                "phone": s.phone,
+                "supports_curbside": s.supports_curbside,
+                "supports_delivery": s.supports_delivery,
+            }
+            for s in result.stores
+        ],
+        "count": result.count,
+        "search_address": result.search_address,
+    }
+
+    # Add geocoded location if available
+    if result.geocoded:
+        response["geocoded"] = {
+            "latitude": result.geocoded.latitude,
+            "longitude": result.geocoded.longitude,
+            "display_name": result.geocoded.display_name,
+        }
+
+    # Add feedback for failed/partial searches
+    if result.error:
+        response["error"] = result.error
+
+    if result.suggestions:
+        response["suggestions"] = result.suggestions
+
+    if result.attempts:
+        response["attempts"] = [
+            {"query": a.query, "result": a.result}
+            for a in result.attempts
+        ]
+
+    # Add helpful note for successful searches
+    if result.stores:
+        response["note"] = "Use store_change with a store_id to select one."
+
+    return response
+
+
+def store_get_default() -> dict[str, Any]:
+    """Get the currently set default store.
+
+    Returns the default store ID if set, otherwise indicates no default.
+    """
+    default_store_id = StateManager.get_default_store_id()
+
+    if default_store_id is None:
+        # Suggest a known store
+        suggested = list(KNOWN_STORES.values())[0]
+        return {
+            "store_id": None,
+            "message": "Default store not set. Use store_change to set one.",
+            "suggestion": {
+                "store_id": suggested.store_id,
+                "name": suggested.name,
+                "address": suggested.address,
+            },
+            "available_stores": [
+                {"store_id": s.store_id, "name": s.name}
+                for s in KNOWN_STORES.values()
+            ],
+        }
+
+    # Return info about the default store - check found stores first
+    cached_store = StateManager.get_cached_store(default_store_id)
+    if cached_store:
+        return {
+            "store_id": default_store_id,
+            "store_name": cached_store.name,
+            "store_address": cached_store.address,
+            "message": f"Default store is {cached_store.name}",
+        }
+
+    # Fall back to known stores
+    if default_store_id in KNOWN_STORES:
+        store = KNOWN_STORES[default_store_id]
+        return {
+            "store_id": default_store_id,
+            "store_name": store.name,
+            "store_address": store.address,
+            "message": f"Default store is {store.name}",
+        }
+
+    return {
+        "store_id": default_store_id,
+        "message": f"Default store is {default_store_id}",
+    }
+
+
+def get_default_store_id() -> str | None:
+    """Get default store ID for internal use."""
+    return StateManager.get_default_store_id()
+
+
+def set_default_store_id(store_id: str | None) -> None:
+    """Set default store ID for internal/test use.
+
+    This is an internal function - use store_change for the public API.
+    """
+    StateManager.set_default_store_id_sync(store_id)
+
+
+@ensure_session
+async def store_change(
+    store_id: Annotated[str, Field(description="Store ID to change to", min_length=1)],
+    ignore_conflicts: Annotated[
+        bool,
+        Field(
+            description=(
+                "Force store change even if cart has conflicts (items unavailable, "
+                "price changes). Default False - will fail safely and report conflicts."
+            ),
+        ),
+    ] = False,
+) -> dict[str, Any]:
+    """Change the active store for HEB operations.
+
+    When authenticated: Changes the store on HEB.com via their API with verification.
+    When not authenticated: Sets a local default for product searches.
+
+    The store change is VERIFIED by checking the cart's actual store after the
+    mutation. This ensures we never return success when the store didn't actually
+    change (e.g., due to cart conflicts).
+
+    Args:
+        store_id: The store ID to change to
+        ignore_conflicts: If True, force store change even if cart has items
+            unavailable at the new store or with price changes. Default False.
+    """
+    from texas_grocery_mcp.auth.session import is_authenticated
+
+    store_id = store_id.strip()
+
+    # Look up store info if available
+    store_name = None
+    store_address = None
+    supports_curbside = True  # Default to True if unknown
+    store = None
+
+    cached_store = StateManager.get_cached_store(store_id)
+    if cached_store:
+        store = cached_store
+        store_name = store.name
+        store_address = store.address
+        supports_curbside = store.supports_curbside
+    elif store_id in KNOWN_STORES:
+        store = KNOWN_STORES[store_id]
+        store_name = store.name
+        store_address = store.address
+        supports_curbside = store.supports_curbside
+
+    # Check if store supports curbside/online shopping
+    if not supports_curbside:
+        # Find nearest eligible store to suggest
+        suggestion = None
+        for s in StateManager.get_cached_stores_values():
+            if s.supports_curbside and s.store_id != store_id:
+                suggestion = {
+                    "store_id": s.store_id,
+                    "name": s.name,
+                    "address": s.address,
+                    "distance_miles": s.distance_miles,
+                }
+                break
+
+        store_label = store_name or f"Store {store_id}"
+        message = (
+            f"{store_label} doesn't support online shopping (curbside pickup). "
+            "This store is in-store only."
+        )
+
+        if suggestion:
+            message = f"{message} Try {suggestion['name']} instead."
+
+        result: dict[str, Any] = {
+            "error": True,
+            "code": "STORE_NOT_ELIGIBLE",
+            "message": message,
+            "store_id": store_id,
+            "store_name": store_name,
+        }
+        if suggestion:
+            result["suggestion"] = suggestion
+        return result
+
+    # If not authenticated, set local default only
+    if not is_authenticated():
+        StateManager.set_default_store_id_sync(store_id)
+        return {
+            "success": True,
+            "store_id": store_id,
+            "store_name": store_name,
+            "store_address": store_address,
+            "message": f"Local default set to {store_name or store_id}",
+            "method": "local_only",
+            "warning": "Not logged in - store set locally for product searches only.",
+            "how_to_sync": (
+                "Run session_refresh to log in, then call store_change again to sync with "
+                "HEB.com."
+            ),
+        }
+
+    # Call the GraphQL API to change the store (with verification)
+    client = _get_client()
+    result = await client.select_store(store_id, ignore_conflicts=ignore_conflicts)
+
+    if result.get("error"):
+        # API failed or verification failed - return the error details
+        error_response = {
+            "error": True,
+            "code": result.get("code", "STORE_CHANGE_FAILED"),
+            "message": result.get("message", "Failed to change store via API"),
+            "store_id": store_id,
+            "store_name": store_name,
+        }
+
+        # Include additional context from the API response
+        if result.get("expected_store"):
+            error_response["expected_store"] = result["expected_store"]
+        if result.get("actual_store"):
+            error_response["actual_store"] = result["actual_store"]
+        if result.get("suggestion"):
+            error_response["suggestion"] = result["suggestion"]
+
+        # For cart conflicts, add specific guidance
+        if result.get("code") == "CART_CONFLICT":
+            error_response["help"] = (
+                "Your cart has items that may be unavailable or priced differently at the "
+                "new store. "
+                "Options: (1) Call store_change with ignore_conflicts=True to force the change, "
+                "(2) Clear your cart first, or (3) Keep your current store."
+            )
+
+        return error_response
+
+    # SUCCESS - Store change verified!
+    # Now safe to update local state since we know server state matches
+    StateManager.set_default_store_id_sync(store_id)
+
+    # Update the cookie in auth.json so session_status reflects the change
+    _update_store_cookie(store_id)
+
+    return {
+        "success": True,
+        "store_id": store_id,
+        "store_name": store_name,
+        "store_address": store_address,
+        "message": f"Store successfully changed to {store_name or store_id}",
+        "method": "api",
+        "verified": result.get("verified", False),
+    }
+
+
+def _update_store_cookie(store_id: str) -> bool:
+    """Update the CURR_SESSION_STORE cookie in auth.json.
+
+    This ensures session_status reflects the new store immediately.
+
+    Args:
+        store_id: The new store ID
+
+    Returns:
+        True if updated successfully, False otherwise
+    """
+    import json
+
+    from texas_grocery_mcp.utils.config import get_settings
+
+    settings = get_settings()
+    auth_path = settings.auth_state_path
+
+    if not auth_path.exists():
+        return False
+
+    try:
+        with open(auth_path) as f:
+            state = json.load(f)
+
+        cookies = state.get("cookies", [])
+        found = False
+
+        for cookie in cookies:
+            if cookie.get("name") == "CURR_SESSION_STORE" and "heb.com" in cookie.get("domain", ""):
+                cookie["value"] = store_id
+                found = True
+                break
+
+        if not found:
+            # Add the cookie if it doesn't exist
+            cookies.append({
+                "name": "CURR_SESSION_STORE",
+                "value": store_id,
+                "domain": "www.heb.com",
+                "path": "/",
+                "expires": -1,
+                "httpOnly": True,
+                "secure": True,
+                "sameSite": "Lax",
+            })
+            state["cookies"] = cookies
+
+        from texas_grocery_mcp.utils.secure_file import write_secure_json
+
+        write_secure_json(auth_path, state)
+
+        return True
+
+    except (json.JSONDecodeError, OSError):
+        return False

texas_grocery_mcp/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility modules for Texas Grocery MCP."""
+
+from texas_grocery_mcp.utils.config import Settings, get_settings
+
+__all__ = ["Settings", "get_settings"]

texas_grocery_mcp/utils/config.py

@@ -0,0 +1,146 @@
+"""Configuration management using Pydantic Settings."""
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # HEB Configuration
+    heb_default_store: str | None = Field(
+        default=None,
+        description="Default HEB store ID for operations",
+    )
+    heb_graphql_url: str = Field(
+        default="https://www.heb.com/graphql",
+        description="HEB GraphQL API endpoint",
+    )
+
+    # Auth State
+    auth_state_path: Path = Field(
+        default=Path("~/.texas-grocery-mcp/auth.json").expanduser(),
+        description="Path to Playwright auth state file",
+    )
+
+    # Redis Configuration
+    redis_url: str | None = Field(
+        default=None,
+        description="Redis connection URL for caching",
+    )
+
+    # Observability
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = Field(
+        default="INFO",
+        description="Logging level",
+    )
+    environment: Literal["development", "staging", "production"] = Field(
+        default="development",
+        description="Deployment environment",
+    )
+
+    # Reliability
+    retry_attempts: int = Field(
+        default=3,
+        ge=1,
+        le=10,
+        description="Number of retry attempts for failed requests",
+    )
+    circuit_breaker_threshold: int = Field(
+        default=5,
+        ge=1,
+        description="Failures before circuit breaker opens",
+    )
+    circuit_breaker_timeout: int = Field(
+        default=30,
+        ge=5,
+        description="Seconds before circuit breaker attempts recovery",
+    )
+
+    # Throttling - SSR
+    max_concurrent_ssr_searches: int = Field(
+        default=3,
+        ge=1,
+        le=20,
+        description="Maximum concurrent SSR product searches",
+    )
+    min_ssr_delay_ms: int = Field(
+        default=200,
+        ge=0,
+        le=5000,
+        description="Minimum delay between SSR requests in milliseconds",
+    )
+    ssr_jitter_ms: int = Field(
+        default=200,
+        ge=0,
+        le=1000,
+        description="Random jitter added to SSR delay (0 to N ms)",
+    )
+
+    # Throttling - GraphQL
+    max_concurrent_graphql: int = Field(
+        default=5,
+        ge=1,
+        le=20,
+        description="Maximum concurrent GraphQL API calls",
+    )
+    min_graphql_delay_ms: int = Field(
+        default=100,
+        ge=0,
+        le=5000,
+        description="Minimum delay between GraphQL requests in milliseconds",
+    )
+    graphql_jitter_ms: int = Field(
+        default=100,
+        ge=0,
+        le=1000,
+        description="Random jitter added to GraphQL delay (0 to N ms)",
+    )
+
+    # Throttling - Global
+    throttling_enabled: bool = Field(
+        default=True,
+        description="Enable/disable request throttling globally",
+    )
+
+    # Session Auto-Refresh
+    auto_refresh_enabled: bool = Field(
+        default=True,
+        description="Enable automatic session refresh before tool execution",
+    )
+    auto_refresh_threshold_hours: float = Field(
+        default=4.0,
+        ge=0.5,
+        le=24.0,
+        description="Refresh session when less than this many hours remaining",
+    )
+    auto_refresh_on_startup: bool = Field(
+        default=False,
+        description=(
+            "Check and refresh session on MCP server startup (disabled by default - "
+            "login should be explicit)"
+        ),
+    )
+
+    def model_post_init(self, __context: Any) -> None:
+        """Ensure auth state path is expanded."""
+        if "~" in str(self.auth_state_path):
+            object.__setattr__(
+                self, "auth_state_path", Path(str(self.auth_state_path)).expanduser()
+            )
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Get cached settings instance."""
+    return Settings()

texas_grocery_mcp/utils/secure_file.py

@@ -0,0 +1,123 @@
+"""Secure file operations for sensitive data."""
+
+import json
+import os
+import stat
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger()
+
+# File permissions: owner read/write only (0o600)
+SECURE_FILE_MODE = stat.S_IRUSR | stat.S_IWUSR
+
+# Directory permissions: owner read/write/execute only (0o700)
+SECURE_DIR_MODE = stat.S_IRWXU
+
+
+def write_secure_json(path: Path, data: Any, indent: int = 2) -> None:
+    """Write JSON data to a file with secure permissions.
+
+    Creates the file with 0o600 permissions (owner read/write only).
+    If the file exists, ensures permissions are correct before writing.
+
+    Args:
+        path: Path to write to
+        data: Data to serialize as JSON
+        indent: JSON indentation level
+
+    Raises:
+        OSError: If file operations fail
+    """
+    # Ensure path is a Path object
+    path = Path(path)
+
+    # Ensure parent directory exists with secure permissions
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Set directory permissions to 0o700 (owner only)
+    try:
+        os.chmod(path.parent, SECURE_DIR_MODE)
+    except OSError as e:
+        logger.warning(
+            "Could not set directory permissions",
+            path=str(path.parent),
+            error=str(e),
+        )
+
+    # Write to a temp file first, then rename (atomic on POSIX)
+    temp_path = path.with_suffix(".tmp")
+
+    try:
+        # Create file with secure permissions using os.open
+        fd = os.open(
+            temp_path,
+            os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
+            SECURE_FILE_MODE,
+        )
+
+        try:
+            with os.fdopen(fd, "w") as f:
+                json.dump(data, f, indent=indent)
+        except Exception:
+            # fd is closed by fdopen even on error, but if fdopen fails
+            # we need to close it manually
+            with suppress(OSError):
+                os.close(fd)
+            raise
+
+        # Atomic rename
+        os.replace(temp_path, path)
+
+        logger.debug(
+            "Wrote secure file",
+            path=str(path),
+            mode=oct(SECURE_FILE_MODE),
+        )
+
+    except Exception:
+        # Clean up temp file if it exists
+        if temp_path.exists():
+            with suppress(OSError):
+                temp_path.unlink()
+        raise
+
+
+def ensure_secure_permissions(path: Path) -> bool:
+    """Ensure a file has secure permissions (0o600).
+
+    Args:
+        path: Path to check/fix
+
+    Returns:
+        True if permissions are now secure, False if unable to fix
+    """
+    path = Path(path)
+
+    if not path.exists():
+        return True
+
+    try:
+        current_mode = path.stat().st_mode & 0o777
+
+        if current_mode != SECURE_FILE_MODE:
+            os.chmod(path, SECURE_FILE_MODE)
+            logger.info(
+                "Fixed file permissions",
+                path=str(path),
+                old_mode=oct(current_mode),
+                new_mode=oct(SECURE_FILE_MODE),
+            )
+
+        return True
+
+    except OSError as e:
+        logger.warning(
+            "Could not fix file permissions",
+            path=str(path),
+            error=str(e),
+        )
+        return False