Damien Email Wrestler

Una plataforma de inteligencia de correo electrónico impulsada por IA que se integra con Gmail y OpenAI. Puede ejecutarse como herramienta CLI o implementarse en AWS Lambda para capacidades mejoradas.

GitHub

Prueba este MCPPatrocinado

Documentación

🤼‍♂️ Damien Email Wrestler

La Plataforma de Inteligencia de Correo Electrónico Impulsada por IA

Damien Email Wrestler es una plataforma de inteligencia de correo electrónico de nivel empresarial que transforma la forma en que gestionas el correo electrónico mediante asistentes de IA de lenguaje natural como Claude. Construida con arquitectura híbrida CLI + AWS Lambda, inteligencia artificial avanzada, optimización de costos e integración MCP sin interrupciones.

✨ Estado Actual: Flujo de Trabajo de Desarrollo Profesional v0.5.0 🎉

🏆 Plataforma Completa de Inteligencia de Correo Electrónico con Flujo de Trabajo Profesional de GitHub

49 Herramientas Optimizadas: Suite mejorada de gestión de correo electrónico con organización en lenguaje natural, limpieza inteligente y sondeo automático
✅ FLUJO DE TRABAJO PROFESIONAL COMPLETO: Automatización de GitHub, plantillas de issues, validación de PR y etiquetado automático
✅ FLUJO DE TRABAJO MEJORADO VALIDADO: 282 correos de marketing procesados con 100% de precisión en pruebas de producción
Arquitectura Híbrida: Confiabilidad de CLI + mejora de IA con AWS Lambda cuando está configurado
Probado en el Mundo Real: 100-500 correos analizados con detección de patrones con 83-86% de confianza
Segmentación de Precisión: Análisis de IA → IDs de correo → Operaciones masivas precisas (cero falsos positivos)
Diseño Privacidad-Primero: Almacenamiento solo de metadatos con limpieza automática TTL (30-90 días)
Rentable: $0.01 por análisis de 100 correos, ~$1/mes para un solo usuario
Nivel Empresarial: Protección de privacidad, arquitectura escalable, degradación elegante

🚀 Qué Hace Especial a Damien

Gestión de Correo en Lenguaje Natural: "Crea una regla para archivar boletines" → Hecho automáticamente
Procesamiento de IA Híbrido: Confiabilidad de CLI + mejora de AWS Lambda para análisis de nivel empresarial
Validado en el Mundo Real: 83% de cobertura de automatización con detección de patrones con 92% de confianza
Arquitectura Privacidad-Primero: Almacenamiento solo de metadatos, cero exposición del contenido del correo
Optimizado en Costos: $0.01 por análisis de 100 correos con AWS Lambda de pago por solicitud
Escalabilidad Empresarial: Maneja conjuntos de datos de 66k+ correos con procesamiento por lotes inteligente
Inteligencia en Tiempo Real: 14.49 segundos para análisis de 100 correos con mejora de Lambda

🎯 Capacidades Principales

🧠 Suite de Inteligencia de IA

📊 Análisis de Correo: Detecta patrones, sentimiento e impacto empresarial en miles de correos
🤖 Automatización Inteligente: Creación de reglas en lenguaje natural - "Archiva correos de boletines"
💡 Información Inteligente: Análisis de tendencias, métricas de eficiencia y recomendaciones de optimización
⚡ Optimización de Bandeja de Entrada: Estrategias de organización y limpieza impulsadas por IA
🔍 Búsqueda Avanzada: Búsqueda semántica con comprensión de contexto mejorada por RAG

📧 Gestión Completa de Correo Electrónico

Gestión de Hilos: Operaciones a nivel de conversación con contexto completo
Ciclo de Vida de Borradores: Crea, edita, envía y gestiona borradores sin interrupciones
Operaciones Masivas: Procesa miles de correos de manera eficiente con seguimiento de progreso
Filtrado Inteligente: Automatización sofisticada basada en reglas con mejora de ML
Gestión de Etiquetas: Categorización y organización inteligente

🛡️ Funciones Empresariales

