CRM MCP Server

Un servidor MCP listo para producción para funcionalidad de Gestión de Relaciones con Clientes (CRM), construido con TypeScript y SQLite.

GitHub

Prueba este MCPPatrocinado

Documentación

CRM MCP Server

Un servidor Model Context Protocol (MCP) listo para producción para funcionalidad de Customer Relationship Management (CRM), construido con TypeScript y SQLite.

🚀 Características

Herramientas CRM Principales (18 en Total)

Gestión de Contactos: Agregar, actualizar, buscar, listar y archivar contactos
Gestión de Organizaciones: Filtrar contactos por organización
Historial de Contactos: Rastrear, actualizar y gestionar interacciones, llamadas, correos electrónicos, reuniones y notas
Gestión de Entradas: Operaciones CRUD completas en entradas de historial de contactos
Gestión de Tareas Pendientes: Agregar, actualizar, filtrar y rastrear elementos de acción para contactos
Exportación de Datos: Exportaciones CSV para contactos, historial y datos CRM completos
Actividades Recientes: Rastrear y recuperar actividades CRM recientes

Excelencia Técnica

✅ 100% de Cobertura de Pruebas - Suite de pruebas integral en 3 fases con aislamiento de base de datos
✅ Listo para Producción - Manejo robusto de errores y validación de entradas
✅ Alto Rendimiento - Optimizado para operaciones masivas y grandes conjuntos de datos
✅ Enfoque en Seguridad - Protección contra inyección SQL y saneamiento de entradas
✅ Manejo de Casos Límite - Condiciones límite exhaustivamente probadas
✅ Gestión de Base de Datos - Sistema seguro de archivo/restauración con cero pérdida de datos
✅ Gestión de Entradas - CRUD completo de historial de contactos con scripts de base de datos
✅ Pruebas Modulares - Fases de prueba aisladas con gestión automática de estado

📦 Instalación

Requisitos Previos

Node.js 18+
npm o yarn

Configuración

# 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

🔧 Configuración

Integración MCP

Agregue a su .cursor/mcp.json o configuración del cliente MCP:

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

Base de Datos

Ubicación: data/crm.sqlite
Tipo: SQLite 3
Creación Automática: La base de datos y las tablas se inicializan automáticamente
Ignorada por Git: Los archivos de base de datos y archivos se excluyen del control de versiones por razones de seguridad y tamaño

🗄️ Gestión de Base de Datos

El sistema CRM incluye potentes comandos de gestión de base de datos para restablecer, archivar y restaurar sus datos de forma segura.

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 Detallado

Restablecer Base de Datos

Archiva de forma segura su base de datos actual y crea una nueva vacía.

# Basic reset
npm run db:reset

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

Qué sucede:

📦 La base de datos actual se archiva con marca de tiempo
🗑️ La base de datos actual se elimina
✅ Se crea una nueva base de datos vacía
🛡️ Sus datos se conservan de forma segura en los archivos

Archivar Base de Datos

Cree una copia de seguridad sin restablecer (conserva la base de datos actual).

# Basic archive
npm run db:archive

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

Listar Archivos

Vea todas sus copias de seguridad de base de datos.

npm run db:list

Ejemplo de salida:

📦 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 desde Archivo

Restaure una base de datos anterior desde el archivo.

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

Qué sucede:

📦 La base de datos actual se archiva (copia de seguridad de seguridad)
🔄 El archivo seleccionado se restaura como base de datos actual
✅ Sus datos vuelven al estado archivado

Estadísticas de Base de Datos

Verifique el estado actual de su base de datos.

npm run db:stats

Ejemplo de salida:

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

Gestión de Entradas de Contacto

Gestione las entradas de historial de contactos con operaciones 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 de entrada que puede actualizar:

entry_type: llamada, correo electrónico, reunión, nota, tarea
subject: Título breve/asunto de la entrada
content: Contenido detallado de la entrada

Ejemplo de salida de 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...

Estructura de Archivos

Los archivos se almacenan en data/archives/ con nombres descriptivos:

crm-backup-2025-06-04T19-15-35.sqlite (marca de tiempo automática)
crm-backup-2025-06-04T19-15-35-cleanup.sqlite (con motivo)
crm-backup-2025-06-04T19-15-35-before-restore.sqlite (copia de seguridad de seguridad automática)

