MCP Mercadinho

🚀 メルカディーニョ・メルカンテス - マルチエージェントAIアシスタント

この高度なマルチエージェントAIシステムは、ブラジルの小売チェーンであるメルカディーニョ・メルカンテスのために開発されています。複数の専門AIエージェントを通じて、商品問い合わせ、販売支援、顧客管理、店舗運営などを行い、スマートな顧客サービスを提供します。

🏪 メルカディーニョ・メルカンテスについて

メルカディーニョ・メルカンテスは、ブラジルの誇る小売会社で、サンパウロとリオデジャネイロに複数の店舗を展開しています。当社のAIアシスタントシステムは、パーソナライズされた商品推薦、プロモーション情報、円滑な予約管理を通じて、顧客体験を向上させます。

✨ 主な機能

🤖 マルチエージェントアーキテクチャ

• 受付エージェント：顧客を歓迎し、適切なサービスに案内します。
• 販売エージェント：商品問い合わせ、推薦、販売支援を行います。
• 顧客管理エージェント：既存の顧客アカウントと特別割引を管理します。

🛍️ コア機能

• 商品カタログ：価格と在庫情報を含む利用可能な商品を閲覧できます。
• 店舗情報：店舗の場所と連絡先を見つけることができます。
• プロモーションシステム：店舗固有のプロモーションと割引を利用できます。
• 顧客管理：顧客プロファイルとロイヤルティ特典を追跡できます。
• 予約管理：店舗訪問と商品予約を予約できます。
• 特別割引：登録顧客向けの独占的なオファーがあります。

🛠️ 技術的特徴

• MCP統合：ツール呼び出し用のModel Context Protocol。
• Streamlit UI：モダンでレスポンシブなウェブインターフェース。
• リアルタイムチャット：AIエージェントとの対話型会話。
• ツール可視化：AIツールの使用状況を透過的に表示。
• セッション管理：会話履歴を永続的に保存。

🚀 クイックスタート

前提条件

• Python 3.8以上
• OpenAI APIキー
• Git

インストール

1. リポジトリをクローンする

   git clone <repository-url>
   cd mcp_mercadinho
   

2. 依存関係をインストールする

   pip install -r requirements.txt
   

3. 環境変数を設定する

   export OPENAI_API_KEY="your_openai_api_key_here"
   

   または、.envファイルを作成します。

   echo "OPENAI_API_KEY=your_openai_api_key_here" > .env
   

アプリケーションの実行

1. MCPサーバーを起動する（1つのターミナルで）

   mcp run server.py --transport sse
   

2. Streamlitクライアントを起動する（別のターミナルで）

   streamlit run chat_multi_agent_client.py
   

3. ブラウザを開き、Streamlitの出力に表示されるURL（通常はhttp://localhost:8501）にアクセスします。

🏗️ アーキテクチャ

システムコンポーネント

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Streamlit UI  │◄──►│  Multi-Agent     │◄──►│   MCP Server    │
│   (Frontend)    │    │  System          │    │   (Backend)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │  OpenAI GPT-4    │
                       │  (LLM Backend)   │
                       └──────────────────┘

エージェントの役割

受付エージェント (RecepcaoAssistente)

• 目的：初期の顧客接触とルーティング。
• 責任：
  • メルカディーニョ・メルカンテスへの顧客の歓迎。
  • 会社情報とウェブサイトの提示。
  • 顧客を適切な専門エージェントにルーティング。
  • 一般的な問い合わせの対応。

販売エージェント (VendasAssistente)

• 目的：商品販売と推薦。
• 責任：
  • 利用可能な商品と在庫の表示。
  • 商品推薦の提供。
  • プロモーションオファーの処理。
  • 店舗訪問の予約。
  • 販売問い合わせの処理。

顧客管理エージェント (ManutencaoSocioAssistente)

• 目的：既存の顧客サポートとロイヤルティ管理。
• 責任：
  • 顧客の会員ステータスの確認。
  • 会員向けの特別割引の適用。
  • 商品予約の処理。
  • 顧客アカウントの管理。

利用可能なツール (MCP関数)

📊 データ構造

商品

• カテゴリー：青果物、電子機器
• 情報：ID、名前、カテゴリー、価格、数量
• 例：バナナ、リンゴ、PlayStation 5、LEDテレビ

店舗

• 場所：サンパウロ（パレルイロス、モオカ）、グアルジャ、サントアンドレ、リオデジャネイロ（イパネマ、ノバイグアシュ）
• 情報：ID、名前、都市、州

顧客

• 種類：通常の顧客、会員（特別割引あり）
• 情報：ID、名前、関連する店舗、割引適用可否

💻 使用例

商品問い合わせ

ユーザー: "あなたたちはどんな商品を扱っていますか？"
エージェント: [価格と在庫情報を含む商品カタログを表示]

店舗訪問予約

ユーザー: "PlayStation 5を見に店舗に行きたいです。"
エージェント: [最寄りの店舗を見つけ、プロモーションを確認し、訪問を予約する]

顧客割引確認

ユーザー: "私の名前はジョン・レノンです。特別割引はありますか？"
エージェント: [会員ステータスを確認し、特別価格を適用する]

🔧 設定

環境変数

• OPENAI_API_KEY：GPT-4にアクセスするためのOpenAI APIキー。

モデル設定

• モデル：GPT-4-1106-preview
• Temperature：0（決定論的な応答）
• Tool Choice：Auto
• Parallel Tool Calls：無効

🛡️ セキュリティに関する考慮事項

• APIキーは環境変数に安全に保存する必要があります。
• APIキーをバージョン管理にコミットしないでください。
• ローカル開発には.envファイルを使用してください。
• 本番環境ではレート制限を実装することを検討してください。

🤝 コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します (git checkout -b feature/amazing-feature)。
3. 変更をコミットします (git commit -m 'Add amazing feature')。
4. ブランチにプッシュします (git push origin feature/amazing-feature)。
5. プルリクエストを開きます。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。

🆘 サポート

サポートや質問については、以下の方法でお問い合わせください。

• Issuesページを確認する。
• 開発チームに連絡する。
• メルカディーニョ・メルカンテスを訪問する。

🔮 将来の機能拡張

• [ ] 実際の在庫システムとの統合
• [ ] 決済処理機能
• [ ] 多言語対応（ポルトガル語/英語）
• [ ] モバイルアプリ開発
• [ ] 高度な分析とレポート
• [ ] CRMシステムとの統合

メルカディーニョ・メルカンテスのために❤️ で開発されました