🛒 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

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

💬 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

🏗 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