Wake Storefront MCP

O Wake Storefront MCP (Model Context Protocol) é um protocolo que permite que qualquer parceiro da Wake desenvolva funcionalidades usando LLMs (Large Language Models) integradas diretamente à Storefront.

Com ele, as LLMs podem interagir com a loja de forma estruturada, consultando produtos, escolhendo atributos (como tamanho e cor) e adicionando itens ao carrinho de compras do usuário, tudo via API.

Obejtivo

O objetivo do Wake Storefront MCP é oferecer uma interface padronizada para que parceiros e desenvolvedores possam criar experiências inteligentes em cima do Storefront Wake, como:

• Assistentes de compra que entendem linguagem natural e adicionam produtos ao carrinho.
• Ferramentas de recomendação de produtos personalizadas.
• Chatbots e integrações de IA capazes de navegar pelo catálogo e realizar compras.
• Automação de processos que dependem da interação com o carrinho e produtos.

Como usar

Para usar o MCP da Wake Storefront, basta ter a URL da sua loja (a mesma que aparece no Admin) e adicionar o sufixo /api/mcp.

Exemplo de endpoint:

https://minhaloja.fbits.store/api/mcp

Esse endpoint expõe um servidor MCP que pode ser usado diretamente em ferramentas de teste como Postman ou integrado a clientes MCP em aplicações.

Tools disponíveis

O MCP da Wake Storefront expõe uma série de tools que representam as operações que uma LLM pode executar.

1. get_cart

Busca informações do carrinho de compras atual.

Exemplo de request:

{
  "method": "tools/call",
  "params": {
    "name": "get_cart",
    "arguments": {
      "checkoutId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  }
}

Uso típico: verificar quais itens já estão no carrinho antes de sugerir novas adições.

2. search_products

Busca produtos de forma proativa com múltiplas opções de refinamento.

Parâmetros:

• search (string) → termo da busca (ex: "camiseta preta").
• offset (integer) → usado para paginação (ex: 0 para primeira página, 10 para pular 10 resultados).
• resultSize (integer) → quantidade de produtos por página (padrão: 10).
• minimumPrice (number) → preço mínimo (ex: 100).
• maximumPrice (number) → preço máximo (ex: 200).
• sortKey (string) → critério de ordenação (PRICE, NAME, RANDOM).
• sortDirection (string) → direção da ordenação (ASC ou DESC).

Resposta contém:

• Lista de produtos.
• Campo requiredSearchAttributes (boolean):
  • false → produto pode ser adicionado diretamente ao carrinho.
  • true → é necessário usar search_product_attributes para escolher atributos antes de adicionar.

Exemplo de request (busca simples):

{
  "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": {
      "search": "camiseta preta",
      "offset": 0,
      "resultSize": 5
    }
  }
}

Exemplo de request (busca filtrada):

{
  "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": {
      "search": "tênis",
      "minimumPrice": 100,
      "maximumPrice": 300,
      "sortKey": "PRICE",
      "sortDirection": "ASC"
    }
  }
}

3. add_products_to_cart

Adiciona um ou mais produtos ao carrinho após confirmação explícita do usuário.

Parâmetros:

checkoutId (string): obrigatório.

products (array<object>): lista de itens com productVariantId e quantity.

Exemplo de request:

{
  "method": "tools/call",
  "params": {
    "name": "add_products_to_cart",
    "arguments": {
      "checkoutId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "products": [
        {
          "productVariantId": 67890,
          "quantity": 1
        }
      ]
    }
  }
}

4. remove_products_from_cart

Remove um ou mais produtos do carrinho quando o usuário expressar essa intenção.

Exemplos de fala do usuário: "Remova a camiseta azul"; "Não quero mais este item"; "Tire o tênis do meu carrinho"

Parâmetros:

checkoutId (string): obrigatório.

products (array): itens a remover. Se quantity não for informado, remove todas as unidades.

Exemplo de request:

{
  "method": "tools/call",
  "params": {
    "name": "remove_products_from_cart",
    "arguments": {
      "checkoutId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "products": [
        {
          "productVariantId": 67890,
          "quantity": 1
        }
      ]
    }
  }
}

5. search_product_attributes

Lista e valida atributos (como cor e tamanho).

Parâmetros:

productId (integer): ID do produto.

attributes (array): lista de escolhas do usuário no formato { "attributeId": 257, "value": "Vermelho" }.

Exemplo para listar atributos disponíveis:

{
  "method": "tools/call",
  "params": {
    "name": "search_product_attributes",
    "arguments": {
      "productId": 12345,
      "attributes": []
    }
  }
}

Exemplo para validar escolha de atributos:

{
  "method": "tools/call",
  "params": {
    "name": "search_product_attributes",
    "arguments": {
      "productId": 12345,
      "attributes": [
        {
          "attributeId": 257,
          "value": "Vermelho"
        },
        {
          "attributeId": 258,
          "value": "M"
        }
      ]
    }
  }
}

Fluxo esperado:

1. Primeiro chamar com attributes: [] para listar opções disponíveis.
2. Depois chamar novamente com as seleções do usuário para validar e obter o productVariantId.