WisWes Magento MCP

WisWes MCP para Magento 2

O módulo oficial WisWes para Magento 2. Conecta sua loja ao assistente de compras com IA WisWes (wiswes.com) por meio do Model Context Protocol (MCP).

O módulo inclui:

• Um endpoint MCP HTTP sem estado em /mcp, servido pelo seu servidor web Magento existente — sem processo separado para gerenciar.
• 22 ferramentas tipadas em catálogo, carrinho, checkout, cliente, vendas e lista de desejos.
• Um handshake administrativo de um clique que entrega um segredo compartilhado ao seu workspace WisWes.
• Envio noturno do catálogo para o índice vetorial WisWes para busca semântica de produtos.

O que isso oferece: a persona de chat Wes na sua loja pode ler seus dados Magento ao vivo e agir no carrinho sem código de integração. Os compradores fazem perguntas em linguagem natural, o Wes chama a ferramenta certa, você vende mais.

• Nome do módulo: WisWes_MCP
• Pacote Composer: wiswes/magento-mcp
• Versões Magento testadas: 2.4.4, 2.4.5, 2.4.6, 2.4.7
• PHP: 8.1 / 8.2 / 8.3 / 8.4

---

Sumário

• Instalação
  • Opção A — Composer (recomendado)
  • Opção B — Git clone
  • Opção C — Arquivo ZIP
• Conectar ao WisWes
• Enviar o catálogo
• Instalar o widget da loja
• Verificar se funciona
• Ferramentas incluídas
• Uso
• Estender — crie sua própria ferramenta
• Referência de configuração
• Atualização
• Desinstalação
• Solução de problemas
• Suporte
• Licença

---

Instalação

Escolha um dos três caminhos de instalação. O Composer é recomendado para produção.

Opção A — Composer (recomendado)

composer require wiswes/magento-mcp
bin/magento module:enable WisWes_MCP
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

O pacote está publicado no Packagist. Fixe uma linha principal com composer require wiswes/magento-mcp:^1.0.

Opção B — Git clone

mkdir -p app/code/WisWes
git clone https://github.com/wiswes/magento.git app/code/WisWes/MCP
cd app/code/WisWes/MCP && git checkout v1.0.7 && cd -

bin/magento module:enable WisWes_MCP
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Opção C — Arquivo ZIP

Baixe o arquivo da página de Releases e descompacte na raiz do seu Magento:

unzip ~/Downloads/wiswes-magento-1.0.7.zip -d .
mkdir -p app/code/WisWes && mv wiswes-magento-1.0.7 app/code/WisWes/MCP

bin/magento module:enable WisWes_MCP
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

---

Conectar ao WisWes

O endpoint MCP é servido pelo seu servidor web existente em https://<your-magento>/mcp. Não há processo separado para iniciar — assim que setup:upgrade for executado, a rota estará ativa.

Conectar ao seu workspace WisWes é um handshake de um clique no admin do Magento:

1. Abra Lojas → Configuração → WisWes Chat → WisWes Chat MCP → Conexão.
2. (Opcional) Defina a URL do Painel WisWes se você estiver conectando a um painel de staging ou auto-hospedado. Padrão: https://api.wiswes.com/.
3. Salve a configuração.
4. Abra Lojas → Configuração → WisWes Chat → WisWes Chat Widget → Instalar e clique no botão Instalar.
5. O Magento gera um segredo compartilhado longo e aleatório, exclusivo desta instalação, persiste-o (criptografado) em wiswes_mcp/auth/shared_secret e redireciona você para o painel WisWes com o segredo embutido como install_token na URL.
6. O painel salva o token no CommerceConfig do seu tenant. A partir de agora, todo chat WisWes alcança sua loja como POST https://<your-magento>/mcp com Authorization: Bearer <secret>.

O comerciante nunca vê o segredo no navegador — ele viaja de servidor para servidor por meio de um redirecionamento via HTTPS.

Modelo de autenticação

As ferramentas se enquadram em três categorias com base no contexto Magento de que precisam:

Grupo de ferramentas	Tipo de token
Catálogo (busca/filtro/get/categoria)	apenas segredo compartilhado de instalação — contexto público da loja
Carrinho, cliente, lista de desejos	segredo compartilhado + bearer do cliente (encaminhado pelo WisWes quando o chat é identificado)
Atualizações de pedidos	segredo compartilhado + cliente (próprios pedidos) ou admin (qualquer pedido)

