mcp-supermercados-cl

v1.4.4

Published

13 hours ago

Servidor MCP para buscar productos, comparar precios y armar la mejor lista de compra en supermercados chilenos (Jumbo, Santa Isabel, Unimarc, Tottus, Lider) desde Claude o ChatGPT.

0High
0Medium
0Low

nlace

mcp model-context-protocol claude supermercado chile jumbo unimarc lider tottus santa-isabel precios shopping-list

🛒 mcp-supermercados-cl

Servidor MCP para buscar productos, comparar precios y armar la mejor lista de compra en supermercados chilenos con Claude, ChatGPT u otro cliente MCP.

El foco es profundidad en la cadena donde tú ya compras — precios club, beneficios por RUT, productos frecuentes, carro — con la comparación entre cadenas como capacidad secundaria. Cubre las cinco grandes cadenas del país.

100 % local: el tráfico sale de tu máquina, a ritmo humano, y tus credenciales nunca tocan un servidor central.

Tabla de contenidos

🚫 ¿Se deploya en Vercel/AWS? No

Este MCP no tiene URL de producción y no se deploya en ningún servidor. Es intencional, y es la razón por la que funciona:

Usa transporte stdio (local), no HTTP. Corre en tu máquina, junto a tu cliente MCP (Claude Desktop, Claude Code, Cursor, ChatGPT Desktop).
Unimarc, Tottus y Lider bloquean el tráfico de datacenter (antibots). Un deploy en la nube no funcionaría para esas cadenas: necesitan tu IP residencial.
El precio socio, tus frecuentes y el carro viven en tu navegador logueado. Las credenciales no deben tocar un servidor central — eso además evita el mayor riesgo legal (un servicio que scrapee cuentas ajenas).

La forma de "producción" de un MCP como este es instalarlo local (vía npx o clonando el repo) y conectarlo a tu cliente. Igual que la mayoría de los MCP servers.

📦 Instalación

Requiere Node.js ≥ 20. Publicado en npm: mcp-supermercados-cl.

Opción 1 — vía npx (recomendada). No instalas nada; tu cliente MCP lo ejecuta al vuelo. En Claude Desktop / Claude Code (claude_desktop_config.json o .mcp.json):

{
  "mcpServers": {
    "supermercados": {
      "command": "npx",
      "args": ["-y", "mcp-supermercados-cl"]
    }
  }
}

Opción 2 — desde el código (para desarrollar o contribuir):

git clone https://github.com/NLACE-COM/mcp-supermercados-cl.git
cd mcp-supermercados-cl
npm install
npm run build

Y apunta tu cliente al build local:

{
  "mcpServers": {
    "supermercados": {
      "command": "node",
      "args": ["/ruta/absoluta/al/repo/dist/index.js"]
    }
  }
}

Para desarrollo rápido:

npm run dev        # servidor por stdio con tsx
npm run inspector  # abre el MCP Inspector

🏬 Cobertura por cadena

| Cadena | Plataforma | Búsqueda | Precio socio | Detalle | Sesión / carro | | ---------------- | ------------------------- | :------: | :-------------: | :-----: | :--------------------------: | | Jumbo | Cencosud (Constructor.io) | ✅ | ✅ Prime | ✅ | ✅ frecuentes, listas, carro | | Santa Isabel | Cencosud (Constructor.io) | ✅ | ✅ | ✅ | carro Cencosud¹ | | Unimarc | VTEX (BFF propio) | ✅ | ✅ Club Unimarc | — | — | | Tottus | Falabella (Next.js SSR) | ✅ | — | — | — | | Lider | Walmart Glass (SSR) | ✅ | —² | — | — |

¹ El carro de Santa Isabel reutiliza el mismo BFF Cencosud que Jumbo; se activa con tu sesión en santaisabel.cl. ² Lider no expone precio socio dual como el Prime de Jumbo; sus descuentos son rebajas directas ("Precio Lider") + bundles.

⚠️ Unimarc, Tottus y Lider requieren IP residencial (tu máquina); desde datacenter bloquean. Como el MCP corre local, en tu equipo funcionan.

Todos los resultados vienen enriquecidos: nombre, marca, descripción, foto, precio vigente, precio normal, precio socio, precio por unidad normalizado (por kg/lt para comparar formatos) y bundles ("2 x $2.000", "Lleva 8 por $X").

🧰 Tools disponibles

Núcleo — armar la mejor lista con tu sesión:

| Tool | Qué hace | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | build_list | Convierte una lista en lenguaje natural en productos concretos. Prioriza tus frecuentes, mejor precio por unidad y ofertas. Flags onlyOffers / onlyInStock y maxBudget (ajusta a alternativas más baratas para caber). Incluye resumen formateado. | | suggest_swaps | Reemplazos convenientes por precio por unidad. Con preferNatural: alternativas de precio similar con menos ingredientes. | | get_frequent_purchases | Tus productos habituales, con precio Prime (requiere sesión). | | get_saved_lists | Tus listas guardadas (requiere sesión). | | add_to_cart / get_cart | Deja la lista en el carro de Jumbo; total, ahorro y ahorro Prime. |

