mcp-yango-retail

Yango Tech Retail MCP

Español | Русский

A1 Yango Tech Retail MCP conecta una aplicación de IA con una cuenta de comercio en Yango Tech Retail. Usa lenguaje natural para consultar tiendas, pedidos, productos, precios y existencias, o para crear pedidos y actualizar datos de la cuenta cuando sea necesario.

El servidor funciona con la API B2B orientada al comercio para el retail de comestibles y darkstores. No es un portal de vendedores de marketplace, ni un servicio de taxi ni Yango Delivery.

• 16 herramientas. Nueve herramientas de solo lectura, cinco de escritura y dos potencialmente destructivas cubren tiendas, catálogo, precios, existencias, pedidos y recibos.
• Un inicio seguro de solo lectura. Verifica los datos conectados antes de cambiar cualquier cosa en la cuenta.
• Límites claros de escritura. La creación y cancelación de pedidos, las actualizaciones de productos, los cambios de precios, la creación de descuentos y las actualizaciones de existencias están separados de las lecturas.
• Cobertura adicional de la API. Los usuarios técnicos pueden acceder a métodos sin una herramienta dedicada a través de raw_request.

Comienza con:

Lista nuestras tiendas y muestra las existencias del producto [product ID] en cada una.

Conectar el servidor · Explorar casos de uso · Abrir documentación técnica

Véalo funcionar en un minuto

Usted: Lista nuestras tiendas y muestra las existencias del producto [product ID] en cada una.

Asistente: Devolveré las tiendas, sus ids y las existencias actuales de este producto en cada una.

Usted: Muestra el precio de este producto en cada lista de precios.

Asistente: Devolveré las listas de precios y el precio actual del producto en cada una. No se cambiará ningún dato de la cuenta.

Usted: Cambia el precio a 99.90 en la lista de precios [price-list ID].

Asistente: Esto cambiará un precio real visible para el cliente. Mostraré el producto, la lista de precios, el valor actual y el nuevo valor antes de pedir confirmación.

Usted: Confirmo.

Asistente: El precio ha sido actualizado. Leeré la lista de precios nuevamente y devolveré el valor actual.

Las tiendas, productos, precios, existencias y estados de pedidos siempre provienen de la cuenta de comercio conectada y de la respuesta actual de la API.

Contenido

• Inicio rápido
• Qué puede pedirle que haga
• Cómo se conectan los datos de retail
• Qué cambia en la cuenta
• Cómo obtener acceso
• Configuración
• Datos y telemetría
• Límites y trabajo en segundo plano
• Documentación técnica
• Soporte

Inicio rápido

Necesita Node.js 20+, una cuenta de Yango Tech Retail y un token Bearer de comercio.

1. Obtenga un token de su gerente de integración de Yango Tech.

2. Agregue el servidor a su aplicación de IA usando una de las instrucciones a continuación.

3. Comience con una solicitud de solo lectura:

   Lista nuestras tiendas y muestra las existencias del producto [product ID] en cada una.

codex mcp add yango-retail \
  --env YANGO_RETAIL_TOKEN=your_token \
  -- npx -y mcp-yango-retail@latest

codex mcp list

claude mcp add \
  --env YANGO_RETAIL_TOKEN=your_token \
  --transport stdio \
  --scope user \
  yango-retail \
  -- npx -y mcp-yango-retail@latest

claude mcp list

{
  "mcpServers": {
    "yango-retail": {
      "command": "npx",
      "args": ["-y", "mcp-yango-retail@latest"],
      "env": {
        "YANGO_RETAIL_TOKEN": "your_token"
      }
    }
  }
}

{
  "mcpServers": {
    "yango-retail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yango-retail@latest"],
      "env": {
        "YANGO_RETAIL_TOKEN": "your_token"
      }
    }
  }
}

{
  "servers": {
    "yango-retail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yango-retail@latest"],
      "env": {
        "YANGO_RETAIL_TOKEN": "${input:yango_retail_token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "yango_retail_token",
      "description": "Yango Tech Retail Bearer token",
      "password": true
    }
  ]
}

Qué puede pedirle que haga

Consultar tiendas y el catálogo de productos

• Liste tiendas con sus ids, estado, ubicación, dirección y nombre cuando estén disponibles.
• Explore productos por cursor e inspeccione su estado, categoría, nombres localizados, códigos de barras y atributos personalizados.
• Cree o actualice hasta 100 productos en una sola solicitud. Los registros de productos se actualizan mediante upsert en lugar de agregarse como duplicados.

Consultar y actualizar precios

• Liste listas de precios y lea precios de productos de una o más listas.
• Compare el mismo producto entre listas de precios.
• Establezca hasta 100 precios en una sola solicitud usando cadenas decimales como "150.00".
• Cree hasta 100 descuentos específicos por tienda después de confirmar la estructura de campos esperada con Yango Tech.

Consultar y actualizar existencias

• Lea existencias en todas las tiendas, incluidos el producto, la cantidad y el tipo de estante.
• Actualice hasta 1,000 líneas de existencias para una tienda.
• Use initialize para la primera carga de existencias y modify para actualizaciones regulares.

Trabajar con pedidos y recibos

• Cree un pedido después de recopilar su tienda, productos, cantidades, precios, detalles de entrega y tipo de pago.
• Lea los detalles del pedido y verifique los estados actuales de varios pedidos a la vez.
• Siga el flujo de eventos de pedidos para nuevos pedidos, cambios de estado y recibos emitidos.
• Lea un recibo fiscal por id de pedido o id de recibo.
• Cancele un pedido después de verificar su estado actual y el motivo de cancelación.

