🛒 mcp-supermercados-cl

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

node tests license

El foco es profundidad en la cadena donde tú ya compras — precios club,beneficios por RUT, productos frecuentes, carro — con la comparación entrecadenas 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 tuscredenciales nunca tocan un servidor central.

Tabla de contenidos

¿Se deploya? (importante)
Instalación
Cobertura por cadena
Tools disponibles
Cómo funciona la sesión
Desarrollo y tests
Arquitectura
Cómo contribuir
Aviso legal
Licencia

🚫 ¿Se deploya en Vercel/AWS? No

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

Usa transporte stdio (local), no HTTP. Corre en tu máquina, junto a tucliente MCP (Claude Desktop, Claude Code, Cursor, ChatGPT Desktop).
Unimarc, Tottus y Lider bloquean el tráfico de datacenter (antibots). Undeploy en la nube no funcionaría para esas cadenas: necesitan tu IPresidencial.
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 elmayor riesgo legal (un servicio que scrapee cuentas ajenas).

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

📦 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 loejecuta 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 activacon tu sesión en santaisabel.cl.² Lider no expone precio socio dual como el Prime de Jumbo; sus descuentos sonrebajas directas ("Precio Lider") + bundles.

⚠️ Unimarc, Tottus y Lider requieren IP residencial (tu máquina); desdedatacenter 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`.
`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.
`adapter_status`	Qué cadenas responden ahora y con qué latencia.

🔐 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, eltoken vive en el localStorage del navegador, así que el servidor nunca vecredenciales: el cliente (junto a tu navegador logueado) extrae los datos delDOM o ejecuta las llamadas autenticadas, y el MCP solo normaliza el resultado.

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

🧪 Desarrollo y tests

npm test          # tests de contrato con fixtures reales (sin red) — 106 tests
npm run test:live # smoke contra los sitios reales (opt-in, LIVE=1)

Los tests de contrato usan respuestas reales grabadas entests/fixtures/. Los live requieren red y, paraUnimarc/Tottus/Lider, IP residencial. Regraba una fixture cuando una cadenacambie su formato, anotando la fecha.

🏗 Arquitectura

Un servidor, un adaptador por cadena (src/adapters/). Esquemanormalizado con zod (src/core/types.ts): precio normal y precio socioseparados, precio por unidad normalizado a base canónica.
HTTP a ritmo humano, por tipo de host: los endpoints de API (Constructor.ioy los BFF de Cencosud/Unimarc/Santa Isabel) van a ~350 ms; los sitios que sescrapean por SSR (Tottus, Lider, PDPs www.*) mantienen ~1 s. Reintentos conbackoff, 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 deprogreso MCP (notifications/progress) si el cliente las soporta, para noquedar en silencio durante listas largas. compare_stores limita cada cadenaa 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 endocs/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 lacomunidad. 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 usuarioopera su propia cuenta desde su propia IP, a ritmo humano, sin redistribuirdatos. Revisa los Términos y Condiciones de cada cadena antes de usarla. Noafiliado a Cencosud, SMU, Falabella ni Walmart. Las marcas mencionadaspertenecen a sus respectivos dueños. Úsalo bajo tu propia responsabilidad.

🛒 mcp-supermercados-cl