# Mercadona Skill (MCP) — compra personalizada con Nutri-Score
> **Versión:** 0.1.0 · Licencia MIT · ver [CHANGELOG](CHANGELOG.md)

Servidor MCP para montar pedidos de Mercadona desde lenguaje natural, con
**onboarding de usuarios nuevos (intake)**, **priorización de Nutri-Score** y
ejecución en tu **carrito real supervisada** (nunca paga).

- **Inteligencia** (catálogo, precios, Nutri-Score, alérgenos): APIs públicas de
  solo lectura — Mercadona + Open Food Facts.
- **Carrito**: navegador visible con tu sesión (Playwright sobre tu Chrome/Edge).
- **Pago**: NO existe herramienta de pago. El flujo termina en el carrito; pagas tú.

## Instalación

```bash
pip install -r requirements.txt          # mcp + playwright (usa tu Chrome/Edge)
```

Registra el MCP en Claude Code: copia `.mcp.json` a la raíz de tu proyecto (o usa
`claude mcp add`). Si la ruta relativa `server.py` no resuelve, pon la ruta
absoluta en `args`. Copia `commands/mercadona-pedido.md` a `.claude/commands/`
para tener el comando `/mercadona-pedido`.

## Onboarding (intake)
Un usuario nuevo responde un breve intake (código postal, nº de personas, alergias,
dieta, umbral de Nutri-Score para avisos, marca blanca, ingredientes a evitar). Se
guarda en `profile.json` y personaliza el resto: avisos, alérgenos y precios.

## Herramientas del MCP (`mercadona`)

| Capa | Herramientas |
|------|--------------|
| Intake | `get_profile`, `save_profile` |
| Catálogo | `search_products`, `build_order`, `set_postal_code` |
| Integración | `import_menu` (menú de tu sistema → pedido) |
| Nutri-Score | `nutri_report`, `suggest_healthier` |
| Carrito (navegador) | `open_session`, `add_to_cart`, `add_order_to_cart`, `substitute_in_cart`, `view_cart`, `close_session` |

⛔ Sin `checkout` ni `pay`: por diseño no se puede pagar desde el MCP.

## Integración con tu sistema (menús)
Tu generador de menús (p.ej. dietas diabéticas) alimenta la skill vía `import_menu`:
- **Contrato JSON** (recomendado): `items=[{"id": 30006, "qty": 1, "name": "...", "note": "..."}]`.
- **HTML**: `html_path`/`html` de un menú con tabla `Sección | ID | Producto | Cantidad | …`.

Devuelve los productos con Nutri-Score y avisos, listos para `add_order_to_cart`.
Así tu sistema produce el menú y la skill lo ejecuta en el carrito (supervisado).

## Nutri-Score
Mercadona no publica Nutri-Score; se obtiene cruzando su `ean` con **Open Food
Facts**. La skill **prioriza** el mejor grado entre variantes equivalentes,
**avisa** en el umbral del perfil o peor (`nutri_warnings`) y **propone
alternativas** más sanas (`suggest_healthier`) que puedes aplicar con
`substitute_in_cart`.

## Seguridad y honestidad
- **Nunca paga**: el agente para en el carrito; el cobro lo confirma una persona.
- **Cobertura parcial**: si Open Food Facts no tiene el EAN (muchos Hacendado y
  todo el fresco/peso variable), el grado es `?` = "sin dato". No se asume nada.
- **API no oficial**: Mercadona puede cambiarla sin aviso. Cachea (`catalog.json`)
  y respeta sus Términos. Apta para automatización personal, no producción crítica.
- **Verificación robusta**: el carrito se valida leyendo su estado real, no fiándose
  del clic; reintenta lo que falte; lee siempre desde página válida.

## Ficheros
- `server.py` — el MCP (FastMCP). 14 herramientas.
- `mercadona_api.py` — cliente del catálogo: descarga cacheada + matcher difuso.
- `nutriscore.py` — Nutri-Score + alérgenos vía EAN→Open Food Facts (cacheado).
- `intake.py` — perfil de usuario (onboarding) y umbral de avisos.
- `menu.py` — ingesta de menús de tu sistema (HTML o JSON) → pedido.
- `commands/mercadona-pedido.md` — el comando/skill para Claude Code.
- `requirements.txt`, `.mcp.json`

Ficheros generados en uso (no se distribuyen): `catalog.json`, `nutri_cache.json`,
`profile.json`, `.mcp-chrome-profile/`.