🛒 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? (importante)

• Instalación

• Cobertura por cadena

• Tools disponibles

• Cómo funciona la sesión

• Desarrollo y tests

• Arquitectura

• Cómo contribuir

• Aviso legal

• Licencia

Related MCP server: Superprecio MCP Server

🚫 ¿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

¹ 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:

Lectura de catálogo:

Comparación y diagnóstico:

🔐 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) — 106 tests
npm run test:live # smoke contra los sitios reales (opt-in, LIVE=1)

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.

🏗 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.

📄 Licencia

MIT © contribuidores de mcp-supermercados-cl