@foolies/mcp

Serveur MCP qui expose l'API de scoring alimentaire Foolies à Claude Desktop, ChatGPT Desktop et Cursor. Scanne un code-barres, obtiens un grade A–E avec les raisons concrètes (huile de palme, sucre > 22.5 g/100 g, additifs à risque, catégorie piège…), trouve des alternatives mieux notées, et consulte les fiches scientifiques d'additifs et de labels.

Backend : API Foolies (Rust/axum), scoring v1.9, ~468 k produits FR. Contrat complet et interactif sur le Swagger de l'API.

Outils exposés

| Outil | Description | Endpoint | |---|---|---| | scan_product(barcode) | Scan code-barres → produit + score (ingère si absent) | POST /v1/scan | | get_product(id_or_ean) | Produit complet + score par UUID ou EAN | GET /v1/products/{id} | | get_alternatives(product_id, limit?, in_source?) | Alternatives mieux notées (UUID ou EAN, résolu auto) | GET /v1/products/{id}/alternatives | | get_additive(code) | Fiche scientifique d'un additif (ADI, EFSA/ANSES, versions) | GET /v1/additives/{code} | | get_label(code) | Fiche label (cahier des charges, autorité, critères) | GET /v1/labels/{code} | | search_products(query?, min_grade?, page?, page_size?) | Recherche full-text + filtre grade | GET /v1/products/search |

Prérequis

• Node.js ≥ 18 (fetch natif).
• Une clé API Foolies. Deux façons :
  • Self-serve (recommandé) — POST sur l'endpoint signup de l'API hébergée :

    curl -X POST https://api.foolies.fr/v1/signup \
      -H "content-type: application/json" -d '{"email":"[email protected]"}'
    # → { "data": { "api_key": "flk_…", "tier": "free", "daily_quota": 500, … } }

    La clé free (30 req/min, 500 appels/jour) n'est affichée qu'une seule fois.
  • Self-hosted — si tu fais tourner ta propre API :

    foolies-api admin create-key --client mcp --rpm 600   # clé illimitée

• L'API Foolies joignable (locale http://127.0.0.1:8080 ou hébergée https://api.foolies.fr).

Configuration (variables d'environnement)

| Variable | Défaut | Description | |---|---|---| | FOOLIES_API_BASE | https://api.foolies.fr | Base URL de l'API (sans slash final). Override pour self-hosted/local | | FOOLIES_API_KEY | (vide) | Clé x-api-key. Sans elle, les appels /v1 renvoient 401 | | FOOLIES_API_TIMEOUT_MS | 15000 | Timeout par requête HTTP (ms) | | FOOLIES_API_RETRIES | 2 | Ré-essais sur erreur transitoire (réseau / 5xx). Les 429 ne sont pas ré-essayés |

Utilisation avec Claude Desktop

Éditer claude_desktop_config.json (macOS : ~/Library/Application Support/Claude/, Windows : %APPDATA%\Claude\) :

{
  "mcpServers": {
    "foolies": {
      "command": "npx",
      "args": ["-y", "@foolies/mcp"],
      "env": {
        "FOOLIES_API_BASE": "https://api.foolies.fr",
        "FOOLIES_API_KEY": "flk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Redémarrer Claude Desktop. Les 6 outils foolies apparaissent. Exemples de prompts : « Scanne le 3017620422003 », « Trouve-moi une meilleure pâte à tartiner », « C'est quoi le E250 ? ».

Cursor : ajouter le même bloc dans ~/.cursor/mcp.json. ChatGPT Desktop : section MCP des réglages.

Développement local

cd mcp
npm install
npm run build           # tsc -> dist/

# Tester avec l'inspecteur officiel MCP
FOOLIES_API_KEY=flk_... npm run inspector

# Ou pointer Claude Desktop sur le build local :
#   "command": "node", "args": ["/chemin/vers/foolies/mcp/dist/index.js"]

Lancement manuel (stdio) :

FOOLIES_API_BASE=http://127.0.0.1:8080 FOOLIES_API_KEY=flk_... node dist/index.js

Publication npm

CI : pousser un tag mcp-vX.Y.Z déclenche .github/workflows/mcp-publish.yml (npm ci && npm run build && npm publish --access public, secret NPM_TOKEN).

# bump version dans package.json, puis :
git tag mcp-v0.1.0 && git push origin mcp-v0.1.0

Le scope @foolies doit exister sur npm et la première publication d'un package scopé requiert --access public (déjà dans le workflow).

Licence

MIT OR Apache-2.0.