Products Recommendation MCP Maf

基于MCP服务器的产品推荐系统

一个全面的产品推荐系统，使用 色度数据库 矢量存储， Azure OpenAI 嵌入， FastMCP HTTP服务器和用于自然语言产品搜索的定制MCP客户端。

🎯 概述

该系统通过模型上下文协议（MCP）服务器实现自然语言产品搜索和推荐。它使用带有嵌入的语义搜索来根据用户查询查找产品，例如“我在找一个防水帐篷”或“价格低于100美元的登山靴”。

🖼️ Chainlit聊天机器人界面

Chainlit Chat Interface

Product Recommendations

🌟 主要特点

1. 语义搜索：使用嵌入进行智能产品匹配
2. 多过滤器支持：类别、品牌和价格过滤
3. 自然语言：了解“经济实惠的防水帐篷”等问题
4. 8 MCP方法：全面的产品搜索功能
5. 可扩展的：可以处理数千种产品
6. 生产准备就绪：具有正确错误处理的HTTP服务器
7. 测试良好：包含10个测试用例的完整测试套件

📋 MCP服务器方法

该系统提供8种强大的MCP方法：

🛠️ 技术栈

• 色度数据库：用于语义搜索的矢量数据库
• Azure OpenAI：文本嵌入和聊天完成
• FastMCP：HTTP MCP服务器框架
• Microsoft代理框架：AI代理编排
• Chainlit：交互式聊天机器人用户界面
• Python 3.11：核心编程语言
• 熊猫：数据处理
• Uvicorn：ASGI服务器

🚀 快速开始

先决条件

• Python 3.11+
• Azure OpenAI帐户：

- 嵌入部署（兼容text-Embedding-ada-002） - 聊天完成部署（gpt-4o-mini或类似）

安装

1. 克隆仓库:

git clone https://github.com/yourusername/Products-Recommendation-MCP-MAF.git
cd Products-Recommendation-MCP-MAF

1. 创建并激活虚拟环境:

python3.11 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

1. 安装依赖项:

pip install -r requirements.txt

1. 配置环境变量:

复制 .env.example 到 .env 并填写您的Azure OpenAI凭据：

cp .env.example .env

编辑 .env:

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_KEY=your-api-key-here
AZURE_OPENAI_API_VERSION=2024-12-01-preview
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o-mini
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-ada-002
TOP_K=50
CHROMA_PERSIST_DIRECTORY=./chroma_db

数据准备

1. 创建价格类别:

python create_price_categories.py

这会产生 products_v2.csv 基于分位数的价格类别：

• 划算的：≤Q1（第25百分位）
• 价格合理的：Q1\Q3

1. 将产品索引到ChromaDB:

python index_products.py

这将创建嵌入，并将产品与元数据一起存储在ChromaDB中。

运行系统

选项1：使用MCP客户端（命令行）进行测试

1. 启动MCP服务器 （1号航站楼）：

python mcp_server.py

服务器将在以下位置可用： http://localhost:8000/mcp

1. 使用自定义MCP客户端进行测试 （2号航站楼）：

python test_mcp_client_custom.py

这运行了一个包含10个不同场景的全面测试套件。

1. 使用Microsoft代理框架进行测试 （2号航站楼）：

python test_mcp_client_maf.py

这将使用Microsoft Agent Framework测试相同的场景。

选项2：带Chainlit的交互式聊天机器人（推荐）

1. 启动MCP服务器 （1号航站楼）：

python mcp_server.py

1. 启动Chainlit聊天机器人 （2号航站楼）：

chainlit run chainlit_app.py -w

聊天机器人用户界面将在以下时间自动打开 http://localhost:8000 （或其他端口）。

尝试以下示例查询：

• “给我看看300美元以下的防水帐篷”
• “你有什么登山靴？”
• “我需要一个轻便的背包进行一日游”
• “有哪些类别可供选择？”
• “查找HikeMate品牌的产品”

📁 项目结构

Products-Recommendation-MCP-MAF/
├── .chainlit/                        # Chainlit configuration
│   └── config.toml                   # UI and app settings
├── .env.example                      # Environment configuration template
├── .gitignore                        # Git ignore rules
├── README.md                         # This file
├── README_CHAINLIT.md                # Chainlit app documentation
├── requirements.txt                  # Python dependencies
├── products.csv                      # Original product data
├── create_price_categories.py        # Script to generate price categories
├── index_products.py                 # Script to index products in ChromaDB
├── mcp_server.py                     # FastMCP HTTP server
├── test_mcp_client_custom.py         # Custom MCP client test suite
├── test_mcp_client_maf.py            # Microsoft Agent Framework test suite
└── chainlit_app.py                   # Chainlit chatbot application

