MCP Mercadinho

🚀 巴西連鎖超市智能客服系統 - Mercadinho Mercantes

本項目是為巴西連鎖超市 Mercadinho Mercantes 打造的一套複雜的多智能體 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 服務器（在一個終端中）：

   mcp run server.py --transport sse
   

2. 啟動 Streamlit 客戶端（在另一個終端中）：

   streamlit run chat_multi_agent_client.py
   

3. 打開瀏覽器，並導航到 Streamlit 輸出中顯示的 URL（通常是 http://localhost:8501）

✨ 主要特性

🤖 多智能體架構

• 接待智能體：歡迎客戶，並將他們引導至合適的服務。
• 銷售智能體：處理產品諮詢、推薦和銷售協助。
• 客戶維護智能體：管理現有客戶賬戶和特殊折扣。

🛍️ 核心功能

• 產品目錄：瀏覽帶有價格和庫存信息的可用產品。
• 門店信息：查找門店位置和聯繫方式。
• 促銷系統：獲取特定門店的促銷活動和折扣信息。
• 客戶管理：跟蹤客戶檔案和忠誠度福利。
• 預約安排：預訂門店參觀和產品預訂。
• 特殊折扣：為註冊客戶提供獨家優惠。

🛠️ 技術特性

• MCP 集成：用於工具調用的模型上下文協議。
• Streamlit UI：現代、響應式的 Web 界面。
• 實時聊天：與 AI 智能體進行交互式對話。
• 工具可視化：透明查看 AI 工具的使用情況。
• 會話管理：持久的對話歷史記錄。

🏪 關於 Mercadinho Mercantes

Mercadinho Mercantes 是一家自豪的巴西零售公司，在聖保羅和里約熱內盧擁有多家門店。我們的 AI 客服系統通過提供個性化的產品推薦、促銷信息和無縫的預約安排，提升了客戶體驗。

🏗️ 架構

系統組件

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

智能體角色

接待智能體 (RecepcaoAssistente)

• 目的：與客戶進行初始接觸並進行路由。
• 職責：
  • 歡迎客戶光臨 Mercadinho Mercantes。
  • 展示公司信息和網站。
  • 將客戶引導至合適的專業智能體。
  • 處理一般諮詢。

銷售智能體 (VendasAssistente)

• 目的：產品銷售和推薦。
• 職責：
  • 展示可用產品和庫存。
  • 提供產品推薦。
  • 處理促銷優惠。
  • 安排門店參觀。
  • 處理銷售諮詢。

客戶維護智能體 (ManutencaoSocioAssistente)

• 目的：現有客戶支持和忠誠度管理。
• 職責：
  • 驗證客戶會員狀態。
  • 為會員應用特殊折扣。
  • 處理產品預訂。
  • 管理客戶賬戶。

可用工具（MCP 函數）

📊 數據結構

產品

• 類別：果蔬、電子產品
• 信息：ID、名稱、類別、價格、數量
• 示例：香蕉、蘋果、PlayStation 5、LED 電視

門店

• 位置：聖保羅（帕雷赫羅斯、穆卡）、瓜魯雅、聖安德烈、里約熱內盧（伊帕內瑪、新伊瓜蘇）
• 信息：ID、名稱、城市、州

客戶

• 類型：普通客戶、會員（享受特殊折扣）
• 信息：ID、姓名、關聯門店、折扣資格

💻 使用示例

產品諮詢

用戶: "你們有哪些產品可供選擇？"
智能體: [展示帶有價格和庫存信息的產品目錄]

門店參觀預約

用戶: "我想參觀一家門店看看 PlayStation 5"
智能體: [找到最近的門店，查看促銷活動，安排參觀]

客戶折扣查詢

用戶: "我叫約翰·列儂，我有什麼特殊折扣嗎？"
智能體: [驗證會員身份，應用特殊定價]

🔧 配置

環境變量

• OPENAI_API_KEY：用於訪問 GPT - 4 的 OpenAI API 密鑰

模型設置

• 模型：GPT - 4 - 1106 - preview
• 溫度：0（確定性響應）
• 工具選擇：自動
• 並行工具調用：禁用

🛡️ 安全注意事項

⚠️ 重要提示

• 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 文件。

🆘 支持

如需支持和提問：

• 查看 問題 頁面
• 聯繫開發團隊
• 訪問 Mercadinho Mercantes

🔮 未來改進

• [ ] 與真實庫存系統集成
• [ ] 支持支付處理功能
• [ ] 支持多語言（葡萄牙語/英語）
• [ ] 開發移動應用程序
• [ ] 高級分析和報告
• [ ] 與 CRM 系統集成

為 Mercadinho Mercantes 用心打造 ❤️