Mautic

Integra com a plataforma de automação de marketing Mautic.

Documentação

Mautic MCP Server

Um servidor abrangente do Model Context Protocol (MCP) para a plataforma de automação de marketing Mautic 7 (Columba Edition). Suporta endpoints v1 (FOSRestBundle) e v2 (API Platform) com 68 ferramentas.

Início Rápido

# Clone and setup
git clone https://github.com/Cbrown35/mantic-MCP.git
cd mantic-MCP
npm install

# Configure your Mautic credentials
cp .env.example .env
# Edit .env with your Mautic API credentials

# Build and run
npm run build

Em seguida, adicione o servidor à sua configuração MCP e comece a usar comandos em linguagem natural, como:

"Buscar todos os contatos com gmail no email"
"Criar um novo projeto para organizar os recursos da minha campanha do Q1"
"Clonar a campanha 5 e exportá-la para staging"
"Enviar o modelo de email 12 para o segmento atribuído"

Novidades na v2.0 (Suporte ao Mautic 7)

Projetos (API v2)

Organize recursos de marketing sob uma única estrutura lógica usando os novos endpoints do API Platform v2 do Mautic 7.

list_projects, get_project, create_project, update_project, patch_project, delete_project

Importação/Exportação de Campanhas

Mova configurações completas de campanhas entre ambientes.

clone_campaign - Clonar uma campanha existente
export_campaign - Exportar dados da campanha com todos os ativos relacionados
import_campaign - Importar uma campanha a partir de dados JSON

Análises de Campanha

get_campaign_event_details - Métricas detalhadas para eventos de campanha
get_campaign_graph_stats - Estatísticas de gráfico de campanha para intervalos de datas
get_campaign_map_stats - Estatísticas de mapa geográfico

Envio de Email Baseado em Segmentos

send_email_to_segment - Enviar email para segmentos atribuídos com adaptação de audiência em tempo real

Rastreamento de Respostas de Email

record_email_reply - Registrar respostas de email por hash de rastreamento
get_email_graph_stats - Estatísticas de gráfico de email para intervalos de datas

Aviso de Descontinuação

As classes da API SMS foram removidas no Mautic 7. As ferramentas list_sms e create_sms incluem avisos de descontinuação.

Recursos

Autenticação

Autenticação OAuth2 com renovação automática de token
Gerenciamento seguro de credenciais por meio de variáveis de ambiente
Suporte a API dupla: v1 (FOSRestBundle) e v2 (API Platform)

Gerenciamento de Contatos (6 ferramentas)

create_contact - Criar novos contatos com campos personalizados
update_contact - Atualizar informações de contatos existentes
get_contact - Recuperar detalhes do contato por ID ou email
search_contacts - Buscar contatos com filtros e paginação
delete_contact - Remover contatos do Mautic
add_contact_to_segment - Adicionar contatos a segmentos específicos

Gerenciamento de Campanhas (13 ferramentas)

list_campaigns - Obter todas as campanhas com status e estatísticas
get_campaign - Obter informações detalhadas da campanha
create_campaign - Criar novas campanhas
add_contact_to_campaign - Adicionar contatos a campanhas
create_campaign_with_automation - Criar campanhas com automação completa de eventos
execute_campaign - Executar/disparar campanhas manualmente
get_campaign_contacts - Obter contatos em uma campanha com seus status
clone_campaign - Clonar uma campanha existente (Mautic 7)
export_campaign - Exportar dados da campanha com ativos (Mautic 7)
import_campaign - Importar campanha a partir de dados JSON (Mautic 7)
get_campaign_event_details - Métricas de eventos de campanha (Mautic 7)
get_campaign_graph_stats - Estatísticas de gráfico de campanha (Mautic 7)
get_campaign_map_stats - Estatísticas geográficas de campanha (Mautic 7)

Operações de Email (8 ferramentas)

