mcp-supermercados-cl: Instructions file for Claude Code

CLAUDE.md — mcp-supermercados-cl

Servidor MCP en TypeScript para armar la mejor lista de compra en supermercados chilenos. Foco: profundidad en UNA cadena con la sesión y beneficios por RUT del usuario (Jumbo primero), no comparación entre cadenas.

Documentos fuente

• docs/PLAN-arquitectura.md — plan vigente (arquitectura, roadmap por fases, tools). Fuente de verdad.
• docs/PLAN-referencia-endpoints.md — plan anterior orientado a comparación; útil solo como referencia de endpoints.
• docs/captura-cencosud-2026-07-06.md — captura verificada del request de Constructor.io, scoping por sucursal (variations_map), y dónde vive el precio Prime (estado deshidratado del SSR de la PDP).

Estado (actualizar al avanzar)

• Fase 1 completa (2026-07-06): tools search_products, get_product y get_offers funcionando contra Jumbo con tests de contrato (fixtures reales) y smoke live. get_product es la fuente del precio Prime (memberPrice).
• Fase 3 parcial (2026-07-07): build_list y suggest_swaps públicos (ranking por precio por unidad + ofertas, lógica en src/core/listBuilder.ts), adapter_status, cache TTL 15 min en el adaptador (src/core/cache.ts). Falta: priorizar frecuentes (depende de fase 2) y carro.
• Fase 2 (frecuentes + precio Prime) completa (2026-07-07): get_frequent_purchases y get_member_price implementadas. Captura clave: el token de Jumbo vive en localStorage (no solo cookies), así que la sesión se opera desde el navegador del usuario. build_list ahora prioriza frecuentes (matchFrequent en listBuilder). Parser en src/adapters/cencosudSession.ts, puente en src/adapters/session.ts, fixture real en tests/fixtures/frequent-products-2026-07-07.json. Pendiente fase 2: listas guardadas.
• Modelo de sesión: el servidor nunca ve credenciales. El cliente (junto al navegador logueado) entrega las cards del DOM de /productos-frecuentes vía el parámetro cards/frequentCards. Vía de producción para automatizarlo: Playwright con perfil de Chrome (BrowserBridge.fetchAuthedHtml).
• Fase 3 (carro) completa (2026-07-07): add_to_cart y get_cart. Endpoints del BFF verificados con la sesión del usuario: GET /cart?store={branchId}&simulationTotals=true y PATCH /cart/items (body con skuId+quantity+banderas). Parser en src/adapters/cencosudCart.ts, tools en src/tools/cart.ts, fixture real en tests/fixtures/cart-2026-07-07.json. El Cart normalizado expone total, savings y primeSavings (el ahorro socio sale de totals.itemDiscounts.details / simulation.*.discountDetails, clave PRIME_USER). Las tools no ejecutan la llamada (el server no ve el token): arman el request y normalizan el JSON que devuelve el navegador. add_to_cart es reversible; no es compra.
• Fases 5-7 completas (2026-07-07): las cinco cadenas del plan y compare_stores.
  • Unimarc (src/adapters/unimarc.ts): POST bff-unimarc-ecommerce.unimarc.cl/catalog/product/search. Precio socio "Club Unimarc" en priceDetail.promotionalTag.
  • Tottus (src/adapters/tottus.ts): SSR __NEXT_DATA__ de /tottus-cl/buscar?Ntt=. Precios string; internetPrice/normalPrice/pum.
  • Lider (src/adapters/lider.ts): SSR __NEXT_DATA__ de /search?query= (nodos __typename:Product). Bloqueo actualizado 2026-07-08 (issue #2): el sitio bloquea todo cliente HTTP plano —incluso IP residencial— por fingerprint del cliente (TLS/JA3 + PerimeterX + F5 BIG-IP), respondiendo 307 → /blocked; la vía confiable es el puente de navegador (browserHtml en search_products, leyendo __NEXT_DATA__ del DOM, no fetch same-origin).
  • compare_stores (src/core/compare.ts + src/tools/compareStores.ts): total de la lista por cadena, marca la más barata; resultados parciales si una cadena falla.
  • HttpClient ganó postJson (Unimarc). Helpers parseClpString/parseUnitPriceString/normalizeUnit en normalize.ts.
  • Unimarc/Tottus/Lider requieren IP residencial (datacenter bloquea); documentado en docs/captura-otras-cadenas-2026-07-07.md. Fixtures reales en tests/fixtures.
  • Publicación: LICENSE MIT, README de lanzamiento con aviso legal. Server v1.0.0, 10 tools, 72 tests de contrato.
• Tres mejoras completas (2026-07-07):
  1. Listas guardadas de Jumbo: get_saved_lists + adapters/cencosudLists.ts. Endpoints /lists, /lists/{scope}/{idList}. Items con misma forma que carro (precio socio en promotions PRIME_USER). Fixture jumbo-list-2026-07-07.json.
  2. Profundidad no-Jumbo: Santa Isabel ganó get_product con precio socio; su carro usa el addToCart/getCart genérico del CencosudAdapter (mismo BFF). Unimarc/Tottus/Lider: carro con login propio, fase futura.
  3. Detalle de Santa Isabel: pdpStyle:"bff-pdp" → POST bff.santaisabel.cl/catalog/pdp con {slug, store} + headers (apiKey pública be-reg-groceries-sisa-catalog-wdhhq5a2fken, x-client-version 2.3.17). Misma forma de item que Jumbo; mapPdpData compartido. store = sucursal (default "pedrofontova", override con branchId). Fixture santaisabel-pdp.json.
• 12 tools, 80 tests de contrato. Detalle en docs/captura-cencosud-2026-07-06.md §4d.
• Alcance de precios y bloqueo de Líder (2026-07-07): search_products, build_list y compare_stores incluyen priceScope/priceScopeNote en la respuesta (priceScopeInfo en src/core/format.ts): sin branchId los precios son de catálogo nacional y el modelo debe advertir que la sucursal del usuario puede mostrar otro precio (caso real: pisco a $10.913 nacional vs $13.190 en la sucursal del usuario). Líder: PerimeterX a veces no responde 403 sino 307 a /blocked ("Robot or human", sin __NEXT_DATA__), que se confundía con 0 resultados; isLiderBlockedHtml (src/adapters/lider.ts) lo detecta y lanza error blocked accionable. 136 tests.
• Fase 4 (Santa Isabel) — búsqueda habilitada (2026-07-07): registrada con SANTA_ISABEL_CONFIG (host ac.cnstrc.com, key key_c73M3GMIWJ8AcNnd). search_products, build_list y suggest_swaps funcionan para santaisabel con precios y ofertas reales. El CencosudBannerConfig ahora lleva capacidades por banner (offersCollectionId, pdpStyle): get_product y get_offers de Santa Isabel lanzan error claro (su PDP window.__renderData/VTEX y ofertas requieren comuna seleccionada; precios en 0 sin ella). URLs de producto en www.sisa.cl. Fixture: tests/fixtures/santaisabel-search-arroz.json. Pendiente para profundidad completa en SI: parser VTEX con selección de comuna → precio socio y carro.
• Contribución externa: puente de navegador + canasta repartida (2026-07-09, PR #3 de @dmnavalon, cierra #2): (1) search_products acepta browserHtml para Líder y Tottus —el HTML/JSON de __NEXT_DATA__ que el usuario trae de un navegador real que ya pasó el antibot— vía wrapLiderHtml/wrapTottusHtml + mapa BROWSER_BRIDGE (src/tools/searchProducts.ts); sin él y bloqueado, la tool devuelve respuesta accionable (openUrl+browserSnippet+retryWith) en vez de error seco. TottusAdapter.searchProducts ahora soporta el puente igual que Líder. (2) Nueva tool build_cheapest_basket (src/core/cheapestBasket.ts función pura chooseCheapestBasket + src/tools/cheapestBasket.ts): a diferencia de compare_stores (elige UNA cadena para toda la lista), asigna CADA ítem a la cadena más barata (cherry-pick) y agrupa por cadena; expone picks, plan, basketTotal, singleStore, splitSaving, mixedFormatItems, missing. Prompt guiado super_eficiente. 13 tools, 145 tests.
• Puente de navegador automático para Líder/Tottus (2026-07-09): antes el PlaywrightBridge existía pero el server nunca lo instanciaba (puente solo manual, vía browserHtml). Ahora src/adapters/browserBridge.ts lo activa por entorno: getConfiguredBrowserBridge() lee SUPERMERCADOS_PLAYWRIGHT_PROFILE (userDataDir, requerida), SUPERMERCADOS_PLAYWRIGHT_CHANNEL (chrome/msedge) y SUPERMERCADOS_PLAYWRIGHT_HEADLESS; devuelve undefined sin configurar (→ flujo manual intacto). bridgeSession(store, bridge, branchId) antepone el host de la cadena (SSR_HOSTS: lider=super.lider.cl, tottus=www.tottus.cl) al path del adaptador. search_products lo usa como fallback automático cuando bloquea y no vino browserHtml; compareStores acepta el bridge como 5º parámetro (default = getConfiguredBrowserBridge()), así compare_stores y build_cheapest_basket incluyen Líder/Tottus automáticamente si está configurado. PlaywrightBridge.fetchSsrHtml(url) navega con networkidle + espera script[id="__NEXT_DATA__"] (App Router hace streaming self.__next_f; leer antes daría documento sin __NEXT_DATA__ = falso "0 resultados"). Playwright sigue siendo dependencia opcional (import dinámico). Tests con bridge fake inyectado por setBrowserBridgeForTests en tests/adapters/browserBridge.test.ts. Límite conocido: cada búsqueda por Playwright es lenta; con muchos ítems compareStores puede tocar su budget de 25 s/cadena y devolver parcial.
• Fix del puente (v1.4.1, 2026-07-09): al validar el puente contra los sitios reales con Playwright aparecieron tres bugs que lo hacían fallar SIEMPRE (invisibles a los tests con fixtures): (1) el HTML del navegador real trae <script nonce="" id="__NEXT_DATA__" …> con el nonce antes del id, que el marcador literal no matcheaba → Líder se reportaba "bloqueado" con datos presentes. Nuevo helper compartido src/adapters/nextData.ts (extractNextDataJson/hasNextData, regex tolerante a orden de atributos) que usan Líder y Tottus. (2) fetchSsrHtml usaba waitUntil:"networkidle", que nunca se cumple en sitios con analytics/polling → timeout; ahora domcontentloaded. (3) waitForSelector esperaba state:"visible" pero un <script> es invisible → timeout; ahora state:"attached". Verificado real: Líder ~46 productos, Tottus ~48 (Chrome real, channel:"chrome"). 13 tools, 157 tests.
• Carga de Playwright con npx (v1.4.2, 2026-07-09): cuando el server corre por npx (caso Claude Desktop), su node_modules efímero no tiene Playwright aunque esté instalado global. NODE_PATH NO ayuda porque el bridge carga con import() (ESM) y NODE_PATH solo aplica a require() (CommonJS) — verificado empíricamente. loadPlaywright() ahora, si el import("playwright") normal falla, usa createRequire(import.meta.url)(process.env.SUPERMERCADOS_PLAYWRIGHT_PATH) para resolver el paquete global desde su carpeta (npm root -g + /playwright). Config de Claude Desktop verificada (npx + SUPERMERCADOS_PLAYWRIGHT_PATH → Líder 46 productos). Dato del entorno: Claude Desktop lanza el MCP con el npx de nvm (~/.nvm/versions/node/vXX/bin/npx), así que el node global es el de nvm.
• Smoke live sin falsos positivos (v1.4.4, 2026-07-13, cierra #9): el workflow semanal smoke-live.yml corría las 5 cadenas y Tottus/Líder bloquean siempre desde IP de datacenter (GitHub Actions), abriendo un issue de falso positivo cada lunes que enterraba las alertas reales. Ahora el smoke (tests/live/otras-cadenas.live.test.ts) distingue bloqueo antibot (HttpStatusError 401/403/307/429 o Error con mensaje de antibot: PerimeterX/BIG-IP/"blocked") de cambio de formato (fetch 200 pero ProductSchema.parse/aserción falla): el bloqueo se tolera con warning, el cambio de formato rompe el smoke. Jumbo/Santa Isabel/Unimarc (sin bloqueo por IP) se validan de verdad. Nuevo SMOKE_STRICT=1 para runner con IP residencial (reendurece el bloqueo a fallo). Verificado en vivo: normal 7/7 (Tottus/Líder tolerados), estricto 2 failed.