mcp-yango-retail

Yango Tech Retail MCP

Inglês | Русский

A1 Yango Tech Retail MCP conecta um aplicativo de IA a uma conta de varejista no Yango Tech Retail. Use linguagem comum para consultar lojas, pedidos, produtos, preços e estoque, ou para criar pedidos e atualizar dados da conta quando necessário.

O servidor funciona com a API B2B voltada ao varejista para supermercados e darkstores. Não é um portal de vendedor de marketplace, serviço de táxi ou Yango Delivery.

• 16 ferramentas. Nove ferramentas somente leitura, cinco ferramentas de escrita e duas ferramentas potencialmente destrutivas cobrem lojas, catálogo, preços, estoque, pedidos e recibos.
• Um início seguro somente leitura. Verifique os dados conectados antes de alterar qualquer coisa na conta.
• Limites claros de escrita. Criação e cancelamento de pedidos, upserts de produtos, alterações de preço, criação de descontos e atualizações de estoque são separados das leituras.
• Cobertura adicional de API. Usuários técnicos podem acessar métodos sem uma ferramenta dedicada por meio de raw_request.

Comece com:

Liste nossas lojas e mostre o estoque do produto [product ID] em cada uma.

Conectar o servidor · Explorar casos de uso · Abrir documentação técnica

Veja funcionando em um minuto

Você: Liste nossas lojas e mostre o estoque do produto [product ID] em cada uma.

Assistente: Vou retornar as lojas, seus ids e o estoque atual deste produto em cada uma.

Você: Mostre o preço deste produto em todas as listas de preços.

Assistente: Vou retornar as listas de preços e o preço atual do produto em cada uma. Nenhum dado da conta será alterado.

Você: Altere o preço para 99.90 na lista de preços [price-list ID].

Assistente: Isso alterará um preço real visível ao cliente. Vou mostrar o produto, a lista de preços, o valor atual e o novo valor antes de pedir confirmação.

Você: Confirmo.

Assistente: O preço foi atualizado. Vou ler a lista de preços novamente e retornar o valor atual.

Lojas, produtos, preços, estoque e estados de pedidos sempre vêm da conta de varejista conectada e da resposta atual da API.

Conteúdo

• Início rápido
• O que você pode pedir para fazer
• Como os dados de varejo são conectados
• O que muda na conta
• Obtendo acesso
• Configuração
• Dados e telemetria
• Limites e trabalho em segundo plano
• Documentação técnica
• Suporte

Início rápido

Você precisa de Node.js 20+, uma conta Yango Tech Retail e um token Bearer de varejista.

1. Obtenha um token com seu gerente de integração Yango Tech.

2. Adicione o servidor ao seu aplicativo de IA usando uma das instruções abaixo.

3. Comece com uma solicitação somente leitura:

   Liste nossas lojas e mostre o estoque do produto [product ID] em cada uma.

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
    }
  ]
}

O que você pode pedir para fazer

Consultar lojas e o catálogo de produtos

• Liste lojas com seus ids, status, localização, endereço e nome quando disponíveis.
• Navegue pelos produtos com cursor e inspecione status, categoria, nomes localizados, códigos de barras e atributos personalizados.
• Crie ou atualize até 100 produtos em uma única solicitação. Os registros de produtos são atualizados via upsert, não adicionados como duplicatas.

Consultar e atualizar preços

• Liste listas de preços e leia preços de produtos de uma ou mais listas.
• Compare o mesmo produto entre listas de preços.
• Defina até 100 preços em uma única solicitação usando strings decimais como "150.00".
• Crie até 100 descontos específicos por loja após confirmar a estrutura esperada de campos com a Yango Tech.

Consultar e atualizar estoque

• Leia o estoque entre lojas, incluindo produto, quantidade e tipo de prateleira.
• Atualize até 1.000 linhas de estoque para uma loja.
• Use initialize para a primeira carga de estoque e modify para atualizações regulares.

Trabalhar com pedidos e recibos

• Crie um pedido após coletar loja, produtos, quantidades, preços, detalhes de entrega e tipo de pagamento.
• Leia detalhes do pedido e verifique os estados atuais de vários pedidos de uma vez.
• Acompanhe o feed de eventos de pedidos para novos pedidos, mudanças de estado e recibos emitidos.
• Leia um recibo fiscal por id do pedido ou id do recibo.
• Cancele um pedido após verificar o estado atual e o motivo do cancelamento.

Usar métodos adicionais de API

