# shop-mcp-python

**Repository Path**: yuan50697105/shop-mcp-python

## Basic Information

- **Project Name**: shop-mcp-python
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-16
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: MCP

## README

# 🛒 电商 MCP 服务器

一个生产级的 **Model Context Protocol (MCP)** 服务器，向 AI 助手提供完整的电商能力。采用企业级安全、认证和模块化架构构建。

## 🏗️ 架构

```
ecommerce-mcp-server/
├── config/              # 配置管理
│   └── settings.py      # 基于环境的配置
├── core/                # 核心功能
│   ├── auth.py         # 双层认证（API Key + 用户）
│   ├── context.py      # 请求上下文模型
│   └── exceptions.py   # 自定义异常
├── tools/               # 领域特定工具
│   ├── auth_tools.py     # 认证与会话管理
│   ├── product_tools.py  # 商品搜索与详情
│   ├── order_tools.py    # 订单管理与追踪
│   └── user_tools.py    # 用户资料与优惠券
├── services/             # AI 服务层
│   ├── langchain_service.py   # LangChain 集成
│   ├── llamaindex_service.py  # LlamaIndex 集成
│   └── crewai_service.py      # CrewAI 集成
└── src/mcp_server/
    └── server.py        # MCP 服务器主入口
```

## ✨ 功能特性

### 🔐 安全与认证
- **双层安全**: API Key 认证 + 用户验证
- **会话管理**: 安全的会话创建、验证和上下文注入
- **基于权限的访问控制**: 客户端特定的工具权限
- **请求上下文注入**: 为所有已认证调用自动注入会话上下文

### 📦 商品领域
- 通过关键词、类别、价格范围搜索商品
- 获取详细商品信息
- 查看商品评论（支持分页）

### 📋 订单领域
- 列出用户订单（支持状态过滤）
- 获取详细订单信息
- 取消订单（验证业务逻辑）
- 追踪物流和发货状态

### 👤 用户领域
- 获取用户资料和偏好
- 更新用户偏好
- 浏览可用优惠券
- 应用优惠券代码到订单

### 🤖 AI 智能能力
- **LangChain**: 商品描述生成、评论情感分析、智能推荐
- **LlamaIndex**: 商品语义搜索、问答系统
- **CrewAI**: 多智能体协作（商品研究、市场分析、用户洞察）

## 🚀 安装

项目提供三种安装方式：UV（推荐）、Conda 和 pip。

### 方式一：使用 UV（推荐）

```bash
# 安装 UV（如果未安装）
pip install uv

# 克隆并安装
git clone <repository>
cd ecommerce-mcp-server
uv sync
```

详细说明请参考 [UV_INSTALL.md](UV_INSTALL.md)

### 方式二：使用 Conda

```bash
# 克隆仓库
git clone <repository>
cd ecommerce-mcp-server

# 创建并激活环境
conda env create -f environment.yml
conda activate ecommerce-mcp
```

详细说明请参考 [CONDA_INSTALL.md](CONDA_INSTALL.md)

### 方式三：使用 pip

```bash
# 克隆并安装
git clone <repository>
cd ecommerce-mcp-server
pip install -e .
```

详细说明请参考 [INSTALL.md](INSTALL.md)

### 自动安装脚本

```bash
python install.py
```

脚本会自动检测环境并选择最佳安装方式。

## ⚙️ 配置

1. 复制示例环境文件：
```bash
cp .env.example .env
```

2. 编辑 `.env` 并配置您的设置：
```bash
# API Keys（JSON 格式支持多个客户端）
MCP_API_KEYS='{"client_app": "dev-key-abc-123", "admin": "admin-key-xyz-789"}'

# 数据库（开发使用 SQLite，生产使用 PostgreSQL）
DATABASE_URL=sqlite:///./ecommerce.db

# 向量数据库（用于语义搜索）
VECTOR_DB_URL=http://localhost:6333

# Redis 缓存
REDIS_URL=redis://localhost:6379/0

# AI 服务配置
OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key
```

## 🎯 使用

### 启动服务器

```bash
ecommerce-mcp-server
```

或使用 UV：
```bash
uv run python -m src.mcp_server.server
```

### MCP 客户端配置

添加到您的 MCP 客户端配置：

```json
{
  "mcpServers": {
    "ecommerce": {
      "command": "ecommerce-mcp-server",
      "args": [],
      "env": {
        "MCP_API_KEYS": "{\"client_app\": \"your-api-key\"}"
      }
    }
  }
}
```

## 📚 可用工具

### 认证工具

| 工具 | 描述 |
|------|-------------|
| `authenticate` | 使用 API Key 和用户 ID 进行认证并创建会话 |
| `validate_session` | 验证会话是否仍然有效 |
| `get_session_info` | 获取详细会话信息 |

### 商品工具

| 工具 | 描述 |
|------|-------------|
| `search_products` | 搜索商品（支持关键词、类别、价格过滤） |
| `get_product_detail` | 获取详细商品信息 |
| `get_product_reviews` | 获取商品评论（支持分页） |

### 订单工具

| 工具 | 描述 |
|------|-------------|
| `list_user_orders` | 获取用户订单（支持状态过滤） |
| `get_order_detail` | 获取详细订单信息 |
| `cancel_order` | 取消订单（验证业务规则） |
| `track_logistics` | 追踪发货状态和历史 |

### 用户工具

| 工具 | 描述 |
|------|-------------|
| `get_user_profile` | 获取用户资料和偏好 |
| `update_user_preference` | 更新用户偏好 |
| `get_available_coupons` | 浏览可用优惠券 |
| `apply_coupon` | 应用优惠券代码检查折扣 |

