首页
分类
发现
Apps
排行榜
博客教程
AI备案查询
全网AI快讯实时
提交/推广产品
登录
Python
MIT License
1
weirdbrains
最近更新：1年前

一个用于与OneSignal API交互的模型上下文协议（MCP）服务器

OneSignal MCP 服务器

一个用于与 OneSignal API 交互的模型上下文协议（MCP）服务器。该服务器通过 OneSignal 的 REST API 提供了便捷的接口，用于管理推送通知、电子邮件、短信、用户设备、细分群组、模板等功能。

许可证: MIT
版本

概述

此 MCP 服务器封装了 OneSignal REST API，提供了一套工具用于管理您的 OneSignal 应用程序和向用户发送消息。它支持所有主要的 OneSignal 操作，包括：

  • 发送推送通知、电子邮件和短信
  • 管理用户设备和订阅
  • 创建和管理细分群组
  • 创建和管理模板
  • 查看应用信息和分析
  • 组织级别操作
  • 管理多个 OneSignal 应用程序

要求

  • Python 3.7 或更高版本
  • python-dotenv 包
  • requests 包
  • 拥有 API 凭证的 OneSignal 账户

安装

选项 1：从 GitHub 克隆

bash 复制代码 
# 克隆仓库
git clone https://github.com/weirdbrains/onesignal-mcp.git
cd onesignal-mcp

# 安装依赖
pip install -r requirements.txt

选项 2：作为包安装（即将推出）

bash 复制代码 
pip install onesignal-mcp

配置

  1. 在根目录创建一个 .env 文件，包含您的 OneSignal 凭证：

    复制代码 
    # 默认应用凭证（可选，也可以通过 API 添加应用）
ONESIGNAL_APP_ID=your_app_id_here
ONESIGNAL_API_KEY=your_rest_api_key_here

# 组织 API 密钥（用于组织级别操作）
ONESIGNAL_ORG_API_KEY=your_organization_api_key_here

  2. 您可以在 OneSignal 仪表板中找到您的凭证：

    • 应用 ID：设置 > 密钥和 ID > OneSignal 应用 ID
    • REST API 密钥：设置 > 密钥和 ID > REST API 密钥
    • 组织 API 密钥：组织设置 > API 密钥

使用

运行服务器

bash 复制代码 
python onesignal_server.py

服务器将启动并向 MCP 系统注册自身，使其工具可供使用。

基本使用示例

发送推送通知

python 复制代码 
# 向所有订阅用户发送通知
result = await send_notification(
    title="你好世界",
    message="这是一条测试通知",
    segment="订阅用户"
)
print(result)

处理多个应用

python 复制代码 
# 添加新的应用配置
await add_app(
    key="my_second_app", 
    app_id="second-app-id", 
    api_key="second-app-api-key", 
    name="我的第二个应用"
)

# 列出所有配置的应用
apps = await list_apps()
print(apps)

# 切换到新应用
await switch_app("my_second_app")

# 使用当前应用发送通知
await send_notification(
    title="你好", 
    message="这是我的第二个应用发送的通知"
)

# 从特定应用发送通知（无需切换）
await send_notification(
    title="你好", 
    message="这是我的第一个应用发送的通知", 
    app_key="mandible"
)

管理细分群组

python 复制代码 
# 列出所有细分群组
segments = await view_segments()
print(segments)

# 创建新的细分群组
result = await create_segment(
    name="高价值用户",
    filters='[{"field":"amount_spent", "relation":">", "value":"100"}]'
)
print(result)

使用模板

python 复制代码 
# 创建电子邮件模板
result = await create_template(
    name="欢迎邮件",
    title="欢迎使用我们的应用",
    message="<html><body><h1>欢迎！</h1><p>感谢您加入我们。</p></body></html>",
    template_type="email"
)
print(result)

多应用支持

此服务器支持管理多个 OneSignal 应用。您可以：

  1. 添加多个具有不同标识符的应用配置
  2. 在调用 API 时切换应用
  3. 为单个操作指定要使用的应用

应用管理工具

  • list_apps：列出服务器中所有配置的 OneSignal 应用
  • add_app：添加新的 OneSignal 应用配置
  • update_app：更新现有的 OneSignal 应用配置
  • remove_app：移除 OneSignal 应用配置
  • switch_app：切换当前用于 API 请求的应用

可用工具

消息管理

  • send_notification：发送新的推送通知、电子邮件或短信
  • view_messages：列出通过 OneSignal 发送的近期消息
  • view_message_details：获取特定消息的详细信息
  • cancel_message：取消已安排的消息

设备管理

  • view_devices：列出在您的 OneSignal 应用中注册的设备（用户）
  • view_device_details：获取特定设备的详细信息

细分群组管理

  • view_segments：列出您的 OneSignal 应用中可用的所有细分群组
  • create_segment：使用指定的过滤器创建新的细分群组
  • delete_segment：删除现有的细分群组

模板管理

  • view_templates：列出您的 OneSignal 应用中可用的所有模板
  • view_template_details：获取特定模板的详细信息
  • create_template：为通知或电子邮件创建新模板

应用信息

  • view_app_details：获取配置的 OneSignal 应用的详细信息

日志记录

服务器包含全面的日志记录功能，以帮助调试和监控。默认情况下日志输出到控制台，格式如下：

复制代码 
YYYY-MM-DD HH:MM:SS - onesignal-mcp - 级别 - 消息

您可以通过修改服务器文件中的 logging.basicConfig 调用来调整日志级别。

测试

OneSignal MCP 服务器包含全面的测试套件，以确保所有功能按预期工作。测试使用 Python 内置的 unittest 框架，并模拟外部 API 调用来测试服务器的行为。

运行测试

要运行测试，请使用以下命令：

bash 复制代码 
python -m unittest discover tests

这将发现并运行 tests 目录中的所有测试。

测试覆盖范围

测试套件覆盖：

  • 应用配置管理
  • 带有正确身份验证的 API 请求处理
  • 错误处理和恢复
  • 多应用支持
  • 组织级别操作

编写新测试

如果您向服务器添加了新功能，请同时添加相应的测试。测试应放在 tests 目录中，并遵循命名约定 test_*.py。

故障排除

常见问题

没有可用的应用配置

如果您看到错误“没有可用的应用配置”，请确保：

  1. 已设置 .env 文件并包含正确的凭证，或
  2. 已使用 add_app 工具添加了应用配置

API 密钥错误

如果您收到身份验证错误，请验证：

  1. 您的 API 密钥是否正确
  2. 您是否为操作使用了正确的密钥（REST API 密钥与组织 API 密钥）
  3. 该密钥在 OneSignal 中具有必要的权限

速率限制

OneSignal 对 API 请求有速率限制。如果遇到速率限制：

  1. 降低请求频率
  2. 实现带有指数退避的重试逻辑

获取帮助

如果您遇到此处未涵盖的问题：

  1. 查看 OneSignal API 文档
  2. 在 GitHub 仓库中提交问题

贡献

我们欢迎对改进 OneSignal MCP 服务器的贡献！请参阅 CONTRIBUTING.md 了解指南。

许可证

此项目根据 MIT 许可证授权 - 详见 LICENSE 文件。

致谢

  • OneSignal 提供的优秀通知服务和 API
  • Weirdbrains 团队对本项目的支持