Protección de Privacidad: Detección de PII con 99.9% de precisión con tokenización reversible
Monitoreo de Costos: Seguimiento de uso de tokens en tiempo real con alertas configurables
Optimización de Rendimiento: Enrutamiento inteligente de modelos (gpt-4o-mini vs gpt-4o)
Cumplimiento de Auditoría: Listo para GDPR/CCPA/HIPAA con registros de auditoría inmutables
Arquitectura Escalable: Maneja cargas de trabajo empresariales con procesamiento por lotes inteligente

🏗️ Descripción General de la Arquitectura Híbrida

Damien Email Wrestler consta de componentes integrados con procesamiento híbrido CLI + AWS Lambda:

┌─────────────────┐    ┌─────────────────────┐    ┌──────────────────┐    ┌─────────────┐
│                 │    │                     │    │                  │    │             │
│   AI Assistant  │◄──►│  Smithery Adapter   │◄──►│   Damien MCP     │◄──►│ Gmail API   │
│    (Claude)     │    │   (Port 8081)       │    │   Server         │    │             │
│                 │    │                     │    │   (Port 8892)    │    │             │
└─────────────────┘    └─────────────────────┘    └──────────────────┘    └─────────────┘
                                │                           │
                                │                           ▼
                                ▼                  ┌─────────────────────┐
                       ┌─────────────────┐        │  Hybrid Processing  │
                       │                 │        │  Layer              │
                       │ Smithery        │        │  • Standard CLI     │◄──────┐
                       │ Registry        │        │  • Privacy Guard    │       │
                       │                 │        │  • Smart Router     │       │
                       └─────────────────┘        │  • Batch Processor  │       │
                                                  └─────────────────────┘       │
                                                             │                  │
                                                             ▼                  │
                                               ┌──────────────────────────┐      │
                                               │ AWS Lambda Enhancement   │      │
                                               │ (When Credentials Set)   │      │
                                               │  • Email Processor       │      │
                                               │  • AI Analyzer (85%+)    │      │
                                               │  • Rule Engine           │      │
                                               └──────────────────────────┘      │
                                                             │                  │
                                                             ▼                  │
                                               ┌──────────────────────────┐      │
                                               │  Privacy-First Storage   │      │
                                               │  • Metadata Only         │      │
                                               │  • TTL Auto-Cleanup      │──────┘
                                               │  • DynamoDB Tables       │
                                               │  • No Content Storage    │
                                               └──────────────────────────┘

Desglose de Componentes

🤖 Servidor MCP de Damien (Puerto 8892)

49 Herramientas MCP Optimizadas: Kit de herramientas enfocado en gestión de correo con capacidades de sondeo automático
Procesamiento Híbrido: Análisis CLI estándar + mejora de IA con AWS Lambda (cuando está configurado)
Degradación Elegante: Funcionalidad completa sin AWS - Lambda mejora pero nunca es requerida
Backend FastAPI: API asíncrona de alto rendimiento con monitoreo integral
Seguridad Empresarial: OAuth 2.0, limitación de velocidad, registro de auditoría

🔗 Adaptador Smithery (Puerto 8081)

Puente de Protocolo MCP: Integración sin interrupciones con asistentes de IA
Descubrimiento de Herramientas: Registro dinámico de herramientas y anuncio de capacidades
Manejo de Errores: Degradaciones elegantes y mecanismos de reintento
Optimización de Rendimiento: Agrupación de conexiones y almacenamiento en caché

🧠 Capa de Inteligencia de IA Híbrida

Procesamiento Estándar: Análisis basado en CLI siempre disponible con detección de patrones
Mejora de Lambda: Clasificación de IA de nivel empresarial cuando se configuran credenciales de AWS
Guardián de Privacidad: Protección de PII y tokenización de nivel empresarial
Enrutador de Inteligencia: Selección de modelos impulsada por ML para optimización de costos
Motor RAG: Búsqueda semántica con incrustaciones vectoriales para comprensión contextual
Procesador por Lotes: Procesamiento escalable de grandes volúmenes de correo con seguimiento de progreso

☁️ Capa de Mejora de AWS Lambda

