Search for HEB stores near an address.

Returns stores sorted by distance, including store ID, name, address, and distance from the search location.

Get the currently set default store.

Returns the default store ID if set, otherwise indicates no default.

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.

Search for products at an HEB store.

Returns products matching the query with pricing and availability for the specified store.

Search for multiple products at once.

More efficient than calling product_search multiple times. Handles throttling internally to prevent rate limiting.

Returns results for each query, with availability at the specified store.

Get comprehensive details for a single product.

Returns detailed product information including:

• Full description

• Complete ingredients text

• Safety/allergen warnings

• Nutritional information (full FDA panel for packaged food)

• Storage and preparation instructions

• Dietary attributes (Gluten-Free, Organic, Vegan, etc.)

• Store location (aisle or section)

Use this when you need more information than product_search provides, such as checking ingredients for dietary restrictions or allergens.

Args: product_id: The product ID from product_search results store_id: Optional store ID for store-specific pricing

Returns: Comprehensive product details or error response

List available HEB digital coupons.

Returns coupons with discount details, descriptions, and expiration dates. Filter by category to find coupons in specific departments.

Search for HEB coupons by keyword.

Search for coupons by product name, brand, or discount type.

Get available coupon categories/departments.

Returns a list of categories with the number of coupons in each. Use category names with coupon_list to filter coupons.

Clip a coupon to your HEB account.

Without confirm=true, returns a preview of the action. With confirm=true, clips the coupon (requires authentication).

Clipped coupons automatically apply at checkout when you buy eligible items.

List your clipped coupons.

Returns all coupons you've clipped to your HEB account. Clipped coupons automatically apply at checkout when you buy eligible items.

Check if authenticated for cart operations.

Returns authentication status and instructions if not authenticated. Use this before attempting cart operations.

Get current cart contents.

Returns all items in the cart with quantities and prices.

Add an item to the shopping cart with verification.

Without confirm=true, returns a preview of the action. With confirm=true, executes the action and VERIFIES it worked.

IMPORTANT: Use both product_id and sku_id from product_search results:

• product_id: shorter ID (e.g., '127074')

• sku_id: longer ID (e.g., '4122071073')

Returns error if item wasn't actually added to cart.

Add multiple items to cart with a single confirmation.

This is more efficient than calling cart_add multiple times and provides a single confirmation gate for the entire batch.

IMPORTANT: This operation uses STRICT success semantics. If ANY item fails to add, the entire operation is reported as a FAILURE. Items that were successfully added will remain in the cart, but you'll receive a clear list of which items failed.

Args: items: List of items, each with product_id, sku_id, and quantity confirm: Must be True to actually add items (human-in-the-loop safety)

Returns: On success: All items added with details On failure: List of failed items with reasons (successful items stay in cart)

Add item to cart with automatic ID correction.

If the initial add fails due to ID format issues and auto_correct_ids=True, this will search for the product and retry with the correct IDs.

This is a more resilient version of cart_add that can recover from incorrect ID formats by looking up the product.

Remove an item from the shopping cart.

Without confirm=true, returns a preview of the action. With confirm=true, executes the action.

Get current session status including token lifecycle and credential storage.

Returns comprehensive session information:

• authenticated: Whether session is valid

• needs_refresh: Whether refresh is required now (token expired)

• refresh_recommended: Whether proactive refresh is advised (< 4 hours remaining)

• time_remaining_hours: Hours until token expires

• expires_at: ISO timestamp of expiration

• message: Human-readable status

• credentials_stored: Whether HEB credentials are saved for auto-login

Use this to check session health before operations or to decide when to proactively refresh.

Get instructions for saving browser session cookies.

Call this to get step-by-step instructions for authenticating via Playwright MCP and saving the session for fast API access.

For automatic session extraction, use session_refresh instead.

Refresh HEB session cookies and tokens.

Uses embedded browser when available (fast: ~10-15 seconds). If credentials are saved and login is required, attempts automatic login. Falls back to returning Playwright MCP commands if browser dependencies aren't installed.

Args: headless: Run browser without visible window (default True). Set to False if you need to complete a manual login (e.g., when your session has fully expired). timeout: Maximum time to wait for page load in milliseconds. Default 30000 (30 seconds). login_timeout: Maximum time to wait for manual login in milliseconds. Default 300000 (5 minutes). Only used when headless=False. use_saved_credentials: If True and credentials are stored, attempt automatic login when session is expired. Default True.

Returns: dict with one of these statuses: - {"status": "success", ...} - Login/refresh completed successfully - {"status": "human_action_required", "action": "login" | "captcha" | "2fa" | "waf", ...} Human intervention required (login form, CAPTCHA, 2FA, or a WAF/security interstitial). The browser remains open; complete the action, then call session_refresh() again. - {"status": "failed", ...} - Login/refresh failed with error details

Use this tool when:

• session_status shows needs_refresh: true

• session_status shows refresh_recommended: true

• product_search returns security_challenge_detected: true

• You want to proactively refresh before token expires

CAPTCHA/2FA handling:

• When CAPTCHA or 2FA is detected, returns immediately with screenshot_path

• The screenshot shows exactly what the user sees in the browser

• Use the Read tool to view the screenshot and describe it to the user

• The browser stays open - user solves CAPTCHA/enters code in that window

• After solving, call session_refresh() again to continue the login flow

• Repeat until status is "success" or "failed"

Clear saved session cookies.

Use this to log out or clear invalid session data. After clearing, you will need to run session_refresh again.

Note: This does NOT clear saved credentials. Use session_clear_credentials() to remove stored login credentials.

Save HEB login credentials for automatic login.

Credentials are stored securely using:

• OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)

• Encrypted file fallback when keyring is unavailable

After saving, session_refresh will automatically use these credentials when your session expires, eliminating manual browser login.

Args: email: Your HEB.com account email address password: Your HEB.com account password

Returns: dict with success status and storage method used

Security notes:

• Credentials are encrypted at rest

• Password is never logged or exposed in output

• Use session_clear_credentials() to remove stored credentials

Example: session_save_credentials("user@example.com", "mypassword") # Now session_refresh will auto-login when session expires

Remove stored HEB login credentials.

After clearing, session_refresh will fall back to manual browser login when your session expires.

Returns: dict with success status

Note: This does NOT clear your current session. Use session_clear() to remove session cookies.

Liveness probe - is the process running?

Returns a simple alive status. Use for Kubernetes liveness probes.

Readiness probe - can the server handle requests?

Returns detailed component health. Use for Kubernetes readiness probes.