texas-grocery

🛒 Texas Grocery MCP

🤖 AI に食料品の買い物を任せましょう！Claude を H-E-B の食料品店に接続する MCP サーバーです。

自然な会話を通じて、商品の検索、カートの管理、クーポンのクリップなどができます。

⚠️ このプロジェクトは H-E-B と提携していません。HEB.com に対して非公式の Web API とブラウザー自動化を使用します。責任を持って利用し、適用される規約と法律を遵守してください。

---

✨ 機能

機能	説明
🏪 店舗検索	住所または郵便番号から HEB の店舗を検索
🔍 商品検索	価格と在庫状況を含む商品を検索
🛒 カート管理	人による確認を挟んで商品を追加・削除
📋 商品詳細	原材料、栄養成分、アレルゲン、警告
🎟️ デジタルクーポン	クーポンの一覧表示、検索、クリップで節約
🔄 セッションの自動更新	ボット検出に自動で対応（約15秒）

---

📦 インストール

クイックスタート

pip install texas-grocery-mcp

フルインストール（推奨） 🚀

pip install texas-grocery-mcp[browser]
playwright install chromium

これにより、埋め込みブラウザーを使用した高速な自動更新（約15秒）が可能になります。

前提条件

カート操作とセッション管理には、Playwright MCP も必要です。

npm install -g @anthropic-ai/mcp-playwright

---

⚙️ 設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-playwright"]
    },
    "heb": {
      "command": "uvx",
      "args": ["texas-grocery-mcp"],
      "env": {
        "HEB_DEFAULT_STORE": "590"
      }
    }
  }
}

環境変数

変数	説明	デフォルト
HEB_DEFAULT_STORE	デフォルトの店舗 ID	None
REDIS_URL	Redis キャッシュ URL	None（メモリ内）
LOG_LEVEL	ログレベル	INFO

---

🎯 使用例

🏪 店舗を探す

User: Find HEB stores near Austin, TX

Agent uses: store_search(address="Austin, TX", radius_miles=10)

🔍 商品を検索する

User: Search for organic milk

Agent uses: store_change(store_id="590")
Agent uses: product_search(query="organic milk")

📋 商品の詳細を取得する

User: What are the ingredients in H-E-B olive oil?

Agent uses: product_search(query="heb olive oil")
Agent uses: product_get(product_id="127074")
# Returns: ingredients, nutrition facts, warnings, dietary attributes

product_get ツールが返す内容：

• 🥗 原材料 - 原材料の全表示
• 📊 栄養成分表示 - FDA の表示項目一式
• ⚠️ 安全上の警告 - アレルゲン情報と注意事項
• 🌿 食事関連属性 - グルテンフリー、オーガニック、ヴィーガン、コーシャなど
• 📍 店舗内の場所 - 通路または売り場

🛒 カートに追加する

User: Add 2 gallons of milk to my cart

Agent uses: cart_add(product_id="123456", quantity=2)
# Returns preview for confirmation

Agent uses: cart_add(product_id="123456", quantity=2, confirm=true)
# ✅ Added to cart!

🎟️ クーポンをクリップする

User: Find coupons for cereal

Agent uses: coupon_search(query="cereal")
Agent uses: coupon_clip(coupon_id="ABC123", confirm=true)
# ✅ Coupon clipped!

---

🔐 セッション管理

HEB のボット検出は約11分ごとに期限切れになります。この MCP が自動で対応します！

⚡ 高速な自動更新（推奨）

[browser] のサポートをインストールすると：

Agent uses: session_refresh()
# ✅ Completes in ~10-15 seconds

🔑 自動ログイン

自動ログインのために、認証情報を一度保存します。

Agent uses: session_save_credentials(email="[email protected]", password="...")
# Credentials stored securely in system keyring
# Future session refreshes will auto-login!

---

🧰 利用可能なツール

🏪 店舗ツール

ツール	説明
store_search	住所から店舗を検索
store_change	優先店舗を設定
store_get_default	現在のデフォルト店舗を取得

🔍 商品ツール

ツール	説明
product_search	価格を含む商品を検索
product_search_batch	複数の商品を検索（最大20件）
product_get	商品の詳細情報を取得

🛒 カートツール

ツール	説明
cart_check_auth	認証状態を確認
cart_get	カートの内容を表示
cart_add	商品を追加（確認が必要）
cart_add_many	複数の商品を一括追加
cart_remove	商品を削除

🎟️ クーポンツール

ツール	説明
coupon_list	利用可能なクーポンを一覧表示
coupon_search	キーワードでクーポンを検索
coupon_clip	クーポンをクリップ
coupon_clipped	クリップ済みのクーポンを一覧表示

🔐 セッションツール

ツール	説明
session_status	セッションの状態を確認します
session_refresh	セッションを更新／ログインします
session_save_credentials	自動ログイン用に認証情報を保存します
session_clear	ログアウトします

---

📚 ドキュメント

• 🔧 トラブルシューティングガイド - よくある問題の解決方法
• 🤝 コントリビューション - コントリビューションの方法
• 📝 変更履歴 - バージョン履歴
• 🔒 セキュリティ - セキュリティポリシー

---

🛠️ 開発

# Clone repository
git clone https://github.com/mgwalkerjr95/texas-grocery-mcp
cd texas-grocery-mcp

# Install with dev dependencies
pip install -e ".[dev]"
playwright install chromium

# Run tests
pytest tests/ -v

# Linting & type checking
ruff check src/
mypy src/

🐳 Docker

docker-compose up --build

---

🏗️ アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│                    User's MCP Environment                    │
│                                                             │
│  ┌─────────────────────┐    ┌─────────────────────────────┐ │
│  │  🎭 Playwright MCP  │    │   🛒 Texas Grocery MCP      │ │
│  │  (Browser Auth)     │───▶│   (Grocery Logic)           │ │
│  └─────────────────────┘    └─────────────────────────────┘ │
│                                        │                     │
└────────────────────────────────────────┼─────────────────────┘
                                         │
                                         ▼
                                   🌐 HEB GraphQL API

---

📄 ライセンス

MIT © Michael Walker

---

❤️ を込めてテキサスで作成 🤠