Kroger MCP

🚀 Kroger MCP Server

このプロジェクトは、Kroger APIをラップするModel Context Protocol (MCP)サーバーを実装しています。これにより、AnthropicのClaudeなどの大規模言語モデル (LLM) がKrogerの食料品サービスとやり取りできるようになり、商品検索、店舗検索、カート管理などの機能が可能になります。

✨ 主な機能

• OAuth2認証：一般データ用のクライアント資格情報と、カート操作のためのユーザーベースの承認を処理します。
• 商品検索：特定の店舗でキーワードを使って商品を検索します。
• 商品詳細：価格、在庫状況、配送オプションなどの詳細な商品情報を取得します。
• 店舗検索：郵便番号でKrogerの店舗を検索します。
• カート管理：ユーザーのKrogerショッピングカートに商品を追加します（ユーザー承認が必要）。

📦 インストール

1. 設定

サーバーを実行する前に、Kroger APIの資格情報とOAuth2設定を構成する必要があります。

1.1. API資格情報 (クライアントIDとシークレット)

1. 資格情報の取得：Kroger Developer Portalでアプリケーションを登録し、Client IDとClient Secretを取得します。
2. 資格情報の設定：以下の2つの方法でこれらの資格情報を設定できます。
   • config.py（ローカル使用の簡単な方法として推奨）： config.pyファイルを開き、KROGER_CLIENT_IDとKROGER_CLIENT_SECRETのプレースホルダー値を実際の資格情報に置き換えます。

     # config.py
     KROGER_CLIENT_ID = "YOUR_ACTUAL_CLIENT_ID"
     KROGER_CLIENT_SECRET = "YOUR_ACTUAL_CLIENT_SECRET"
     

   • 環境変数：auth.pyスクリプトを変更して、環境変数を介してシークレットを管理する場合は、os.environ.get("KROGER_CLIENT_ID")とos.environ.get("KROGER_CLIENT_SECRET")を読み取るようにすることもできます。（注：tools.pyとserver.pyの現在の実装では、直接config.pyの値を使用しています。）

1.2. ユーザー承認 (カート操作の場合)

ユーザーのカートを変更するツール（例：add_to_cart）を使用するには、ユーザーがアプリケーションを承認する必要があります。このサーバーはOAuth2 Authorization Code Grantフローを使用します。

1. リダイレクトURI：config.pyのKROGER_REDIRECT_URIが、Krogerアプリケーションに登録されたリダイレクトURIと一致することを確認してください。ローカルテストの場合は、http://localhost:8080/callbackが一般的なデフォルトですが、このリダイレクトからコードを取得する方法が必要です。

   # config.py
   KROGER_REDIRECT_URI = "http://localhost:8080/callback" # またはあなたが設定したURI
   

2. 承認コードとリフレッシュトークンの取得：
   • auth.pyスクリプトを直接実行します (python auth.py)。
   • 「承認URL」が表示されます。このURLをコピーしてウェブブラウザに貼り付けます。
   • Krogerアカウントでログインし、アクセスを許可します。
   • あなたはKROGER_REDIRECT_URIにリダイレクトされます。ブラウザのアドレスバーのURLには、承認コードが含まれています（例：http://localhost:8080/callback?code=YOUR_AUTH_CODE&...）。
   • このコードをコピーします。
   • プロンプトが表示されたら、コードをauth.pyスクリプトに貼り付けます。
   • スクリプトは、コードをアクセストークンとリフレッシュトークンに交換します。
   • 重要：表示されたリフレッシュトークンを安全に保存してください。
