# MCP Carrefour

Serveur MCP open-source qui connecte Carrefour Drive a Claude, Cursor, VS Code et tout client MCP.

Recherchez des produits avec les vrais prix, nutriscore et disponibilite. Gerez un panier de courses en langage naturel.

## Fonctionnalites

| Tool | Description |
|---|---|
| `search_products` | Recherche produits avec prix temps reel, nutriscore, bio, promos |
| `get_product_details` | Details d'un produit (nutrition, ingredients) |
| `find_stores` | Magasins/drives par code postal |
| `add_to_cart` | Ajout au panier |
| `view_cart` | Consultation du panier avec total |
| `remove_from_cart` | Suppression du panier |
| `get_promotions` | Promos en cours par categorie |

## Installation

### Prerequis

- Python 3.11+
- `curl_cffi` (bypass Cloudflare)

### Setup

```bash
git clone https://github.com/nicovlr/mcp-carrefour.git
cd mcp-carrefour
pip install mcp httpx curl_cffi
```

### Ajouter a Claude Code

```bash
claude mcp add carrefour -- python3 /chemin/vers/mcp-carrefour/src/server.py
```

### Config JSON (Claude Desktop / Cursor)

```json
{
  "mcpServers": {
    "carrefour": {
      "command": "python3",
      "args": ["/chemin/vers/mcp-carrefour/src/server.py"]
    }
  }
}
```

## Exemples de prompts

```
"Cherche du lait d'avoine bio au meilleur prix"
"Fais-moi une liste de courses pour 2 personnes vegetariennes, 50EUR max"
"Quelles sont les promos sur les fruits ?"
"Ajoute 2kg de carottes et 500g de lentilles a mon panier"
"Compare les prix du lait entre Carrefour Bio et Bjorg"
```

## Comment ca marche

1. **Session** : `curl_cffi` imite un navigateur Chrome pour passer Cloudflare
2. **Scraping SSR** : parse le `routeData` Nuxt (format JSON:API indexe) depuis le HTML
3. **Cache SQLite** : TTL 30min pour eviter le rate limiting
4. **Throttle** : 2s entre chaque requete

### Donnees extraites par produit

- Nom, marque, slug
- Prix, prix/unite (EUR/kg, EUR/L)
- Nutriscore (A-E)
- Label Bio
- Promotions
- Note clients + nombre d'avis
- Code EAN-13
- Image

## Architecture

```
mcp-carrefour/
  src/
    server.py          # Serveur MCP (7 tools)
    api/
      client.py        # Client HTTP Carrefour (curl_cffi + parsing Nuxt)
      models.py        # Product, Store, Cart, CartItem
    cache/
      cache.py         # Cache SQLite
  config/
    config.json        # Configuration utilisateur
```

## Limitations

- Pas d'API publique Carrefour : on parse le HTML SSR (peut casser si Carrefour change son front)
- Rate limiting : le cache et le throttle limitent a ~30 req/min
- Panier local uniquement (pas de sync avec un compte Carrefour)
- Disponibilite produits = catalogue national (pas par magasin sans authentification)

## Licence

MIT