YaVendió Herramientas 🧰

Un sistema de mensajería y notificaciones basado en MCP que permite a los sistemas de IA interactuar con diversas plataformas de mensajería mediante el Protocolo de Contexto de Modelo (MCP). Este proyecto implementa un servidor MCP que expone herramientas de mensajería para el envío de texto, imágenes, documentos, botones y alertas.

Tabla de contenido

Características
¿Qué es MCP?
Instalación
- Requisitos
Configuración
Ejecutando con Docker
Ejecutando localmente
Desarrollo
Estructura del proyecto
Integración MCP
- Herramientas MCP disponibles
Pruebas
Contribuyendo
Licencia

Características

Capacidades de mensajería :
- Envía mensajes de texto por WhatsApp y otras plataformas
- Envíe imágenes y medios con el formato adecuado
- Envíe vídeos con metadatos apropiados
- Enviar documentos con nombres de archivo y metadatos
- Cree botones interactivos para la participación del usuario
Gestión de clientes de WhatsApp :
- Registra y administra varios clientes de WhatsApp con diferentes credenciales
- Almacene tokens de forma segura usando Infisical
- Arquitectura sin estado para la gestión de clientes
- Herramientas dedicadas para cada operación de WhatsApp
Funciones de notificación :
- Configurar alertas en múltiples canales (WhatsApp, correo electrónico, SMS)
- Soporte para botones de pago y notificaciones de transacciones
Gestión de conversaciones :
- Seguimiento del estado de entrega de mensajes y metadatos
Utilidades adicionales :
- Funcionalidad de suspensión/retraso para interacciones temporizadas
- Gestión de configuración para empresas y usuarios
- Entrega de mensajes en tiempo real con seguimiento de estado

¿Qué es MCP?

El Protocolo de Contexto de Modelo (MCP) es un estándar abierto desarrollado por Anthropic que permite una integración fluida entre sistemas de IA y fuentes o herramientas de datos externas. Proporciona un estándar universal y abierto para conectar sistemas de IA con fuentes de datos, reemplazando las integraciones fragmentadas con un único protocolo.

Este proyecto implementa un servidor MCP que expone diversas herramientas de mensajería, haciéndolas accesibles a los sistemas de IA de forma estandarizada. Mediante MCP, los asistentes de IA pueden:

Envía mensajes de WhatsApp directamente a los usuarios
Subir y enviar archivos multimedia
Crea experiencias interactivas con botones
Gestionar el contexto de la conversación de forma eficiente
Activar notificaciones multicanal

Instalación

Este proyecto utiliza uv para la gestión de paquetes:

# Install uv if you don't have it
curl -L https://github.com/astral-sh/uv/releases/latest/download/install.sh | sh

# Alternatively, install with pip
pip install uv

# Clone the repository
git clone https://your-repo-url/yatools.git
cd yatools

# Install all dependencies (including dev dependencies)
make sync
# Or individually
make install      # Regular dependencies
make dev-install  # Development dependencies

Requisitos

Python 3.13 o superior
Docker y Docker Compose (para implementación en contenedores)

Configuración

Cree un archivo .env en el directorio raíz con su configuración:

# Logging configuration
LOG_LEVEL=INFO
LOG_FORMAT=json

Ejecutando con Docker

# Start all services
docker-compose up -d

# Stop all services
docker-compose down

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f app

Ejecutando localmente

# Development mode with auto-reload
make run

# Production mode
make run-prod

# Run with specific port
PORT=8080 make run

Desarrollo

El proyecto incluye varios comandos Makefile para agilizar el desarrollo:

# Show all available commands
make help

# Run tests
make test

# Run tests with coverage report
make coverage

# Format code
make format

# Lint code
make lint

# Clean cache files
make clean

Estructura del proyecto

app/ : Código de la aplicación principal
- server.py : La implementación del servidor MCP
- logging.py : Configuración de registro con structlog
- lifespan.py : Gestión del ciclo de vida de las aplicaciones
tools/ : Implementaciones de herramientas
- base_tool.py : Clases base abstractas para todas las herramientas
- text_tool.py : Herramienta para enviar mensajes de texto
- image_tool.py : Herramienta para enviar imágenes
- video_tool.py : Herramienta para enviar vídeos
- document_tool.py : Herramienta para enviar documentos
- button_tool.py : Herramienta para enviar botones interactivos
- alert_tool.py : Herramienta para enviar alertas multicanal
- sleep_tool.py : Herramienta para agregar retrasos en la ejecución de la herramienta
services/ : Implementaciones de servicios
- interfaces.py : Interfaces de servicio que definen contratos
- message_service.py : Servicio para el almacenamiento y recuperación de mensajes
- message_service_mock.py : Implementación simulada para pruebas
- whatsapp_service.py : Servicio para la gestión de clientes de WhatsApp
- whatsapp_service_mock.py : Servicio de WhatsApp simulado para pruebas
tests/ : Implementaciones de pruebas
- app/ : Pruebas para la estructura de la aplicación
- tools/ : Pruebas para herramientas individuales
- services/ : Pruebas para servicios
- server/ : Pruebas para la integración del servidor MCP

Integración MCP

Este servicio se puede integrar con aplicaciones LLM a través del Protocolo de Contexto de Modelo:

# Install the server in Claude Desktop
make mcp-install

# Run in development mode with auto-reload
make mcp-dev

# Install from PyPI (if published)
make mcp-install-pkg

Herramientas MCP disponibles

`send_text`

Envía un mensaje de texto a un número de WhatsApp.

Parámetros:

