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".

🖼️ Chainlit Chatbot Interface

🌟 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:

#	Method Name	Description
1	search_products	Search products using natural language
2	search_products_by_category	Search within a specific category
3	search_products_by_brand	Search products from a specific brand
4	search_products_by_category_and_brand	Combined category and brand search
5	get_categories	Get all available product categories
6	get_brands	Get all available brands
7	get_product_description	Get complete product information by name
8	search_products_with_price_filter	Search with price constraints (less/greater than)

🛠️ Technology Stack

• ChromaDB: Vector database for semantic search
• Azure OpenAI: Text embeddings and chat completions
• FastMCP: HTTP MCP server framework
• Microsoft Agent Framework: AI agent orchestration
• Chainlit: Interactive chatbot UI
• 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:

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

2. Create and activate virtual environment:

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

3. Install dependencies:

pip install -r requirements.txt

4. Configure environment variables:

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

cp .env.example .env

Edit .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

Data Preparation

1. Create price categories:

python create_price_categories.py

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:

python index_products.py

This creates embeddings and stores products in ChromaDB with metadata.

Running the System

Option 1: Test with MCP Client (Command Line)

1. Start the MCP Server (Terminal 1):

python mcp_server.py

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

2. Test with Custom MCP Client (Terminal 2):

python test_mcp_client_custom.py

This runs a comprehensive test suite with 10 different scenarios.

3. Test with Microsoft Agent Framework (Terminal 2):

python test_mcp_client_maf.py

This tests the same scenarios using Microsoft Agent Framework.

Option 2: Interactive Chatbot with Chainlit (Recommended)

1. Start the MCP Server (Terminal 1):

python mcp_server.py

2. Start the Chainlit Chatbot (Terminal 2):

chainlit run chainlit_app.py -w

The chatbot UI will open automatically at http://localhost:8000 (or another port).

Try these example queries:

• "Show me waterproof tents under $300"
• "What hiking boots do you have?"
• "I need a lightweight backpack for day trips"
• "What categories are available?"
• "Find me products from the HikeMate brand"

📁 Project Structure

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

🧪 Testing Examples

Example 1: Natural Language Search

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

Example 2: Category Filter

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

Example 3: Price Filter

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
}

Example 4: Product Details

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

🔧 Configuration

Environment Variables

Variable	Description	Example
AZURE_OPENAI_ENDPOINT	Azure OpenAI endpoint URL	https://xxx.openai.azure.com
AZURE_OPENAI_API_KEY	Azure OpenAI API key	your-key-here
AZURE_OPENAI_API_VERSION	API version	2024-12-01-preview
AZURE_OPENAI_DEPLOYMENT_NAME	Chat model deployment	gpt-4o-mini
AZURE_OPENAI_EMBEDDING_DEPLOYMENT	Embedding model deployment	text-embedding-ada-002
TOP_K	Default number of results	50
CHROMA_PERSIST_DIRECTORY	ChromaDB storage path	./chroma_db

📊 Data Schema

Products CSV Format

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

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:

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

🔍 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:

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

🔐 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 ✅