Características de Seguridad

✅ Nunca Elimina Datos: Todas las operaciones archivan antes de realizar cambios
✅ Marcas de Tiempo Automáticas: Cada archivo tiene un nombre único
✅ Copias de Seguridad de Seguridad: Las operaciones de restauración respaldan el estado actual primero
✅ Seguimiento de Motivos: Los motivos opcionales ayudan a rastrear por qué se crearon los archivos
✅ Recuperación Fácil: Comandos simples para restaurar cualquier estado anterior

🛠️ Herramientas Disponibles

Gestión de Contactos

Herramienta	Descripción	Parámetros
`add_contact`	Crear un nuevo contacto	`name` (obligatorio), `organization`, `job_title`, `email`, `phone`, `notes`
`update_contact`	Actualizar contacto existente	`id` (obligatorio), opcional: `name`, `organization`, `job_title`, `email`, `phone`, `notes`
`get_contact_details`	Obtener información detallada del contacto	`id` (obligatorio)
`list_contacts`	Listar todos los contactos	`include_archived` (opcional, predeterminado: false)
`search_contacts`	Buscar contactos por nombre, correo electrónico u organización	`query` (obligatorio)
`list_contacts_by_organization`	Filtrar contactos por organización	`organization` (obligatorio)
`archive_contact`	Archivar un contacto (eliminación suave)	`id` (obligatorio)

Historial de Contactos

Herramienta	Descripción	Parámetros
`add_contact_entry`	Agregar entrada de historial de interacción	`contact_id`, `entry_type` (llamada/correo electrónico/reunión/nota/tarea), `subject`, `content`
`update_contact_entry`	Actualizar entrada de contacto existente	`entry_id` (obligatorio), opcional: `entry_type`, `subject`, `content`
`get_contact_history`	Obtener todo el historial de un contacto	`contact_id` (obligatorio), `limit` (opcional)
`get_recent_activities`	Obtener actividades CRM recientes	`limit` (opcional, predeterminado: 10)

Gestión de Tareas Pendientes

Herramienta	Descripción	Parámetros
`add_todo`	Agregar tarea pendiente para un contacto	`contact_id` (obligatorio), `todo_text` (obligatorio), `target_date` (opcional)
`update_todo`	Actualizar tarea pendiente existente	`todo_id` (obligatorio), opcional: `todo_text`, `target_date`, `is_completed`
`get_todos`	Obtener tareas pendientes con filtrado avanzado	`contact_id` (opcional), `include_completed` (opcional), `days_ahead` (opcional), `days_old` (opcional)

Exportación de Datos

Herramienta	Descripción	Parámetros
`export_contacts_csv`	Exportar contactos a CSV con resúmenes de tareas pendientes	`include_archived` (opcional)
`export_contact_history_csv`	Exportar historial de contactos a CSV con detalles de tareas pendientes	`contact_id` (opcional, exporta todo si no se especifica)
`export_full_crm_csv`	Exportar datos CRM completos con columnas de tareas pendientes	Ninguno
`export_todos_csv`	Exportar todas las tareas pendientes a CSV	Ninguno

📊 Ejemplos de Uso

Agregar un Contacto

// 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"
  }
}

Buscar Contactos

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

Agregar Historial de Contacto

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

Agregar Tareas Pendientes

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

Obtener Tareas Pendientes

// 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
  }
}

Exportar Tareas Pendientes

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

Actualizar Historial de Contacto

{
  "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."
  }
}

🧪 Pruebas

Ejecutar Todas las Pruebas

# 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

Pruebas Modulares con Aislamiento de Base de Datos

La nueva suite de pruebas integral aprovecha nuestros scripts de gestión de base de datos para:

🔒 Aislamiento Completo: Cada fase de prueba obtiene una base de datos nueva
📦 Archivado Automático: Todos los datos de prueba se conservan en archivos con marca de tiempo
🔄 Gestión de Estado: Configuración y desmontaje limpios entre fases de prueba
📊 Informes Integrales: Informes detallados con métricas de rendimiento

Cobertura de Pruebas

