E-commerce MongoDB MCP Server
A modern Model Context Protocol (MCP) server that integrates with e-commerce platforms, enabling shop owners to query their business data using natural language. Built with MongoDB Atlas, clean architecture, and async Python.
🚀 Overview
This project provides a scalable, cloud-native solution for e-commerce platforms to offer AI-powered data queries. The server uses MongoDB Atlas for flexible data storage and supports multiple local AI models (Llama 3, Mistral, Phi-3) to process natural language queries.
🏗️ Modern Architecture
- MongoDB Atlas: Cloud-native document database with connection pooling
- AsyncMongoClient: Modern async database operations
- Clean Architecture: Separated concerns and dependency injection
- UUID Primary Keys: Scalable, database-agnostic document IDs
- Type-Safe Models: Pydantic validation with full async support
Key Features
- Natural Language Queries: Shop owners can ask questions about their business data in plain English
- Local AI Processing: All AI inference happens locally for data privacy and cost efficiency
- Multi-Model Support: Dynamic selection between Llama 3, Mistral, and Phi-3 based on query complexity
- Secure Data Access: Role-based permissions with secure authentication integration
- Real-time Responses: Low-latency query processing for seamless user experience
- Comprehensive Tools: Built-in tools for sales reports, inventory checks, customer analytics, and order management
Target Users
- E-commerce platform shop owners
- Platform administrators
- Customer support teams
Architecture
Core Components
- MCP Server Core: Central request processing hub with FastAPI
- Model Management System: Dynamic AI model lifecycle management
- Tool Registry: Extensible data operation definitions
- Data Access Layer: Secure database interface with permission enforcement
- Integration Layer: Platform authentication and API gateway
Technology Stack
- Backend: Python, FastAPI, SQLAlchemy
- AI Inference: llama.cpp, Ollama, CUDA
- Database: PostgreSQL
- Caching: Redis
- Authentication: JWT integration with existing platform
Performance Targets
- Simple queries: < 3 seconds response time
- Complex queries: < 10 seconds response time
- System uptime: > 99.5%
- Concurrent users: 10+ without degradation
- Query accuracy: 90%+ for data retrieval
Development Phases
Phase 1: Foundation Setup (Weeks 1-2)
- Infrastructure preparation with GPU support
- MCP server core implementation
- Security framework establishment
Phase 2: Core Functionality (Weeks 3-5)
- Model management system
- Tool registry development
- Query processing pipeline
Phase 3: Integration & Testing (Weeks 6-7)
- API integration with chat UI
- Comprehensive testing suite
- Performance optimization
Phase 4: Deployment & Documentation (Week 8)
- Production deployment
- Documentation and training
- Operational handover
Security Features
- Token-based authentication validation
- Role-based access control
- Input sanitization and injection prevention
- Comprehensive audit logging
- Local data processing (no external API calls)
- Encrypted data transmission
Quick Start
Prerequisites
- Python 3.9+
- CUDA-capable GPU (recommended)
- PostgreSQL database
- Redis server
- Access to e-commerce platform database
Installation
# Clone the repository
git clone <repository-url>
cd test
# Install dependencies
pip install -r requirements.txt
# Configure environment
cp .env.example .env
# Edit .env with your database credentials and API keys
# Initialize database
python scripts/init_db.py
# Download AI models
python scripts/download_models.py
# Start the server
python main.py
Configuration
Edit the .env file with your specific configuration:
DATABASE_URL=postgresql://user:password@localhost/ecommerce_db
REDIS_URL=redis://localhost:6379
PLATFORM_AUTH_URL=https://your-platform.com/auth
GPU_MEMORY_LIMIT=8192
MODEL_CACHE_DIR=./models
Usage Examples
Basic Queries
- "What were my sales last week?"
- "Show me low inventory items"
- "How many orders are pending?"
- "Which products are my top sellers this month?"
Advanced Analytics
- "Compare this month's revenue to last month"
- "Show customer acquisition trends"
- "Analyze seasonal sales patterns"
- "Generate inventory turnover report"
API Endpoints
Chat Interface
POST /chat/query- Process natural language queryGET /chat/history/{session_id}- Retrieve conversation historyPOST /chat/session- Create new chat session
Model Management
GET /models/status- Check model availabilityPOST /models/load/{model_name}- Load specific modelDELETE /models/unload/{model_name}- Unload model
Tools
GET /tools/list- Available data toolsPOST /tools/execute- Execute specific tool
Available Tools
- Sales Analytics: Revenue reports, trend analysis, period comparisons
- Inventory Management: Stock levels, low inventory alerts, reorder suggestions
- Customer Insights: Customer analytics, segmentation, behavior patterns
- Order Management: Order status, fulfillment tracking, shipping analytics
- Product Performance: Best sellers, product analytics, category insights
Monitoring and Maintenance
Health Checks
GET /health- System health statusGET /metrics- Performance metricsGET /models/health- AI model status
Logging
- Application logs:
logs/app.log - Query logs:
logs/queries.log - Security audit:
logs/security.log
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/new-feature) - Commit your changes (
git commit -am 'Add new feature') - Push to the branch (
git push origin feature/new-feature) - Create a Pull Request
Testing
# Run unit tests
pytest tests/unit/
# Run integration tests
pytest tests/integration/
# Run performance tests
pytest tests/performance/
# Generate coverage report
pytest --cov=src tests/
Deployment
Production Deployment
- Set up production environment with GPU support
- Configure secure database connections
- Set up SSL certificates
- Configure monitoring and alerting
- Deploy using Docker or direct installation
Docker Deployment
# Build the image
docker build -t ecommerce-mcp-server .
# Run the container
docker run -d \
--gpus all \
-p 8000:8000 \
-v ./data:/app/data \
-v ./models:/app/models \
--env-file .env \
ecommerce-mcp-server
Support
For technical issues and feature requests, please:
- Check the documentation
- Search existing issues
- Create a new issue with detailed description
- Contact the development team
License
This project is licensed under the MIT License - see the LICENSE file for details.
Changelog
See CHANGELOG.md for version history and updates.