Lectura de catálogo:

| Tool | Qué hace | | -------------------- | ----------------------------------------------------------------------------------------------------------- | | search_products | Busca en cualquier cadena. Filtros maxPrice/minPrice/inStockOnly, orden sortBy (price / unitPrice). | | get_product | Detalle por URL/slug: precio socio, EAN, ingredientes y sellos nutricionales. | | get_offers | Ofertas vigentes de Jumbo; primeOnly, filtro por categoría. | | find_opportunities | Mayores descuentos con stock, ordenados por discountPct. excludeIds para destacar lo que no tienes. |

Comparación y diagnóstico:

| Tool | Qué hace | | ----------------- | --------------------------------------------------------------------------------------------------- | | compare_stores | Total de una lista en varias cadenas; marca la más barata y advierte si compara formatos distintos. | | discover_branch | Descubre tu sucursal (branchId) leyéndola del navegador, para no pedírtela a mano. | | adapter_status | Qué cadenas responden ahora y con qué latencia. |

💬 Prompts guiados

Para no adivinar qué pedir, el servidor expone plantillas que tu cliente MCP muestra como sugerencias: armar_lista (con presupuesto opcional), conectar_sesion, comparar_carro y ofertas_frecuentes. El servidor además trae instructions para que el modelo te guíe en el primer uso (qué cadena, cuándo pedir sesión, cómo leer los errores).

Los errores vienen accionables: cada uno trae un campo action con el siguiente paso concreto (re-loguearte, reintentar, usar IP residencial…) en vez de un mensaje técnico.

🔐 Cómo funciona la sesión (sin credenciales en el servidor)

El precio socio, los frecuentes y el carro viven detrás del login. En Jumbo, el token vive en el localStorage del navegador, así que el servidor nunca ve credenciales: el cliente (junto a tu navegador logueado) extrae los datos del DOM o ejecuta las llamadas autenticadas, y el MCP solo normaliza el resultado.

Ver src/adapters/session.ts y docs/captura-cencosud-2026-07-06.md.

¿Y esas API keys que aparecen en el código?

Verás claves como key_JopvNXKS61kwGkBe (Jumbo) o be-reg-groceries-sisa-catalog-wdhhq5a2fken (Santa Isabel) en los adaptadores. No son secretos. Son las claves públicas del frontend de Constructor.io y del BFF de catálogo: van embebidas en el JavaScript de jumbo.cl y santaisabel.cl, y son visibles en las DevTools de cualquier visitante. Solo identifican el índice de búsqueda del lado cliente — no dan acceso a ninguna cuenta ni permiten escribir. Sin ellas, el buscador no responde.

Los datos que sí son sensibles (token de sesión, precio socio, carro) viven en tu navegador logueado y nunca están en este repositorio. Un escáner automático puede marcar estas claves públicas como "token expuesto"; es un falso positivo.

🧪 Desarrollo y tests

npm test           # tests de contrato con fixtures reales (sin red) — 132 tests
npm run test:live  # smoke contra los sitios reales (opt-in, LIVE=1)
npm run typecheck  # tsc --noEmit
npm run lint       # ESLint
npm run format     # Prettier (--write); format:check para verificar

Los tests de contrato usan respuestas reales grabadas en tests/fixtures/. Los live requieren red y, para Unimarc/Tottus/Lider, IP residencial. Regraba una fixture cuando una cadena cambie su formato, anotando la fecha.

Cada push y PR corre lint + typecheck + build + test en CI (GitHub Actions, Node 20 y 22). Un smoke live semanal avisa por issue si una cadena cambia su formato. Para contribuir, revisa CONTRIBUTING.md.

Flujo de sesión: manual o automatizado

Las tools que requieren sesión (get_cart, get_frequent_purchases, get_saved_lists, add_to_cart) devuelven un browserSnippet: un fetch de una sola llamada para ejecutar en una pestaña ya logueada del sitio. Pasas el JSON de vuelta y la tool lo normaliza — el servidor nunca ve tu token.

Para automatizarlo (sin copiar/pegar), existe un puente opcional con Playwright (src/adapters/playwrightBridge.ts) que reusa el perfil de Chrome donde ya tienes la sesión. Playwright no viene con el paquete (es pesado); instálalo aparte si lo quieres:

npm install playwright
npx playwright install chromium

Líder y Tottus: puente automático contra el antibot