O WisWes encaminha automaticamente o token do comprador quando o chat está conectado. Compradores anônimos ainda podem usar ferramentas de catálogo, mas não podem ler o carrinho até fazer login.

---

Enviar o catálogo

O WisWes atende à busca de produtos a partir do seu próprio índice vetorial, populado pela sua loja Magento. O envio ocorre diariamente às 03:00 por padrão; acione manualmente após uma alteração em massa no catálogo:

# from Magento root
bin/magento wiswes:products:push
# Pushed 4271 products in 43 batches (upserted=4271, skipped_operator=0, skipped_cap=0)

Ou clique em Enviar catálogo agora em Lojas → Configuração → WisWes Chat → WisWes Chat MCP → Sincronização de Catálogo.

O envio entrega um payload compacto de recuperação (sku, name, url, price) além de um blob de metadados construído a partir de nome + descrição curta + atributos pesquisáveis. O blob é o que o WisWes incorpora; o payload de recuperação é o que o LLM vê literalmente quando um resultado corresponde.

O envio é incremental — apenas produtos habilitados e visíveis são enviados, em lotes de 100 por vez. A autenticação usa o mesmo segredo compartilhado gerado pelo handshake de Instalação.

---

Instalar o widget da loja

O balão de chat WisWes é uma única tag <script>. O módulo não o injeta automaticamente — cole-o nas áreas nativas de script do Magento, para que seu caminho de instalação seja idêntico ao Shopify ou a qualquer loja personalizada:

• Lojas → Configuração → Design → HTML Head → Scripts e Folhas de Estilo, ou
• default_head_blocks.xml no seu tema

Copie o trecho do seu workspace WisWes em Configuração → Commerce → Trecho de incorporação. Ele se parece com:

<script src="https://app.wiswes.com/api/widget/embed.js?user_token=YOUR_TENANT_TOKEN" defer></script>

O token no trecho é o ID do seu tenant — todo chat carregado por esse trecho é limitado ao seu workspace.

---

Verificar se funciona

1. Endpoint MCP acessível. De qualquer host que o WisWes possa alcançar:

   curl -X POST https://<your-magento>/mcp \
     -H 'Authorization: Bearer <your-shared-secret>' \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   

   Você deve ver uma resposta JSON-RPC listando as 22 ferramentas integradas.
2. Ferramentas descobertas no WisWes. Abra WisWes → Comportamento → Ferramentas. As 22 ferramentas aparecem em segundos.
3. Catálogo conectado. Pergunte ao Wes: "recomende um carregador sem fio para iPhone." O Wes deve chamar product:filter e retornar linhas reais do catálogo.
4. Carrinho conectado. Enquanto estiver conectado na loja, pergunte: "adicione o segundo à minha sacola." O Wes deve chamar cart:add e confirmar o novo item.
5. Conversa registrada. Atualize Conversas no WisWes — seu chat de teste aparece com as chamadas de ferramenta no painel direito.

A referência completa de ferramentas + argumentos está na documentação do WisWes.

---

Ferramentas incluídas

22 ferramentas em seis grupos. Os nomes listados são os IDs de ferramenta MCP que o agente vê.

Grupo	Ferramenta	Resumo
Catálogo	category:list	Árvore de categorias como lista aninhada
Catálogo	product:filter	Consultas de filtro estruturadas (campo EAV, operador, valor)
Catálogo	product:filter:options	Descobre os atributos filtráveis + seus valores de opção
Catálogo	product:get	Payload completo do produto por SKU ou ID
Carrinho	cart:info	Instantâneo do carrinho ativo
Carrinho	cart:add	Adicionar produto (configurável / pacote / opções personalizadas)
Carrinho	cart:update	Quantidade, aplicar / remover cupom
Carrinho	cart:remove	Remover item por id
Checkout	checkout:set:address	Endereço de cobrança ou entrega (convidado ou conectado)
Checkout	checkout:shipping_methods	Métodos de envio disponíveis para o carrinho ativo
Checkout	checkout:payment_methods	Métodos de pagamento disponíveis para o carrinho ativo
Checkout	checkout:place_order	Finalizar o pedido a partir do carrinho ativo
Cliente	customer:create	Registrar novo cliente
Cliente	customer:info	Perfil, endereços, pedidos recentes
Cliente	customer:update	Atualizar campos do perfil
Cliente	customer:address:list	Todos os endereços salvos
Cliente	customer:address:update	Criar ou atualizar um endereço
Cliente	customer:address:remove	Excluir um endereço
Vendas	order:info	Status compacto do pedido + histórico + rastreamento
Vendas	order:update	Comentar / reter / cancelar / alterar endereço de entrega
Lista de desejos	wishlist:items	Todos os itens na lista de desejos do cliente
Lista de desejos	wishlist:add:item	Adicionar produto à lista de desejos