3. リフレッシュトークンの設定：
   • サーバーを再起動しても毎回再認証する必要がなく、カート操作を可能にするには、取得したリフレッシュトークンをconfig.pyまたはAuthManagerが読み込める環境変数に設定する必要があります。
   • auth.pyのAuthManager.__init__を変更して、このKROGER_USER_REFRESH_TOKENをconfig.pyまたは環境から読み込むようにします。

     # In auth.py -> AuthManager.__init__
     # self.user_refresh_token = os.environ.get("KROGER_USER_REFRESH_TOKEN") 
     # OR
     # from config import KROGER_USER_REFRESH_TOKEN # Add this to config.py
     # self.user_refresh_token = KROGER_USER_REFRESH_TOKEN 
     

     そして、config.pyにKROGER_USER_REFRESH_TOKEN = "YOUR_SAVED_REFRESH_TOKEN"を追加します。
   • get_user_token()が呼び出されたときに、アクセストークンが期限切れまたは存在しない場合、このリフレッシュトークンを使用しようとします。

2. サーバーの実行

1. 依存関係のインストール：まだインストールしていない場合は、必要なPythonライブラリをインストールします。

   pip install requests mcp
   

   （注：mcpライブラリ名は仮定です。異なる場合は調整してください。例：modelcontextprotocol）
2. サーバーの起動： ターミナルからserver.pyスクリプトを実行します。

   python server.py
   

3. サーバーの動作：
   • サーバーは、MCPクライアントとの通信にSTDIO (標準入出力) を使用します。ネットワークポートを開きません。
   • 起動すると、初期化メッセージが表示され、登録されたツールのリストが表示されます。
   • その後、MCPクライアントからのJSON - RPC要求を待機します。
4. サーバーの停止： サーバーが実行されているターミナルでCtrl + Cを押します。

💻 使用例

3. MCPクライアントの統合

3.1. Claude Desktop

• Claude Desktopの設定に移動します。
• 統合（またはMCPサーバー用の同様のセクション）に移動します。
• MCPサーバーの追加（または同等の項目）をクリックします。
• サーバーを実行するコマンドを提供します。これには通常、Pythonインタープリターとserver.pyへのパスを指定する必要があります。例えば：
  • PythonがPATHにある場合：python /path/to/your/project/server.py
  • そうでない場合：/path/to/your/python /path/to/your/project/server.py
• 追加すると、ClaudeはKrogerのツール（例：find_stores、search_products）を表示し、呼び出すことができます。

3.2. プログラムによる使用 (例)

開発者は、MCPクライアントライブラリを使用してサーバーとプログラムでやり取りすることもできます。

# This is a conceptual example based on the MCP specification.
# The actual library might differ.
from modelcontext import Client, StdioClientTransport # Assuming library structure

async def main():
    client = Client(name="example-kroger-client", version="1.0", capabilities={})
    
    # Adjust command if python/server.py are not in PATH or need full paths
    python_executable = "python" # Or full path to python interpreter
    server_script_path = "server.py" # Or full path to server.py
    
    transport = StdioClientTransport(command=[python_executable, server_script_path])
    
    await client.connect(transport)
    
    # Example: Find stores
    try:
        store_results = await client.call_tool(
            "find_stores", 
            {"zip_code": "45202", "limit": 1}
        )
        print("Store Search Results:", store_results)

        if store_results and not store_results.get("error") and len(store_results) > 0:
            location_id = store_results[0].get("locationId")
            if location_id:
                # Example: Search products
                product_results = await client.call_tool(
                    "search_products",
                    {"query": "milk", "location_id": location_id, "limit": 2}
                )
                print("Product Search Results:", product_results)
                
                # Example: Add to cart (requires user auth token to be set up in server)
                # Ensure product_results[0] exists and has 'productId'
                if product_results and not product_results.get("error") and len(product_results) > 0:
                    product_id = product_results[0].get("productId")
                    cart_result = await client.call_tool(
                        "add_to_cart",
                        {"product_id": product_id, "quantity": 1, "location_id": location_id}
                    )
                    print("Add to Cart Result:", cart_result)

    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        await client.disconnect()

if __name__ == "__main__":
    # For asyncio if your client library uses it
    # import asyncio
    # asyncio.run(main())
    print("Run the async main() function with an asyncio event loop if needed by your MCP client library.")

4. LLMとの対話例

