CRM MCP Server

Um servidor MCP pronto para produção, voltado para funcionalidades de Gestão de Relacionamento com o Cliente (CRM), construído com TypeScript e SQLite.

GitHub

Documentação

CRM MCP Server

Um servidor Model Context Protocol (MCP) pronto para produção para funcionalidades de Customer Relationship Management (CRM), construído com TypeScript e SQLite.

🚀 Recursos

Ferramentas Principais de CRM (18 no total)

Gerenciamento de Contatos: Adicionar, atualizar, pesquisar, listar e arquivar contatos
Gerenciamento de Organizações: Filtrar contatos por organização
Histórico de Contatos: Rastrear, atualizar e gerenciar interações, ligações, e-mails, reuniões e anotações
Gerenciamento de Entradas: Operações CRUD completas nas entradas do histórico de contatos
Gerenciamento de Tarefas: Adicionar, atualizar, filtrar e rastrear itens de ação para contatos
Exportação de Dados: Exportações em CSV para contatos, histórico e dados completos do CRM
Atividades Recentes: Rastrear e recuperar atividades recentes do CRM

Excelência Técnica

✅ 100% de Cobertura de Testes - Suíte de testes abrangente em 3 fases com isolamento de banco de dados
✅ Pronto para Produção - Tratamento robusto de erros e validação de entrada
✅ Alto Desempenho - Otimizado para operações em lote e grandes conjuntos de dados
✅ Foco em Segurança - Proteção contra injeção de SQL e sanitização de entrada
✅ Tratamento de Casos Extremos - Condições de contorno testadas de forma abrangente
✅ Gerenciamento de Banco de Dados - Sistema seguro de arquivamento/restauração com zero perda de dados
✅ Gerenciamento de Entradas - CRUD completo do histórico de contatos com scripts de banco de dados
✅ Testes Modulares - Fases de teste isoladas com gerenciamento automático de estado

📦 Instalação

Pré-requisitos

Node.js 18+
npm ou yarn

Configuração

# Clone the repository
git clone <repository-url>
cd mcp-crm

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm run start:crm

🔧 Configuração

Integração MCP

Adicione ao seu .cursor/mcp.json ou configuração do cliente MCP:

{
  "mcpServers": {
    "mcp-crm": {
      "command": "node",
      "args": ["./build/crm-server.js"],
      "cwd": "/path/to/mcp-crm"
    }
  }
}

Banco de Dados

Localização: data/crm.sqlite
Tipo: SQLite 3
Criação Automática: O banco de dados e as tabelas são inicializados automaticamente
Ignorado pelo Git: Arquivos de banco de dados e arquivos de arquivamento são excluídos do controle de versão por segurança e tamanho

🗄️ Gerenciamento de Banco de Dados

O sistema CRM inclui comandos poderosos de gerenciamento de banco de dados para redefinir, arquivar e restaurar seus dados com segurança.

Comandos Rápidos

# Reset database (archive current, create fresh)
npm run db:reset

# Archive current database (backup without reset)
npm run db:archive

# List all archived databases
npm run db:list

# Show current database statistics
npm run db:stats

# Contact entry management
npm run db:list-entries        # List all contact entries
npm run db:list-entries 1      # List entries for contact ID 1
npm run db:list-entries "" 10  # List 10 most recent entries (all contacts)
npm run db:view-entry 1        # View detailed entry
npm run db:delete-entry 1      # Delete entry by ID
npm run db:update-entry 1 content "Updated content"  # Update entry field

# Show help for database commands
npm run db:help

Uso Detalhado

Redefinir Banco de Dados

Arquiva com segurança seu banco de dados atual e cria um novo vazio.

# Basic reset
npm run db:reset

# Reset with reason (helpful for tracking)
npm run db:reset cleanup
npm run db:reset "testing-new-features"

O que acontece:

📦 O banco de dados atual é arquivado com carimbo de data/hora
🗑️ O banco de dados atual é removido
✅ Um novo banco de dados vazio é criado
🛡️ Seus dados são preservados com segurança nos arquivos

Arquivar Banco de Dados

Crie um backup sem redefinir (mantém o banco de dados atual).

# Basic archive
npm run db:archive

# Archive with reason
npm run db:archive "before-major-update"

Listar Arquivos

Visualize todos os seus backups de banco de dados.

npm run db:list

Exemplo de saída:

📦 Database Archives
==================================================
📁 crm-backup-2025-06-04T19-15-35-cleanup.sqlite
   Created: 6/4/2025, 7:15:35 PM
   Size: 45.32 KB
   Path: /data/archives/crm-backup-2025-06-04T19-15-35-cleanup.sqlite

