智能购物顾问MCP
“帮助由AI提供，选择和判断由用户提供”
输入要购买的物品时，请注意产品的特点、优缺点和购买时的注意事项。\ 智能购物决策支持MCP服务器，提供每个购物中心的优缺点和购买链接
演示
核心功能
1.产品详细分析（get_product)
📦 제품 정보 제공
├─ 주요 특징 및 사양
├─ 장점 / 단점 정리
└─ 구매 전 주의사항 (정품 확인, AS 정책 등)2.创建购物指南（create_shopping_guide)
🛒 지원 쇼핑몰 : 쿠팡, 네이버 쇼핑, SSG, G마켓, 무신사, 알리익스프레스 등每个购物中心提供以下信息：
- 优点（配送速度、退货政策、价格竞争力等）
- 缺点（可能缺货、配送时间、价位等）
- 产品搜索链接
3.产品比较（compare_products)
⚖️ 비교 분석 제공
├─ 항목별 사양 비교표
├─ 제품별 장단점 요약
└─ 사용 목적별 추천技术堆栈
分类技术 |------|------| |语言| Python 3.11| |框架|FastAPI、FastMCP| |服务器|Uvicorn（ASGI）| |AI | OpenAI API| |Cache|LRU内存高速缓存+SQLite| |容器| Docker，Docker Compose| |包管理器|uv|
开始
前提条件
- 码头工人 和Docker Compose
- OpenAI API密钥
1.存储库克隆
git clone
cd shopping_advisor2.设置环境变量
.env 创建文件并填充以下内容：
cp .env.example .env# OpenAI API Key (필수)
OPENAI_API_KEY=sk-...
# 서버 설정
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
BASE_URL=http://localhost:8000
# 캐시 설정
CACHE_DB_PATH=data/product_cache.db
CACHE_EXPIRE_DAYS=30
MEMORY_CACHE_SIZE=1000
# CORS 설정
ALLOWED_ORIGINS=*
# 기타
LOG_LEVEL=INFO
ENVIRONMENT=production3.作为Docker运行
docker compose up -d如果服务器正常运行 http://localhost:8000可以从访问。
# 서버 상태 확인
curl http://localhost:8000/health
# 로그 확인
docker compose logs -f4.停止服务器
docker compose down环境变量
| 变量 | 说明 | 默认值 |
|---|---|---|
OPENAI_API_KEY | OpenAI API密钥（必需）-- | |
SERVER_PORT | 服务器端口 | 8000 |
CACHE_DB_PATH SQLite缓存文件路径 | data/product_cache.db | |
CACHE_EXPIRE_DAYS | 缓存有效期（天） | 30 |
MEMORY_CACHE_SIZE | 内存LRU高速缓存最大条目数 | 1000 |
ALLOWED_ORIGINS | 允许CORS的来源 | * |
LOG_LEVEL | 日志级别 | INFO |
API端点
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /mcp | 处理MCP JSON-RPC请求 |
GET | /mcp SSE流（keep-alive） | |
GET | /health | 健康检查 |
GET | /.well-known/mcp.json | MCP服务器清单 |
MCP客户端连接设置：
{
"mcpServers": {
"shopping-advisor": {
"url": "http://localhost:8000/mcp"
}
}
}使用示例
示例1:查看产品信息
输入
마샬 블루투스 스피커 추천해줘输出
# 마샬 블루투스 스피커
## 제품 특징
- 빈티지 감성의 독특한 디자인
- 마샬 특유의 저음 강조 사운드
- 휴대용(Emberton)부터 대형(Woburn)까지 다양한 라인업
## 장점
- 디자인 만족도가 매우 높음
- 브랜드 사운드 아이덴티티가 확실함
- 내구성이 우수함
## 단점
- 가격 대비 음질 성능 논란 있음
- 병행수입 제품의 경우 AS 불편
- 무게감이 있어 휴대성 제한적
## 구매 전 체크리스트
- 정품/공식 유통 여부 확인
- 방수 등급(IPX7 등) 확인
- AS 정책 및 기간 확인示例2:创建购物指南
输出
## 쇼핑몰별 비교
| 쇼핑몰 | 장점 | 단점 | 추천 상황 |
|--------|------|------|-----------|
| 쿠팡 | 로켓배송, 무료반품 | 인기 모델 품절 잦음 | 빠른 배송 필요 시 |
| 네이버쇼핑 | 가격 비교 용이 | 판매자별 정책 상이 | 가격 비교 원할 때 |
| SSG | 정품 신뢰도 높음 | 가격대 다소 높음 | AS 중요할 때 |项目结构
shopping-advisor/
├── Dockerfile # 멀티 스테이지 빌드 (builder + runtime)
├── docker-compose.yml # 컨테이너 실행 설정
├── pyproject.toml # 프로젝트 메타데이터 및 의존성
├── uv.lock # 버전 잠금 파일
├── .env # 환경 변수 (git 제외)
├── .dockerignore
├── data/
│ ├── product_cache.db # SQLite 캐시 DB
│ └── shopping_malls.json # 쇼핑몰 정보
├── logs/
│ ├── shopping_advisor.log
│ └── error.log
├── src/
│ └── shopping_advisor/
│ ├── server.py # FastAPI 앱 및 MCP 엔드포인트
│ ├── logging_config.py # 로깅 설정
│ └── utils/
│ ├── tool.py # MCP 툴 정의 (get_product 등)
│ ├── cache_manager.py # 2계층 캐시 (메모리 LRU + SQLite)
│ ├── gpt_api.py # OpenAI API 연동
│ ├── prompt_template.py # 프롬프트 템플릿
│ ├── shopping_mall.py # 쇼핑몰 URL 생성 및 정보
│ └── formatter.py # 응답 포맷 변환
└── tests/
└── manual_tests/
├── test_cache_manager.py # 캐시 매니저 테스트
├── test_formatter.py # 포맷터 테스트
├── test_gpt_api.py # GPT API 테스트
└── test_shopping_mall.py # 쇼핑몰 유틸 테스트缓存结构
使用两层缓存以降低API调用成本并提高响应速度。
요청
│
▼
[1차] 메모리 캐시 (LRU, 최대 1,000개)
│ 미스
▼
[2차] SQLite 캐시 (만료: 30일)
│ 히트 → 메모리에 write-back
│ 미스
▼
OpenAI API 호출 → 캐시 저장法律声明
本项目 不执行Web抓取、滚动和自动数据收集。
做的
- 生成公开的购物中心搜索URL
- 提供一般产品特性信息（AI生成）
- 各购物中心公开的政策信息摘要
不做的
- 实时价格信息收集
- 滚动库存状态
- 写评论数据
- 收集和存储个人信息
所有购物中心链接均由基于产品名称的公开搜索URL模板组合而成，不用于自动访问或提取数据。