send_email - Enviar emails para contatos específicos
list_emails - Obter todos os modelos de email e campanhas
get_email - Obter informações detalhadas do email
create_email_template - Criar novos modelos de email
get_email_stats - Obter estatísticas de desempenho do email
send_email_to_segment - Enviar email para segmentos (Mautic 7)
record_email_reply - Registrar resposta de email por hash de rastreamento (Mautic 7)
get_email_graph_stats - Estatísticas de gráfico de email (Mautic 7)

Gerenciamento de Formulários (3 ferramentas)

list_forms - Obter todos os formulários com contagens de envios
get_form - Obter detalhes e campos do formulário
get_form_submissions - Obter dados de envios de formulário

Gerenciamento de Segmentos (3 ferramentas)

list_segments - Obter todos os segmentos de contatos
create_segment - Criar novos segmentos de contatos com filtros
get_segment_contacts - Obter contatos em um segmento específico

Gerenciamento de Conteúdo (7 ferramentas)

list_assets - Obter todos os ativos (PDFs, imagens, documentos)
get_asset - Obter detalhes do ativo por ID
create_asset - Criar novos ativos (locais ou remotos)
list_pages - Obter todas as landing pages
create_page - Criar novas landing pages
list_sms - Obter todos os modelos de SMS [DESCONTINUADO no Mautic 7]
create_sms - Criar modelos de SMS [DESCONTINUADO no Mautic 7]

Entidades de Negócio (10 ferramentas)

list_companies - Obter todas as empresas
create_company - Criar novas empresas
add_contact_to_company - Associar contatos a empresas
create_note - Adicionar notas a contatos ou empresas
get_contact_notes - Obter todas as notas de um contato
list_tags - Obter todas as tags disponíveis
create_tag - Criar novas tags
add_contact_tags - Adicionar tags a contatos
list_categories - Obter todas as categorias
create_category - Criar novas categorias

Recursos Avançados (7 ferramentas)

add_contact_points - Adicionar pontos a contatos
subtract_contact_points - Subtrair pontos de contatos
list_stages - Obter todos os estágios do ciclo de vida
change_contact_stage - Alterar o estágio do ciclo de vida do contato
list_contact_fields - Obter todos os campos personalizados de contato
create_contact_field - Criar novos campos personalizados de contato
get_contact_activity - Obter histórico de interações do contato

Integração e Automação (5 ferramentas)

list_webhooks - Obter todos os webhooks
create_webhook - Criar novos webhooks
upload_file - Enviar arquivos para o Mautic
list_reports - Obter todos os relatórios
create_report - Criar relatórios personalizados

Gerenciamento de Projetos - API v2 (6 ferramentas, Mautic 7)

list_projects - Listar todos os projetos
get_project - Obter detalhes do projeto
create_project - Criar um novo projeto
update_project - Atualizar completamente um projeto existente
patch_project - Atualizar parcialmente um projeto
delete_project - Excluir um projeto

Instalação

Pré-requisitos

Node.js (v16 ou superior)
npm ou yarn
Acesso a uma instância do Mautic 7 com credenciais de API

Configuração

Clonar o repositório:

git clone https://github.com/Cbrown35/mantic-MCP.git
cd mantic-MCP

Instalar dependências:
```
npm install
```

Configurar variáveis de ambiente:

cp .env.example .env

Edite o .env e preencha suas credenciais da API do Mautic:

MAUTIC_BASE_URL=https://your-mautic-instance.com/api/
MAUTIC_CLIENT_ID=your_client_id_here
MAUTIC_CLIENT_SECRET=your_client_secret_here
MAUTIC_TOKEN_ENDPOINT=https://your-mautic-instance.com/oauth/v2/token

Compilar o servidor:
```
npm run build
```

Configurar as configurações do MCP: Adicione o servidor ao seu arquivo de configuração MCP:

