项目简介

这是一个基于 Model Context Protocol (MCP) 构建的智能购物助手服务器。它集成了 SerpAPI 进行实时商品搜索，利用 Qdrant 实现语义搜索，并通过 OpenRouter 和 AWS S3 提供 AI 驱动的虚拟试穿功能。该服务器旨在为大语言模型（LLM）客户端提供丰富的购物上下文和功能调用能力，支持 LLM 以标准化的方式访问商品数据和执行高级购物任务。

主要功能点

实时商品搜索: 通过 Google Shopping (SerpAPI) 获取最新商品信息，支持根据查询关键词、商品类别、价格范围、是否包邮或促销等多种条件进行筛选。
智能语义搜索: 集成 Qdrant 向量数据库，利用语义嵌入技术，让用户可以通过自然语言描述来查询商品，实现更智能、更相关的产品匹配。
商品对比分析: 能够对多个商品进行并排比较，重点分析价格、用户评分、库存状态等关键指标，并为用户推荐最优选择。
AI 虚拟试穿与放置: 利用 AI 模型（如 Google Gemini 2.5 Flash via OpenRouter）实现衣物、家具、手机或其它物品的虚拟试穿或场景放置。生成逼真的效果图，并可将结果图片持久化存储到 AWS S3。
产品数据持久化: 自动将搜索到的产品信息保存到向量数据库，以便后续进行语义搜索和管理。

安装步骤

克隆仓库: 首先，使用 Git 克隆项目仓库到您的本地计算机：

git clone https://github.com/tihado/mistral-hackathon-sep-2025
cd mistral-hackathon-sep-2025

安装 Python 依赖: 确保您的系统安装了 Python 3.13+ 和 'uv' 包管理器 (参考 'https://docs.astral.sh/uv/getting-started/installation/')。然后安装项目所需的 Python 依赖：
```
uv python install
uv sync --locked
```

配置环境变量: 在项目根目录创建一个名为 '.env' 的文件，并填入以下关键 API 密钥和配置信息。请将 'your_..._key_here' 替换为您的实际密钥和信息：

# SerpAPI 配置
SERPAPI_KEY=your_serpapi_key_here

# OpenRouter API 配置
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Qdrant 向量数据库配置
# 对于本地 Qdrant 实例 (默认)
QDRANT_URL=http://localhost:6333
# 对于云端 Qdrant 实例 (可选)
# QDRANT_URL=https://your-cluster-url.eu-central.aws.cloud.qdrant.io:6333
# QDRANT_API_KEY=your_qdrant_api_key_here

# AWS S3 配置 (用于虚拟试穿图片存储)
AWS_ACCESS_KEY_ID=your_aws_access_key_here
AWS_SECRET_ACCESS_KEY=your_aws_secret_key_here
AWS_S3_BUCKET_NAME=your_s3_bucket_name_here
AWS_REGION=auto
AWS_ENDPOINT_URL="https://..."
AWS_PUBLIC_URL="https://..."

注意: 如果不提供 API 密钥，服务器将以模拟数据模式运行，便于测试和开发。

启动 Qdrant 数据库: 推荐使用 Docker 本地启动 Qdrant 向量数据库：

docker run -p 6333:6333 qdrant/qdrant

启动 MCP 服务器: 在配置完所有环境变量和 Qdrant 数据库后，运行以下命令启动 MCP 服务器：
```
uv run main.py
```
服务器将默认在 'http://127.0.0.1:3000' 端口启动。

MCP 客户端服务器配置示例

MCP 客户端需要以下信息来连接和使用此服务器。请将以下信息配置到您的 MCP 客户端中，并替换其中的 'YOUR_...' 占位符为您的实际密钥和信息：

{
  "name": "Shopping MCP Server",
  "description": "基于MCP协议的AI智能购物助手，提供商品搜索、比较和虚拟试穿功能。",
  "command": "uv",
  "args": ["run", "main.py"],
  "environment": {
    "SERPAPI_KEY": "YOUR_SERPAPI_KEY_HERE",
    "OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY_HERE",
    "QDRANT_URL": "http://localhost:6333",
    "AWS_ACCESS_KEY_ID": "YOUR_AWS_ACCESS_KEY_ID",
    "AWS_SECRET_ACCESS_KEY": "YOUR_AWS_SECRET_ACCESS_KEY",
    "AWS_S3_BUCKET_NAME": "YOUR_S3_BUCKET_NAME_HERE",
    "AWS_REGION": "auto",
    "AWS_ENDPOINT_URL": "https://...",
    "AWS_PUBLIC_URL": "https://..."
  },
  "connection_details": {
    "transport": "streamable-http",
    "url": "http://127.0.0.1:3000/mcp"
  },
  "notes": "此服务器通过HTTP协议提供服务。在MCP客户端连接前，请确保服务器已通过 'uv run main.py' 命令独立启动，并配置好所有必需的环境变量。"
}

配置说明:

name: 服务器在客户端界面显示的名称。
description: 服务器功能的简要描述。
command / args: 启动此 MCP 服务器进程所需的命令和参数。对于 'streamable-http' 传输模式，服务器通常作为独立进程运行，MCP 客户端直接通过 URL 连接。这些参数主要用于文档或在客户端需要管理服务器生命周期（如 'stdio' 传输）时使用。
environment: 运行服务器所需的各项环境变量，请确保填入您的真实密钥。
connection_details: 客户端连接到服务器所需的具体信息。
- transport: 使用的传输协议，此处为 'streamable-http'。
- url: MCP 服务器的访问地址，客户端将通过此 URL 与服务器进行 JSON-RPC 通信。

基本使用方法

一旦 MCP 服务器启动并被 MCP 客户端成功连接，大语言模型（LLM）客户端即可通过 JSON-RPC 协议调用其提供的工具和 Prompt 模板，以实现智能购物助手的各项功能。

激活购物助手: LLM 可以首先调用 'shopping_assistant' Prompt，该 Prompt 会向 LLM 提供系统级的指令，引导其遵循特定的购物交互工作流程（搜索 -> 比较 -> 试穿）。
搜索商品: 根据用户的查询请求，LLM 会调用 'search_products_tool' 工具，传入商品查询、类别、价格范围等参数，以获取相关的商品列表。
比较商品: 在获取搜索结果后，LLM 会调用 'compare_products_tool' 工具，对商品进行多维度比较，并筛选出最佳推荐选项。
虚拟试穿/放置: 在用户从比较结果中选择特定商品并提供其个人图片（如人像照片或房间照片）后，LLM 会调用 'virtual_try_on_tool' 工具，实现 AI 驱动的虚拟试穿或商品在场景中的放置效果，并向用户展示生成的图像。

LLM 客户端应严格遵循 'shopping_assistant' Prompt 中定义的强制工作流程，以提供连贯和高效的购物体验。

关键词

项目简介

主要功能点

安装步骤

MCP 客户端服务器配置示例

基本使用方法

信息