Products

You can run a production-ready MCP server that enables natural language product search and recommendations. It uses a vector store with semantic search, Azure OpenAI embeddings for powerful text representations, and a FastMCP HTTP interface so you can query products by natural language, category, brand, or price with robust filtering and a testable client workflow.

How to use

You interact with the MCP server through an MCP client to perform natural language product searches and refined lookups. You can search across all products, filter by category or brand, combine category and brand filters, and apply price constraints. You can also request complete product descriptions to display detailed information. Start by launching the server, then use the available MCP methods to run queries like searching for waterproof tents, finding affordable hiking boots, or listing all available categories and brands.

How to install

Prerequisites: you need Python 3.11 or newer.

1. Clone the project and navigate into it.

git clone https://github.com/josephazar/products-recommendation-mcp-maf.git
cd Products-Recommendation-MCP-MAF

2. Create and activate a 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 the template and fill in your Azure OpenAI credentials and data settings.

cp .env.example .env

Edit the .env file to set your Azure OpenAI endpoint, API key, API version, deployments, and vector store path.

## Additional configuration and run steps

5) Prepare data and index into ChromaDB.

python create_price_categories.py python index_products.py

## Start options

Option A: Test with an MCP client (command line) – start the server and run the test suite.

python mcp_server.py

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

python test_mcp_client_custom.py

This runs a comprehensive test suite with 10 scenarios.

python test_mcp_client_maf.py

This tests the same scenarios using the Microsoft Agent Framework.

Option B: Interactive Chatbot with Chainlit – start the server, then start the chatbot UI.

python mcp_server.py

chainlit run chainlit_app.py -w

The chatbot UI will open automatically at http://localhost:8000.

## Available tools

### search\_products

Search products using natural language across the catalog with semantic embeddings.

### search\_products\_by\_category

Search within a specific category and return matched products.

### search\_products\_by\_brand

Search within a specific brand to find relevant items.

### search\_products\_by\_category\_and\_brand

Combine category and brand filters for refined results.

### get\_categories

Return all unique product categories in sorted order.

### get\_brands

Return all unique product brands in sorted order.

### get\_product\_description

Retrieve complete product information by its name.

### search\_products\_with\_price\_filter

Search with price constraints such as less\_than or greater\_than.