Vitally

Servidor MCP da Vitally

Um servidor MCP (Model Context Protocol) que fornece acesso aos dados de clientes da Vitally por meio da API da Vitally.

Containerizado

Se você precisar de uma versão containerizada, confira github.com/fiscaltec/vitally-mcp

Recursos

• Listar contas de clientes como recursos
• Ler detalhes da conta
• Buscar usuários por e-mail ou ID externo
• Encontrar contas pelo nome
• Consultar pontuações de saúde da conta
• Visualizar conversas e tarefas da conta
• Criar notas para contas
• Pesquisar entre as ferramentas disponíveis
• Modo demo com dados simulados quando nenhuma chave de API é fornecida

Configuração

1. Instale as dependências:

   npm install
   

2. Crie um arquivo .env no diretório raiz com o seguinte conteúdo:

   # Vitally API Configuration
   VITALLY_API_SUBDOMAIN=nylas  # Your Vitally subdomain
   VITALLY_API_KEY=your_api_key_here  # Your Vitally API key
   VITALLY_DATA_CENTER=US  # or EU depending on your data center
   

3. Compile o projeto:

   npm run build
   

Nota: Se você ainda não tem uma chave de API da Vitally, o servidor será executado em modo demo com dados simulados.

Obtendo sua chave de API da Vitally

1. Navegue até sua conta Vitally
2. Vá para Configurações (⚙️) > Integrações > API REST
3. Ative o interruptor para habilitar a integração
4. Copie a chave de API

Uso

Há duas maneiras de usar este servidor MCP:

Usando o MCP Inspector

Execute o MCP Inspector para testar e depurar o servidor:

npm run inspector

Isso abrirá a interface do MCP Inspector onde você pode interagir com seu servidor.

Conectar ao Claude Desktop

1. Primeiro, encontre o arquivo de configuração do Claude Desktop:

   • No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • No Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Edite o arquivo de configuração para adicionar o servidor MCP da Vitally:

   {
     "mcpServers": {
       "vitally-api": {
         "command": "node",
         "args": ["--experimental-modules", "--experimental-specifier-resolution=node", "/Users/johnjung/nylas/vitally/vitally/build/index.js"]
       }
     }
   }
   

3. Reinicie o Claude Desktop e você poderá usar o servidor MCP da Vitally.

Ferramentas Disponíveis

Descoberta de Ferramentas

• search_tools - Pesquisar ferramentas disponíveis por palavra-chave

Gerenciamento de Contas

• search_accounts - Pesquisar contas usando múltiplos critérios (nome, externalId)
• find_account_by_name - Encontrar contas pelo nome (correspondência parcial suportada)
• refresh_accounts - Atualizar a lista em cache de contas
• get_account_health - Obter pontuações de saúde para uma conta específica

Gerenciamento de Usuários

• search_users - Pesquisar usuários por e-mail, ID externo ou subdomínio de e-mail

Comunicação e Tarefas

• get_account_conversations - Obter conversas recentes de uma conta
• get_account_tasks - Obter tarefas de uma conta (pode filtrar por status)
• create_account_note - Criar uma nova nota para uma conta

Exemplos de Perguntas para Fazer

Quando conectado a um cliente MCP como o Claude, você pode fazer perguntas como:

• "Liste todos os nossos clientes"
• "Encontre contas com 'Acme' no nome"
• "Qual é a pontuação de saúde da conta X?"
• "Encontre o usuário com e-mail example@company.com"
• "Mostre-me detalhes sobre o cliente Y"
• "Obtenha conversas recentes da conta Z"
• "Quais tarefas estão abertas para a conta A?"
• "Adicione uma nota à conta B sobre nossa chamada recente"
• "Quais ferramentas posso usar para gerenciamento de contas?"

Solução de Problemas

• Se você encontrar erros de análise JSON, certifique-se de ter removido todas as instruções console.log do código
• Certifique-se de que seu arquivo .env contém as credenciais de API corretas
• Verifique se você compilou o projeto (npm run build) após fazer alterações
• Verifique se o caminho em claude_desktop_config.json é absoluto e correto para o seu sistema
• Se você não tiver uma chave de API válida, o servidor será executado em modo demo com dados simulados