Líder y Tottus bloquean el fetch del servidor por fingerprint del cliente (TLS/JA3 + desafío JS de PerimeterX; en Líder además F5 BIG-IP con 307 → /blocked). No es tu IP: la misma IP en un navegador real carga los datos (issue #2). Hay dos formas de sortearlo en search_products, compare_stores y build_cheapest_basket:

Manual: search_products devuelve openUrl + browserSnippet; abres esa búsqueda en tu navegador, ejecutas el snippet (lee __NEXT_DATA__ del DOM) y reintentas pasando el resultado en browserHtml.
Automático: si configuras el puente Playwright por entorno, el servidor navega solo reusando tu perfil de Chrome (nunca ve tu token) y resuelve esas cadenas sin intervención. Variables (en la sección env de tu cliente MCP):
| Variable | Requerida | Descripción | | ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | SUPERMERCADOS_PLAYWRIGHT_PROFILE | sí | Carpeta del perfil de Chrome con tu sesión (userDataDir). Activa el puente. | | SUPERMERCADOS_PLAYWRIGHT_PATH | con npx | Carpeta del paquete playwright cuando está instalado global (por npx el server no lo resuelve solo). Valor: salida de npm root -g + /playwright. | | SUPERMERCADOS_PLAYWRIGHT_CHANNEL | no | chrome o msedge para usar el navegador instalado (si no, el Chromium de Playwright). | | SUPERMERCADOS_PLAYWRIGHT_HEADLESS | no | 1 para headless (por defecto con ventana, evita gatillar antibots/2FA). |
Requiere Playwright instalado y Chrome cerrado (para no chocar con el lock del perfil). Sin estas variables, el comportamiento es el manual de arriba.
Con npx (Claude Desktop, etc.): el paquete corre en un cache efímero sin Playwright, así que instálalo global (npm install -g playwright) y apunta SUPERMERCADOS_PLAYWRIGHT_PATH a su carpeta. NODE_PATH no sirve: el server carga Playwright con import() (ESM) y NODE_PATH solo aplica a require() de CommonJS.
```
{
  "mcpServers": {
    "supermercados-cl": {
      "command": "npx",
      "args": ["-y", "mcp-supermercados-cl@latest"],
      "env": {
        "SUPERMERCADOS_PLAYWRIGHT_PROFILE": "/Users/tu-usuario/Library/Application Support/Google/Chrome",
        "SUPERMERCADOS_PLAYWRIGHT_PATH": "/ruta/de/npm-root-g/playwright",
        "SUPERMERCADOS_PLAYWRIGHT_CHANNEL": "chrome"
      }
    }
  }
}
```

🏗 Arquitectura

Un servidor, un adaptador por cadena (src/adapters/). Esquema normalizado con zod (src/core/types.ts): precio normal y precio socio separados, precio por unidad normalizado a base canónica.
HTTP a ritmo humano, por tipo de host: los endpoints de API (Constructor.io y los BFF de Cencosud/Unimarc/Santa Isabel) van a ~350 ms; los sitios que se scrapean por SSR (Tottus, Lider, PDPs www.*) mantienen ~1 s. Reintentos con backoff, user-agent realista (src/http/client.ts). Cache TTL 15 min. Ajustable por entorno: SUPERMERCADOS_MIN_DELAY_MS, SUPERMERCADOS_FAST_DELAY_MS, SUPERMERCADOS_TIMEOUT_MS, SUPERMERCADOS_MAX_RETRIES.
Feedback en vivo: build_list y compare_stores emiten notificaciones de progreso MCP (notifications/progress) si el cliente las soporta, para no quedar en silencio durante listas largas. compare_stores limita cada cadena a 25 s y devuelve resultado parcial en vez de bloquear a las demás.
Adaptadores aislados: un cambio de sitio rompe un adaptador, no todo.
Endpoints documentados en docs/ y en docs/PLAN-arquitectura.md.

src/
├── index.ts            # entrada MCP (stdio)
├── server.ts           # registro de tools
├── core/               # types, registry, normalize, listBuilder, compare, ...
├── adapters/           # cencosud (Jumbo+Santa Isabel), unimarc, tottus, lider
├── tools/              # una tool MCP por archivo
└── http/               # cliente HTTP con rate limit y reintentos

🤝 Cómo contribuir

¡Bienvenidas las contribuciones! Este proyecto está pensado para crecer con la comunidad. Ver CONTRIBUTING.md.

Ideas de alto impacto:

Carro/sesión en Unimarc, Tottus y Lider (cada una con su login propio).
Detalle (get_product) para Unimarc/Tottus/Lider.
Nuevas cadenas o farmacias.
Mantener las fixtures al día cuando una cadena cambie su API.

Cuando una cadena cambie su formato, npm run test:live lo detecta.

⚖️ Aviso legal

Herramienta personal, de código abierto, sin backend central. Cada usuario opera su propia cuenta desde su propia IP, a ritmo humano, sin redistribuir datos. Revisa los Términos y Condiciones de cada cadena antes de usarla. No afiliado a Cencosud, SMU, Falabella ni Walmart. Las marcas mencionadas pertenecen a sus respectivos dueños. Úsalo bajo tu propia responsabilidad.