@leonidasjf/mcp-client

v1.0.5

Published

2 months ago

MCP client configuration

0High
0Medium
0Low

leonidasjf

mcp client

🚀 SenseData MCP — Sistema Completo de Customer Success

MCP Server que permite que qualquer IA (ChatGPT, Claude, etc) interaja com a plataforma SenseData através de perguntas em linguagem natural

📋 O que este MCP faz?

Este é um servidor MCP (Model Context Protocol) que transforma perguntas simples em análises complexas de Customer Success:

✅ Análise automática de risco de churn - Identifica clientes em risco e explica os motivos
✅ Visão 360° do cliente - Financeiro, satisfação, suporte, engajamento em uma única resposta
✅ Perguntas em linguagem natural - "Como está o cliente X?" e recebe análise completa
✅ Comparação de clientes - Compara métricas entre múltiplos clientes
✅ Alertas inteligentes - Identifica problemas e sugere ações
✅ Acesso a todos os dados - Clientes, contratos, NPS, tickets, KPIs, jornadas, etc

🎯 Para Leigos: Como Usar

Basta fazer perguntas naturais para uma IA conectada a este MCP:

Exemplos de perguntas que funcionam:

"Como está o cliente TechCorp?"
"Quais clientes estão em risco de churn?"
"O cliente Acme está inadimplente?"
"Comparar TechCorp e SoftInc"
"Qual foi o último NPS da empresa XYZ?"
"Resumo das tarefas de hoje"
"Quantos dias desde o último contato com o cliente ABC?"

A IA responde automaticamente com:

Status do cliente
Risco de churn calculado automaticamente
Situação financeira (MRR, inadimplência)
Satisfação (NPS, promotores/detratores)
Suporte (tickets abertos)
Engajamento (última atividade, dias sem contato)

🚀 Instalação Rápida

⚡ 3 Comandos e Pronto!

# 1. Clone o repositório
git clone https://github.com/leonidasjf/mcp-sensedata.git && cd mcp-sensedata

# 2. Execute o instalador (pede credenciais de forma segura)
chmod +x install.sh && ./install.sh

# 3. Inicie o servidor
npm run start

🎉 Instalação completa e segura!

O instalador:

✅ Verifica pré-requisitos (Node.js 18+)
✅ Pede suas credenciais interativamente (nunca expõe no código)
✅ Gera API Key automática (256-bit segura)
✅ Testa a conexão com SenseData
✅ Compila o projeto

🚀 Deploy em Produção (Opcional)

Para rodar com PM2 + Nginx + SSL:

./deploy.sh

Configura automaticamente:

✅ PM2 (gerenciamento de processos)
✅ Nginx (proxy reverso com rate limiting)
✅ SSL/HTTPS (Let's Encrypt)
✅ Auto-restart no boot

📖 Guia completo de instalação →

🔐 SSL/HTTPS rápido

O deploy.sh usa emissão via webroot (mais robusta) e cria a rota /.well-known/acme-challenge/.
Pré-requisitos: domínio apontando pro servidor e porta 80 liberada.
Durante o deploy, valide a URL de teste que o script informa. Se responder, o SSL é emitido e aplicado automaticamente.
Mais detalhes em INSTALL.md (seção SSL/HTTPS).

🔧 Instalação Manual (Opcional)

1. Instalar dependências

npm install

2. Configurar credenciais

Crie um arquivo .env:

cp .env.example .env
nano .env

Preencha:

SENSEDATA_TOKEN=seu_token_aqui
SENSEDATA_BASE_URL=https://api.sensedata.io
MCP_API_KEY=$(openssl rand -hex 32)  # Gere uma chave segura
PORT=3333

3. Build e Start

npm run build
npm run start

O servidor vai iniciar em http://localhost:3333

📡 Endpoints Disponíveis

1. Health Check

GET /health
# Retorna: { "ok": true }

2. Listar Ferramentas

GET /mcp/tools
# Retorna lista de todas as ferramentas disponíveis (40+ ferramentas)

3. Consultas Inteligentes (Recomendado para IAs)

POST /mcp/query
Content-Type: application/json

# Análise completa de um cliente
{
  "customerName": "TechCorp"
}

# Lista de clientes em risco
{
  "riscoMinimo": "Médio"
}

# Comparar clientes
{
  "customerNames": ["TechCorp", "SoftInc", "DataCo"]
}

# Pergunta em linguagem natural
{
  "pergunta": "Quais clientes não foram contatados há mais de 60 dias?"
}

# Resumo do dia
{}

4. Ferramentas Diretas

POST /mcp/tools/{nome_ferramenta}/call
Content-Type: application/json

{
  "arguments": {
    "limit": 10,
    "page": 1,
    "customer:id": [123]
  }
}

💡 Exemplos Práticos

Exemplo 1: Análise Completa de Cliente

Pergunta:

curl -X POST http://localhost:3333/mcp/query \
  -H "Content-Type: application/json" \
  -d '{"customerName": "TechCorp Sistemas"}'

Resposta:

{
  "ok": true,
  "data": {
    "resumo": {
      "nome": "TechCorp Sistemas LTDA",
      "status": "Ativo",
      "cs": "Maria Silva",
      "csm": "João Santos",
      "riscoChurn": "Médio",
      "motivosRisco": [
        "45 dias sem contato",
        "2 tickets abertos com prioridade alta"
      ]
    },
    "financeiro": {
      "mrr": "R$ 5.000,00",
      "contratoAtivos": 2,
      "inadimplente": false,
      "valorVencido": "R$ 0,00"
    },
    "satisfacao": {
      "ultimoNPS": {
        "nota": 8,
        "status": "promoter",
        "data": "2024-10-01",
        "comentario": "Excelente produto!"
      },
      "resumoNPS": "3 promotores, 1 neutros, 0 detratores",
      "mediaScore": "8.5"
    },
    "suporte": {
      "ticketsAbertos": 2,
      "ticketsTotal": 15,
      "ticketsRecentes": [...]
    },
    "engajamento": {
      "diasSemContato": 45,
      "atividadesUltimos30Dias": 8,
      "ultimasAtividades": [...]
    },
    "healthScore": {
      "valor": 75,
      "data": "2024-10"
    }
  }
}

Exemplo 2: Clientes em Risco

curl -X POST http://localhost:3333/mcp/query \
  -H "Content-Type: application/json" \
  -d '{"riscoMinimo": "Médio"}'

Exemplo 3: Usar Ferramenta Específica

# Listar últimos NPSs
curl -X POST http://localhost:3333/mcp/tools/nps_list/call \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "limit": 10,
      "nps_status": ["detractor"],
      "ref_date:start": "2024-10-01"
    }
  }'

