# AI 客服商城 MCP Server

> 一款将 **大模型客服 + 商品数据 + 安全审计** 打包成 MCP 服务的综合练习项目。
> 面向 AI Agent 开发,覆盖 LLM API、Function Calling、RAG、MCP 协议、Web 安全审计、人工审核闭环。

---

## ✨ 功能总览

### 1. 智能客服(LLM + RAG + Function Calling)
- DeepSeek 大模型驱动,`system prompt` 角色+规则+知识注入
- **RAG 检索增强**:FAQ 知识库(退货/保修/发票/物流等 13 条)按需检索,注入上下文
- **函数调用**:模型自主决定调用 `search_products` 查商品(名称/价格/库存/描述)
- **自动转人工**:AI 回答不了时自动建议转人工 + 按钮高亮
- **人工客服后台**:排队队列 / 接单 / 回复,状态机 `ai → queue → human`

### 2. 商品网页
- 商品卡片网格 + 实时搜索(模糊 2 字滑窗匹配)
- 用户登录(演示靶场版)+ 可拖动客服聊天窗口

### 3. MCP Server(4 个工具)
| 工具 | 说明 |
|---|---|
| `search_products_tool` | 按关键词搜索商品 |
| `get_product_tool` | 按 id 查商品详情 |
| `ask_customer_service` | 调用完整 AI 客服 |
| `run_security_audit` | 8 项安全审计 + 证据定位 |

### 4. 安全审计闭环(特色亮点)
```
AI 审计(8 项检测,含静态+动态)
  → 证据定位(文件/行号/代码上下文字符串)
  → 人工审核台(/review): 确认 / 误报 / 修复
  → 修复方案(修复前后代码对照)
  → 状态追踪(new → confirmed → fixed) + 修复率看板
```

审计检测项:
- ✅ 明文密码存储(文本比对)
- ✅ 用户枚举(错误消息差异)
- ✅ 登录限流缺失
- ✅ Token 无过期
- ✅ IDOR 越权(跨用户订单)
- ✅ 敏感信息泄露(无鉴权返回密码)
- ✅ 任意改密码(无旧密码校验)
- ✅ 硬编码密钥扫描

> ⚠️ **安全说明**:项目内登录/订单接口**故意保留**典型漏洞,作为安全审计练习靶场。**仅供本地学习演示**,切勿部署公网或用于真实系统。

---

## 🚀 快速开始

### 1. 环境准备
```bash
# Python 3.10+,创建虚拟环境
cd ai-customer-service-mcp
python -m venv .venv
.venv\Scripts\activate          # Windows
pip install -r requirements.txt # flask requests python-dotenv mcp beautifulsoup4 lxml
```

### 2. 配置 LLM(可选,未配置走规则版)
```bash
# 复制 .env.example 为 .env,填入 DeepSeek API Key
# deepseek 平台: https://platform.deepseek.com/
```

### 3. 启动网页服务器
```bash
python server/app.py
# 打开 http://127.0.0.1:5000(商城+客服窗)
# 客服后台: http://127.0.0.1:5000/agent
# 审核台:   http://127.0.0.1:5000/review
```

### 4. 测试账号
```
admin / admin123    (管理员)
test  / 123456      (普通用户)
```

### 5. 启动 MCP Server(stdio,供 MCP 客户端调用)
```bash
python server/mcp_server.py
```

opencode 配置示例(`opencode.json`):
```json
{
  "mcp": {
    "shop": {
      "type": "local",
      "command": ["python", "server/mcp_server.py"],
      "cwd": "D:/lesson/ai-customer-service-mcp",
      "enabled": true
    }
  }
}
```

---

## 🧭 项目结构

```
ai-customer-service-mcp/
├── server/
│   ├── app.py              # Flask 路由(网页/API/审核/转人工)
│   ├── mcp_server.py       # MCP Server(@mcp.tool() 4 工具)
│   ├── data_service.py     # 商品数据服务
│   ├── auth_service.py     # 登录认证(靶场版)
│   ├── order_service.py    # 订单服务(IDOR 靶点)
│   ├── chat_service.py     # 客服(LLM+RAG+Function Calling)
│   ├── llm_client.py       # LLM API 客户端(OpenAI 兼容)
│   ├── rag_service.py      # 知识库检索(Cosine 相似度)
│   ├── audit_service.py    # 安全审计(8 项+证据定位)
│   ├── review_service.py   # 审核闭环(状态/修复方案/统计)
│   ├── human_service.py    # 转人工会话状态机
│   └── templates/          # index.html / agent.html / review.html
├── data/
│   ├── products.json       # 商品
│   ├── users.json          # 用户(明文靶点)
│   ├── orders.json         # 订单(IDOR 靶点)
│   └── faq_knowledge.json  # 客服 FAQ 知识库
├── crawler/                # 商品爬虫(规划)
├── web/                    # 前端资源(规划)
├── .env.example            # LLM 配置模板
└── .gitignore              # 保护 .env 不提交
```

---

## 🎯 设计要点(面试可讲)

1. **RAG**:chunk → 向量化(词频/cosine)→ Top-K → 注入 system prompt;生产可换 embedding + FAISS
2. **Function Calling 协议**:assistant `tool_calls` 与 `role=tool` 消息配对(亲身踩坑:缺 assistant 记录会 400)
3. **MCP 2.x**:`MCPServer` + `@tool()` 装饰器,stdio 通信,被 opencode 实测调用成功
4. **安全闭环**:检测(静态+动态黑盒)→ 证据(文件/行号/上下文)→ 人工审核(确认/误报)→ 修复方案 → 状态追踪
5. **兜底设计**:AI 答不上 → 自动建议转人工;用户排队 → 接单 → 回复 → 轮询展示

---

## 📜 License

MIT License

> 本项目所有数据均为本地模拟,演示账号与漏洞为教学靶场设计。仅供学习交流。