### AI 工具

| 工具 | 描述 |
|------|-------------|
| `ai_generate_product_description` | 生成商品描述 |
| `ai_analyze_reviews` | 分析评论情感 |
| `ai_recommend_products` | 基于用户偏好推荐商品 |
| `ai_semantic_search_products` | 商品语义搜索 |
| `ai_answer_product_question` | 商品问答系统 |
| `ai_create_product_recommendation_team` | 创建商品推荐多智能体团队 |

## 🔄 示例工作流

```python
# 步骤 1: 认证
{
  "tool": "authenticate",
  "arguments": {
    "api_key": "dev-key-abc-123",
    "user_id": "user_001"
  }
}
# 响应: "✅ 认证成功！会话 ID: abc-123..."

# 步骤 2: 搜索商品
{
  "tool": "search_products",
  "arguments": {
    "session_id": "abc-123...",
    "keyword": "耳机",
    "category": "Electronics"
  }
}

# 步骤 3: 查看订单
{
  "tool": "list_user_orders",
  "arguments": {
    "session_id": "abc-123...",
    "status": "delivered"
  }
}

# 步骤 4: 追踪发货
{
  "tool": "track_logistics",
  "arguments": {
    "session_id": "abc-123...",
    "order_id": "ORD-2024-002"
  }
}

# 步骤 5: 使用 AI 推荐商品
{
  "tool": "ai_recommend_products",
  "arguments": {
    "session_id": "abc-123...",
    "category": "Electronics"
  }
}
```

## 🏛️ 设计原则

1. **原子工具**: 每个工具只做好一件事
2. **清晰契约**: 工具描述指导 AI 理解
3. **友好错误**: 错误消息引导下一步操作
4. **向后兼容**: 已发布的 API 保持稳定
5. **安全优先**: 所有工具都需要有效的会话上下文

## 🔒 安全特性

- **API Key 验证**: 第一层安全
- **用户验证**: 第二层确保用户存在
- **会话管理**: 基于 UUID 的安全会话
- **权限检查**: 客户端特定的工具访问
- **审计日志**: 所有调用都记录上下文

## 🤖 AI 能力集成

项目集成了三大 AI 框架，提供智能化电商能力：

### LangChain
- 商品描述自动生成
- 用户评论情感分析
- 个性化商品推荐

### LlamaIndex
- 商品语义搜索
- 智能问答系统
- 向量检索增强

### CrewAI
- 多智能体协作团队
- 商品研究智能体
- 市场分析智能体
- 用户洞察智能体

详细说明请参考 [AI_FEATURES.md](AI_FEATURES.md)

## 🛠️ 开发

### 测试用模拟数据

服务器包含用于开发的模拟数据：
- **用户**: `user_001` (john_doe), `user_002` (jane_smith)
- **商品**: 4 个跨类别的示例商品
- **订单**: 用于测试的示例订单
- **优惠券**: 可用的测试优惠券

### 扩展服务器

1. **添加新工具**: 在 `tools/` 目录创建新工具文件
2. **注册工具**: 添加 `get_xxx_tools()` 和 `handle_xxx_tool()` 函数
3. **路由调用**: 更新 `server.py` 中的 `call_tool()`
4. **添加安全**: 使用 `@require_session` 装饰器保护需要认证的工具

示例：
```python
# tools/custom_tools.py
from tools.base_tool import require_session

def get_custom_tools() -> list[Tool]:
    return [Tool(...)]

@require_session
async def handle_custom_tool(_session, **kwargs) -> list[TextContent]:
    # _session.user.id 自动可用
    return [TextContent(type="text", text="...")]
```

## 📊 生产环境考虑

- 使用真实数据库替换内存数据（推荐 PostgreSQL）
- 添加 Redis 缓存
- 实现连接池
- 设置监控和告警
- 添加速率限制
- 实现适当的日志记录（ELK 栈）
- 使用密钥管理（Vault、AWS Secrets Manager）

## 🌍 多语言接入指南

项目支持多种编程语言接入 MCP 服务器，包括：

- **Python**: LangChain、原生 MCP SDK
- **Java**: Spring AI
- **JavaScript/TypeScript**: Node.js MCP SDK
- **Go**: Go MCP 客户端
- **Rust**: Rust MCP 实现
- **微信小程序**: 微信云开发集成

详细的接入说明请参考 [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md)

## 🤝 贡献

1. Fork 本仓库
2. 创建功能分支
3. 按照设计原则进行修改
4. 添加测试
5. 提交 Pull Request

## 📄 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

## 📚 相关文档

- [安装指南](INSTALL.md) - pip 安装说明
- [UV 安装指南](UV_INSTALL.md) - UV 安装说明
- [Conda 安装指南](CONDA_INSTALL.md) - Conda 安装说明
- [AI 功能文档](AI_FEATURES.md) - AI 能力详解
- [多语言接入指南](INTEGRATION_GUIDE.md) - 各语言接入方法
- [.gitignore 说明](GITIGNORE_EXPLANATION.md) - 忽略规则说明

## 🙏 致谢

基于以下技术构建：
- [MCP SDK](https://modelcontextprotocol.io/) - Model Context Protocol
- [Pydantic](https://docs.pydantic.dev/) - 数据验证
- [python-dotenv](https://github.com/theskumar/python-dotenv) - 配置管理
- [LangChain](https://langchain.com/) - AI 应用框架
- [LlamaIndex](https://llamaindex.ai/) - 数据框架
- [CrewAI](https://www.crewai.com/) - 多智能体框架