📁 crm-backup-2025-06-03T14-22-18.sqlite
   Created: 6/3/2025, 2:22:18 PM
   Size: 42.17 KB
   Path: /data/archives/crm-backup-2025-06-03T14-22-18.sqlite

Restaurar a partir de Arquivo

Restaure um banco de dados anterior a partir do arquivo.

npm run db:list  # First, see available archives
# Then restore specific archive (replace with actual filename):
npx tsx scripts/database-manager.ts restore crm-backup-2025-06-04T19-15-35.sqlite

O que acontece:

📦 O banco de dados atual é arquivado (backup de segurança)
🔄 O arquivo selecionado é restaurado como banco de dados atual
✅ Seus dados voltam ao estado arquivado

Estatísticas do Banco de Dados

Verifique o status atual do seu banco de dados.

npm run db:stats

Exemplo de saída:

📊 Current Database Statistics
==================================================
Contacts: 546
Entries: 1,234
Size: 45.32 KB

Gerenciamento de Entradas de Contato

Gerencie entradas do histórico de contatos com operações CRUD completas.

# List contact entries
npm run db:list-entries                    # All entries (newest first)
npm run db:list-entries 1                  # All entries for contact 1
npm run db:list-entries "" 10              # 10 most recent entries (all contacts)
npm run db:list-entries 1 5                # 5 most recent entries for contact 1

# View detailed entry
npm run db:view-entry 2                    # View entry ID 2 with full content

# Update entry
npm run db:update-entry 2 content "New content here"     # Update content
npm run db:update-entry 2 subject "New subject"          # Update subject
npm run db:update-entry 2 entry_type note               # Update type

# Delete entry
npm run db:delete-entry 2                  # Delete entry ID 2 (with confirmation)

Campos da entrada que você pode atualizar:

entry_type: ligação, e-mail, reunião, anotação, tarefa
subject: Título/assunto breve da entrada
content: Conteúdo detalhado da entrada

Exemplo de saída da lista de entradas:

📝 Contact Entries
   Showing 3 most recent entries (limited to 10)
================================================================================
Entry #5 (Jane Smith)
  Type: CALL
  Subject: Follow-up discussion
  Date: 2025-06-04 15:30:00
  Content: Discussed project requirements and timeline. Next meeting scheduled...

Entry #4 (John Doe)
  Type: EMAIL
  Subject: Proposal sent
  Date: 2025-06-04 14:15:00
  Content: Sent project proposal via email. Awaiting feedback by Friday...

Estrutura de Arquivos

Os arquivos são armazenados em data/archives/ com nomes descritivos:

crm-backup-2025-06-04T19-15-35.sqlite (carimbo de data/hora automático)
crm-backup-2025-06-04T19-15-35-cleanup.sqlite (com motivo)
crm-backup-2025-06-04T19-15-35-before-restore.sqlite (backup de segurança automático)

Recursos de Segurança

✅ Nunca Exclui Dados: Todas as operações arquivam antes de fazer alterações
✅ Carimbos de Data/Hora Automáticos: Cada arquivo tem nome único
✅ Backups de Segurança: Operações de restauração fazem backup do estado atual primeiro
✅ Rastreamento de Motivo: Motivos opcionais ajudam a rastrear por que os arquivos foram criados
✅ Recuperação Fácil: Comandos simples para restaurar qualquer estado anterior

🛠️ Ferramentas Disponíveis

Gerenciamento de Contatos

Ferramenta	Descrição	Parâmetros
`add_contact`	Criar um novo contato	`name` (obrigatório), `organization`, `job_title`, `email`, `phone`, `notes`
`update_contact`	Atualizar contato existente	`id` (obrigatório), opcionais: `name`, `organization`, `job_title`, `email`, `phone`, `notes`
`get_contact_details`	Obter informações detalhadas do contato	`id` (obrigatório)
`list_contacts`	Listar todos os contatos	`include_archived` (opcional, padrão: false)
`search_contacts`	Pesquisar contatos por nome, e-mail ou organização	`query` (obrigatório)
`list_contacts_by_organization`	Filtrar contatos por organização	`organization` (obrigatório)
`archive_contact`	Arquivar um contato (exclusão lógica)	`id` (obrigatório)

Histórico de Contatos

Ferramenta	Descrição	Parâmetros
`add_contact_entry`	Adicionar entrada de histórico de interação	`contact_id`, `entry_type` (ligação/e-mail/reunião/anotação/tarefa), `subject`, `content`
`update_contact_entry`	Atualizar entrada de contato existente	`entry_id` (obrigatório), opcionais: `entry_type`, `subject`, `content`
`get_contact_history`	Obter todo o histórico de um contato	`contact_id` (obrigatório), `limit` (opcional)
`get_recent_activities`	Obter atividades recentes do CRM	`limit` (opcional, padrão: 10)