ユーザー："90210近くのKrogerで、有機全乳を2ガロンと卵を1ダース欲しいです。"

LLM (アシスタント) の内部手順：

1. （オプション：ユーザーの郵便番号が提供されていないか曖昧な場合、LLMがユーザーに郵便番号を尋ねます）
2. LLMがfind_storesを呼び出します：{"zip_code": "90210", "limit": 1}
   • サーバーは店舗詳細を返します。例：[{ "locationId": "01400123", "name": "Beverly Hills Kroger", ... }]
3. LLMが（牛乳の）search_productsを呼び出します：{"query": "organic whole milk", "location_id": "01400123", "limit": 5}
   • サーバーは牛乳製品のリストを返します。LLMは1つを選択します。例：{"productId": "0001111060404", "description": "Simple Truth Organic Milk...", ...}
4. LLMが（卵の）search_productsを呼び出します：{"query": "dozen eggs", "location_id": "01400123", "limit": 3}
   • サーバーは卵製品のリストを返します。LLMは1つを選択します。
5. （まだ行っていない場合は、カートのユーザー承認を完了する必要があります）
6. LLMが（牛乳の）add_to_cartを呼び出します：{"product_id": "0001111060404", "quantity": 2, "location_id": "01400123"}
   • サーバーは追加を確認します。
7. LLMが（卵の）add_to_cartを呼び出します：{"product_id": "...", "quantity": 1, "location_id": "01400123"}
   • サーバーは追加を確認します。

LLM (アシスタント) からユーザーへ："了解しました。ビバリーヒルズのKrogerを見つけました。シンプルトゥース有機全乳を2ガロンと卵を1ダースあなたのカートに追加しました。他に何か必要ですか？"

🔧 技術詳細

5. エラーシナリオ

• ユーザー承認が不足している場合：ユーザーがアプリケーションを承認していない状態でadd_to_cartを使用しようとすると、ツールはエラーを返します。

  {
    "error": "User authentication required.",
    "message": "No user access token found. The user needs to authorize the application...",
    "action_needed": "User must complete OAuth2 authorization flow." 
  }
  

  LLMはユーザーに承認手順を実行するように案内する必要があります（セクション1.2を参照）。エラーメッセージに承認URLが含まれる場合があります。
• 無効または期限切れのトークン：アクセストークンが期限切れの場合、AuthManagerはそれを更新しようとします。リフレッシュトークンも無効な場合（例：add_to_cartで401エラーが発生した後のユーザートークン）、再承認が必要になります。
• APIレート制限：KrogerのAPIにはレート制限があります（例：developer.kroger.com/support/rate-limits/を参照）。サーバーがこれらの制限に達すると、API呼び出しは失敗します。サーバーは通常HTTP 429ステータスコードでKrogerからのエラーを返します。LLMはユーザーに後で再試行するように通知する必要があります。
• その他のAPIエラー：KrogerのAPIが他のエラーを返す場合（例：無効な商品ID、locationIdに対応する店舗が見つからない）、ツールはerror、details、status_code（KrogerからのHTTPステータス）、および場合によってはraw_responseまたはkroger_errorフィールドを含むJSON辞書を返します。

6. 利用可能なツール

サーバーは、LLMに以下のツールを公開しています。

• find_stores(zip_code: str, radius_miles: int = 10, limit: int = 5) -> list | dict
  • 説明：郵便番号でKrogerの店舗を検索します（ID付きの最寄りの店舗を返します）。
• search_products(query: str, location_id: str, limit: int = 10) -> list | dict
  • 説明：指定された店舗でキーワードを使ってKrogerの商品を検索します。
• get_product(product_id: str, location_id: str) -> dict
  • 説明：IDで商品の詳細情報（価格、サイズ、在庫、配送オプション）を取得します。
• add_to_cart(product_id: str, quantity: int, location_id: str) -> dict
  • 説明：ユーザーのKrogerカートに商品を追加します（ユーザー認証が必要）。

（上記の説明は、tools.pyの@toolデコレータに基づいています。）