---

title: Customer Support Chatbot emoji: 🤖 colorFrom: blue colorTo: purple sdk: gradio sdk_version: 4.0.0 app_file: app.py pinned: false license: mit

Customer Support Chatbot

A prototype Customer Support chatbot for a company that sells computer products (monitors, printers, etc.). The chatbot integrates with an MCP (Model Context Protocol) server to provide real-time product information, order management, and customer support.

Features

• 🔐 Customer Authentication: Secure login with email and PIN via MCP server
• 🛍️ Product Search: Search and browse computer products with natural language queries
• 📦 Order Management: View order history and track orders for authenticated customers
• 💬 Natural Language Interface: Powered by Groq’s Llama 3.1 8B Instant model (cost-effective)
• 🔌 MCP Integration: Seamless integration with MCP server via Streamable HTTP (all 8 tools)
• 🛡️ Error Handling: User-friendly error messages with graceful error recovery
• 💾 Session Management: In-memory session state for multi-turn conversations
• 🎨 Modern UI: Clean Gradio interface with intuitive login and chat experience

Setup

Local Development

1. Clone the repository:

git clone 
cd customer-support-chatbot

2. Install dependencies:

pip install -r requirements.txt

3. Create a .env file:

cp .env.example .env

4. Add your API keys to .env:

MCP_SERVER_URL=https://vipfapwm3x.us-east-1.awsapprunner.com/mcp
GROQ_API_KEY=your_groq_api_key_here

5. Run the application:

python app.py

The app will be available at http://localhost:7860

HuggingFace Spaces Deployment

1. Create a new Space on HuggingFace Spaces
2. Upload all project files
3. Add environment variables in Space settings:
   • GROQ_API_KEY: Your Groq API key
   • MCP_SERVER_URL: https://vipfapwm3x.us-east-1.awsapprunner.com/mcp
4. The Space will automatically build and deploy

Test Credentials

Use these test credentials to login:

Usage

1. Login: Enter your email and PIN to authenticate
2. Browse Products: Ask questions like:
   • “Show me available monitors”
   • “Search for printers”
   • “What is the price of MON-0054?”
3. View Orders: After authentication, you can:
   • “Show my orders”
   • “What’s the status of my order?”
   • “Get order details for [order-id]”

Architecture

• Frontend: Gradio (Python-based UI framework) - Fast deployment, perfect for demos
• LLM: Groq API with Llama 3.1 8B Instant (cost-effective flash model)
• MCP Integration: Streamable HTTP client for MCP server communication
• Authentication: Email + PIN verification via MCP server with session management
• Error Handling: Comprehensive error handling with user-friendly messages
• Session Management: In-memory state management for conversation context

Project Structure

.
├── app.py                 # Main Gradio application with UI
├── chatbot.py             # Chatbot orchestration logic (MCP + LLM + Auth)
├── mcp_client.py          # MCP server communication module (HTTP client)
├── llm_handler.py         # LLM integration and conversation management
├── auth.py                # Customer authentication logic with error handling
├── requirements.txt       # Python dependencies
├── README.md             # Project documentation (this file)
├── DEPLOYMENT.md         # Detailed deployment guide
├── TEST_SCENARIOS.md     # Comprehensive test scenarios
├── QUICKSTART.md         # Quick start guide
├── REQUIREMENTS.md       # Requirements and setup instructions
└── .env.example          # Environment variables template

MCP Server Tools

The chatbot integrates with the following MCP server tools:

• list_products: List products with optional filters
• get_product: Get detailed product information by SKU
• search_products: Search products by name or description
• verify_customer_pin: Verify customer identity
• get_customer: Get customer information
• list_orders: List orders with optional filters
• get_order: Get detailed order information
• create_order: Create a new order

Environment Variables

Required environment variables:

• GROQ_API_KEY: Your Groq API key (required)
• MCP_SERVER_URL: MCP server URL (optional, defaults to provided URL)

Implementation Checklist

This project implements all core requirements:

• ✅ MCP Integration: All 8 MCP server tools integrated via Streamable HTTP
• ✅ Cheap LLM: Groq API with Llama 3.1 8B Instant (cost-effective flash model)
• ✅ Authentication: Email + PIN verification via MCP server
• ✅ Demo UI: Gradio-based interface with login and chat
• ✅ Live Deployment: Ready for HuggingFace Spaces deployment
• ✅ Clear Architecture: Modular design with separation of concerns
• ✅ Time-boxed Design: Simple, focused implementation

Architecture Components

1. Frontend (Gradio): User interface with login and chat
2. Authentication Module: Email + PIN validation and session management
3. MCP Client: HTTP client for MCP server communication
4. LLM Handler: Groq API integration with conversation management
5. Chatbot Orchestrator: Coordinates MCP, LLM, and authentication

Key Features

• Real-time Product Search: Browse and search products using natural language
• Customer Order Management: View order history and track orders (requires authentication)
• Natural Language Interface: Conversational AI powered by Groq’s Llama 3.1 8B
• Secure Authentication: Email + PIN verification via MCP server
• Enhanced Error Handling: User-friendly error messages with graceful recovery
• Session Management: Maintains conversation context across multiple turns
• MCP Tool Integration: All 8 MCP server tools integrated (products, orders, customers)
• Cost-Effective: Uses flash/mini LLM model for optimal cost-performance balance

Testing

Comprehensive test scenarios are documented in TEST_SCENARIOS.md, including:

• ✅ Authentication tests (valid/invalid login, logout)
• ✅ Product search and browsing tests
• ✅ Order management tests
• ✅ Multi-turn conversation tests
• ✅ Error handling and edge cases

Use the provided test credentials to verify all functionality.

Troubleshooting

If you encounter issues:

1. Authentication fails:

   • Verify you’re using correct test credentials from the table above
   • Check that email format is correct (case-sensitive)
   • Ensure PIN is exactly 4 digits

2. API errors:

   • Check that GROQ_API_KEY is set correctly in environment variables
   • Verify your Groq API key is valid and has available quota
   • Check Groq API status at console.groq.com

3. MCP connection errors:

   • Verify the MCP server is accessible: https://vipfapwm3x.us-east-1.awsapprunner.com/mcp
   • Check your internet connection
   • Server timeout is set to 15 seconds - slow connections may need retry

4. Message format errors:

   • Ensure all dependencies are up to date: pip install -r requirements.txt
   • Check Python version (3.8+ required)

5. Chat not responding:

   • Check that you’re logged in (chat is disabled until authentication)
   • Verify session is active (try logging out and back in)
   • Check browser console for any JavaScript errors

See DEPLOYMENT.md for detailed deployment instructions. See TEST_SCENARIOS.md for comprehensive test scenarios. See REQUIREMENTS.md for setup requirements.

License

MIT