Pruebas de Infraestructura: Gestión de Base de Datos (6/6 pruebas, 100% de cobertura)
Pruebas de Funcionalidades Principales: Las 13 herramientas CRM (3 suites, 100% de cobertura)
Pruebas de Aseguramiento de Calidad: Casos límite y validación de rendimiento (2 suites, 100% de cobertura)
General: 3 fases de prueba con aislamiento completo de base de datos y pruebas de ciclo de vida

Fases de Prueba

🏗️ Infraestructura - Gestión de base de datos, archivado y control de estado
⚙️ Funcionalidades Principales - Gestión de contactos, seguimiento de historial y exportación de datos
🔍 Aseguramiento de Calidad - Casos límite, manejo de errores y validación de rendimiento

Puntos de Referencia de Rendimiento

Ejecución de Suite de Pruebas: ~20 segundos para pruebas integrales completas
Operaciones de Base de Datos: Tiempos de respuesta de menos de un segundo para todos los comandos de gestión
Aislamiento de Pruebas: Restablecimiento completo de base de datos entre fases en <1 segundo
Operaciones de Archivo: Copias de seguridad automáticas con marca de tiempo y cero pérdida de datos
Creación de Contactos: 2100+ contactos/segundo
Operaciones de Búsqueda: Tiempo de respuesta promedio <1ms
Operaciones Masivas: 100% de tasa de éxito en todos los tamaños de lote
Operaciones de Exportación: Rendimiento de 40+ KB/ms

🏗️ Desarrollo

Estructura del Proyecto

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 Compilación

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 de Base de Datos

contacts: Información principal de contacto con soporte de eliminación suave
contact_entries: Seguimiento de interacciones con marcas de tiempo
Archivos: Copias de seguridad automáticas con marca de tiempo en data/archives/
Índices: Optimizados para operaciones de búsqueda y recuperación

Configuración de Git

Archivos de base de datos: Todos los archivos .sqlite se excluyen del control de versiones
Archivos: El contenido del directorio data/archives/ se ignora pero se conserva la estructura
Desarrollo local: Cada desarrollador mantiene su propia base de datos y archivos localmente
Configuración nueva: Ejecute npm run db:reset para crear una base de datos limpia en instalaciones nuevas

🔒 Características de Seguridad

Validación de Entradas: Validación integral de parámetros usando Zod
Protección contra Inyección SQL: Consultas parametrizadas en todo el sistema
Prevención XSS: Saneamiento de entradas para caracteres especiales
Manejo de Errores: Respuestas de error elegantes sin exposición de datos sensibles
Pruebas de Límites: Validación extensiva de casos límite

📈 Preparación para Producción

Escalabilidad

Operaciones SQLite eficientes con indexación adecuada
Soporte de operaciones masivas para grandes conjuntos de datos
Tiempos de respuesta consistentes por debajo de 100ms
Diseño eficiente en memoria

Fiabilidad

Manejo integral de errores
Validación y saneamiento de entradas
Degradación elegante para casos límite
Cobertura extensiva de pruebas (100%)
Protección de integridad de base de datos con archivado automático
Garantía de cero pérdida de datos mediante sistema seguro de copia de seguridad/restauración

Monitoreo

Recopilación de métricas de rendimiento
Registro detallado para depuración
Informes y análisis de resultados de pruebas

📄 Licencia

Licencia MIT - consulte el archivo LICENSE para más detalles.

🤝 Contribuciones

Haga un fork del repositorio
Cree una rama de funcionalidad
Ejecute la suite de pruebas integral: npm run test:all
Asegúrese de que las 3 fases de prueba pasen (Infraestructura, Funcionalidades Principales, Aseguramiento de Calidad)
Confirme sus cambios
Envíe una solicitud de extracción

📞 Soporte

Para problemas y preguntas:

Ejecute npm run test:all para verificar el estado del sistema
Revise los resultados de las pruebas en tests/results/test-reports/
Revise los escenarios de prueba integrales, incluida la gestión de base de datos
Use npm run db:help para comandos de gestión de base de datos
Las 13 herramientas CRM más la gestión de base de datos están documentadas y probadas

Estado: ✅ Listo para Producción | 🧪 Pruebas en 3 Fases | 🚀 Optimizado para Rendimiento | 🗄️ Gestión de Base de Datos | 🔒 Aislamiento Completo