# leclerc-drive

Serveur [MCP](https://modelcontextprotocol.io) pour faire ses courses sur [Leclerc Drive](https://www.leclercdrive.fr) depuis Claude : recherche avec labels, Nutri-Score et prix au kilo, promotions de la semaine, produits habituels, habitudes d'achat, qualité nutritionnelle d'après Open Food Facts, panier.

Projet indépendant, non affilié à E.Leclerc. Leclerc Drive n'a pas d'API publique : le serveur lit les pages du site, qui peuvent changer sans préavis.

## Fonctionnement

Le serveur pilote un vrai Chrome, avec un profil dédié et un port de débogage, et exécute ses requêtes depuis l'onglet du drive où l'on est connecté. Elles portent donc les cookies et l'empreinte du navigateur. Les requêtes passent une à une, espacées d'au moins 1,2 s.

## Prérequis

- [Bun](https://bun.sh) 1.2 ou plus récent
- Google Chrome
- Un compte Leclerc Drive

## Installation

```bash
git clone https://github.com/vanhovev/leclerc-drive.git
cd leclerc-drive
bun install
claude mcp add leclerc-drive -s user -- bun run "$PWD/src/index.ts"
```

Tout client MCP en stdio convient, avec la commande `bun run /chemin/vers/leclerc-drive/src/index.ts`.

Au premier appel, une fenêtre Chrome s'ouvre : s'y connecter à Leclerc Drive et ouvrir la page de son drive. Le profil Chrome garde la session et le drive détecté est mémorisé.

## Outils

| Outil | Rôle |
| --- | --- |
| `search_products` | Recherche dans le catalogue ; produits habituels marqués HABITUEL et listés en premier ; tri par prix, prix au kilo ou note appliqué par le site |
| `get_promotions` | Promotions en cours : réductions, lots, Tickets E.Leclerc, remises Carte (cache 1 h) |
| `get_usual_products` | Produits achetés habituellement, relus chaque semaine |
| `get_purchase_habits` | Analyse des dernières commandes : rythme, panier moyen, basiques, fréquence et quantité par produit |
| `check_quality` | NOVA, additifs classés par risque, sucres, sel et ingrédients d'après Open Food Facts |
| `get_cart` | Panier, total, économies, prochain créneau de retrait |
| `set_quantity` | Fixe la quantité finale d'un produit (0 = retirer) et renvoie le panier confirmé par le site |
| `remember_preference` | Ajoute une préférence durable au profil |
| `get_status` | Drive détecté, connexion, page ouverte dans la fenêtre Chrome |

Le paiement et la réservation du créneau restent sur le site.

## Profil

`~/.leclerc-drive/profil.md` décrit le foyer, les critères de qualité et la façon de faire les courses, en Markdown libre. Le serveur l'ajoute à ses instructions : l'agent le connaît sans rien charger. Il se modifie à la main ou via `remember_preference`, et les changements valent pour les sessions suivantes.

```markdown
# Profil de courses

## Foyer
- 2 personnes, un drive par semaine.

## Qualité
- Limiter les additifs, en particulier les émulsifiants.
- Le Nutri-Score n'est pas un critère.
```

## Données locales

Tout reste sur la machine, dans `~/.leclerc-drive/` :

| Fichier | Contenu |
| --- | --- |
| `chrome/` | Profil Chrome dédié, avec la session Leclerc Drive |
| `profil.md` | Profil de courses |
| `store.json` | Drive détecté et ses adresses |
| `usual.json` | Produits habituels |
| `history.sqlite` | Commandes passées |
| `quality.sqlite` | Codes-barres et réponses d'Open Food Facts |

`get_purchase_habits` lit l'historique de l'année en cours dans l'espace client, au plus tous les deux jours, et ne télécharge que les commandes absentes de la base.

## Configuration

Variables d'environnement, toutes facultatives :

| Variable | Défaut | Rôle |
| --- | --- | --- |
| `LECLERC_STATE_DIR` | `~/.leclerc-drive` | Dossier des données locales |
| `LECLERC_PROFILE_FILE` | `profil.md` du dossier | Profil de courses |
| `LECLERC_CHROME_PATH` | Chrome selon le système | Exécutable de Chrome |
| `LECLERC_CHROME_PROFILE_DIR` | `chrome/` du dossier | Profil Chrome |
| `LECLERC_CHROME_PORT` | `9222` | Port de débogage |
| `LECLERC_MIN_INTERVAL_MS` | `1200` | Délai minimal entre deux requêtes |
| `LECLERC_JITTER_MS` | `600` | Délai aléatoire ajouté |
| `LECLERC_BACKOFF_BASE_MS` | `2000` | Attente avant de réessayer une requête refusée (403, 429) |
| `LECLERC_REQUEST_TIMEOUT_MS` | `30000` | Durée maximale d'une requête |

Avec Claude Code : `claude mcp add leclerc-drive -s user -e LECLERC_CHROME_PORT=9333 -- bun run "$PWD/src/index.ts"`.

## Sécurité

Tant que la fenêtre Chrome du serveur est ouverte, n'importe quel programme local peut piloter la session Leclerc Drive par le port de débogage. Mieux vaut la fermer en dehors des courses : le serveur la relance au besoin.

## Développement

```bash
bun test
bun run typecheck
```

Les tests tournent sur des pages synthétiques qui reproduisent le balisage du site : aucun compte ni navigateur n'est nécessaire.

`src/quality/additives.json` est généré à partir des taxonomies d'Open Food Facts ([additives.json](https://static.openfoodfacts.org/data/taxonomies/additives.json) et [additives_classes.json](https://static.openfoodfacts.org/data/taxonomies/additives_classes.json)) :

```bash
bun scripts/build-additives.ts additives.json additives_classes.json
```

## Licence

Code sous licence [MIT](LICENSE). `src/quality/additives.json` est dérivé des données d'Open Food Facts, publiées sous licence [ODbL](https://opendatacommons.org/licenses/odbl/1-0/).