🛍️ MCP - MCP for Commerce Platforms - Universal E-commerce Customer Support Assistant

One Chat, Every Platform - A platform-agnostic customer support assistant that
connects to any e-commerce platform through pluggable strategies, using MCP (Model
Context Protocol) server and Gradio for the interface.

🎯 Features

- 📦 Order Management: Track orders, check status, view history
- 🔄 Returns & Refunds: Initiate returns, process refunds seamlessly
- ❌ Cancellations: Quick and easy order cancellations
- 💬 Natural Language: Conversational interface for customer support
- 🔌 Platform Agnostic: Extensible to any e-commerce platform
- 🚀 Auto-Deploy: Continuous deployment to Hugging Face Spaces

🏗️ Architecture

The system uses a Strategy Pattern to abstract different e-commerce platforms:

┌─────────────────────────────────────────────────────────┐
│                    Gradio UI Layer                      │
│        (Customer Support Conversational Interface)      │
└─────────────────────────────┬───────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────┐
│                    MCP Server Core                      │
│  (Order Management, NLP Processing, Context Engine)     │
└─────────────────────────────┬───────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────┐
│              E-commerce Strategy Interface              │
│   (MockData, Shopify, Magento, WooCommerce, etc.)       │
└─────────────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

- Python 3.10 or higher
- Git
- Virtual environment tool (venv)

Installation

1. Clone the repository

   git clone https://github.com/slavpilus/mcp.git
   cd mcp
   

2. Run the setup script (macOS/Linux)

   chmod +x scripts/setup_dev.sh
   ./scripts/setup_dev.sh
   

Or manually:

   # Create virtual environment
   python -m venv venv
# Activate virtual environment

   # On macOS/Linux:

   source venv/bin/activate

   # On Windows:

   venv\Scripts\activate
# Install dependencies

   pip install -r requirements-dev.txt
# Install pre-commit hooks

   pre-commit install

   

3. Configure environment variables

   cp .env.example .env
   # Edit .env with your configuration
   

4. Run the application

   python app.py
   

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

🛠️ Development

Project Structure

mcp/
├── .github/workflows/    # CI/CD pipelines
├── mcp_server/          # Core MCP server implementation
│   ├── strategies/      # E-commerce platform strategies
│   ├── models/          # Data models
│   └── utils/           # Utility functions
├── ui/                  # Gradio UI components
├── tests/               # Test suite
├── app.py               # Main Gradio application
└── requirements.txt     # Python dependencies

Development Workflow

1. Activate virtual environment

   source venv/bin/activate  # macOS/Linux
   # or
   venv\Scripts\activate     # Windows
   

2. Make your changes
- Follow the existing code style
- Add tests for new functionality
- Update documentation as needed

3. Run code quality checks

   # Format code
   black .
   isort .
# Run linter

   ruff check .
# Type checking

   mypy mcp_server ui

   

4. Run tests

   # Run all tests with coverage
   pytest
# Run specific test file

   pytest tests/unit/test_strategies.py
# Run with verbose output

   pytest -v

   

5. Commit changes

   git add .
   git commit -m "feat: your feature description"
   

Pre-commit hooks will automatically run code quality checks.

Code Style

This project uses:

- Black for code formatting (line length: 88)
- isort for import sorting
- Ruff for linting
- MyPy for type checking

All code must pass these checks before merging.

Testing

- Minimum test coverage: 80%
- Write unit tests for all new functionality
- Integration tests for critical workflows
- Use pytest fixtures for test data

Adding a New E-commerce Platform

1. Create a new strategy in mcp_server/strategies/:

   from .base import EcommerceStrategy
class YourPlatformStrategy(EcommerceStrategy):

       async def get_order(self, order_id: str) -> Optional[Order]:

           # Implementation here

           pass

   

2. Add tests in tests/unit/test_your_platform_strategy.py

3. Update the strategy factory to include your platform

📊 Environment Variables

Create a .env file based on .env.example:

```env