title	emoji	colorFrom	colorTo	sdk	sdk_version	app_file	pinned	license	tags
Enneagora - E-commerce MCP Server	🛍️	blue	purple	gradio	5.33.0	main.py	true	mit	mcp-server-track cuustomer support commerce e-commerce

Enneagora - E-commerce MCP Server

Enneagora is a Universal E-commerce Customer Support Assistant using the Model Context Protocol (MCP) that provides a platform-agnostic solution for customer support across different e-commerce platforms. This comprehensive MCP server can be integrated with Claude Desktop or any MCP-compatible client to handle all aspects of customer inquiries.

🚀 Features

• MCP-Compliant: Dual MCP server implementation using both Gradio and FastMCP with SSE and STDIO transports
• 14 Comprehensive Customer Support Tools:
  • Order Management: get_order_status, cancel_order, process_return, track_package
  • Support Information: get_support_info, get_return_policy, get_shipping_info, get_contact_information
  • Product Guidance: get_size_guide, get_warranty_information, get_product_care_info
  • Account & Payment: get_payment_information, get_account_help, get_loyalty_program_info
• Platform Agnostic: Strategy pattern for easy integration with any e-commerce platform
• Dynamic Mock Data: Intelligent test data system with pattern-based order behavior
• Dual Implementation Support: Gradio MCP server for web deployment, FastMCP for Claude Desktop STDIO integration
• Production Ready: CI/CD pipeline with automated deployment to Hugging Face Spaces

📋 Prerequisites

• Python 3.10 or higher
• pip package manager
• (Optional) Hugging Face account for deployment

🛠️ Installation

1. Clone the repository:

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

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

🚀 Usage Options

Option 1: Gradio MCP Server (Recommended for Hugging Face Spaces)

Use the hosted Gradio MCP server on Hugging Face Spaces:

Gradio MCP Endpoint: https://huggingface.co/spaces/SlavPilus/mpc-for-commerce-platforms

Advantages:

• Native Gradio MCP server implementation with mcp_server=True
• No local setup required
• Always up-to-date with latest features
• Perfect for MCP-compatible clients and integrations
• Seamless Hugging Face Spaces deployment

Gradio MCP Server (local development)

python main.py

The Gradio MCP server starts on http://localhost:7860 with MCP SSE endpoint at http://localhost:7860/gradio_api/mcp/sse.

FastMCP Claude Desktop Integration (STDIO)

Step 1: Configure Claude Desktop

macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "enneagora": {
      "command": "python",
      "args": ["/full/absolute/path/to/mcp/main_stdio.py"],
      "env": {}
    }
  }
}

⚠️ Important:

• Use the full absolute path to main_stdio.py
• Ensure your Python environment has all dependencies installed
• Restart Claude Desktop after configuration changes

Step 2: Test Configuration

You can test the STDIO version manually:

python main_stdio.py

🔧 All Available Tools

Order Management Tools

1. get_order_status - Get detailed order status and tracking information
2. cancel_order - Cancel orders with validation checks
3. process_return - Handle return requests with prepaid labels
4. track_package - Track package delivery with real-time updates

Information & Support Tools

5. get_support_info - General support information and guidance
6. get_return_policy - Detailed return policies by product category
7. get_shipping_info - Shipping rates, delivery times, and international options
8. get_contact_information - Contact details by issue type and urgency

Product & Service Tools

9. get_size_guide - Size charts for clothing, shoes, and accessories
10. get_warranty_information - Warranty coverage and claims processing
11. get_product_care_info - Care instructions and maintenance guidance

Account & Payment Tools

12. get_payment_information - Payment methods, billing help, and troubleshooting
13. get_account_help - Account troubleshooting and login assistance
14. get_loyalty_program_info - Rewards program details and member benefits

🧪 Testing with Dynamic Mock Data

Enneagora features an intelligent mock data system where order behavior is determined by ID patterns:

Order Status Patterns

• ORD-XXXX-D - Delivered orders (e.g., ORD-1001-D)
• ORD-XXXX-S - Shipped orders with tracking (e.g., ORD-1002-S)
• ORD-XXXX-T - In Transit with location updates (e.g., ORD-1003-T)
• ORD-XXXX-P - Processing orders (e.g., ORD-1004-P)
• ORD-XXXX-R - Ready for Pickup (e.g., ORD-1005-R)
• ORD-XXXX-C - Cancelled orders (e.g., ORD-1006-C)
• ORD-XXXX-F - Failed/Problem orders (e.g., ORD-1007-F)
• ORD-XXXX-E - Error/Not Found (e.g., ORD-1008-E)
• ORD-XXXX - Pending orders (no suffix, e.g., ORD-1009)

Example Queries

Once connected to Claude Desktop or an MCP client, you can use natural language:

Order Management:

• "Check the status of order ORD-1001-S"
• "Cancel order ORD-1004-P because I found a better price"
• "I want to return my order ORD-1002-D, it didn't fit properly"

Product Information:

• "What's your return policy for electronics?"
• "How much does shipping cost to Canada for a $45 order?"
• "What's the size guide for men's shirts?"
• "Is my laptop still under warranty? I bought it on 2023-06-15"

