DataFirefly MCP Commerce: guia completo

O módulo DataFirefly MCP Commerce transforma a sua loja PrestaShop num servidor MCP (Model Context Protocol) que os agentes de IA (ChatGPT, Claude, Claude Desktop, Claude Code, n8n) podem consumir diretamente para percorrer o catálogo, constituir carrinhos e preparar encomendas. Este guia cobre a instalação, o endpoint, a dupla autenticação (OAuth 2.1 e tokens Bearer), a ligação dos principais agentes, as ferramentas expostas, os scopes, os modos de encomenda e a resolução de problemas.

Pré-requisitos

• PrestaShop 8.0 a 9.x.
• PHP 7.4 a 8.3 com a extensão cURL ativa.
• Uma loja servida em HTTPS (obrigatório para os conectores de IA).
• Recomendado: os URL amigáveis ativos (Parâmetros avançados > SEO e URL) para pontos de acesso limpos.

Instalação

1. No back-office, abra Módulos > Gestor de módulos, depois Carregar um módulo e envie o ficheiro dfmcpcommerce.zip.
2. Uma vez instalado, abra a configuração através do botão Configurar.
3. A instalação cria as tabelas técnicas (tokens, clientes OAuth, carrinhos, registo, limitador de débito) e ativa o servidor por defeito.

O seu endpoint MCP

O URL do servidor MCP é apresentado no separador Ligar um agente. Com os URL amigáveis, tem este aspeto:

https://a-sua-loja.pt/mcp

É este URL que cola no conector do agente. O transporte é Streamable HTTP (JSON-RPC 2.0): um endpoint único, em POST.

Autenticação: dois mecanismos

O módulo gere dois modos de autenticação em paralelo, consoante o cliente usado.

OAuth 2.1: conectores web (Claude.ai, ChatGPT)

Os conectores web do Claude.ai e do ChatGPT só aceitam OAuth: nada de token colado, nada de token no URL. O módulo fornece um servidor de autorização OAuth 2.1 completo (authorization code + PKCE S256, metadados de recurso protegido e registo dinâmico de cliente). O agente declara-se sozinho e abre um ecrã de consentimento onde o cliente inicia sessão e aprova o acesso.

Tokens Bearer: API, Desktop, CLI, n8n

Para a API Anthropic (conector MCP), Claude Desktop, Claude Code ou n8n, cria um token Bearer estático no separador Tokens de acesso e passa-o no cabeçalho Authorization: Bearer.

Ligar o Claude.ai ou o ChatGPT (web)

1. Mantenha o OAuth 2.1 ativo no separador Definições.
2. No agente, adicione um conector personalizado e cole o URL do servidor MCP.
3. O agente descobre automaticamente a autenticação, regista-se e abre o ecrã de consentimento.
4. O cliente inicia sessão na sua conta da loja e aprova os scopes pedidos. Nenhum token a introduzir.

Ligar a API Anthropic, Claude Desktop, Claude Code ou n8n

1. Abra o separador Tokens de acesso, escolha os scopes e clique em Criar um token.
2. Copie o token apresentado.
3. Configure o conector com o URL do servidor MCP e o cabeçalho Authorization: Bearer O_SEU_TOKEN.

Scopes

Cada acesso é delimitado por scopes, pedidos pelo agente e concedidos no consentimento (OAuth) ou associados ao token (Bearer):

• catalog:read: pesquisa e fichas de produtos, categorias, informações da loja, transportadoras.
• cart:write: criação e gestão de carrinhos.
• order:write: preparação de encomenda.

Ferramentas expostas

Estão disponíveis nove ferramentas. Cada uma pode ser ativada ou desativada individualmente no separador Definições, e está sujeita ao scope correspondente.

• search_products: pesquisa por palavra-chave, referência ou EAN, com filtros de categoria e preço.
• get_product: ficha detalhada de um produto (preço, stock, combinações, imagens).
• list_categories: árvore de categorias.
• get_shop_info: nome, idiomas, moedas e países servidos.
• get_carriers: transportadoras disponíveis.
• create_cart: criação de um carrinho.
• add_to_cart: adição de um produto ao carrinho.
• view_cart: conteúdo e totais do carrinho.
• create_order: finalização, consoante o modo de encomenda configurado.

Modos de encomenda

O separador Definições propõe dois comportamentos para create_order.

Modo transferência (por defeito)

O agente monta o carrinho e devolve depois um URL de pagamento seguro. Ao segui-lo, o cliente encontra exatamente esse carrinho na sua sessão e finaliza o pagamento no funil habitual do PrestaShop. Nenhum dado de pagamento passa pelo agente: zero exposição PCI.

Modo encomenda

O agente cria diretamente uma encomenda a aguardar pagamento, no estado configurável (por defeito «Aguarda pagamento por transferência bancária»). Pensado para o B2B, o pagamento na entrega ou os orçamentos.

Definições complementares

• Exigir autenticação: recomendado. Um pedido não autenticado aciona o fluxo OAuth (resposta 401 com cabeçalho WWW-Authenticate).
• Leitura anónima do catálogo: autoriza as chamadas catalog:read sem token, para expor um catálogo público.
• Limite de débito: número de pedidos por minuto e por IP (por defeito 120), em janela deslizante.
• Registo e retenção: regista cada pedido (método, ferramenta, estado, duração) no separador Registo de atividade, com um número de linhas conservadas configurável.

Descoberta e pontos de acesso

Os agentes descobrem o servidor automaticamente. Os URL úteis estão listados no separador Ligar um agente:

• Protected Resource Metadata (RFC 9728): /.well-known/oauth-protected-resource.
• Authorization Server Metadata (RFC 8414): /.well-known/oauth-authorization-server.
• Registo dinâmico de cliente (RFC 7591), autorização e token: endpoints OAuth geridos pelo módulo.

Segurança

• Todos os tokens são guardados em hash SHA-256, nunca em claro.
• PKCE S256 obrigatório, redirect_uri validados, códigos de autorização de uso único, rotação dos refresh tokens.
• Limitação de débito por IP e registo de atividade consultável.
• CORS gerido para os conectores web. Compatibilidade nativa com multiloja, multilingue e multimoeda.

Resolução de problemas

• O agente web não se liga: verifique que a loja está em HTTPS e que o OAuth está ativo. Cole o URL /mcp (não uma página do back-office).
• O cliente API devolve 401: o token Bearer está ausente, revogado ou expirado. Crie um novo no separador Tokens de acesso e verifique o cabeçalho Authorization.
• Uma ferramenta não aparece: provavelmente está desativada nas Definições, ou o scope correspondente não foi concedido.
• Erro 429: o limite de débito por IP foi atingido. Aumente o limiar nas Definições, se necessário.
• A ligação de pagamento transferida expira: as ligações de carrinho têm uma duração de vida limitada; peça ao agente para regenerar o carrinho.

Desinstalação

A desinstalação elimina as tabelas do módulo (tokens, clientes OAuth, carrinhos, registo, limitador) e as suas variáveis de configuração. Os seus produtos, clientes e encomendas não são afetados. Para uma simples atualização, basta substituir os ficheiros: o esquema e os tokens existentes são preservados.