convez.ai
MCP ServerIntegração & APIsIntermediário
Trinityy2

AI Notification Distribution

Trinityy2/ai-notification-distribution

API unificada para notificações multi-canal com RBAC e auditoria

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server para distribuição de notificações multi-canal (Telegram, WhatsApp e outros) com uma API unificada. Construído em FastAPI com arquitetura agnóstica a provedores, autenticação por chave de API com RBAC, despacho concorrente em lote e auditoria completa de tentativas de envio.

Instalação

$npx convez-ai Trinityy2/ai-notification-distribution

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Centralizar distribuição de notificações de múltiplos canais (Telegram, WhatsApp, SMS)
  • Sistemas de alertas escaláveis com despacho em lote concorrente
  • Arquitetura que permite trocar ou adicionar provedores sem alterar a API
  • Implementar controle de acesso granular (RBAC) para diferentes tipos de notificação

Veredito

Solução sólida e bem arquitetada para orquestração de notificações multi-canal. A abordagem baseada em ABCs (Abstract Base Classes) garante extensibilidade robusta e a separação clara entre camadas (providers, repositories, routers) facilita manutenção e testes. Pronto para produção com logging estruturado e auditoria integrada.

README

A tradução para o português deste README ainda está na fila.

AI Notification Distribution

A provider-agnostic, multi-channel notification server built with FastAPI and Python. Designed as an MCP (Multi-Channel Platform) service — broadcast messages to Telegram, WhatsApp, and other platforms through a single unified API.

Features

  • Provider-agnostic — swap or add messaging providers without changing the API (ABC pattern throughout)
  • API key auth with RBAC — scoped API keys with implication rules
  • Concurrent batch dispatch — send to multiple targets in parallel via asyncio.gather
  • Audit log — every send attempt (success or failure) is logged
  • Target validation — each provider validates identifiers before attempting a send
  • Swappable backends — repositories, hashers, and rate limiters are all ABCs; swap SQLAlchemy for anything else without touching business logic
  • Structured logging — JSON in production, plain in development; OTel-bridge ready

Project Structure

app/
├── config.py               # pydantic-settings config (env vars / .env files)
├── container.py            # DI container — wires ABCs to concrete implementations
├── dependencies.py         # FastAPI shared dependencies (auth, rate limiting)
├── logging_config.py       # Logging setup (JSON prod / plain dev)
├── main.py                 # App factory, middleware, routers
├── models/                 # Pydantic domain models
│   ├── api_key.py
│   ├── message.py
│   ├── result.py
│   └── target.py
├── providers/              # Messaging provider implementations
│   ├── base.py             # MessagingProvider ABC
│   ├── registry.py         # ProviderRegistry
│   ├── telegram.py
│   └── whatsapp.py         # Stub (not yet implemented)
├── repositories/           # Data access layer
│   ├── base.py             # APIKeyRepository + NotificationLogRepository ABCs
│   ├── in_memory.py        # In-memory implementations (dev / tests)
│   └── sqlalchemy/         # SQLAlchemy implementations (production)
├── routers/
│   ├── health.py
│   ├── keys.py             # API key CRUD
│   └── notify.py           # Single + batch notification dispatch
└── security/
    ├── hashing/            # KeyHasher ABC + SHA256 / BCrypt impls
    ├── rate_limiting/      # RateLimiter ABC + InMemory / SlowAPI impls
    └── rbac.py             # Scopes, implication rules, require_scope()

tests/
├── conftest.py             # Shared fixtures (InMemory repos, mock provider)
├── unit/                   # Pure unit tests (no HTTP)
└── integration/            # Full HTTP tests via ASGI test client

API Endpoints

MethodPathScope requiredDescription
GET/health—Health check (unauthenticated)
POST/notifynotify:sendSend a message to a single target
POST/notify/batchnotify:sendSend a message to multiple targets concurrently
GET/keyskeys:readList all API keys
POST/keyskeys:writeCreate a new API key
GET/keys/{id}keys:readGet an API key by ID
PATCH/keys/{id}keys:writeUpdate an API key
DELETE/keys/{id}keys:writeDelete an API key