{
  "mcpServers": {
    "mautic-server": {
      "command": "node",
      "args": ["/path/to/mautic-server/build/index.js"],
      "env": {
        "MAUTIC_BASE_URL": "https://your-mautic-instance.com/api/",
        "MAUTIC_CLIENT_ID": "your_client_id",
        "MAUTIC_CLIENT_SECRET": "your_client_secret",
        "MAUTIC_TOKEN_ENDPOINT": "https://your-mautic-instance.com/oauth/v2/token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Arquitetura

Suporte a API Dupla

O Mautic 7 possui uma arquitetura de API em três camadas:

Camada	Finalidade	Endpoints
API Platform 4.x	Novos endpoints REST v2 (JSON-LD/Hydra)	`/api/v2/projects`
FOSRestBundle	Endpoints v1 existentes	`/api/contacts`, `/api/campaigns`, etc.
FOSOAuthServerBundle	Autenticação OAuth2	`/oauth/v2/token`

O servidor MCP gerencia automaticamente ambas as versões da API. Os endpoints v1 usam o MAUTIC_BASE_URL configurado diretamente, enquanto os endpoints v2 são derivados automaticamente.

Estrutura do Projeto

src/
├── index.ts              # Entry point: server setup and startup
├── types/                # TypeScript interfaces
│   ├── common.ts         # Shared types (OAuth2Token, ToolResult, etc.)
│   ├── contacts.ts       # MauticContact interface
│   ├── campaigns.ts      # MauticCampaign interface
│   ├── emails.ts         # MauticEmail interface
│   ├── forms.ts          # MauticForm interface
│   ├── segments.ts       # MauticSegment interface
│   └── projects.ts       # MauticProject interface (Mautic 7)
├── api/
│   └── client.ts         # Dual API client (v1 + v2) with OAuth2
└── tools/
    ├── index.ts           # Tool registry and dispatch
    ├── contacts.ts        # Contact tools
    ├── campaigns.ts       # Campaign tools (includes Mautic 7 additions)
    ├── emails.ts          # Email tools (includes Mautic 7 additions)
    ├── forms.ts           # Form tools
    ├── segments.ts        # Segment tools
    ├── projects.ts        # Project tools (Mautic 7 API v2)
    ├── content.ts         # Asset, page, and SMS tools
    ├── business.ts        # Company, note, tag, and category tools
    ├── advanced.ts        # Points, stages, fields, and activity tools
    └── integration.ts     # Webhook, file, and report tools

Configuração

Variáveis de Ambiente

Variável	Descrição	Exemplo
`MAUTIC_BASE_URL`	URL base da API do Mautic	`https://your-mautic.com/api/`
`MAUTIC_CLIENT_ID`	ID do Cliente OAuth2	`1_abc123...`
`MAUTIC_CLIENT_SECRET`	Segredo do Cliente OAuth2	`secret123...`
`MAUTIC_TOKEN_ENDPOINT`	Endpoint de Token OAuth2	`https://your-mautic.com/oauth/v2/token`

Obtendo Credenciais da API do Mautic

Faça login na sua instância do Mautic como administrador
Acesse Configurações > Configuração > Configurações de API
Habilite o acesso à API
Acesse Configurações > Credenciais da API
Crie uma nova credencial de API com autorização OAuth2
Anote o ID do Cliente e o Segredo do Cliente

Tratamento de Erros

O servidor inclui tratamento abrangente de erros:

Renovação automática de token OAuth2
Mensagens de erro detalhadas dos formatos de API v1 e v2
Tratamento adequado de falhas de autenticação
Lógica de repetição para erros transitórios

Segurança

Todas as credenciais são armazenadas como variáveis de ambiente
Tokens OAuth2 são renovados automaticamente
Nenhum dado sensível é registrado ou exposto
Comunicação HTTPS segura com a API do Mautic

Desenvolvimento

Para modificar ou estender o servidor:

Edite o código-fonte no diretório src/
Adicione novas ferramentas criando um arquivo em src/tools/ e importando-o em src/tools/index.ts
Compile o servidor: npm run build
Teste com o MCP Inspector: npm run inspector

Contribuição

Aceitamos contribuições! Consulte o repositório para obter as diretrizes de contribuição.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

Construído com o Model Context Protocol SDK v1.26.0
Integra-se com o Mautic 7 (Columba Edition)