Ligar um assistente de IA (MCP)

A aplicação executa um servidor MCP, pelo que um assistente de IA pode analisar a sua configuração, criar e traduzir layouts de e-mail, gerir os seus pedidos HTTP e organizar a sua biblioteca multimédia diretamente, em vez de ter de estar sempre a copiar a configuração de um lado para o outro.

Funções úteis que pode realizar: elaborar um modelo de marketing com os seus textos de rodapé, traduzir um modelo para todas as línguas em que comercializa os seus produtos, verificar quais os modelos de e-mail que fazem referência a um código secreto prestes a ser alterado, identificar todas as imagens carregadas que já não são utilizadas por nenhum modelo, explicar por que razão os envios de ontem falharam ou criar um novo pedido HTTP a partir da documentação de uma API de terceiros.

Ponto final

POST https://shopify.workflow-transactional-email.app/api/mcp

O transporte é feito através de Streamable HTTP. A autenticação é feita com a mesma chave «bearer» da API REST - consulte Autenticação e chaves de API.

A ligar

O separador «MCP» na página «Desenvolvedor» da aplicação gera um comando pronto a copiar, com o seu URL e a sua chave já preenchidos, para o Claude, o Claude Desktop, o Cursor, o VS Code e o Gemini CLI. Utilize-o em vez de o escrever manualmente.

No Claude Code, o comando tem o seguinte aspeto:

claude mcp add --transport http flow-transactional-email \
  https://shopify.workflow-transactional-email.app/api/mcp \
  --header "Authorization: Bearer fak_your_key_here"

No caso dos editores que utilizam uma configuração JSON, o formato é o seguinte:

{
  "mcpServers": {
    "flow-transactional-email": {
      "url": "https://shopify.workflow-transactional-email.app/api/mcp",
      "headers": {
        "Authorization": "Bearer fak_your_key_here"
      }
    }
  }
}

Ferramentas disponíveis

O conjunto de ferramentas reflete o nível da sua chave. Uma chave de leitura exclusiva não é simplesmente recusada quando invoca uma ferramenta de escrita - essa ferramenta nem sequer aparece na lista, pelo que não é possível convencer um assistente a tentar utilizá-la.

Leia (15 ferramentas)

Modelos de e-mail: list_email_templates, get_email_template, get_layout_schema, list_template_translations, list_template_versions, get_template_version. O endereço list_email_templates aceita q, category (transactional ou marketing), page e limit.

Remetentes de e-mail: list_smtp_configs, list_senders

Segredos: list_secret_keys (apenas nomes)

Pedidos HTTP: list_http_requests, get_http_request

Mídia: list_files (introduza usage: true para ver o que ainda faz referência a cada ficheiro)

Histórico: list_history (filtrar por status, incluindo SKIPPED para e-mails de marketing cujos destinatários se tenham, na totalidade, cancelado a subscrição), get_history_entry, get_stats

Leitura e escrita (soma de 12)

Modelos de e-mail: create_email_template, update_email_template, delete_email_template

Idiomas: set_template_translation, delete_template_translation, promote_template_translation

Versões: restore_template_version, restore_template_github_version

Pedidos HTTP: create_http_request, update_http_request, delete_http_request

Meios de comunicação: delete_file

Ler, escrever e executar (adiciona 1)

test_http_request - executa um pedido HTTP configurado junto do alvo real.

Criação de plantas de edifícios com a ajuda de um assistente

Peça ao assistente para ler primeiro get_layout_schema: este documento descreve o formato de design visual com as predefinições de cada bloco, o Liquid que pode utilizar e os limites, gerados pelo próprio construtor. Em seguida, create_email_template aceita um name, um subject e um bodyDesign (visual, a predefinição) ou um HTML body (texto). O layout aparece imediatamente na aplicação e todas as alterações são guardadas no histórico de versões, pelo que nada do que um assistente fizer é irreversível.

Existem dois campos que determinam o comportamento de um layout num e-mail:

• category: transactional (por predefinição) ou marketing. Um modelo de marketing exclui os destinatários que cancelaram a subscrição e inclui um link para cancelar a subscrição e um rodapé; consulte E-mails de marketing e cancelamentos de subscrição.
• marketingTexts: os textos do rodapé de um layout de marketing, em vez dos da loja, definidos em «Definições», { unsubscribeText, unsubscribeLinkLabel, companyDetails }; todos os campos são opcionais; null significa os textos das «Definições». A frase de cancelamento de subscrição deve conter {{ unsubscribe_link }} ou {{ unsubscribe_url }}.

set_template_translation cria ou substitui um idioma pelo conteúdo totalmente traduzido. No caso de um layout de texto, também pode incluir attachments (a list = ficheiros próprios deste idioma, null = os do layout, «omitted» = inalterado), e, no caso de um layout de marketing, marketingTexts para esse idioma, para além dos do layout. promote_template_translation define um idioma como o idioma principal do layout; os dois trocam de lugar, pelo que nada se perde.

Um bom primeiro pedido:

«Leia o esquema do layout e, em seguida, traduza o meu layout «Pedido enviado» para alemão e francês. Mantenha todas as tags Liquid e os URLs exatamente como estão.»

Cada gravação é verificada tal como um processo de gravação na aplicação: o Liquid tem de analisar os ficheiros, estes têm de ser da sua autoria e a ferramenta indica o campo em que ocorreu a falha.

Organizar a biblioteca multimédia

Uma boa forma de utilizar um assistente. Peça-lhe para listar os seus ficheiros, indicando a sua utilização, e, em seguida, elimine aqueles a que nada faz referência:

«Apresente-me uma lista dos ficheiros que carreguei, indicando a sua utilização, e indique-me quais não estão a ser utilizados por nada. Em seguida, elimine esses ficheiros.»

delete_file é recusado com um erro 409 se algum layout de e-mail ou predefinição de cabeçalho/rodapé ainda fizer referência ao ficheiro, e a recusa indica o que o está a utilizar - pelo que o assistente não pode remover um logótipo de que um e-mail ativo ainda necessita, mesmo que lhe peça para o fazer.

O que o assistente nunca pode ver

Não existe, deliberadamente, nenhuma ferramenta que devolva um valor secreto, um nome de utilizador ou palavra-passe SMTP, nem um token de início de sessão na caixa de correio. O comando list_secret_keys devolve apenas nomes.

É esse o objetivo do design: pode pedir a um assistente que crie um pedido HTTP que efetue a autenticação junto do seu prestador de serviços de pagamento, e este irá referenciar {{ secrets.stripeApiKey }} corretamente, sem que a própria chave entre, em momento algum, no contexto do modelo.

O histórico devolvido através do MCP é mascarado exatamente da mesma forma que no REST. Aplica-se a mesma ressalva: a mascaragem funciona em nomes de campos e padrões de valores, e os campos de texto livre podem continuar a conter dados pessoais na conversa. Tenha isso em consideração antes de indicar a um assistente um intervalo alargado do histórico.