Procesador de Correo: Extracción y almacenamiento de metadatos seguros para la privacidad
Analizador de IA: Clasificación de correo de alta confianza (85%+ de precisión)
Motor de Reglas: Ejecución inteligente de reglas con resolución de conflictos
Almacenamiento DynamoDB: Almacenamiento solo de metadatos con limpieza automática TTL (30-90 días)
Optimización de Costos: Modelo de pago por solicitud (~$1/mes para un solo usuario)

🚀 Inicio Rápido

Requisitos Previos

Python 3.11+ con Poetry
Node.js 18+ con npm
Credenciales de Gmail API (Guía de Configuración)
Clave de API de OpenAI (para funciones de IA)
Credenciales de AWS (opcional - para mejora de Lambda) (Guía de Configuración)

1. Instalación (2 minutos)

# Clone repository
git clone https://github.com/your-org/damien-email-wrestler.git
cd damien-email-wrestler

# Configure environment
cp .env.example .env
# Add your Gmail credentials and OpenAI API key to .env

# Install dependencies
cd damien-cli && poetry install && cd ..
cd damien-mcp-server && poetry install && cd ..
cd damien-smithery-adapter && npm install && cd ..

2. Iniciar Servicios (30 segundos)

# Start all services with one command
./scripts/start-all.sh

Salida Esperada: ✅ Todos los servicios en ejecución con verificaciones de salud aprobadas

3. Conectar Claude Desktop (2 minutos)

Agrega a tu ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "damien-email-wrestler": {
      "command": "node",
      "args": ["./damien-smithery-adapter/dist/index.js"],
      "cwd": "/path/to/damien-email-wrestler",
      "env": {
        "DAMIEN_MCP_SERVER_URL": "http://localhost:8892",
        "DAMIEN_MCP_SERVER_API_KEY": "your-api-key-from-.env"
      }
    }
  }
}

4. Probar Integración (1 minuto)

# Authenticate with Gmail
cd damien-cli && poetry run damien login

# Run validation tests
cd .. && ./run_e2e_tests.sh

🎉 ¡Estás listo! Prueba en Claude Desktop: "Lista mis correos recientes y sugiere 3 reglas de automatización"

💡 Ejemplos de Uso

Gestión de Correo en Lenguaje Natural

You: "Analyze my emails from the last week and find patterns"
Claude: [Uses damien_ai_analyze_emails] Found 3 key patterns:
• 15 newsletter emails (suggest auto-archive rule)
• 8 meeting requests (suggest calendar integration)  
• 12 customer support emails (suggest priority labeling)

You: "Create a rule to automatically archive newsletters"
Claude: [Uses damien_ai_create_rule] Created rule with 95% confidence:
✅ Auto-archive emails containing "unsubscribe" from marketing domains

You: "Optimize my inbox for better productivity"  
Claude: [Uses damien_ai_optimize_inbox] Completed optimization:
• Archived 47 old newsletters
• Labeled 23 emails as "Action Required"
• Created 3 smart filters for automatic organization

Operaciones Avanzadas de Correo

# CLI Usage
poetry run damien emails list --query "from:boss@company.com" --max-results 10
poetry run damien ai analyze-emails --days 30 --min-confidence 0.8
poetry run damien rules suggest --categories "productivity,automation"

# Bulk Operations  
poetry run damien emails bulk-label --query "is:unread older_than:30d" --label "Archive"
poetry run damien emails bulk-trash --query "category:promotions older_than:90d" --dry-run

📊 Optimización de Rendimiento y Costos

Eficiencia de Costos

Enrutamiento Inteligente de Modelos: Usa automáticamente gpt-4o-mini (90% más barato) para tareas simples
AWS Lambda: Modelo de pago por solicitud con escalado automático
Optimización de Tokens: El parámetro include_headers reduce las llamadas a la API en 80%+
Optimización de Consultas: Segmentación inteligente de categorías específicas de correo
Monitoreo en Tiempo Real: Rastrea costos con alertas configurables
Costos Reales: $0.01 por análisis de 100 correos, ~$1/mes para un solo usuario

Métricas de Rendimiento (Probadas en el Mundo Real)