Cada ferramenta retorna um array tipado ou lança um LocalizedException do Magento com uma mensagem segura para o comprador — nenhum stack trace bruto vaza para o agente.

---

Uso

Uma vez instalado e conectado, o fluxo de trabalho diário é:

1. Os clientes conversam com o Wes por meio do widget WisWes na sua loja.
2. O Wes seleciona ferramentas para responder perguntas ou executar ações — buscar no catálogo, consultar um pedido, adicionar ao carrinho.
3. As chamadas de ferramenta atingem /mcp na sua loja, que lê/grava por meio dos contratos de serviço padrão do Magento, para que todos os seus hooks de extensão existentes sejam acionados (regras de preço, reservas de estoque, regras de vendas etc.).
4. Os resultados retornam ao Wes, que responde em linguagem natural com cartões de produto, atualizações de status ou confirmações.

Você pode definir quais ferramentas estão disponíveis por workspace em Comportamento → Ferramentas no WisWes — ative/desative ferramentas individuais, substitua a descrição (o texto de prompt que o modelo lê) ou fixe padrões de argumentos. Nada disso exige tocar em PHP.

---

Estender — crie sua própria ferramenta

Cada ferramenta Magento é uma classe PHP simples com um atributo #[McpTool]. Coloque uma classe em Mcp/Tool/..., reconstrua o cache DI, limpe o OPcache, e a ferramenta aparecerá no seu workspace WisWes em segundos.

Exemplo mínimo

<?php
declare(strict_types=1);

namespace WisWes\MCP\Mcp\Tool\Loyalty;

use PhpMcp\Server\Attributes\McpTool;

class LoyaltyPointsTool
{
    public function __construct(
        private readonly \Acme\Loyalty\Api\PointsClient $client,
    ) {}

    #[McpTool(
        name: 'loyalty:points',
        description: 'Returns the authenticated customer\'s loyalty tier and current points balance. Arguments: none. Customer bearer token required.'
    )]
    public function points(): array
    {
        $snapshot = $this->client->snapshotForCurrentUser();

        return [
            'tier'          => $snapshot->getTier(),
            'points'        => $snapshot->getBalance(),
            'tier_progress' => $snapshot->getProgressToNext(),
        ];
    }
}

Depois:

bin/magento setup:di:compile
bin/magento cache:flush

A ferramenta aparece em Comportamento → Ferramentas no WisWes rotulada como loyalty:points.

Convenções que valem a pena

• Uma ferramenta, uma função. O modelo escolhe melhor entre dez ferramentas estreitas do que entre três amplas.
• Seja específico em description. É o prompt que o modelo lê ao decidir se deve chamar sua ferramenta. Inclua cada argumento, o formato de retorno e quando não usar a ferramenta.
• Valide no limite. Lance Magento\Framework\Exception\LocalizedException com uma mensagem segura para o comprador — o agente a exibirá como está.
• Retorne arrays, não DTOs. Arrays estritamente tipados serializam limpo para MCP. Oculte internals (row_id, parent_id, flags internas) da resposta, a menos que o modelo precise deles.
• Permaneça sem estado. As ferramentas devem funcionar igual na primeira chamada e na milésima. O estado do carrinho/pedido pertence ao Magento, não à classe da ferramenta.

Ferramenta com argumentos

#[McpTool(
    name: 'sales:track_order',
    description: 'Returns carrier and tracking URL for an order. Arguments: order_id (string, required).'
)]
public function track(string $orderId): array
{
    $shipment = $this->client->getLatestShipment($orderId);
    return [
        'order_id'     => $orderId,
        'carrier'      => $shipment->getCarrier(),
        'status'       => $shipment->getStatus(),
        'tracking_url' => $shipment->getTrackingUrl(),
    ];
}

Suprimindo ferramentas integradas

Para executar um subconjunto selecionado, defina o valor de configuração wiswes_mcp/tools/include como uma lista de globs separada por vírgulas:

bin/magento config:set wiswes_mcp/tools/include 'product:*,cart:*,order:info'
bin/magento cache:flush

* (o padrão) significa que todas as ferramentas integradas + personalizadas são expostas.

---

Referência de configuração

