mautic-cli: dá mãos ao teu agente de AI no Mautic

O Claude Code, o Codex e o Cursor já leem o teu código, correm os teus testes e abrem pull requests. Pergunta a um deles como correu a newsletter desta manhã, ou pede-lhe que corrija um rótulo num formulário de subscrição, e ele encrava: o Mautic está atrás de uma interface web e de uma REST API que o agente teria de aprender do zero, um curl de cada vez.

O mautic-cli resolve isso. É um cliente de linha de comandos para a REST API do Mautic, acompanhado de uma skill que ensina os agentes de programação a usá-lo, para que o agente trabalhe no Mautic como já trabalha no teu repositório: corre um comando, lê o resultado e confirma o efeito. É open source sob licença MIT, está publicado no PyPI, e usamo-lo nas instâncias de Mautic que operamos.

O que podes pedir

Com a skill instalada, falas com o agente sobre o Mautic em linguagem corrente e ele escolhe os comandos:

• "Como correu o email 296 desde que saiu?" O agente consulta a tabela email_stats desse email e diz-te quem o recebeu e quem o abriu.
• "Exporta toda a gente do segmento VIP para CSV."
• "Muda o rótulo do campo de email no formulário 4, e mostra-me a alteração antes de a enviares."
• "O popup fica cortado no telemóvel. Corrige o CSS e diz-me quantas visualizações e cliques teve desde segunda-feira."
• "Cria um campo Dimensão da empresa e um webhook para contactos novos em staging, e depois faz o mesmo em produção."
• "Acrescenta uma nota ao contacto 42: liguei, não atendeu."

Tudo o que o agente faz é um comando que podes ler na transcrição e voltar a correr tu mesmo.

Porquê uma CLI e não um servidor MCP

Os agentes de programação já têm uma shell, por isso uma CLI não precisa de mais nada: nenhum processo de servidor para manter a correr, nenhuma configuração no cliente. A skill só carrega quando a conversa chega ao Mautic, e no resto do tempo não custa nada ao agente.

A shell também mantém os dados grandes fora do contexto do agente. Com --page-all, cada contacto sai como uma linha de JSON, e o agente passa isso pelo jq ou para um ficheiro e lê só a resposta, não cem mil registos. As pessoas usam os mesmos comandos com --format table.

Se o teu agente não tem shell, uma app de chat no browser por exemplo, um servidor MCP serve-te melhor, e a comunidade já publicou vários para o Mautic.

Edições que o agente consegue verificar

A documentação da API do Mautic descreve o PATCH como uma atualização parcial, que só muda o que o pedido envia. Não é parcial em todos os campos. Num formulário, um PATCH sem postAction repõe-no a return, e quem submete fica no formulário em vez de chegar à página de agradecimento; um campo enviado sozinho é renumerado para o topo do formulário. Descobrimo-lo quando um agente mudou um único rótulo num formulário em produção.

Desde a 0.2.0, o forms edit e o focus edit leem primeiro o item, juntam-lhe a alteração, enviam o item completo e dizem o que mudou, a partir de um GET antes e de um GET depois. Duas chaves extra deixam o agente verificar o próprio trabalho: unexpected lista o que o servidor mudou sem lhe ser pedido, e not_applied o que lhe foi pedido e não mudou, normalmente uma chave mal escrita. A skill diz ao agente que pare e reporte tudo o que aparecer em unexpected antes de fazer mais alguma coisa, e que corra primeiro com --dry-run, para veres a alteração antes de ela seguir.

Salvaguardas

Um agente com mãos também pode partir coisas. Três coisas limitam o que ele pode fazer:

• O agente nunca toca na tua password. A skill diz-lhe que te peça para correres tu o mautic auth setup, que pede o segredo sem o mostrar no ecrã.
• A API do Mautic verifica a role do utilizador autenticado antes de criar, editar, publicar ou apagar o que quer que seja. Dá ao agente um utilizador Mautic só dele, com uma role que permita apenas o que ele precisa.
• Os perfis mantêm as instâncias separadas. O agente trabalha em --profile staging até lhe dizeres o contrário.

A skill traz também armadilhas que verificámos no Mautic 7 e que a documentação não menciona, como campos de escolha cujas opções não aparecem se o syncList não estiver definido. O agente lê-as antes de precisar delas, em vez de as redescobrir no teu formulário em produção.

O que não faz

Desenhar emails e construir campanhas continua a fazer-se nos builders do Mautic; a CLI cria-os e edita-os em JSON. O emails edit continua a ser um PATCH simples, e o Mautic substitui o conteúdo dinâmico de um email pelo texto de exemplo sempre que um PATCH deixa o dynamicContent de fora (reportado em mautic/mautic#17850, com a correção em #17851), por isso a skill diz ao agente que o copie do email atual para cada edição. A escrita de páginas ainda não está coberta. A versão atual foi verificada contra o Mautic 7.1, e clonar campanhas exige o Mautic 7.

Como começar

O mautic-cli corre na tua máquina e fala com o Mautic por HTTPS, por isso não se instala nada no servidor. Ativa a API nas definições do Mautic, com Basic Auth ou OAuth2, e depois instala a CLI e liga-a:

uv tool install mautic-cli
mautic auth setup

Depois acrescenta a skill ao teu agente e pede-lhe que liste os teus contactos do Mautic:

npx skills add bloomidea/mautic-cli

O código está no GitHub e o pacote no PyPI. É uma das pontes de que falámos em Drupal is good for AI use and hard for AI build (em inglês): o agente fica do lado que domina bem, e a ponte absorve a plataforma. Issues e pull requests são bem-vindos.