Análisis de Correo: 100 correos en 14.49 segundos (6.9 correos/segundo) ✅
✅ FLUJO DE TRABAJO MEJORADO: 282 correos de marketing segmentados y eliminados con precisión en pruebas de 100/200/500 correos ✅
Segmentación de Precisión: 100% de precisión - cada correo identificado por IA procesado exitosamente ✅
Detección de Patrones: 83-86% de confianza en clasificación de boletines/promocionales con validación estadística ✅
Procesamiento Escalable: Manejo sin interrupciones de 100-500 correos con flujo de trabajo asíncrono ✅
Mejora de Lambda: 85%+ de precisión para clasificación de alta confianza ✅
Procesamiento Lambda: Menos de 300ms por llamada de función ✅
Respuesta de Gmail API: < 2 segundos ✅
Ejecución de Herramientas MCP: < 5 segundos por operación ✅
Uso de Memoria: < 1GB durante operación normal ✅

Escalabilidad

Procesamiento por Lotes: Maneja 100K+ correos con fragmentación inteligente
Operaciones Progresivas: Retroalimentación en tiempo real para tareas de larga duración
Operaciones Paralelas: Procesamiento multi-hilo con seguimiento de progreso
Gestión de Recursos: Limpieza automática y recolección de basura
Salud del Servicio: Monitoreo integral con reinicios automáticos

🛡️ Seguridad y Privacidad

Protección de Privacidad

Almacenamiento Solo de Metadatos: No se almacena contenido de correo, solo metadatos seguros para la privacidad
Privacidad de AWS Lambda: Procesamiento en la nube con cero exposición de contenido
Expiración Automática de Datos: Limpieza basada en TTL (30-90 días)
99.9% de Detección de PII: Reconocimiento avanzado de patrones para datos sensibles
Tokenización Reversible: Procesamiento seguro manteniendo la recuperabilidad
Registros de Auditoría: Registro inmutable para cumplimiento y depuración

Cumplimiento Empresarial

Listo para GDPR: Gestión de consentimiento de procesamiento de datos y derecho a la eliminación
Cumplimiento CCPA: Cumplimiento de la ley de privacidad de California integrado
Consideraciones HIPAA: Patrones de protección de datos de salud
Control de Acceso: Permisos basados en roles y gestión de claves de API

Funciones de Seguridad

OAuth 2.0: Autenticación estándar de la industria con Google APIs
Limitación de Velocidad: Previene el abuso y garantiza un uso justo
Manejo de Errores: Fallos elegantes sin exponer datos sensibles
Almacenamiento Cifrado: Todas las credenciales y tokens almacenados de forma segura

📚 Documentación

Guía de Inicio Rápido - Ponte en marcha en 15 minutos
Referencia de API - Documentación completa de herramientas
Solución de Problemas - Problemas comunes y soluciones
Guía de Pruebas E2E - Lista de verificación de validación de producción

🔧 Configuración Avanzada

Variables de Entorno

# AI Intelligence Configuration
AI_MODEL_STRATEGY="cost_optimized"          # cost_optimized | performance_optimized | balanced
USE_OPENAI_API=true                          # Use OpenAI API vs local models
TRACK_TOKEN_USAGE=true                       # Enable cost monitoring
COST_ALERT_THRESHOLD_USD=10.00               # Alert when costs exceed threshold

# Performance Tuning
MAX_TOKENS_PER_REQUEST=4000                  # Token limit per API call
SIMPLE_TASK_MAX_TOKENS=1000                  # Threshold for gpt-4o-mini usage
COMPLEX_TASK_MIN_CONFIDENCE=0.8              # Threshold for gpt-4o usage

# Privacy & Security
PII_DETECTION_ENABLED=true                   # Enable PII protection
AUDIT_LOGGING_ENABLED=true                   # Enable compliance logging
CONSENT_REQUIRED=false                       # Require explicit consent for processing

Gestión de Servicios

# Start/Stop Services
./scripts/start-all.sh                       # Start all services
./scripts/stop-all.sh                        # Stop all services

# Service Health
curl http://localhost:8892/health            # MCP Server health
curl http://localhost:8081/health            # Smithery Adapter health

# Logs
tail -f logs/damien-mcp-server.log          # MCP Server logs
tail -f logs/smithery-adapter.log           # Adapter logs
tail -f logs/token_usage.json               # Cost tracking logs

🏆 ¿Por Qué Elegir Damien?