Account & Payment:

• "My credit card was declined, what should I do?"
• "I forgot my password, how can I reset it?"
• "How does your loyalty program work?"

Product Care:

• "How do I care for my silk dress?"
• "What's the best way to clean leather shoes?"

🏗️ Architecture

┌─────────────────────────────────────┐
│         MCP Clients                 │
│  (Claude Desktop, Web Clients)      │
└──────────────┬──────────────────────┘
               │ MCP Protocol Transport
┌──────────────▼──────────────────────┐
│      Dual MCP Implementation        │
│  • main.py (Gradio MCP Server)      │
│  • main_stdio.py (FastMCP STDIO)    │
├─────────────────────────────────────┤
│  14 MCP Tools:                      │
│  • Order Management (4 tools)       │
│  • Information & Support (4 tools)  │
│  • Product & Service (3 tools)      │
│  • Account & Payment (3 tools)      │
├─────────────────────────────────────┤
│   E-commerce Strategy Layer         │
│  • Mock Strategy (Demo/Testing)     │
│  • Shopify Strategy (Future)        │
│  • Magento Strategy (Future)        │
│  • WooCommerce Strategy (Future)    │
└─────────────────────────────────────┘

🚢 Deployment

Hosted on Hugging Face Spaces

The server is deployed and accessible at:

• Web UI: https://huggingface.co/spaces/SlavPilus/mpc-for-commerce-platforms
• SSE Endpoint: https://huggingface.co/spaces/SlavPilus/mpc-for-commerce-platforms/sse

Manual Deployment

# Build Docker image
docker build -t enneagora .

# Run container
docker run -p 7860:7860 enneagora

Deploy Your Own Instance

1. Fork this repository
2. Set up GitHub secrets:
   • HF_TOKEN: Your Hugging Face token
   • HF_USERNAME: Your Hugging Face username
   • HF_SPACE_NAME: Name for your Space
3. Push to main branch to trigger deployment

🧪 Development

Running Tests

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests with coverage
pytest --cov=mcp_server --cov=main

# Run linting and formatting
pre-commit run --all-files

Project Structure

mcp/
├── main.py                 # Gradio MCP server (mcp_server=True)
├── app.py                  # MCP tools for Gradio registration
├── main_stdio.py          # FastMCP server (STDIO transport for Claude Desktop)
├── mcp_server/            # Core server implementation
│   ├── server.py          # Main server logic
│   ├── mcp_tools.py       # All 14 MCP tool definitions
│   └── strategies/        # E-commerce platform strategies
│       ├── base.py        # Base strategy interface
│       └── mock_strategy.py # Mock data strategy
├── tests/                 # Comprehensive test suite
│   ├── unit/              # Unit tests (96%+ coverage)
│   └── integration/       # Integration tests
├── static/                # Web UI assets
│   └── index.html         # Server info and documentation page
├── requirements.txt       # Python dependencies
├── requirements-dev.txt   # Development dependencies
└── pyproject.toml         # Project configuration

🔧 Configuration

Environment Variables

Currently uses mock data for demonstration. In production, configure:

• ECOMMERCE_PLATFORM: Platform to use (e.g., "shopify", "magento")
• Platform-specific credentials (API keys, endpoints, etc.)

Adding New E-commerce Platforms

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

from .base import EcommerceStrategy

class ShopifyStrategy(EcommerceStrategy):
    async def get_order(self, order_id: str):
        # Implement Shopify API integration
        pass

2. Register the strategy in your configuration
3. Configure credentials and endpoints

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🐛 Troubleshooting

Common Issues

1. Claude Desktop doesn't see the tools

   • Verify the configuration file path and syntax
   • Ensure you're using the full absolute path to main_stdio.py
   • Check that Python environment has all dependencies
   • Restart Claude Desktop after configuration changes

2. Server connection issues

   • Ensure the server is running on the correct port
   • Check firewall settings for local development
   • Verify the SSE endpoint is accessible

3. Import errors or missing dependencies

   • Activate your virtual environment
   • Run pip install -r requirements.txt
   • Ensure Python 3.10+ is installed

Testing Configuration

Test your local setup:

# Test STDIO version
python main_stdio.py

# Test SSE version
python main.py
# Then visit http://localhost:7860

📚 Resources

• Project Repository: https://github.com/slavpilus/mcp
• MCP Documentation: Model Context Protocol
• FastMCP Documentation: FastMCP GitHub
• Hugging Face Spaces: HF Spaces Documentation

🏆 Acknowledgments

Enneagora was built to demonstrate the power of Model Context Protocol for creating comprehensive AI-powered customer support systems as part of the Hugging Face MCP Hackathon. It showcases how MCP can bridge the gap between AI assistants and real-world e-commerce operations.

Key Features Demonstrated:

• Comprehensive tool ecosystem (14 interconnected tools)
• Dynamic mock data with intelligent behavior patterns
• Multi-transport support (SSE + STDIO)
• Production-ready deployment and CI/CD
• Type-safe implementation with 96%+ test coverage