Gerenciamento de Tarefas

Ferramenta	Descrição	Parâmetros
`add_todo`	Adicionar tarefa para um contato	`contact_id` (obrigatório), `todo_text` (obrigatório), `target_date` (opcional)
`update_todo`	Atualizar tarefa existente	`todo_id` (obrigatório), opcionais: `todo_text`, `target_date`, `is_completed`
`get_todos`	Obter tarefas com filtragem avançada	`contact_id` (opcional), `include_completed` (opcional), `days_ahead` (opcional), `days_old` (opcional)

Exportação de Dados

Ferramenta	Descrição	Parâmetros
`export_contacts_csv`	Exportar contatos para CSV com resumos de tarefas	`include_archived` (opcional)
`export_contact_history_csv`	Exportar histórico de contatos para CSV com detalhes de tarefas	`contact_id` (opcional, exporta tudo se não especificado)
`export_full_crm_csv`	Exportar dados completos do CRM com colunas de tarefas	Nenhum
`export_todos_csv`	Exportar todas as tarefas para CSV	Nenhum

📊 Exemplos de Uso

Adicionando um Contato

// Via MCP call
{
  "name": "add_contact",
  "arguments": {
    "name": "John Doe",
    "organization": "Acme Corp",
    "job_title": "Software Engineer",
    "email": "john.doe@acme.com",
    "phone": "+1-555-0123",
    "notes": "Interested in our enterprise solution"
  }
}

Pesquisando Contatos

{
  "name": "search_contacts",
  "arguments": {
    "query": "Acme"
  }
}

Adicionando Histórico de Contato

{
  "name": "add_contact_entry",
  "arguments": {
    "contact_id": 1,
    "entry_type": "call",
    "subject": "Discovery Call",
    "content": "Discussed requirements and pricing. Follow up in 1 week."
  }
}

Adicionando Tarefas

{
  "name": "add_todo",
  "arguments": {
    "contact_id": 1,
    "todo_text": "Follow up on pricing discussion",
    "target_date": "2025-06-15T10:00:00Z"
  }
}

Obtendo Tarefas

// Get all incomplete todos
{
  "name": "get_todos",
  "arguments": {}
}

// Get todos due in next 7 days
{
  "name": "get_todos", 
  "arguments": {
    "days_ahead": 7
  }
}

// Get todos for specific contact
{
  "name": "get_todos",
  "arguments": {
    "contact_id": 1,
    "include_completed": true
  }
}

Exportando Tarefas

// Export all todos to CSV
{
  "name": "export_todos_csv",
  "arguments": {}
}

Atualizando Histórico de Contato

{
  "name": "update_contact_entry",
  "arguments": {
    "entry_id": 2,
    "subject": "Updated Discovery Call",
    "content": "Discussed requirements and pricing. Client requested additional features. Follow up scheduled for next Tuesday."
  }
}

🧪 Testes

Executar Todos os Testes

# Comprehensive test suite (recommended) - uses database isolation
npm run test:comprehensive

# Individual test phases:
# Database management tests
npm run test:db

# Core functionality tests (Phase B)
cd tests && npx tsx run-phase-b-tests.ts

# Advanced tests - edge cases and performance (Phase C) 
cd tests && npx tsx run-phase-c-tests.ts

# Legacy comprehensive test runner
cd tests && npx tsx run-all-tests.ts

Testes Modulares com Isolamento de Banco de Dados

A nova suíte de testes abrangente utiliza nossos scripts de gerenciamento de banco de dados para:

🔒 Isolamento Completo: Cada fase de teste recebe um banco de dados novo
📦 Arquivamento Automático: Todos os dados de teste são preservados em arquivos com carimbo de data/hora
🔄 Gerenciamento de Estado: Configuração e limpeza entre fases de teste
📊 Relatórios Abrangentes: Relatórios detalhados com métricas de desempenho

Cobertura de Testes

Testes de Infraestrutura: Gerenciamento de Banco de Dados (6/6 testes, 100% de cobertura)
Testes de Recursos Principais: Todas as 13 ferramentas de CRM (3 suítes, 100% de cobertura)
Testes de Garantia de Qualidade: Casos extremos e validação de desempenho (2 suítes, 100% de cobertura)
Geral: 3 fases de teste com isolamento completo de banco de dados e teste de ciclo de vida

Fases de Teste

🏗️ Infraestrutura - Gerenciamento de banco de dados, arquivamento e controle de estado
⚙️ Recursos Principais - Gerenciamento de contatos, rastreamento de histórico e exportação de dados
🔍 Garantia de Qualidade - Casos extremos, tratamento de erros e validação de desempenho

Benchmarks de Desempenho

