Customer Support Chatbot

A prototype Customer Support chatbot for a computer products company, built with MCP (Model Context Protocol) integration and a lightweight LLM.

Features

• Customer authentication using email and PIN
• Product search and browsing
• Order history viewing
• Product details lookup
• Natural language conversation using OpenRouter API

Architecture

• MCP Server: Handles all product and order operations via Streamable HTTP
• LLM: Uses OpenRouter API for intelligent responses
• UI: Gradio interface for easy interaction
• Deployment: HuggingFace Spaces

Project Structure

chatbot/
├── app.py                 # Main Gradio application entry point
├── config.py             # Configuration and environment variables
├── mcp_client.py          # MCP server client implementation
├── llm_client.py         # OpenRouter LLM API client
├── utils.py              # Utility functions (extractors, helpers)
├── intent_detection.py   # Intent detection logic
├── response_generator.py # LLM response generation
├── auth.py               # User authentication functions
├── message_processor.py  # Message processing and tool orchestration
├── requirements.txt      # Python dependencies
├── README.md            # This file
└── .env                 # Environment variables (not in repo)

Module Descriptions

• app.py: Main application file that sets up the Gradio interface and handles UI interactions
• config.py: Loads environment variables, configures logging, and initializes LLM client
• mcp_client.py: MCPServer class for interacting with the MCP server (products, orders, authentication)
• llm_client.py: Functions for calling the OpenRouter API
• utils.py: Helper functions for extracting SKUs, search queries, and customer IDs
• intent_detection.py: Determines user intent and selects appropriate tools
• response_generator.py: Generates conversational responses using LLM
• auth.py: Handles customer authentication via email and PIN
• message_processor.py: Orchestrates message processing, tool execution, and response generation

Setup

Local Development

1. Create and activate virtual environment:

python3 -m venv venv
source venv/bin/activate

2. Install dependencies:

pip install --upgrade pip
pip install -r requirements.txt

3. Run the application:

python app.py

4. Open your browser to http://localhost:7860

Test Credentials

• donaldgarcia@example.net / PIN: 7912
• michellejames@example.com / PIN: 1520
• laurahenderson@example.org / PIN: 1488
• spenceamanda@example.org / PIN: 2535
• glee@example.net / PIN: 4582

MCP Server Tools

• verify_customer_pin - Authenticate customers
• list_products - Browse product catalog
• search_products - Search products by keyword
• get_product - Get detailed product information
• list_orders - View customer order history
• get_order - Get order details
• create_order - Place new orders

Deployment

HuggingFace Spaces

1. Create a new Space on HuggingFace
2. Set SDK to "Gradio"
3. Upload all Python files (app.py, config.py, mcp_client.py, llm_client.py, utils.py, intent_detection.py, response_generator.py, auth.py, message_processor.py), requirements.txt, and README.md
4. Set environment variables in Space settings
5. The Space will automatically build and deploy

Environment Variables

Required

• OPENROUTER_API_KEY: OpenRouter API key (required)
• OPENROUTER_MODEL: OpenRouter model to use (default: google/gemini-2.5-flash)

Optional

• MCP_SERVER_URL: MCP server endpoint (default: provided URL)
• OPENROUTER_BASE_URL: OpenRouter API base URL (default: https://openrouter.ai/api/v1)

Example Setup

1. Copy the example environment file:

cp .env.example .env

2. Edit .env and add your OpenRouter API key:

OPENROUTER_API_KEY=your-actual-api-key-here

3. Run the application:

python app.py

Alternatively, you can set environment variables directly:

export OPENROUTER_API_KEY="your-api-key-here"
export OPENROUTER_MODEL="google/gemini-2.5-flash"  # Optional, this is the default
python app.py

Requirements

• Python 3.8+
• Gradio 4.44.0+
• Requests 2.31.0+
• python-dotenv 1.0.0+

LLM Configuration

• Provider: OpenRouter API
• Default Model: google/gemini-2.5-flash (lightweight, fast)
• No Local Models: Uses API-based LLMs (no model downloads required)