Plaza Vea MCP

Servidor MCP local para consultar el catalogo publico de plazaVea mediante las APIs publicas de VTEX. Permite buscar, filtrar, comparar precios, mostrar imagenes dentro de un cliente MCP y generar enlaces para continuar la compra directamente en Plaza Vea.

Incluye un crawler Scrapy opcional que mantiene un cache SQLite y un historial local de precios.

Proyecto independiente, sin afiliacion con Plaza Vea, Compania Food Retail S.A.C. ni VTEX.

Caracteristicas

• Servidor basado exclusivamente en el SDK oficial mcp, usando la API de bajo nivel y stdio.
• Consultas live-first al catalogo VTEX con respaldo en SQLite.
• Extraccion de todos los SKUs y sellers de cada producto.
• Filtros por nombre parcial y marca exacta, tolerantes a mayusculas y acentos.
• Ordenamiento por precio ascendente, descendente o nombre.
• Imagenes PNG como ImageContent para vision del modelo y Markdown para mostrarlas al usuario.
• Enlaces individuales y combinados para agregar productos al carrito.
• Crawler Scrapy respetuoso con robots.txt, AutoThrottle, cache HTTP y reintentos.
• Sin Selenium, credenciales, CAPTCHA ni automatizacion del pago.

Requisitos

• Python 3.12 o 3.13.
• uv.
• Codex CLI o cualquier cliente compatible con MCP por stdio.

Instalacion

git clone https://github.com/jeffreymonjacastro/plaza-vea-mcp.git
cd plaza-vea-mcp
uv sync --all-groups

Para registrar el servidor local en Codex desde este checkout:

codex mcp add plaza-vea -- uv --directory C:\ruta\a\plaza-vea-mcp run plaza-vea-mcp
codex mcp get plaza-vea

Reinicia o abre una nueva tarea de Codex para que las tools aparezcan en la sesion.

Tools

Tool	Descripcion
search_products	Filtra por nombre y marca y ordena por precio o nombre.
get_product	Devuelve todas las variantes, sellers, ofertas e imagenes.
list_brands	Lista marcas activas, opcionalmente por prefijo.
get_product_image	Devuelve ImageContent PNG y el Markdown necesario para mostrar la imagen en la respuesta.
build_cart_links	Valida SKUs y genera enlaces para continuar en Plaza Vea.
start_catalog_refresh	Inicia el crawler local en segundo plano.
get_catalog_refresh_status	Consulta el progreso y resultado del crawler.

Ejemplos de solicitudes naturales en Codex:

Busca productos que contengan "leche" y ordenalos del mas barato al mas caro.
Busca cafe de la marca ALTOMAYO y muestra la imagen del producto mas barato.
Genera un enlace de carrito para dos unidades del SKU 12345.
Actualiza la categoria 814 y dime cuando termine.

Respuestas y precios

Los precios se devuelven como enteros en centimos de sol (price_cents) y con moneda PEN. Cada consulta indica si la fuente es live o cache. Cuando se usa el cache, stale es true.

La version inicial usa el catalogo anonimo del canal de venta 1. Precio, stock, promociones, region y entrega se vuelven a validar al abrir Plaza Vea.

Carrito y pago

build_cart_links no abre el navegador ni modifica directamente el carrito. Devuelve:

• La pagina de cada producto.
• El addToCartLink oficial proporcionado por VTEX para cada SKU.
• Un enlace combinado para varios SKUs.
• La pagina de checkout de Plaza Vea.

El usuario abre el enlace y completa identificacion, entrega y pago en Plaza Vea. Si el enlace combinado deja de ser compatible con la tienda, se pueden abrir los enlaces individuales.

El proyecto nunca solicita ni almacena contrasenas, DNI, direcciones o datos de tarjeta.

Actualizacion del catalogo

Desde MCP, usa start_catalog_refresh. Sin category_id recorre las categorias hoja del arbol publico; con un ID solo actualiza esa categoria. La tool devuelve un run_id que puede consultarse con get_catalog_refresh_status.

Los datos locales se guardan en data/catalog.sqlite3; los logs del crawler quedan en data/logs/. Ambos estan excluidos de Git.

Variables opcionales:

Variable	Uso
PLAZA_VEA_PROJECT_ROOT	Directorio de trabajo del proyecto.
PLAZA_VEA_DATA_DIR	Directorio para base de datos, logs y cache HTTP.
PLAZA_VEA_DATABASE_PATH	Ruta explicita del archivo SQLite.

Desarrollo y validacion

uv sync --all-groups
uv run ruff check src tests scripts
uv run mypy src
uv run pytest
uv run python scripts/smoke_mcp.py

El smoke test inicia el MCP por stdio, consulta productos reales, obtiene una imagen y construye un enlace de carrito. No abre el enlace ni avanza al pago.

Uso responsable

• Respeta los terminos, disponibilidad y politicas publicadas por Plaza Vea.
• No incrementes la concurrencia ni desactives AutoThrottle sin autorizacion.
• No accedas automaticamente a /checkout; esa ruta esta bloqueada en robots.txt.
• No uses este proyecto para evadir CAPTCHA, controles de acceso o limites del sitio.
• Las imagenes y datos comerciales pertenecen a sus respectivos titulares.

Consulta THIRD_PARTY_NOTICES.md para referencias y atribuciones.

Licencia

Codigo publicado bajo licencia MIT. Esta licencia no concede derechos sobre marcas, imagenes ni contenido comercial obtenido de Plaza Vea.