Product Recommendation System with MCP Server

A comprehensive product recommendation system using ChromaDB vector store, Azure OpenAI embeddings, FastMCP HTTP server, and a custom MCP client for natural language product search.

🎯 Overview

This system enables natural language product search and recommendations through a Model Context Protocol (MCP) server. It uses semantic search with embeddings to find products based on user queries like "I'm looking for a waterproof tent" or "affordable hiking boots under $100".

🌟 Key Features

1. Semantic Search: Uses embeddings for intelligent product matching

2. Multi-Filter Support: Category, brand, and price filtering

3. Natural Language: Understands queries like "affordable waterproof tent"

4. 8 MCP Methods: Comprehensive product search capabilities

5. Scalable: Can handle thousands of products

6. Production-Ready: HTTP server with proper error handling

7. Well-Tested: Full test suite with 10 test cases

📋 MCP Server Methods

The system provides 8 powerful MCP methods:

🛠️ Technology Stack

• ChromaDB: Vector database for semantic search

• Azure OpenAI: Text embeddings and chat completions

• FastMCP: HTTP MCP server framework

• Python 3.11: Core programming language

• Pandas: Data processing

• Uvicorn: ASGI server

🚀 Quick Start

Prerequisites

• Python 3.11+

• Azure OpenAI account with:

  • Embedding deployment (text-embedding-ada-002 compatible)

  • Chat completion deployment (gpt-4o-mini or similar)

Installation

1. Clone the repository:

2. Create and activate virtual environment:

3. Install dependencies:

4. Configure environment variables:

Copy .env.example to .env and fill in your Azure OpenAI credentials:

Edit .env:

Data Preparation

1. Create price categories:

This generates products_v2.csv with quantile-based price categories:

• Budget-Friendly: ≤ Q1 (25th percentile)

• Affordable: Q1 < price ≤ Q2 (median)

• Mid-Range: Q2 < price ≤ Q3 (75th percentile)

• Premium: > Q3

2. Index products into ChromaDB:

This creates embeddings and stores products in ChromaDB with metadata.

Running the System

1. Start the MCP Server (Terminal 1):

The server will be available at: http://localhost:8000/mcp

2. Test the MCP Server (Terminal 2):

This runs a comprehensive test suite with 10 different scenarios.

📁 Project Structure

🧪 Testing Examples

Example 1: Natural Language Search

Example 2: Category Filter

Example 3: Price Filter

Example 4: Product Details

🔧 Configuration

Environment Variables

📊 Data Schema

Products CSV Format

ChromaDB Metadata

Each product is stored with:

• name: Product name

• category: Product category

• brand: Product brand

• price: Numeric price

• price_category: Text price category (Budget-Friendly, Affordable, Mid-Range, Premium)

• description: Full product description

Embedding Document Format

Documents for embedding concatenate:

🔍 MCP Server API

search_products

Search for similar products using natural language.

Parameters:

• query (string): Natural language search query

• limit (integer, optional): Maximum results (default: TOP_K)

search_products_by_category

Search products within a specific category.

Parameters:

• query (string): Search query

• category (string): Category name

• limit (integer, optional): Maximum results

search_products_by_brand

Search products from a specific brand.

Parameters:

• query (string): Search query

• brand (string): Brand name

• limit (integer, optional): Maximum results

search_products_by_category_and_brand

Search with both category and brand filters.

Parameters:

• query (string): Search query

• category (string): Category name

• brand (string): Brand name

• limit (integer, optional): Maximum results

get_categories

Get all unique product categories.

Parameters: None

Returns: Sorted list of category names

get_brands

Get all unique product brands.

Parameters: None

Returns: Sorted list of brand names

get_product_description

Get complete product information by name.

Parameters:

• product_name (string): Exact or partial product name

Returns: Product metadata dictionary

search_products_with_price_filter

Search products with price constraints.

Parameters:

• query (string): Search query

• price_operator (string): "less_than", "greater_than", "less_or_equal", "greater_or_equal"

• price_threshold (float): Price value to compare

• limit (integer, optional): Maximum results

🛠️ Troubleshooting

ChromaDB collection not found

Solution: Run python index_products.py to create and populate the collection

MCP server connection refused

Solution: Ensure the server is running on port 8000 and not blocked by firewall

Azure OpenAI authentication error

Solution: Verify your API key and endpoint in .env file

No results from search

Solution: Check if products are indexed correctly by running the verification in index_products.py

📝 Development

Adding New Products

1. Add products to products.csv

2. Run python create_price_categories.py to regenerate price categories

3. Run python index_products.py to re-index all products

Modifying Search Behavior

• Adjust TOP_K in .env to change default result count

• Modify embedding document format in index_products.py

• Customize price categories in create_price_categories.py

Extending MCP Methods

Add new tools in mcp_server.py using the @mcp.tool() decorator:

🔐 Security

• Store API keys securely in .env file (never commit to version control)

• Use HTTPS in production deployments

• Consider adding authentication to the MCP server

• Implement rate limiting for public-facing deployments

📚 References

• FastMCP Documentation

• Model Context Protocol

• ChromaDB Documentation

• Azure OpenAI Service

📄 License

This project is available under the MIT License.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Test thoroughly with the provided test suite

4. Submit a pull request

Version: 1.0.0
Status: Production Ready ✅