raw_request cobre /b2b/v1/* métodos sem uma ferramenta dedicada, incluindo atualizações de pedidos, dados de IVA, vínculos de listas de preços, separação, logística e operações de entrega 3PL. Pode alterar dados reais da conta e é destinado a usuários técnicos que entendem a API upstream.

Esquemas completos, campos de resposta e lacunas de API estão disponíveis na referência de ferramentas.

Como os dados de varejo são conectados

Feeds usam paginação por cursor. Uma página com menos itens que o limite solicitado significa que o feed atual de produtos, listas de preços ou estoque está esgotado. O feed de eventos de pedidos é contínuo: mantenha o último cursor e solicite a próxima página mais tarde.

O que muda na conta

O servidor expõe anotações MCP para ações somente leitura, escrita e destrutivas. O cliente de IA decide quando e como pedir confirmação.

Antes de uma escrita, peça ao assistente para mostrar a loja alvo, ids de produtos, lista de preços, quantidades, valores atuais e valores propostos. Respostas de escrita não são totalmente documentadas upstream, então após uma atualização bem-sucedida de preço ou estoque, o servidor pode ler os dados correspondentes novamente e mostrar o valor atual.

Obtendo acesso

A Yango Tech emite um token Bearer para uma conta de varejista por meio de um gerente de integração. Este repositório não descreve um portal de tokens de autoatendimento.

1. Contate seu gerente de integração Yango Tech e solicite um token Bearer de varejista.
2. Adicione-o ao cliente de IA como YANGO_RETAIL_TOKEN.
3. Mantenha-o fora do Git e compartilhe-o apenas pela configuração de segredo ou variável de ambiente do cliente de IA.

O host da API de produção é https://api.retailtech.yango.com. Cada chamada de API é um POST com corpo JSON sob /b2b/v1/*, incluindo operações de leitura.

O token é armazenado na configuração local do cliente de IA. Trate-o como uma senha e nunca faça commit de uma configuração contendo um token real.

Configuração

Dados e telemetria

Solicitações ao Yango Tech Retail

O servidor roda na sua máquina e envia dados de varejo diretamente ao host da API Yango Tech Retail configurado. O token Bearer é anexado apenas a solicitações resolvidas para esse host. Até mesmo raw_request aceita um caminho relativo e rejeita um caminho que resolva para outra origem.

Telemetria anônima

Por padrão, o servidor envia eventos técnicos para usage.gistrec.cloud: início do servidor, nome da ferramenta chamada e um código de motivo fixo quando a inicialização falha.

Os eventos contêm um id de instalação aleatório, versão do pacote, nome e versão do cliente de IA, versão do Node.js e sistema operacional. O token Bearer, dados de varejo, argumentos de ferramentas e prompts não são lidos ou enviados. A telemetria tem um tempo limite de dois segundos e não bloqueia chamadas de ferramentas.

Para desativar a telemetria, adicione:

ASKADS_TELEMETRY=0

A implementação está em src/telemetry.ts.

Limites e trabalho em segundo plano

• A cota da API pública não é documentada. O cliente Python oficial mantém 5 requisições por segundo para um token e endpoint; use isso como uma diretriz operacional, não como um limite de API publicado. Este servidor não limita proativamente todas as chamadas.
• Respostas 429 são repetidas. O servidor segue Retry-After quando presente e não faz mais tentativas do que YANGO_RETAIL_MAX_RETRIES permite.
• Escritas não são repetidas após falhas incertas. Tentativas de rede e erros 5xx se aplicam apenas a leituras sem efeitos colaterais. Após uma escrita incerta, leia o pedido, preço ou estoque atual antes de tentar novamente.
• Limites de lote se aplicam. Produtos, preços e descontos aceitam até 100 entradas por requisição; atualizações de estoque aceitam até 1.000 linhas.
• Não há monitoramento em segundo plano. O servidor funciona apenas quando chamado pelo aplicativo de IA. Se o aplicativo suportar tarefas agendadas, ele pode verificar estados de pedidos ou estoque periodicamente.
• Não há reversão automática. Uma atualização bem-sucedida altera a conta do varejista imediatamente.
• A exclusão é limitada pela API upstream. Produtos e preços são atualizados via upsert; não há métodos conhecidos de exclusão para produtos, preços ou descontos.
• O suporte a descontos está incompleto upstream. As chaves exatas para o período de atividade e o valor do desconto não são documentadas, e não há método conhecido para listar ou excluir descontos. Confirme o payload com a Yango Tech antes de usá-lo.

Documentação técnica

• Catálogo de capacidades do MCP — páginas orientadas a tarefas para cada ferramenta.
• Todas as ferramentas — esquemas de entrada, respostas, paginação, lacunas da API e limites de lote.
• Desenvolvimento — configuração local e verificações do projeto.
• Publicação — lançamento de pacotes e listagem no catálogo MCP.
• Pacote npm — o pacote mcp-yango-retail publicado.
• Cliente Python oficial da Yango Tech — a especificação upstream disponível para esta API.

Suporte

Encontrou um bug ou falta um caso de uso? Crie uma issue ou envie uma mensagem para nós no Telegram.

Você chegou ao final!