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

texas_grocery_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: texas-grocery-mcp
+Version: 0.1.0
+Summary: MCP server for HEB grocery store integration
+Author: Michael Walker
+License: MIT
+License-File: LICENSE
+Keywords: ai,grocery,heb,llm,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: cryptography>=42.0
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25.0
+Requires-Dist: prometheus-client>=0.19
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: redis>=5.0
+Requires-Dist: structlog>=24.0
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40.0; extra == 'browser'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: playwright>=1.40.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Texas Grocery MCP
+
+An MCP (Model Context Protocol) server that enables AI agents to interact with HEB grocery stores for product search, product details, cart management, and digital coupons.
+
+This project is **not affiliated with H-E-B**. It uses unofficial web APIs and browser automation against HEB.com; use responsibly and ensure your usage complies with applicable terms and laws.
+
+## Features
+
+- **Store Search**: Find HEB stores by address or zip code
+- **Product Search**: Search products with pricing and availability
+- **Cart Management**: Add/remove items with human-in-the-loop confirmation
+- **Product Details**: Ingredients, nutrition facts, allergens, warnings, and dietary attributes
+- **Coupons**: List/search/clip digital coupons (requires authentication)
+- **Session Management**: Refresh sessions automatically (fast with embedded Playwright)
+
+## Installation
+
+### Basic Installation
+
+```bash
+pip install texas-grocery-mcp
+```
+
+This provides all core functionality. Session refresh requires orchestrating Playwright MCP (~4 minutes).
+
+### Full Installation (Recommended)
+
+```bash
+pip install texas-grocery-mcp[browser]
+playwright install chromium
+```
+
+This enables **fast auto-refresh** (~15 seconds) using an embedded browser. Adds ~150MB for Chromium.
+
+### Prerequisites
+
+For cart operations and session management, you'll also need **Microsoft Playwright MCP**:
+
+```bash
+npm install -g @anthropic-ai/mcp-playwright
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@anthropic-ai/mcp-playwright"]
+    },
+    "heb": {
+      "command": "uvx",
+      "args": ["texas-grocery-mcp"],
+      "env": {
+        "HEB_DEFAULT_STORE": "590"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HEB_DEFAULT_STORE` | Default store ID | None |
+| `REDIS_URL` | Redis cache URL | None (in-memory) |
+| `LOG_LEVEL` | Logging level | INFO |
+
+## Usage
+
+### Finding a Store
+
+```
+User: Find HEB stores near Austin, TX
+
+Agent uses: store_search(address="Austin, TX", radius_miles=10)
+```
+
+### Searching Products
+
+```
+User: Search for organic milk
+
+Agent uses: store_change(store_id="590")
+Agent uses: product_search(query="organic milk")
+```
+
+### Getting Product Details
+
+For detailed information about a specific product (ingredients, nutrition, allergens, warnings):
+
+```
+User: What are the ingredients in H-E-B olive oil?
+
+Agent uses: product_search(query="heb olive oil")
+# Returns products with product_id
+
+Agent uses: product_get(product_id="127074")
+# Returns detailed info: ingredients, nutrition facts, warnings, dietary attributes
+```
+
+The `product_get` tool returns comprehensive information including:
+- **Ingredients**: Full ingredient statement
+- **Nutrition Facts**: Complete FDA panel with serving size, calories, and all nutrients
+- **Safety Warnings**: Allergen info and safety precautions
+- **Dietary Attributes**: Gluten-free, organic, vegan, kosher, etc.
+- **Preparation/Storage**: Instructions for use and storage
+- **Store Location**: Aisle or section where product is located
+
+### Adding to Cart
+
+Cart operations require authentication via Playwright MCP:
+
+```
+User: Add 2 gallons of milk to my cart
+
+Agent uses: cart_add(product_id="123456", quantity=2)
+# Returns preview with confirm=true instruction
+
+Agent uses: cart_add(product_id="123456", quantity=2, confirm=true)
+# Executes the action
+```
+
+## Session Management
+
+HEB uses bot detection (reese84 token) that expires every ~11 minutes. This MCP handles session refresh automatically.
+
+### Fast Auto-Refresh (Recommended)
+
+If you installed with `[browser]` support:
+
+```
+Agent uses: session_refresh()
+# Completes in ~10-15 seconds
+```
+
+This runs an embedded browser to refresh your session automatically.
+
+### Manual Refresh (Fallback)
+
+Without browser support, use the Playwright MCP orchestration:
+
+```
+Agent uses: session_refresh()
+# Returns Playwright commands to execute (~4 minutes)
+```
+
+### Initial Login
+
+For first-time authentication or when session fully expires:
+
+1. `browser_navigate('https://www.heb.com/my-account/login')`
+2. Complete login in the browser
+3. Save storage state:
+   ```javascript
+   await page.context().storageState({ path: '~/.texas-grocery-mcp/auth.json' })
+   ```
+4. Retry cart operations
+
+Or use `session_refresh(headless=False)` to login in a visible browser window.
+
+## Available Tools
+
+### Store Tools
+- `store_search` - Find stores by address
+- `store_change` - Set preferred store (syncs with HEB.com when authenticated)
+- `store_get_default` - Get current default store
+
+### Product Tools
+- `product_search` - Search products by name with pricing and availability
+- `product_search_batch` - Search multiple products at once (up to 20 queries)
+- `product_get` - Get comprehensive product details (ingredients, nutrition, warnings, dietary attributes)
+
+### Cart Tools
+- `cart_check_auth` - Check authentication status
+- `cart_get` - View cart contents
+- `cart_add` - Add item (requires confirmation)
+- `cart_add_with_retry` - Add item with automatic retry on failure
+- `cart_remove` - Remove item (requires confirmation)
+
+### Coupon Tools
+- `coupon_list` - List available digital coupons
+- `coupon_search` - Search coupons by keyword
+- `coupon_categories` - Get coupon category list
+- `coupon_clip` - Clip a coupon to your account (requires confirmation)
+- `coupon_clipped` - List your clipped coupons
+
+### Session Tools
+- `session_status` - Check session health and token expiration
+- `session_refresh` - Refresh/login (fast with `[browser]`, otherwise returns Playwright MCP commands)
+- `session_save_instructions` - Get manual login + session-save instructions
+- `session_save_credentials` - Save credentials for auto-login (secure)
+- `session_clear_credentials` - Remove saved credentials
+- `session_clear` - Clear saved session (logout)
+
+### Health Tools
+- `health_live` - Liveness probe
+- `health_ready` - Readiness probe with component status
+
+## Documentation
+
+- [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Solutions for common issues
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/yourusername/texas-grocery-mcp
+cd texas-grocery-mcp
+
+# Install with dev dependencies (includes Playwright)
+pip install -e ".[dev]"
+playwright install chromium
+
+# Run tests
+pytest tests/ -v
+
+# Run linting
+ruff check src/
+
+# Run type checking
+mypy src/
+```
+
+### Docker Development
+
+```bash
+# Build and run with Redis
+docker-compose up --build
+
+# Run tests in container
+docker-compose run texas-grocery-mcp pytest
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    User's MCP Environment                    │
+│                                                             │
+│  ┌─────────────────────┐    ┌─────────────────────────────┐ │
+│  │  Playwright MCP     │    │     Texas Grocery MCP       │ │
+│  │  (Browser Auth)     │───▶│     (Grocery Logic)         │ │
+│  └─────────────────────┘    └─────────────────────────────┘ │
+│                                        │                     │
+└────────────────────────────────────────┼─────────────────────┘
+                                         │
+                                         ▼
+                                  HEB GraphQL API
+```
+
+## License
+
+MIT

texas_grocery_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,40 @@
+texas_grocery_mcp/__init__.py,sha256=X5acO89_cdDdyPbAHrrcHuC3APD29uRbYf90YCrVsV0,94
+texas_grocery_mcp/server.py,sha256=ysY8c8GDNYVCFd96v29meaBPoL5LyUFae-d6YdKk_Us,8064
+texas_grocery_mcp/state.py,sha256=I4QianF2myRA7rWEjl3ReSW1uc1uJZbgvztLTfLjSF8,5675
+texas_grocery_mcp/auth/__init__.py,sha256=K4dysnkkzEBfnCfRWgdg-FAoLlGZT08eXukxPdyhtGw,200
+texas_grocery_mcp/auth/browser_refresh.py,sha256=T3Ncy26PcvJOeE_xR7Br8esa9JCconO1OXO8IMeHHXg,60911
+texas_grocery_mcp/auth/credentials.py,sha256=fNMAAf4QvBp4YcDTbM1h9FknKrGlYhvjEX4x3PN0z2E,11264
+texas_grocery_mcp/auth/session.py,sha256=6_FZJoUNXM7W0P-eHSzyoYkrv1AEkSpukKE4mTHx_q8,24883
+texas_grocery_mcp/clients/__init__.py,sha256=DnNJVNq2LwFJShdaAjpJcHF-ivFaiJmuLhinhuOPHs0,137
+texas_grocery_mcp/clients/graphql.py,sha256=2gMpXYP1LRzup6-dJEw6KunM92ZB4-7bdl1Q9Ru2zyI,87360
+texas_grocery_mcp/models/__init__.py,sha256=XY0aiazApqvvFITBoMwNzhXq-SCknRReo88ztPA_KWQ,1280
+texas_grocery_mcp/models/cart.py,sha256=E0jjHS5uttLA0aQeyR49LExPmSkp7v2KsVPCtcx2Z_w,2005
+texas_grocery_mcp/models/coupon.py,sha256=uhgbfwVZ81TAJ-3rFw9jEgoQty3a7aws6vaqMGiK5qU,1851
+texas_grocery_mcp/models/errors.py,sha256=AmCMyfQoIUoGN1Si8yqZo6BXHL1Afak5-QxNjmwgjAU,1525
+texas_grocery_mcp/models/health.py,sha256=vohg3IKQMWH5Yww_40xyisn9eli--9XenEYvA-LBJ6U,1309
+texas_grocery_mcp/models/product.py,sha256=Qwvpwy2699oiZZk-xGM_AAAHxjA8ahcCLzpxVLK0J6w,10526
+texas_grocery_mcp/models/store.py,sha256=8EExIEFjhNt0B0oBA-67rg3KEeVCb4jpiIjXCtChyfs,2936
+texas_grocery_mcp/observability/__init__.py,sha256=UnCGf_KCwgEJ6zZoI3BZ__yie5gjD6B7ANdZF0fnvic,296
+texas_grocery_mcp/observability/health.py,sha256=_XkaKY0pM5QLN7zORfFbYxku8lCmUuEY5eNCLh8D_io,4329
+texas_grocery_mcp/observability/logging.py,sha256=n6gEBTs15o4eaFkr1jUsAUGEi27LQQqTFjFziUaX1nI,2164
+texas_grocery_mcp/reliability/__init__.py,sha256=cWOb-zyIAdeuoofOR5Q7bSCJZOF4lh9VPTWPB3esySQ,624
+texas_grocery_mcp/reliability/cache.py,sha256=hefUCyioP2ezHDCTrIH_x7oEtsbIccuzfUTatHMAhkY,3469
+texas_grocery_mcp/reliability/circuit_breaker.py,sha256=Lx5j990kDuGbLsxh4pnLwAlfLKXRx2Imutjhfylcabo,4686
+texas_grocery_mcp/reliability/retry.py,sha256=K5XdXPl4DhFQkuXY1Wj754LxVYkvPxlzA0pEsNqipSI,2851
+texas_grocery_mcp/reliability/throttle.py,sha256=N1pDtjO3u_0epwXUgCqec9zypTRDs7ofCmg1G8jgmig,3155
+texas_grocery_mcp/services/__init__.py,sha256=PZxNtdO_xyThxhNapA_fSO6ikNFBFY1UOrh3vAEj1dk,173
+texas_grocery_mcp/services/geocoding.py,sha256=I9fPTP3KLYHLth4GyYZSWzDPza_XkuCL6eU6hmf4WqM,6936
+texas_grocery_mcp/tools/__init__.py,sha256=5za_ExgYTkwNaSMy3U1YwtPhlkmf9_LKb7Hjq4EDWCs,164
+texas_grocery_mcp/tools/cart.py,sha256=jEeimL6DPuTT6UdNb8ecssGe1QyPRnhO89BoPRzr99I,27344
+texas_grocery_mcp/tools/coupon.py,sha256=VfujygAov4bDqM0kmvIv0K4bO0NqMtepLT4DwhW_NXA,10368
+texas_grocery_mcp/tools/product.py,sha256=bHmvWURYoDYau--zj-voQwOPo9Em2ZynczcuNiDVT98,14155
+texas_grocery_mcp/tools/session.py,sha256=DtoCq2K37PsxOCcW1pNqy0gz8On5yq0NHLUtlaBUhL4,17266
+texas_grocery_mcp/tools/store.py,sha256=UAyoIJbzfNmtnFnwM3jJs1WMlYuzrmG3tnywif-ochY,11716
+texas_grocery_mcp/utils/__init__.py,sha256=sSMOf8isFMso1DsFdsppLIXEsPv0CtAKI1heHG_p1ec,152
+texas_grocery_mcp/utils/config.py,sha256=CtB8HqnEFRkHbT7NR3iMIRJtZJBxYEEB2IWYuaL_0e4,4052
+texas_grocery_mcp/utils/secure_file.py,sha256=Y8vlkN9rL4VQPg1-39lZz937HpR4FDbUpQWXULhbwAg,3200
+texas_grocery_mcp-0.1.0.dist-info/METADATA,sha256=XMdLMP_yXhIxTSXDZ6rR2UK0w4QaEtAzC3opU7wprDw,9219
+texas_grocery_mcp-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+texas_grocery_mcp-0.1.0.dist-info/entry_points.txt,sha256=i0MQYbryCcZryfCvkBkNx_3bdi4UnddscJA2wgCYOic,68
+texas_grocery_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=KRosPCO4879Stw30rAviYap_rxEBG2RIpqMogAcnxFY,1071
+texas_grocery_mcp-0.1.0.dist-info/RECORD,,

texas_grocery_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

texas_grocery_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+texas-grocery-mcp = texas_grocery_mcp.server:main

texas_grocery_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Walker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.