Usar métodos adicionales de la API

raw_request cubre /b2b/v1/* métodos sin una herramienta dedicada, incluidas actualizaciones de pedidos, datos de IVA, enlaces de listas de precios, picking, logística y operaciones de entrega 3PL. Puede cambiar datos reales de la cuenta y está destinado a usuarios técnicos que comprenden la API upstream.

Los esquemas completos, los campos de respuesta y las brechas de la API están disponibles en la referencia de herramientas.

Cómo se conectan los datos de retail

Los flujos usan paginación por cursor. Una página con menos elementos que el límite solicitado significa que el flujo actual de productos, listas de precios o existencias está agotado. El flujo de eventos de pedidos es continuo: conserve su último cursor y solicite la siguiente página más tarde.

Qué cambia en la cuenta

El servidor expone anotaciones MCP para acciones de solo lectura, escritura y destructivas. El cliente de IA decide cuándo y cómo pedir confirmación.

Antes de una escritura, pida al asistente que muestre la tienda objetivo, los ids de productos, la lista de precios, las cantidades, los valores actuales y los valores propuestos. Las respuestas de escritura no están completamente documentadas upstream, por lo que después de una actualización exitosa de precio o existencias, el servidor puede leer los datos correspondientes nuevamente y mostrar el valor actual.

Cómo obtener acceso

Yango Tech emite un token Bearer para una cuenta de comercio a través de un gerente de integración. Este repositorio no describe un portal de tokens de autoservicio.

1. Contacte a su gerente de integración de Yango Tech y solicite un token Bearer de comercio.
2. Agregue el token al cliente de IA como YANGO_RETAIL_TOKEN.
3. Manténgalo fuera de Git y compártalo solo a través de la configuración de secretos o variables de entorno del cliente de IA.

El host de la API de producción es https://api.retailtech.yango.com. Cada llamada a la API es un POST con un cuerpo JSON bajo /b2b/v1/*, incluidas las operaciones de lectura.

El token se almacena en la configuración local del cliente de IA. Trátelo como una contraseña y nunca confirme una configuración que contenga un token real.

Configuración

Datos y telemetría

Solicitudes a Yango Tech Retail

El servidor se ejecuta en su máquina y envía datos de retail directamente al host de la API de Yango Tech Retail configurado. El token Bearer se adjunta solo a solicitudes resueltas contra ese host. Incluso raw_request acepta una ruta relativa y rechaza una ruta que se resuelva a otro origen.

Telemetría anónima

De forma predeterminada, el servidor envía eventos técnicos a usage.gistrec.cloud: inicio del servidor, nombre de la herramienta llamada y un código de motivo fijo cuando el inicio falla.

Los eventos contienen un id de instalación aleatorio, versión del paquete, nombre y versión del cliente de IA, versión de Node.js y sistema operativo. El token Bearer, los datos de retail, los argumentos de herramientas y las indicaciones no se leen ni se envían. La telemetría tiene un tiempo de espera de dos segundos y no bloquea las llamadas a herramientas.

Para deshabilitar la telemetría, agregue:

ASKADS_TELEMETRY=0

La implementación está en src/telemetry.ts.

Límites y trabajo en segundo plano

• La cuota de la API pública no está documentada. El cliente oficial de Python se mantiene en 5 solicitudes por segundo para un token y endpoint; úsalo como una guía operativa, no como un límite de API publicado. Este servidor no limita proactivamente cada llamada.
• Las respuestas 429 se reintentan. El servidor sigue Retry-After cuando está presente y no hace más reintentos de los que permite YANGO_RETAIL_MAX_RETRIES.
• Las escrituras no se reproducen después de fallos inciertos. Los reintentos de red y de errores 5xx se aplican solo a lecturas sin efectos secundarios. Después de una escritura incierta, lee el pedido, precio o stock actual antes de intentarlo de nuevo.
• Se aplican límites de lote. Productos, precios y descuentos aceptan hasta 100 entradas por solicitud; las actualizaciones de stock aceptan hasta 1,000 líneas.
• No hay monitoreo en segundo plano. El servidor solo funciona cuando se llama desde la aplicación de IA. Si la aplicación admite tareas programadas, puede verificar estados de pedidos o stock periódicamente.
• No hay reversión automática. Una actualización exitosa cambia la cuenta del minorista inmediatamente.
• La eliminación está limitada por la API upstream. Productos y precios se actualizan mediante upsert; no hay métodos conocidos de eliminación para productos, precios o descuentos.
• El soporte de descuentos está incompleto upstream. Las claves exactas para el período de actividad y el valor del descuento no están documentadas, y no hay un método conocido para listar o eliminar descuentos. Confirma el payload con Yango Tech antes de usarlo.

Documentación técnica

• Catálogo de capacidades de MCP — páginas orientadas a tareas para cada herramienta.
• Todas las herramientas — esquemas de entrada, respuestas, paginación, brechas de API y límites de lote.
• Desarrollo — configuración local y verificaciones del proyecto.
• Publicación — lanzamiento del paquete y listado en el catálogo de MCP.
• Paquete npm — el paquete publicado mcp-yango-retail.
• Cliente oficial de Python de Yango Tech — la especificación upstream disponible para esta API.

Soporte

¿Encontraste un error o te falta un caso de uso? Crea un issue o escríbenos en Telegram.

¡Llegaste al final!