# Leclerc Drive MCP

Serveur MCP et CLI non officiels pour lire le catalogue actuel d’un Drive E.Leclerc dans une session web Camoufox persistante appartenant à l’utilisateur.

Le téléphone ou l’application mobile Leclerc ne sont pas nécessaires. Le site bloque cependant les requêtes HTTP nues : Camoufox est donc le navigateur local réel qui conserve la session et exécute les lectures dans le contexte autorisé de chaque utilisateur.

## Capacités

- `connect_leclerc` : ouvre le Drive configuré et signale une éventuelle connexion humaine ;
- `session_status` : prouve Camoufox, le Drive exact et l’état connecté visible ;
- `search_products` : retourne les produits actuels, leur prix et leur disponibilité dans ce Drive ;
- `get_product` : lit une fiche retournée par la recherche, dans le même catalogue ;
- `get_cart` : lit le panier sans exposer l’identité, l’adresse, le créneau ou le paiement ;
- `add_to_cart` : prévisualise puis ajoute une fiche fraîche après confirmation ;
- `remove_from_cart` : prévisualise puis retire un produit présent après confirmation.

Le MCP ne choisit aucun créneau, ne valide aucune commande et ne réalise aucun paiement.

## Prérequis

- Node.js 22.12 ou supérieur ;
- `camofox-browser` 2.4.6 ou une version compatible ;
- un compte E.Leclerc autorisé par son propriétaire ;
- l’URL exacte du Drive choisi.

Installation de Camoufox :

```bash
npm install --global camofox-browser@2.4.6
```

Créez une clé aléatoire forte dans votre gestionnaire de secrets, puis démarrez le service local avec `CAMOFOX_AUTH_MODE=required` et `CAMOFOX_API_KEY` définis dans son environnement :

```bash
camofox server start --background
```

Ne transmettez jamais cette clé, vos cookies, votre mot de passe, un code 2FA ou un CAPTCHA à un assistant.

## Installation du MCP

```bash
git clone https://github.com/ncleton/leclerc-drive-mcp.git
cd leclerc-drive-mcp
npm ci
npm run build
cp .env.example .env
```

Renseignez localement `.env` :

- `LECLERC_STORE_URL` : URL HTTPS exacte du catalogue ;
- `LECLERC_STORE_CODE` : code magasin à six chiffres présent dans l’URL ;
- `LECLERC_STORE_LABEL` : libellé lisible du Drive ;
- `CAMOFOX_USER_ID` : identifiant unique pour cette personne et ce compte ;
- `CAMOFOX_URL` : normalement `http://127.0.0.1:9377` ;
- `CAMOFOX_AUTH_MODE=required` ;
- `CAMOFOX_API_KEY` : la même clé forte que le service Camoufox.

Les variables AgentVegan équivalentes sont également reconnues pour faciliter une migration, mais le paquet ne dépend d’aucun chemin ni fichier AgentVegan.

## Première connexion

```bash
npm run build
node dist/cli.js connect
```

Camoufox ouvre le Drive dans son profil persistant. Saisissez vous-même vos identifiants et éventuels codes dans la fenêtre du navigateur, puis vérifiez :

```bash
node dist/cli.js status
node dist/cli.js search "tofu" --limit 5
node dist/cli.js cart
```

Une réponse n’est acceptée comme disponibilité que si elle provient du catalogue configuré, contient le prix et les champs de stock attendus, et porte l’heure du contrôle.

Une mutation CLI est toujours prévisualisée. Après vérification du delta, relancez exactement la même commande avec `--confirm` :

```bash
node dist/cli.js add '<product_url retourné par search>' --quantity 1
node dist/cli.js add '<même product_url>' --quantity 1 --confirm
node dist/cli.js remove '<product_id retourné par cart>' --quantity 1
node dist/cli.js remove '<même product_id>' --quantity 1 --confirm
```

Dans MCP, le premier appel à `add_to_cart` ou `remove_from_cart` retourne un jeton expirant après cinq minutes. Le second appel doit reprendre exactement les mêmes paramètres et ce jeton. Toute modification intermédiaire du panier invalide la confirmation.

## Configuration MCP

Exemple recommandé pour un client MCP utilisant directement la release publique `v0.1.1` en `stdio` :

```json
{
  "mcpServers": {
    "leclerc-drive": {
      "command": "npx",
      "args": [
        "-y",
        "--package=github:ncleton/leclerc-drive-mcp#v0.1.1",
        "leclerc-drive-mcp"
      ],
      "env": {
        "LECLERC_STORE_URL": "https://fd8-courses.leclercdrive.fr/magasin-000000-000000-ville.aspx",
        "LECLERC_STORE_CODE": "000000",
        "LECLERC_STORE_LABEL": "Mon Drive",
        "CAMOFOX_USER_ID": "leclerc-drive-personal",
        "CAMOFOX_URL": "http://127.0.0.1:9377",
        "CAMOFOX_AUTH_MODE": "required",
        "CAMOFOX_API_KEY": "référence-vers-votre-secret-local"
      }
    }
  }
}
```

Préférez le gestionnaire de secrets du client MCP à une clé écrite en clair dans sa configuration.

## Limites et erreurs explicites

Camoufox limite par défaut `evaluate-extended` à 20 appels par profil et par minute. Le client sérialise les lectures. Si la limite est atteinte, il renvoie `rate_limited` et le délai de reprise fourni par Camoufox ; il ne bascule jamais vers l’application mobile, un autre compte, un autre Drive ou des données en cache.

Une page de connexion, un CAPTCHA ou une protection anti-robot produit `authentication_required` avec l’action manuelle attendue. Une évolution du contrat Leclerc produit `contract_changed` au lieu d’inventer une réponse.

## Développement et validation

```bash
npm run verify
```

Cette commande exécute le typage, les tests, un échange avec le SDK MCP officiel, l’audit de confidentialité et l’inspection du paquet npm.

## Statut juridique

Projet non officiel, sans affiliation ni approbation d’E.Leclerc. L’utilisateur reste responsable de respecter les conditions du service et de n’utiliser que son propre compte et ses propres sessions.