Ecommerce MCP Chatbot

🛍️ E-Commerce Chatbot MCP — Skill Guide

Vue d'ensemble de l'architecture

Utilisateur
    │
    ▼
FastAPI (chatbot REST API)
    │
    ▼
MCP Client Orchestrateur  ◄──── Claude claude-sonnet-4-6 (Anthropic SDK)
    │       (mcp SDK)
    ├── SSE ──► MCP Context Server  (FastMCP + SQLAlchemy + asyncpg → PostgreSQL)
    ├── SSE ──► MCP Memory Server   (FastMCP + Motor + Beanie → MongoDB)
    └── SSE ──► MCP Decision Server (FastMCP + google-cloud-bigquery → BigQuery)

Structure du Projet

ecommerce-chatbot-mcp/
├── README.md
├── .env
├── pyproject.toml
├── requirements.txt
│
├── chatbot/
│   ├── __init__.py
│   ├── main.py
│   └── interface/
│       ├── cli.py
│       └── api.py
│
├── mcp_orchestrator/
│   ├── __init__.py
│   ├── client.py
│   ├── router.py
│   ├── prompt_builder.py
│   └── response_aggregator.py
│
├── mcp_servers/
│   ├── context_server/       # 🟥 PostgreSQL
│   │   ├── server.py
│   │   ├── tools/
│   │   │   ├── orders.py
│   │   │   ├── customers.py
│   │   │   └── transactions.py
│   │   └── db/
│   │       ├── connection.py
│   │       └── models.py
│   │
│   ├── memory_server/        # 🟦 MongoDB
│   │   ├── server.py
│   │   ├── tools/
│   │   │   ├── products.py
│   │   │   ├── reviews.py
│   │   │   └── inventory.py
│   │   └── db/
│   │       └── connection.py
│   │
│   └── decision_server/      # 🟩 BigQuery
│       ├── server.py
│       ├── tools/
│       │   ├── forecasting.py
│       │   ├── trends.py
│       │   └── kpis.py
│       └── db/
│           └── connection.py
│
├── shared/
│   ├── models/
│   │   ├── chat.py
│   │   └── responses.py
│   ├── logging.py
│   └── exceptions.py
│
├── tests/
│   ├── unit/
│   └── integration/
│
├── infrastructure/
│   └── docker/
│       ├── docker-compose.yml
│       └── Dockerfile.*
│
└── scripts/
    ├── seed_postgres.py
    ├── seed_mongodb.py
    └── init_bigquery.py

Références détaillées

Pour la génération de code, consulter les fichiers de référence suivants :

Règles fondamentales

1. Toujours utiliser async/await

Tous les handlers FastMCP et les accès DB doivent être async. Ne jamais bloquer la boucle d'événements.

2. Transport MCP = SSE en production

• Développement local → stdio (plus simple)
• Production / Docker → sse (chaque serveur sur son propre port)

3. Pydantic v2 partout

• BaseModel pour tous les schemas d'entrée/sortie des tools
• model_validator pour la validation croisée
• Field(description=...) obligatoire sur chaque champ (utilisé par le LLM)

4. Gestion des erreurs dans les tools MCP

# Pattern standard pour un tool MCP
@mcp.tool()
async def get_order(order_id: str) -> dict:
    """Récupère les détails d'une commande par son ID."""
    try:
        result = await db.fetch_order(order_id)
        if not result:
            return {"error": f"Commande {order_id} introuvable", "found": False}
        return {"data": result, "found": True}
    except Exception as e:
        logger.error(f"get_order error: {e}")
        return {"error": str(e), "found": False}

5. Variables d'environnement

Toujours utiliser pydantic-settings avec un fichier .env. Ne jamais hardcoder les credentials.

Ports par défaut

Workflow de génération de code

Quand l'utilisateur demande du code pour ce projet, suivre cet ordre :

1. Lire le fichier de référence pertinent dans references/
2. Générer le code en respectant les patterns définis
3. Vérifier : async/await, gestion d'erreur, pydantic v2, variables d'env
4. Proposer les fichiers adjacents nécessaires (models, config, tests)