Todas as configurações ficam em Lojas → Configuração → WisWes Chat (ou via bin/magento config:set).

Conexão (wiswes_mcp/install/*)

Caminho	Finalidade	Padrão
wiswes_mcp/install/wiswes_url	URL base do painel WisWes para o qual o botão Instalar redireciona	https://api.wiswes.com/

Auth — definido automaticamente pelo handshake de Instalação (wiswes_mcp/auth/*)

Caminho	Finalidade
wiswes_mcp/auth/shared_secret	Segredo compartilhado criptografado usado para autenticar tokens bearer /mcp
wiswes_mcp/auth/admin_id	ID do usuário administrador capturado no momento da instalação, controla a ACL

Ferramentas (wiswes_mcp/tools/*)

Caminho	Finalidade	Padrão
wiswes_mcp/tools/include	Lista glob de nomes de ferramentas a expor	*

Identidade do servidor (wiswes_mcp/server/*)

Caminho	Finalidade	Padrão
wiswes_mcp/server/name	Nome do servidor anunciado no handshake initialize do MCP	WisWes Magento MCP

---

Atualização

# Composer
composer update wiswes/magento-mcp
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

# Git
cd app/code/WisWes/MCP && git fetch && git checkout v<new-tag> && cd -
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

# ZIP — download the new archive and unzip over the existing folder, then run the same setup commands.

---

Desinstalação

bin/magento module:disable WisWes_MCP
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

# Composer
composer remove wiswes/magento-mcp

# Git / ZIP
rm -rf app/code/WisWes/MCP

# Optional — wipe the install secret
bin/magento config:set wiswes_mcp/auth/shared_secret ''
bin/magento config:set wiswes_mcp/auth/admin_id ''

No WisWes, limpe a conexão em Configuração → Commerce.

---

Solução de problemas

O módulo instala, mas nenhuma ferramenta aparece no WisWes

• Execute bin/magento setup:di:compile — necessário após adicionar qualquer nova classe de ferramenta.
• Limpe o OPcache (bin/magento cache:flush ou reinicie o php-fpm) — a descoberta de ferramentas ocorre na primeira requisição após um deploy.
• Verifique se a URL do MCP está acessível a partir do WisWes (firewall, NAT). De um host no lado do WisWes:

  curl -i -X POST https://<your-magento>/mcp \
    -H 'Authorization: Bearer <your-secret>' \
    -H 'Content-Type: application/json' \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  

Chamadas de ferramenta retornam 401 Não Autorizado

• O segredo compartilhado foi rotacionado ou não foi instalado. Execute novamente o handshake de Instalação em Lojas → Configuração → WisWes Chat → Instalar.
• Para ferramentas com escopo de cliente (carrinho, cliente, pedido), o chat da loja deve estar identificado — chats anônimos não podem ler o carrinho.

O Composer não encontra uma versão compatível de wiswes/magento-mcp

Execute composer clear-cache e tente novamente composer require wiswes/magento-mcp:^1.0. O Packagist atualiza seu índice em segundos após cada push com tag, então isso é quase sempre um cache local desatualizado.

Para instalar a partir de um branch de funcionalidade que ainda não recebeu tag, adicione a fonte do GitHub como repositório VCS no seu composer.json:

{
  "repositories": [
    { "type": "vcs", "url": "https://github.com/wiswes/magento" }
  ]
}

O push do catálogo reporta skipped_cap ou skipped_operator

• skipped_cap — o limite de índice de produtos do seu plano WisWes foi atingido. Faça upgrade do plano ou ajuste o filtro do catálogo.
• skipped_operator — uma linha foi rejeitada pelo lado WisWes como malformada (SKU ausente, nome vazio). Inspecione via:

  bin/magento wiswes:products:push -vvv
  

/mcp retorna 404

• Confirme se o módulo está habilitado: bin/magento module:status WisWes_MCP.
• Confirme se a rota mcp está registrada: bin/magento info:routes:url:list 2>/dev/null | grep mcp (ou verifique etc/frontend/routes.xml).
• Execute novamente bin/magento setup:upgrade.

---

Suporte

• Docs: https://wiswes.com/docs
• Guia de instalação: https://wiswes.com/install/magento
• Problemas: https://github.com/wiswes/magento/issues
• E-mail: services@wiswes.com
• Integração paga: https://wiswes.com/services#magento-dev — nós instalamos, configuramos e entregamos o widget na sua loja para você.

---

Licença

Lançado sob a GNU General Public License v3.0 — veja o arquivo LICENSE para os termos completos.