mcp-yango-delivery

Yango Delivery MCP

Inglês | Русский

A1 Yango Delivery MCP conecta um aplicativo de IA a uma conta corporativa Yango Delivery. Estime uma entrega expressa, peça um entregador, acompanhe a rota e compartilhe um link de rastreamento com o destinatário usando linguagem comum.

Este servidor funciona com a API internacional Express Claims. Ele não oferece suporte a entrega no dia seguinte, pontos de retirada ou lockers para encomendas.

• 13 ferramentas. Sete para o ciclo de vida da entrega, cinco para rastreamento e contato com o entregador, além de uma ferramenta de requisição direta à API.
• Estime antes de pedir. Verifique o preço atual, a distância da rota e o ETA sem criar uma solicitação de entrega.
• Crie e peça separadamente. Uma solicitação pode ser preparada e revisada antes de iniciar a busca pelo entregador.
• Acompanhe uma entrega ativa. Obtenha o status, a posição do entregador, os ETAs dos pontos, o número de telefone temporário, o código de confirmação e o link de rastreamento do destinatário.

Comece com:

Estime a entrega de uma encomenda de 2 kg de [endereço de retirada] para [endereço de entrega].

Conecte o servidor · Explore casos de uso · Abra a documentação técnica

Veja funcionando em um minuto

Você: Estime a entrega de uma encomenda de 2 kg do nosso armazém para o endereço do cliente.

Assistente: Retornei o preço atual, a distância da rota e o ETA. Nenhuma solicitação de entrega foi criada.

Você: Crie a solicitação e pare antes de pedir o entregador.

Assistente: A solicitação foi criada. Vou mostrar o id, o preço, o status e a versão antes da aceitação.

Você: Aceite a oferta.

Assistente: A solicitação foi aceita e a busca pelo entregador foi iniciada.

Você: Envie-me o link de rastreamento do destinatário.

Assistente: Retornei o link público de rastreamento para o destino.

Preço, disponibilidade, status e condições de cancelamento sempre vêm da conta de entrega conectada e da resposta atual da API.

Conteúdo

• Início rápido
• O que você pode pedir para ele fazer
• Como uma entrega se torna real
• 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 do Node.js 20+, de uma conta corporativa Yango Delivery e de um token de integração.

1. Obtenha um token de integração.

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

3. Comece com uma estimativa de preço:

   Estime a entrega de uma encomenda de 2 kg de [endereço de retirada] para [endereço de entrega].

codex mcp add yango-delivery \
  --env YANGO_DELIVERY_TOKEN=your_token \
  -- npx -y mcp-yango-delivery@latest

codex mcp list

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

claude mcp list

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

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

{
  "servers": {
    "yango-delivery": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yango-delivery@latest"],
      "env": {
        "YANGO_DELIVERY_TOKEN": "${input:yango_delivery_token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "yango_delivery_token",
      "description": "Yango Delivery integration token",
      "password": true
    }
  ]
}

O que você pode pedir para ele fazer

Estimar uma entrega expressa

• Calcular o preço atual, a distância da rota e o ETA sem criar uma solicitação.
• Estimar o serviço de entregador, expresso ou carga para os endereços, peso e dimensões fornecidos.
• Verificar se a API consegue construir a rota e atender ao veículo ou aos requisitos de entrega solicitados.

Preparar e pedir um entregador

• Criar uma solicitação com contatos do remetente e do destinatário, pontos da rota, itens e requisitos de entrega.
• Revisar o preço retornado, o status e a versão da solicitação antes de pedir.
• Aceitar uma solicitação após a estimativa bem-sucedida e iniciar a busca pelo entregador.
• Encontrar uma solicitação por id, número de telefone, status, data ou id do pedido externo.

Acompanhar a entrega e contatar o entregador

• Obter a posição atual do entregador e o ETA para cada ponto da rota.
• Gerar um link público de rastreamento para o destinatário.
• Obter um número de telefone temporário encaminhado para o entregador.
• Obter um código de confirmação de retirada ou entrega quando a solicitação atual suportar um.