# Buscar tickets abertos
curl -X POST http://localhost:3333/mcp/tools/support_tickets_list/call \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "status": ["Aberto", "Em Andamento"],
      "priority": ["Alta", "Crítica"]
    }
  }'

🤖 Integração com IAs

Para ChatGPT / Claude / Outras IAs

Configure este MCP server para rodar
Registre os endpoints do MCP na sua IA
A IA pode fazer perguntas naturais e receber respostas completas

Recomendação: Use sempre o endpoint /mcp/query para análises complexas, pois ele já faz:

Cálculo automático de risco de churn
Agregação de múltiplas fontes de dados
Formatação de respostas contextualizadas

📊 Ferramentas Disponíveis (40+)

👥 Clientes

customers_list / customer_get - Listar e buscar clientes
customers_notes_list - Notas sobre clientes

📝 Contratos & Financeiro

contracts_list / contract_get - Contratos e MRR
billing_list / billing_get - Faturas e inadimplência

📞 Contatos

contacts_list / contact_get - Contatos, sponsors, e-mails

📊 Satisfação

nps_list / nps_get - Pesquisas NPS (promotores/detratores)

🎫 Suporte

support_tickets_list / support_ticket_get - Tickets e chamados

📈 Métricas

kpis_list / kpi_get - Health score, faturamento, uso

🎯 Atividades

tasks_list / task_get - Tarefas, reuniões, tratativas

🗺️ Jornadas

journeys_list - Jornadas configuradas
journeys_customers_list - Clientes nas jornadas
journeys_logs_list - Movimentações

🎮 Playbooks & Usuários

playbooks_list / playbook_get - Templates de atividades
users_list / user_get - Usuários (CS, CSM, etc)

🧠 Como o Sistema Calcula Risco de Churn

O sistema analisa automaticamente e classifica risco com base em:

| Fator | Risco Alto | Risco Médio | |-------|-----------|-------------| | NPS | Mais detratores que promotores | - | | Financeiro | Inadimplente | - | | Suporte | - | Mais de 3 tickets abertos | | Engajamento | Mais de 60 dias sem contato | 30-60 dias sem contato | | Status | Cliente inativo/churned | - |

🔧 Arquitetura

┌─────────────┐
│     IA      │ (ChatGPT, Claude, etc)
└──────┬──────┘
       │
       │ Pergunta: "Cliente X está em risco?"
       │
       v
┌─────────────────────┐
│   MCP Server        │
│  (server.ts)        │
├─────────────────────┤
│                     │
│  high-level.ts      │ ← Análises automáticas
│  - analisarCliente  │   Calcula risco, agrega dados
│  - listarRiscos     │
│  - compararClientes │
│                     │
└──────┬──────────────┘
       │
       │ Chama múltiplas APIs
       v
┌─────────────────────┐
│  API SenseData      │
│  /v2/customers      │
│  /v2/nps            │
│  /v2/tasks          │
│  /v2/billing        │
│  /v2/support_tickets│
│  ... etc            │
└─────────────────────┘

🐛 Tratamento de Erros

O sistema tem tratamento robusto de erros:

❌ Cliente não encontrado: Busca inteligente com fuzzy matching
❌ Token inválido: Mensagem clara sobre configuração
❌ API indisponível: Retorna erro detalhado
❌ Ferramenta não encontrada: Lista ferramentas disponíveis

📝 Logs e Debug

O servidor loga todas as requisições automaticamente. Para ver logs:

npm run start
# Logs aparecem no console

🔐 Segurança

Token de autenticação obrigatório via variável de ambiente
Não expõe credenciais nos logs
Valida todas as entradas

🤝 Contribuindo

Quer adicionar novas análises ou ferramentas?

Adicione novas ferramentas em tools-extended.json
Crie novas funções de alto nível em high-level.ts
Atualize a documentação

📄 Uso e Distribuição

Este projeto é para uso interno e não será publicado no npm ("private": true).

Para usar:

Clone ou copie o projeto
Configure o .env com seu token
Execute npm install && npm run start

Feito com ❤️ para Customer Success