Authentication

Pass your API key in the X-API-Key header:

X-API-Key: your-api-key-here

RBAC Scopes

ScopeImpliesDescription
notify:send—Send notifications
keys:read—Read API key records
keys:writekeys:readCreate / update / delete API keys
adminnotify:send, keys:read, keys:writeFull access

Quick Start

Prerequisites

  • Python 3.13+
  • uv (recommended) or pip

Setup

# Clone the repo
git clone https://github.com/Trinityy2/ai-notification-distribution
cd ai-notification-distribution

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

# Copy and edit the environment config
cp .env.example .env
# Edit .env — set ADMIN_ROOT_KEY, DATABASE_URL, TELEGRAM__BOT_TOKEN, etc.

Running the Server

uvicorn app.main:app --reload        # development
uvicorn app.main:app --host 0.0.0.0  # production (set ENVIRONMENT=production)

Interactive docs are available at http://localhost:8000/docs (development only).

Running with Docker

# Copy and configure secrets
cp .env.example .env
# Edit .env — set ADMIN_ROOT_KEY, TELEGRAM__BOT_TOKEN, etc.

# Build and start
docker compose up -d

# View logs
docker compose logs -f app

Persistent volumes created automatically:

VolumeMounted atContains
logs/app/logsRotating log files
data/app/dataSQLite database file

Configuration

All config is via environment variables (or a .env / .env.local file). See .env.example for the full list.

VariableDefaultDescription
ENVIRONMENTdevelopmentdevelopment or production
ADMIN_ROOT_KEY—Bootstrap admin API key (created on first startup)
REPOSITORY_BACKENDsqlalchemysqlalchemy or in_memory
DATABASE_URL—SQLAlchemy async DB URL (required for sqlalchemy backend)
HASHER_BACKENDsha256sha256 (deterministic) or bcrypt (salted)
HASHER_SECRET—HMAC secret for SHA256 hashing
RATE_LIMIT_REQUESTS60Max requests per window per API key
RATE_LIMIT_WINDOW_SECONDS60Rate limit window size
TELEGRAM__BOT_TOKEN—Telegram Bot API token (enables telegram provider)

Example Usage

Send a notification (Telegram)

curl -X POST http://localhost:8000/notify \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "target": { "provider": "telegram", "identifier": "@mychannel" },
    "message": { "text": "Hello from the notification server!" }
  }'

Batch send

curl -X POST http://localhost:8000/notify/batch \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [
      { "provider": "telegram", "identifier": "@channel1" },
      { "provider": "telegram", "identifier": "123456789" }
    ],
    "message": { "text": "Broadcast message" }
  }'

Batch dispatch is best-effort — all targets are attempted concurrently and individual failures do not abort the rest.


Development

Running Tests

# All tests with coverage report
python -m pytest

# Specific file
python -m pytest tests/integration/test_notify.py -v

Coverage is reported to the terminal and to htmlcov/index.html after each run. Current coverage: 93%.

Adding a New Provider

  1. Create app/providers/myprovider.py implementing the MessagingProvider ABC:
from app.providers.base import MessagingProvider
from app.models.target import Target
from app.models.message import Message
from app.models.result import SendResult

class MyProvider(MessagingProvider):
    async def send(self, target: Target, message: Message) -> SendResult:
        # your implementation
        ...

    def validate_target(self, target: Target) -> None:
        # raise InvalidTargetError if identifier is invalid
        ...
  1. Register it in app/container.py inside the provider_registry property.

That's it — no changes to any router or auth logic required.


Security Notes

  • API keys are stored as hashes (never in plain text)
  • SecretStr is used for all sensitive config values — they never appear in logs or tracebacks
  • Request body size is capped at 64 KB
  • OpenAPI docs (/docs, /openapi.json) are disabled in production
  • HTTPS redirect middleware is enabled in production (app-level, since there is no TLS-terminating reverse proxy). If you add a reverse proxy that terminates TLS, remove HTTPSRedirectMiddleware in app/main.py to avoid redirect loops.
Ver o original no GitHub

Bom para

Relacionados