🎯 Para Individuos

Ahorro de Tiempo: Automatiza el 80% de las tareas rutinarias de correo
Inteligencia: Información y detección de patrones impulsadas por IA
Control: Comandos en lenguaje natural con control preciso
Privacidad: Protección de nivel empresarial para correos personales

🏢 Para Equipos y Organizaciones

Escalabilidad: Maneja miles de correos entre miembros del equipo
Cumplimiento: Registros de auditoría integrados y protección de privacidad
Eficiencia de Costos: El uso optimizado de IA ahorra 80% en costos de API
Integración: Conexión sin interrupciones con flujos de trabajo existentes

🚀 Para Desarrolladores

Protocolo MCP: Integración estándar con asistentes de IA
Extensible: 48 herramientas con opciones fáciles de personalización
Integración con AWS: Funciones Lambda sin servidor con almacenamiento DynamoDB
Arquitectura Híbrida: Procesamiento CLI + Nube para rendimiento óptimo
Listo para Empresas: Arquitectura y monitoreo de grado de producción

📈 Hoja de Ruta

Actual (v0.4.2) - ✅ Flujo de Trabajo Mejorado Completo

✅ PROCESAMIENTO DE CORREO MEJORADO: Implementación de 3 semanas del sistema de segmentación precisa de IDs de correo
✅ VALIDADO EN PRODUCCIÓN: 282 correos de marketing procesados con 100% de precisión en escalas de prueba
✅ Caché Inteligente: Desalojo LRU/LFU con optimización TTL para operaciones repetidas
✅ Procesamiento de Trabajos Asíncronos: Manejo sin interrupciones de grandes conjuntos de datos con seguimiento de progreso en tiempo real
✅ Suite de herramientas MCP mejorada (48 herramientas en total: 39 principales + 2 de papelera mejorada + 5 de organización + 2 de limpieza inteligente)
✅ Arquitectura híbrida de mejora de IA CLI + AWS Lambda
✅ Almacenamiento solo de metadatos con privacidad primero y limpieza TTL
✅ Validación en el mundo real: 100-500 correos con detección de patrones con 83-86% de confianza
✅ Segmentación de precisión: Análisis de IA → IDs de correo → Operaciones masivas precisas
✅ Rentable: $0.01 por análisis de 100 correos
✅ Escalabilidad empresarial: Maneja conjuntos de datos de 66k+ correos
✅ Degradación elegante: Funcionalidad completa sin dependencia de AWS

Próxima Versión (v0.5.0) - Q1 2025

🔄 Funciones de colaboración en tiempo real
🔄 Panel de análisis avanzado
🔄 Soporte multi-cuenta de Gmail
🔄 Entrenamiento personalizado de modelos de IA
🔄 Compatibilidad móvil mejorada

Fase de Desarrollo (v0.6.0 - v0.9.x) - Q2-Q4 2025

📅 Soporte multi-proveedor (Outlook, Yahoo)
📅 Integración con Slack y Teams
📅 Automatización avanzada de flujos de trabajo
📅 Gestión predictiva de correos electrónicos
📅 Consola de administración empresarial
📅 Endurecimiento y optimización de producción

Lanzamiento Público (v1.0.0) - Q1 2026

🚀 Primer lanzamiento público
🚀 Documentación y soporte completos
🚀 Listo para despliegue empresarial
🚀 Lanzamiento de comunidad y ecosistema

🤝 Soporte y Comunidad

Problemas: GitHub Issues
Documentación: Este repositorio y guías enlazadas
Discusiones: GitHub Discussions
Seguridad: Envía un correo a security@damien-platform.com para problemas de seguridad

📄 Licencia

Sin licencia - consulta LICENSE para más detalles.

🙏 Agradecimientos

Construido con:

Model Context Protocol (MCP) - Estándar de integración de asistentes de IA
Smithery - Registro y descubrimiento de herramientas MCP
FastAPI - Framework web de Python de alto rendimiento
OpenAI - Modelos de lenguaje y embeddings de IA
Gmail API - Integración de servicios de correo electrónico

Transforma tu experiencia de correo electrónico con inteligencia impulsada por IA. Bienvenido al futuro de la gestión de correos. 🚀