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 用心打造 ❤️