Execução da Suíte de Testes: ~20 segundos para testes abrangentes completos
Operações de Banco de Dados: Tempos de resposta inferiores a 1 segundo para todos os comandos de gerenciamento
Isolamento de Testes: Redefinição completa do banco de dados entre fases em <1 segundo
Operações de Arquivamento: Backups automáticos com carimbo de data/hora e zero perda de dados
Criação de Contatos: 2100+ contatos/segundo
Operações de Pesquisa: Tempo médio de resposta <1ms
Operações em Lote: 100% de taxa de sucesso em todos os tamanhos de lote
Operações de Exportação: Taxa de transferência de 40+ KB/ms

🏗️ Desenvolvimento

Estrutura do Projeto

mcp-crm/
├── src/
│   └── crm-server.ts          # Main MCP server implementation
├── scripts/
│   └── database-manager.ts    # Database management utilities
├── tests/
│   ├── scenarios/             # Test scenarios (including DB management)
│   ├── client/                # Test client utilities
│   └── run-*.ts              # Test runners
├── data/
│   ├── crm.sqlite            # SQLite database
│   └── archives/             # Database archive backups
├── build/                    # Compiled JavaScript
└── docs/                     # Documentation

Comandos de Build

npm run build       # Compile TypeScript
npm run watch       # Watch mode for development
npm run clean       # Clean build directory
npm run dev         # Development mode

# Database management
npm run db:reset    # Reset database (archive + fresh)
npm run db:archive  # Archive current database
npm run db:list     # List archived databases
npm run db:stats    # Show database statistics
npm run db:help     # Database management help

# Contact entry management
npm run db:list-entries     # List contact entries (with optional contact_id and limit)
npm run db:view-entry       # View detailed contact entry by ID
npm run db:delete-entry     # Delete contact entry by ID
npm run db:update-entry     # Update contact entry by ID

# Testing
npm run test:db     # Run database management tests
npm run test:comprehensive  # Run all tests with database isolation (recommended)
npm run test:all    # Alias for comprehensive tests

Esquema do Banco de Dados

contacts: Informações principais do contato com suporte a exclusão lógica
contact_entries: Rastreamento de interações com carimbos de data/hora
Arquivos: Backups automáticos com carimbo de data/hora em data/archives/
Índices: Otimizados para operações de pesquisa e recuperação

Configuração do Git

Arquivos de banco de dados: Todos os arquivos .sqlite são excluídos do controle de versão
Arquivos: O conteúdo do diretório data/archives/ é ignorado, mas a estrutura é preservada
Desenvolvimento local: Cada desenvolvedor mantém seu próprio banco de dados e arquivos localmente
Configuração limpa: Execute npm run db:reset para criar um banco de dados limpo em novas instalações

🔒 Recursos de Segurança

Validação de Entrada: Validação abrangente de parâmetros usando Zod
Proteção contra Injeção de SQL: Consultas parametrizadas em toda a aplicação
Prevenção de XSS: Sanitização de entrada para caracteres especiais
Tratamento de Erros: Respostas de erro elegantes sem exposição de dados sensíveis
Testes de Limite: Validação extensiva de casos extremos

📈 Prontidão para Produção

Escalabilidade

Operações SQLite eficientes com indexação adequada
Suporte a operações em lote para grandes conjuntos de dados
Tempos de resposta consistentes abaixo de 100ms
Design eficiente em memória

Confiabilidade

Tratamento abrangente de erros
Validação e sanitização de entrada
Degradação elegante para casos extremos
Extensa cobertura de testes (100%)
Proteção de integridade do banco de dados com arquivamento automático
Garantia de zero perda de dados por meio do sistema seguro de backup/restauração

Monitoramento

Coleta de métricas de desempenho
Registro detalhado para depuração
Relatórios e análise de resultados de testes

📄 Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🤝 Contribuição

Faça um fork do repositório
Crie um branch de recurso
Execute a suíte de testes abrangente: npm run test:all
Garanta que as 3 fases de teste sejam aprovadas (Infraestrutura, Recursos Principais, Garantia de Qualidade)
Faça commit das suas alterações
Envie um pull request

📞 Suporte

Para problemas e dúvidas:

Execute npm run test:all para verificar a integridade do sistema
Verifique os resultados dos testes em tests/results/test-reports/
Revise os cenários de teste abrangentes, incluindo gerenciamento de banco de dados
Use npm run db:help para comandos de gerenciamento de banco de dados
Todas as 13 ferramentas de CRM, além do gerenciamento de banco de dados, estão documentadas e testadas

Status: ✅ Pronto para Produção | 🧪 Testes em 3 Fases | 🚀 Performance Otimizada | 🗄️ Gerenciamento de Banco de Dados | 🔒 Isolamento Completo