company_id : Identificador de la empresa
phone_number : Número de teléfono del destinatario
message : Texto para enviar

Ejemplo:

result = await send_text(
    company_id="company123",
    phone_number="5551234567",
    message="Hello, this is a test message!"
)
print(f"Message ID: {result['message_id']}")

`send_image`

Envía una o más imágenes a un número de WhatsApp.

Parámetros:

company_id : Identificador de la empresa
phone_number : Número de teléfono del destinatario
image_urls : Lista de URL de imágenes para enviar

Ejemplo:

result = await send_image(
    company_id="company123",
    phone_number="5551234567",
    image_urls=["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
)
print(f"Message IDs: {result['message_ids']}")

`send_video`

Envía uno o más videos a un número de WhatsApp.

Parámetros:

company_id : Identificador de la empresa
phone_number : Número de teléfono del destinatario
video_urls : Lista de URL de videos para enviar

Ejemplo:

result = await send_video(
    company_id="company123",
    phone_number="5551234567",
    video_urls=["https://example.com/video.mp4"]
)
print(f"Message IDs: {result['message_ids']}")

`send_document`

Envía archivos de documentos a un número de WhatsApp.

Parámetros:

company_id : Identificador de la empresa
phone_number : Número de teléfono del destinatario
files : Lista de archivos de documentos como {"url": "...", "filename": "..."}

Ejemplo:

result = await send_document(
    company_id="company123",
    phone_number="5551234567",
    files=[
        {
            "url": "https://example.com/document.pdf",
            "filename": "report.pdf"
        }
    ]
)
print(f"Message IDs: {result['message_ids']}")

`send_alert`

Envía alertas a través de múltiples canales (WhatsApp, Email, SMS).

Parámetros:

company_id : Identificador de la empresa
phone_number : Número de teléfono del destinatario
message : Mensaje de alerta
whatsapp : Si desea enviar un mensaje de WhatsApp
email : Configuración de correo electrónico {"subject": "..."}
sms : configuración de SMS {"type": "...", "recipients": ["..."]}
pause_number : Si se debe pausar la conversación
track_sale : Si se debe rastrear esto como una venta

Ejemplo:

result = await send_alert(
    company_id="company123",
    phone_number="5551234567",
    message="Important alert: New activity detected",
    whatsapp=True,
    email={
        "subject": "Important Alert", 
        "recipients": ["user@example.com"]
    },
    sms={
        "type": "urgent", 
        "recipients": ["5551234567", "5557654321"]
    },
    pause_number=False,
    track_sale=True
)
print(f"Alert Result: {result['result']}")

`sleep`

Pausa la ejecución durante segundos especificados.

Parámetros:

company_id : Identificador de la empresa
phone_number : Número de teléfono del destinatario
seconds : Número de segundos para dormir

Ejemplo:

result = await sleep(
    company_id="company123",
    phone_number="5551234567",
    seconds=5
)
print(f"Slept for {result['seconds']} seconds")

`send_button`

Envía botones interactivos.

Parámetros:

company_id : Identificador de la empresa
phone_number : Número de teléfono del destinatario
body_text : Cuerpo del mensaje del botón
buttons : Lista de configuraciones de botones [{"id": "...", "title": "..."}]
button_type : "responder" o "pago"
header : configuración de encabezado opcional
footer_text : Texto de pie de página opcional
payment_data : Datos de pago para los botones de pago

Ejemplo (botones de respuesta):

result = await send_button(
    company_id="company123",
    phone_number="5551234567",
    body_text="Please select an option:",
    buttons=[
        {"id": "btn1", "title": "Option 1"},
        {"id": "btn2", "title": "Option 2"},
        {"id": "btn3", "title": "Option 3"}
    ],
    button_type="reply",
    footer_text="Tap a button to proceed"
)
print(f"Button Message ID: {result['message_id']}")

Ejemplo (Botón de pago):

result = await send_button(
    company_id="company123",
    phone_number="5551234567",
    body_text="Complete your purchase:",
    buttons=[{"id": "pay1", "title": "Pay Now"}],
    button_type="payment",
    payment_data={
        "title": "Premium Subscription",
        "url": "https://pay.example.com/invoice123",
        "amount": "19.99",
        "currency": "USD"
    }
)
print(f"Payment Button Message ID: {result['message_id']}")

`get_config`

Obtiene la configuración de la empresa.

Parámetros:

company_id : Identificador de la empresa

Ejemplo:

config = await get_config(
    company_id="company123"
)
print(f"Company Config: {config['config']}")

`update_config`

Actualiza la configuración de la empresa.

Parámetros:

company_id : Identificador de la empresa
config : Nueva configuración

Ejemplo:

result = await update_config(
    company_id="company123",
    config={
        "welcome_message": "Welcome to our service!",
        "auto_reply": True,
        "notification_emails": ["admin@example.com"]
    }
)
print(f"Update Result: {result['message']}")

Pruebas

Para obtener información detallada sobre cómo ejecutar y escribir pruebas, consulte TEST.md.

Comandos de prueba básicos:

# Run all tests
make test

# Run tests with coverage
make coverage

Contribuyendo

¡Agradecemos sus contribuciones! Siga estos pasos:

Bifurcar el repositorio
Crear una rama de características ( git checkout -b feature/amazing-feature )
Realiza tus cambios
Ejecutar pruebas para asegurarse de que pasan ( make test )
Confirme sus cambios ( git commit -m 'Add amazing feature' )
Empujar a la rama ( git push origin feature/amazing-feature )
Abrir una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.