# Ecommerce MCP Chatbot

> Skill complet pour construire un chatbot e-commerce basé sur l'architecture MCP (Model Context Protocol) avec trois couches de données : PostgreSQL (Context), MongoDB (Memory), BigQuery (Decision). UTILISER CE SKILL dès que l'utilisateur mentionne : MCP server, MCP client, chatbot e-commerce, orchestrateur MCP, FastMCP, PostgreSQL + MongoDB + BigQuery, architecture multi-base de données IA, MCP Context/Memory/Decision, ou toute demande de code pour ce projet. Couvre : création de serveurs MCP, orchestrateur client, outils (tools), connexions DB async, structure du projet, Docker, tests, et déploiement.

- Skill: `andrisu-mian/ecommerce-mcp-chatbot` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add andrisu-mian/ecommerce-mcp-chatbot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/andrisu-mian/ecommerce-mcp-chatbot/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: andrisu-mian (https://skillmd.com/u/andrisu-mian)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/andrisu-mian/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 :

| Fichier | Contenu |
|---|---|
| `references/01_mcp_servers.md` | Code des 3 serveurs MCP (FastMCP) |
| `references/02_orchestrator.md` | MCP Client orchestrateur + routeur |
| `references/03_databases.md` | Connexions DB async (PG, Mongo, BQ) |
| `references/04_api_chatbot.md` | FastAPI chatbot + interface CLI |
| `references/05_models_config.md` | Pydantic models, .env, pyproject.toml |
| `references/06_docker_infra.md` | Docker Compose + Dockerfiles |
| `references/07_tests.md` | Tests unitaires et d'intégration |
| `references/08_seeding.md` | Scripts de seed des bases de données |

---

## 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
```python
# 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

| Service | Port |
|---|---|
| Chatbot API (FastAPI) | 8000 |
| MCP Context Server (SSE) | 8001 |
| MCP Memory Server (SSE) | 8002 |
| MCP Decision Server (SSE) | 8003 |
| PostgreSQL | 5432 |
| MongoDB | 27017 |

---

## 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)