Servidor MCP de OneSignal

Un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con la API de OneSignal. Este servidor proporciona una interfaz práctica para gestionar notificaciones push, correos electrónicos, SMS, dispositivos de usuario, segmentos, plantillas y más a través de la API REST de OneSignal.

Descripción general

Este servidor MCP integra la API REST de OneSignal para proporcionar un conjunto de herramientas que permiten administrar las aplicaciones de OneSignal y enviar mensajes a los usuarios. Es compatible con las principales operaciones de OneSignal, incluyendo:

Envío de notificaciones push, correos electrónicos y SMS
Administrar dispositivos de usuario y suscripciones
Creación y gestión de segmentos
Creación y gestión de plantillas
Visualización de información y análisis de la aplicación
Operaciones a nivel de organización
Administrar múltiples aplicaciones OneSignal

Requisitos

Python 3.7 o superior
paquete python-dotenv
paquete requests
Cuenta OneSignal con credenciales API

Instalación

Opción 1: Clonar desde GitHub

# Clone the repository
git clone https://github.com/weirdbrains/onesignal-mcp.git
cd onesignal-mcp

# Install dependencies
pip install -r requirements.txt

Opción 2: Instalar como paquete (próximamente)

pip install onesignal-mcp

Configuración

Cree un archivo .env en el directorio raíz con sus credenciales de OneSignal:
# Default app credentials (optional, you can also add apps via the API) ONESIGNAL_APP_ID=your_app_id_here ONESIGNAL_API_KEY=your_rest_api_key_here # Organization API key (for org-level operations) ONESIGNAL_ORG_API_KEY=your_organization_api_key_here
Puede encontrar sus credenciales de OneSignal en su panel de OneSignal:
- ID de la aplicación: Configuración > Claves e ID > ID de la aplicación OneSignal
- Clave de API REST: Configuración > Claves e ID > Clave de API REST
- Clave API de la organización: Configuración de la organización > Claves API

Uso

Ejecución del servidor

python onesignal_server.py

El servidor se iniciará y se registrará en el sistema MCP, haciendo que sus herramientas estén disponibles para su uso.

Ejemplos básicos de uso

Enviar una notificación push

# Send a notification to all subscribed users
result = await send_notification(
    title="Hello World",
    message="This is a test notification",
    segment="Subscribed Users"
)
print(result)

Trabajar con múltiples aplicaciones

# Add a new app configuration
await add_app(
    key="my_second_app", 
    app_id="second-app-id", 
    api_key="second-app-api-key", 
    name="My Second App"
)

# List all configured apps
apps = await list_apps()
print(apps)

# Switch to the new app
await switch_app("my_second_app")

# Send a notification using the current app
await send_notification(
    title="Hello", 
    message="This is from my second app"
)

# Send a notification from a specific app (without switching)
await send_notification(
    title="Hello", 
    message="This is from my first app", 
    app_key="mandible"
)

Gestión de segmentos

# List all segments
segments = await view_segments()
print(segments)

# Create a new segment
result = await create_segment(
    name="High Value Users",
    filters='[{"field":"amount_spent", "relation":">", "value":"100"}]'
)
print(result)

Trabajar con plantillas

# Create an email template
result = await create_template(
    name="Welcome Email",
    title="Welcome to Our App",
    message="<html><body><h1>Welcome!</h1><p>Thank you for joining us.</p></body></html>",
    template_type="email"
)
print(result)

Compatibilidad con múltiples aplicaciones

Este servidor permite administrar varias aplicaciones OneSignal. Puede:

Agregar múltiples configuraciones de aplicaciones con diferentes identificadores
Cambiar entre aplicaciones al realizar llamadas API
Especifique qué aplicación utilizar para operaciones individuales

Herramientas de gestión de aplicaciones

list_apps : enumera todas las aplicaciones OneSignal configuradas en el servidor
add_app : Agregar una nueva configuración de la aplicación OneSignal
update_app : Actualizar una configuración de la aplicación OneSignal existente
remove_app : Eliminar una configuración de la aplicación OneSignal
switch_app : Cambia la aplicación actual para usarla en solicitudes de API

Herramientas disponibles

Gestión de mensajes

send_notification : envía una nueva notificación push, correo electrónico o SMS
view_messages : Lista de mensajes recientes enviados a través de OneSignal
view_message_details : Obtener información detallada sobre un mensaje específico
cancel_message : Cancelar un mensaje programado

Administración de dispositivos

view_devices : Lista los dispositivos (usuarios) registrados en tu aplicación OneSignal
view_device_details : Obtenga información detallada sobre un dispositivo específico

Gestión de segmentos

view_segments : enumera todos los segmentos disponibles en su aplicación OneSignal
create_segment : Crea un nuevo segmento con filtros específicos
delete_segment : Eliminar un segmento existente

Gestión de plantillas

view_templates : enumera todas las plantillas disponibles en su aplicación OneSignal
view_template_details : Obtenga información detallada sobre una plantilla específica
create_template : Crea una nueva plantilla para notificaciones o correos electrónicos

Información de la aplicación

view_app_details : Obtenga información detallada sobre la aplicación OneSignal configurada

Explotación florestal

El servidor incluye un registro completo para facilitar la depuración y la monitorización. Los registros se envían a la consola de forma predeterminada, con el siguiente formato:

YYYY-MM-DD HH:MM:SS - onesignal-mcp - LEVEL - Message

Puede ajustar el nivel de registro modificando la llamada logging.basicConfig en el archivo del servidor.

Pruebas

El servidor MCP de OneSignal incluye un conjunto completo de pruebas para garantizar que todas las funciones funcionen correctamente. Las pruebas utilizan el framework de unittest integrado en Python y simulan llamadas a API externas para evaluar el comportamiento del servidor.

Ejecución de pruebas

Para ejecutar las pruebas, utilice el siguiente comando:

python -m unittest discover tests

Esto descubrirá y ejecutará todas las pruebas en el directorio tests .

Cobertura de la prueba

El conjunto de pruebas cubre:

Gestión de configuración de aplicaciones
Manejo de solicitudes API con autenticación adecuada
Manejo y recuperación de errores
Compatibilidad con múltiples aplicaciones
Operaciones a nivel de organización

Escritura de nuevas pruebas

Si añade nueva funcionalidad al servidor, agregue también las pruebas correspondientes. Las pruebas deben ubicarse en el directorio tests y seguir la convención de nombres test_*.py .

Solución de problemas

Problemas comunes

No hay configuración de aplicación disponible

Si ve el error "No hay configuración de aplicación disponible", asegúrese de tener:

Configure su archivo .env con las credenciales correctas, o
Se agregó una configuración de aplicación usando la herramienta add_app

Errores de clave API

Si recibe errores de autenticación, verifique que:

Sus claves API son correctas
Estás utilizando la clave correcta para la operación (Clave API REST vs Clave API de la organización)
La clave tiene los permisos necesarios en OneSignal

Limitación de velocidad

OneSignal tiene límites de velocidad para las solicitudes de API. Si encuentra algún límite de velocidad:

Reduce la frecuencia de tus solicitudes
Implementar lógica de reintento con retroceso exponencial

Obtener ayuda

Si encuentra problemas que no se abordan aquí:

Consulte la documentación de la API de OneSignal
Abrir un problema en el repositorio de GitHub

Contribuyendo

Agradecemos las contribuciones para mejorar el servidor MCP de OneSignal. Consulte las directrices en CONTRIBUTING.md .

Licencia

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

Expresiones de gratitud

OneSignal por su excelente servicio de notificaciones y API
Al equipo de Weirdbrains por apoyar este proyecto.

OneSignal MCP Server

Integrations