内容
# 🛒 商业助理 MCP
用于食品电商商业分析的AI代理系统。
## 📋 解决问题
该助手帮助商业和客户服务团队快速获取关于以下内容的可靠信息：
- **客户**：搜索、消费概况、高价值识别
- **产品**：热销产品、类别分析
- **销售**：地区分析、支付方式
- **分析**：客户分类（VIP、高级、普通）
**主要用户：** 电商的商业和客户服务团队。
**需求：** 无需直接查询数据库即可快速获取客户、销售、产品和地区信息。
**涵盖内容：**
- ✅ 按姓名、姓氏或地区搜索客户
- ✅ 客户消费概况
- ✅ 热销产品
- ✅ 按类别和地区分析销售
- ✅ 支付方式偏好
- ✅ 客户分类（VIP、高级、普通）
**不涵盖内容：**
- ❌ 数据修改（仅读取）
- ❌ 支付处理
- ❌ 实时库存管理
## 🏗️ 系统架构
### 组件架构
```text
┌───────────────────────────────────────────────────────────────┐
│ 用户 │
└───────────────────────┬───────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ 网络界面（Streamlit） │
│ app_streamlit.py │
│ • 交互式聊天 │
│ • 证据可视化 │
│ • 会话 ID 管理 │
└───────────────────────┬───────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ LangChain + Groq 代理 │
│ agent_core.py │
│ • 意图解释 │
│ • 工具选择 │
│ • 短期记忆（InMemorySaver） │
└───────────────────────┬───────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ MCP 客户端（langchain-mcp-adapters） │
│ • 工具发现 │
│ • 工具调用 │
└───────────────────────┬───────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ MCP 服务器（FastMCP） │
│ mcp_server.py │
│ • 暴露 8 个自定义工具 │
│ • 输入验证 │
│ • 结构化响应 │
└───────────────────────┬───────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ SQLite 数据库 │
│ data/mcp_laboratorio.db │
│ • 客户 • 销售 • 产品 │
│ • 类别 • 支付方式 │
└───────────────────────────────────────────────────────────────┘
```
### 架构
```mermaid
graph TD
A[用户] --> B[Streamlit UI]
B --> C[LangChain + Groq 代理]
C --> D{需要工具？}
D -->|是| E[MCP 客户端]
D -->|否| F[直接响应]
E --> G[MCP 服务器 FastMCP]
G --> H[SQLite 数据库]
H --> I[结构化结果]
I --> C
F --> J[最终响应]
C --> J
J --> B
B --> A
style A fill:#B30909,stroke:#fff,stroke-width:2px
style B fill:#00f,stroke:#fff,stroke-width:2px
style C fill:#056c5c,stroke:#fff,stroke-width:2px
style G fill:#f2f,stroke:#fff,stroke-width:2px
style H fill:#1D7799,stroke:#fff,stroke-width:2px
```
### 执行流程
1. **用户** 在 Streamlit 中输入问题
2. **Streamlit** 将问题发送给带有会话 ID 的代理
3. **LangChain + Groq 代理** 解释意图
4. **决策**：
- 如果需要数据 → 调用 MCP 工具
- 如果不需要 → 直接响应
5. **MCP 服务器** 在 SQLite 上执行工具
6. **结果** 返回给代理
7. **代理** 综合响应和证据
8. **Streamlit** 显示响应、使用的工具和跟踪
9. **内存** 为下一次交互保存上下文
### 组件和职责
| 层 | 技术 | 文件 | 职责 |
|------|-----------|---------|-----------------|
| **界面** | Streamlit | app_streamlit.py | 接收问题，显示响应和证据 |
| **编排** | LangChain + Groq | agent_core.py | 解释意图，选择工具，管理内存 |
| **MCP** | FastMCP | mcp_server.py | 暴露自定义工具，具有明确的契约 |
| **数据** | SQLite | data/ | 提供信息并执行受控操作 |
| **内存** | InMemorySaver | agent_core.py | 通过会话 ID 维护对话上下文 |
## 🛠️ 使用的技术
| 技术 | 版本 | 目的 |
|------------|---------|-----------|
| **Python** | 3.10+ | 基础语言 |
| **Streamlit** | 1.28+ | 网络界面 |
| **LangChain** | 0.3+ | 代理编排 |
| **Groq** | - | 语言模型（llama-3.3-70b-versatile） |
| **FastMCP** | 0.3+ | MCP 服务器 |
| **SQLite** | 3.x | 本地数据库 |
| **Pandas** | 2.0+ | 数据处理 |
## 🔧 MCP 工具
| 工具 | 目的 | 输入 | 输出 | 风险 |
|------|-----------|---------|--------|--------|
| `buscar_clientes` | 搜索客户 | 文本搜索, 限制 | 客户列表 | 低 |
| `perfil_consumo_cliente` | 客户消费概况 | 客户 ID | 消费指标 | 低 |
| `clientes_alto_valor` | 高价值客户 | 最低支出, 限制 | 顶级客户 | 低 |
| `top_productos_vendidos` | 热销产品 | 限制, 排序方式 | 产品排名 | 低 |
| `analisis_categoria` | 类别销售 | 类别（可选） | 类别指标 | 低 |
| `ventas_por_region` | 地区销售 | 地区（可选） | 地区指标 | 低 |
| `preferencia_metodo_pago` | 支付偏好 | 地区（可选） | 支付指标 | 低 |
| `calcular_nivel_cliente` | 客户分类 | 总支出, 总订单 | 等级和推荐 | 低 |
## 🧠 内存
- **类型：** 短期（InMemorySaver）
- **会话 ID：** 每个对话的唯一标识符
- **窗口：** 最后 6-10 条消息
- **限制：** 服务器重启后内存丢失
## 🔐 机密和配置
### 必需的环境变量
| 变量 | 描述 | 获取位置 |
|----------|-------------|-----------------|
| `GROQ_API_KEY` | Groq API 密钥 | [console.groq.com](https://console.groq.com) |
| `GROQ_MODEL` | 使用的模型 | `llama-3.3-70b-versatile` |
| `MCP_SERVER_URL` | MCP 服务器 URL | 本地：`http://127.0.0.1:8000/mcp` |
### 本地配置（.env）
1. 复制示例文件：
```bash
cp .env.example .env
```
2. 使用您的值编辑 `.env`：
```env
GROQ_API_KEY=gsk_你的_api_key_在此
GROQ_MODEL=llama-3.3-70b-versatile
MCP_SERVER_URL=http://127.0.0.1:8000/mcp
```
### Streamlit Cloud 配置（机密）
在 Streamlit Cloud 界面中，添加这些机密：
```toml
GROQ_API_KEY = "gsk_你的_api_key_在此"
GROQ_MODEL = "llama-3.3-70b-versatile"
MCP_SERVER_URL = "https://你的-mcp-server.onrender.com/mcp"
```
## 🚀 本地安装
1. **克隆仓库**
```bash
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# .venv\Scripts\activate # Windows
```
2. **克隆仓库**
```bash
git clone https://github.com/systemyuri/agente-mcp-groq.git
cd agente-mcp-groq
```
3. **安装依赖**
```bash
pip install -r requirements.txt
```
4. **配置环境变量**
```bash
cp .env.example .env
# 编辑 .env 文件，填写 GROQ_API_KEY
```
5. **准备数据**
```bash
# 将 CSV 文件放在 data/ 目录中
python load_data.py
```
6. **运行 MCP 服务器（终端 1）**
```bash
python mcp_server.py
```
**预期输出：**
```text
🚀 初始化 MCP 服务器...
数据库：data/mcp_laboratorio.db
✅ 参数类型验证
📋 可用工具：
- buscar_clientes
- perfil_consumo_cliente
- clientes_alto_valor
- top_productos_vendidos
- analisis_categoria
- ventas_por_region
- preferencia_metodo_pago
- calcular_nivel_cliente
🌐 HTTP 服务器监听 127.0.0.1:8000
MCP 端点：http://127.0.0.1:8000/mcp
```
7. **运行 Streamlit（终端 2）**
```bash
streamlit run app_streamlit.py
```
## 🌐 部署
### 在 Streamlit 社区云上
1. **将代码上传到 GitHub**
```bash
git add .
git commit -m "feat: 带有 Groq 的商业助理 MCP"
git push origin main
```
2. **前往** [share.streamlit.io](https://share.streamlit.io)
3. **连接您的存储库**
- 选择 GitHub
- 选择存储库和分支 `main`
- 主文件：`app_streamlit.py`
4. **配置机密**
在“机密”部分，添加：
```toml
GROQ_API_KEY = "gsk_你的_api_key_在此"
GROQ_MODEL = "llama-3.3-70b-versatile"
MCP_SERVER_URL = "https://你的-mcp-server.onrender.com/mcp"
```
5. **部署**
- 点击“部署”
- 等待 ~5 分钟
- 您将获得公共 URL！
### 远程 MCP 服务器
**选项 1：[Render.com](https://Render.com)（推荐）**
创建 `render.yaml`:
```yaml
services:
- type: web
name: mcp-server
env: python
buildCommand: pip install -r requirements.txt
startCommand: python mcp_server.py
envVars:
- key: GROQ_API_KEY
sync: false
```
**选项 2：ngrok（用于快速测试）**
```bash
# 终端 1
python mcp_server.py
# 终端 2（新建终端）
ngrok http 8000
# 复制 https://xxxx.ngrok.io URL
# 使用此 URL + /mcp 更新 MCP_SERVER_URL
```
* * *
## 📁 项目结构
```text
mi_agente_mcp_groq/
├── app_streamlit.py # 网络界面
├── agent_core.py # 代理逻辑（Groq、MCP、内存）
├── mcp_server.py # MCP 服务器与工具
├── load_data.py # 数据加载脚本
├── requirements.txt # 依赖项
├── README.md # 此文件
├── .gitignore # 要忽略的文件
├── .env.example # 环境变量示例
├── data/ # 数据
│ ├── clientes.csv
│ ├── ventas.csv
│ ├── productos.csv
│ ├── categorias.csv
│ └── metodos_pago.csv
├── tests/ # 测试
│ ├── test_tools.py
│ └── test_agent.py
└── .streamlit/
└── secrets.toml.example # 机密示例
```
* * *
## 🔗 链接
### 生产和存储库
- **生产应用：** [https://你的应用.streamlit.app](https://你的应用.streamlit.app)
- **GitHub 存储库：** [https://github.com/systemyuri/agente-mcp-groq](https://github.com/systemyuri/agente-mcp-groq)
### 官方文档
- **模型上下文协议：** [https://modelcontextprotocol.io](https://modelcontextprotocol.io)
- **LangChain 文档：** [https://docs.langchain.com](https://docs.langchain.com)
- **Streamlit 文档：** [https://docs.streamlit.io](https://docs.streamlit.io)
- **Groq 控制台：** [https://console.groq.com](https://console.groq.com)
- **FastMCP：** [https://github.com/jlowin/fastmcp](https://github.com/jlowin/fastmcp)
* * *
## 👥 团队
- **开发者：** David Yurivilca
- **课程：** 集成策略
- **交付日期：** 2026 年 7 月 19 日
* * *
## 📄 许可证
MIT - 免费用于教育用途。
* * *
## 🙏 致谢
- **Groq** 提供高性能语言模型
- **LangChain** 提供代理编排
- **FastMCP** 提供工具服务器
- **Streamlit** 提供网络界面
- **课程指南** 提供结构和要求