🧪 测试示例

示例1：自然语言搜索

Query: "I'm looking for a waterproof tent for camping"
Tool: search_products
Result: Returns tents with waterproof features, ranked by relevance

示例2：类别筛选器

Query: "Show me hiking boots from the Hiking Footwear category"
Tool: search_products_by_category
Arguments: {query: "hiking boots", category: "Hiking Footwear"}

示例3：价格过滤器

Query: "Find hiking clothing items that cost less than 100 USD"
Tool: search_products_with_price_filter
Arguments: {
  query: "Hiking Clothing",
  price_operator: "less_than",
  price_threshold: 100
}

示例4：产品详细信息

Query: "Tell me everything about the TrailMaster X4 Tent"
Tool: get_product_description
Arguments: {product_name: "TrailMaster X4 Tent"}

🔧 配置

环境变量

📊 数据模式

产品CSV格式

id,name,price,category,brand,description
1,TrailMaster X4 Tent,250.0,Tents,OutdoorLiving,"Unveiling the TrailMaster..."

ChromaDB元数据

每种产品都存放在：

• name：产品名称
• category：产品类别
• brand：产品品牌
• price：数字价格
• price_category：文本价格类别（预算友好、经济实惠、中档、高级）
• description：完整的产品描述

嵌入文档格式

用于嵌入的文档连接起来：

{name} {category} {brand} {description} {price_category}

🔍 MCP服务器API

搜索产品

使用自然语言搜索类似产品。

参数：

• query （string）：自然语言搜索查询
• limit （整数，可选）：最大结果（默认值：TOP_K）

按类别搜索产品

搜索特定类别中的产品。

参数：

• query （string）：搜索查询
• category （string）：类别名称
• limit （整数，可选）：最大结果

搜索_产品_品牌

搜索特定品牌的产品。

参数：

• query （string）：搜索查询
• brand （string）：品牌名称
• limit （整数，可选）：最大结果

按类别和品牌搜索产品

使用类别和品牌过滤器进行搜索。

参数：

• query （string）：搜索查询
• category （string）：类别名称
• brand （string）：品牌名称
• limit （整数，可选）：最大结果

get_类别

获取所有独特的产品类别。

参数： 无

退货： 类别名称排序列表

get_brands

获取所有独特的产品品牌。

参数： 无

退货： 品牌名称排序列表

get_product_description

按名称获取完整的产品信息。

参数：

• product_name （string）：确切或部分产品名称

退货： 产品元数据字典

搜索_产品_价格_筛选器

搜索有价格限制的产品。

参数：

• query （string）：搜索查询
• price_operator （字符串）：“less_than”、“greater_tthan”、“less_or_equal”、“greater_or_equate”
• price_threshold （浮动）：要比较的价格值
• limit （整数，可选）：最大结果

🛠️ 故障排除

未找到ChromaDB集合

解决方案： 跑 python index_products.py 创建和填充集合

MCP服务器连接被拒绝

解决方案： 确保服务器在端口8000上运行，并且没有被防火墙阻止

Azure OpenAI身份验证错误

解决方案： 在中验证API密钥和终结点 .env 文件

搜索无结果

解决方案： 通过在中运行验证来检查产品是否正确索引 index_products.py

📝 发展

添加新产品

1. 将产品添加到 products.csv
2. 跑 python create_price_categories.py 重新生成价格类别
3. 跑 python index_products.py 重新索引所有产品

修改搜索行为

• 调整 TOP_K 在 .env 更改默认结果计数
• 修改中的嵌入文档格式 index_products.py
• 自定义价格类别 create_price_categories.py

扩展MCP方法

在中添加新工具 mcp_server.py 使用 @mcp.tool() 装饰师：

@mcp.tool()
def your_new_method(param: str) -> Dict:
    """Your method description"""
    # Implementation
    return result

🔐 安全

• 将API密钥安全地存储在 .env 文件（从不提交版本控制）
• 在生产部署中使用HTTPS
• 考虑向MCP服务器添加身份验证
• 对面向公众的部署实施速率限制

📚 参考文献

• FastMCP文档
• 模型上下文协议
• ChromaDB文档
• Azure OpenAI服务

📄 许可证

该项目在MIT许可证下可用。

🤝 贡献

欢迎投稿！拜托：

1. 复刻仓库
2. 创建要素分支
3. 使用提供的测试套件进行彻底测试
4. 提交拉取请求

______________________________________________________________________

版本: 1.0.0\ 状态：生产就绪✅