Verificar e cancelar uma entrega

• Verificar se o cancelamento é gratuito, pago ou não está mais disponível.
• Cancelar uma solicitação usando a versão atual e o modo de cancelamento retornado pela API.

Usar métodos adicionais da API

raw_request cobre métodos sem uma ferramenta dedicada, incluindo tarifas, métodos de entrega, comprovante de entrega, edição de solicitações e operações de devolução. Ele pode criar ou alterar dados reais, portanto é destinado a usuários técnicos que entendem a API upstream.

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

Como uma entrega se torna real

1. Estimar. Uma verificação de preço retorna a oferta atual, a distância e o ETA sem criar nada.
2. Criar. Uma solicitação é adicionada à conta e passa pela estimativa. Por padrão, nenhum entregador é pedido ainda.
3. Revisar. Leia o status, o preço e a versão mais recentes da solicitação. Uma solicitação bem-sucedida fica pronta para aprovação.
4. Aceitar. A aceitação inicia a busca pelo entregador. A partir deste ponto, a entrega é pedida e pode gerar uma cobrança real.
5. Acompanhar. Assim que um entregador é atribuído, o servidor pode retornar a posição, o ETA, os dados de contato e o link do destinatário.

A oferta com preço geralmente expira cerca de dez minutos após a estimativa. Se auto_accept: true for passado ao criar uma solicitação, a etapa separada de revisão e aceitação é ignorada e o entregador pode ser pedido automaticamente.

O que muda na conta

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

A criação de solicitações usa um request_id único, então repeti-la com o mesmo id retorna a mesma solicitação. Aceitação e cancelamento não são repetidos automaticamente após um erro de rede ou uma resposta 5xx, pois a operação pode já ter sido concluída. Leia a solicitação atual antes de tentar novamente.

Obtendo acesso

1. Registre-se como cliente corporativo Yango Delivery e assine o contrato de serviço de entrega.
2. Abra a aba Integração na conta de entrega.
3. Selecione Obter token.
4. Adicione o token ao cliente de IA como YANGO_DELIVERY_TOKEN.

O token está vinculado à conta corporativa. Ele não expira por conta própria, mas alterar a senha da conta o redefine.

O token de integração é armazenado como texto simples na configuração local do cliente de IA. Trate-o como uma senha e nunca envie uma configuração contendo um token real.

Configuração

Dados e telemetria

Requisições ao Yango Delivery

O servidor roda na sua máquina e envia dados de solicitação diretamente para b2b.taxi.yandex.net. O token de integração é anexado apenas a requisições para o host da API configurado. Até mesmo raw_request aceita um caminho relativo e bloqueia requisições que resolvem para outro host.

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 de integração, dados de solicitação, 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 uma chamada de ferramenta.

Para desativar a telemetria, adicione:

ASKADS_TELEMETRY=0

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

Limites e trabalho em segundo plano

• Não há sandbox documentado. Trate a criação e a aceitação de solicitações como operações de produção.
• A oferta tem prazo limitado. A oferta com preço geralmente expira cerca de dez minutos após a estimativa; leia a solicitação atual antes da aceitação.
• O rastreamento exige uma solicitação ativa. Posição, ETA, dados de contato e links de rastreamento podem não estar disponíveis até que um entregador seja atribuído ou após a conclusão da solicitação.
• As cotas numéricas da API não são publicadas. Quando a API retorna 429, o servidor segue Retry-After quando presente e tenta novamente até YANGO_DELIVERY_MAX_RETRIES.
• 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 uma solicitação ativa periodicamente.
• Não há rollback automático. Após um resultado incerto de aceitação ou cancelamento, leia a solicitação antes de repetir a ação.

Documentação técnica

• Catálogo de capacidades MCP — páginas orientadas a tarefas para cada ferramenta.
• Todas as ferramentas — esquemas de entrada, respostas, status e erros.
• 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-delivery publicado.
• API Yango/Yandex Delivery — documentação de métodos upstream.

Suporte

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

Você chegou ao final!