Unified Notification Conduit (MCP Gateway)

This service acts as an intermediary, implementing the Model Context Protocol (MCP) to interface with the robust, HTTP-based ntfy messaging platform. It furnishes AI entities (such as generative models) with the capability to broadcast richly formatted, priority-aware notifications, bypassing the need for agents to handle raw network communication.

Core Functionality

This application bridges the abstraction layer provided by MCP with the simplicity of ntfy's publish/subscribe mechanism, ensuring that critical asynchronous outputs from computational agents reach human operators instantaneously.

mermaid graph TD A[Intelligent Agent/LLM] -->|MCP Call| B(Notification Gateway Server) B -->|HTTP POST| C(Ntfy Messaging Broker) C -->|Push Alert| D[User Mobile/Desktop Client]

Key Capabilities

• MCP Compliance: Fully built against the @modelcontextprotocol/sdk, ensuring plug-and-play compatibility with various MCP clients (e.g., Cline, Claude Desktop).
• Rich Ntfy Tooling (dispatch_alert): Supports advanced payload customization:
  • Severity Levels (Priorities 1 through 5).
  • Topic Subscription and Emoji Tagging.
  • Interactive elements (Action Buttons, Clickable URLs).
  • Payload Attachment support.
  • Time-shifted Delivery scheduling.
  • Markdown Rendering.
• Resource Exposition: Advertises the pre-configured master notification channel as an accessible MCP resource for discovery.
• Development Stack: Modern, type-safe TypeScript development environment.
• Auditing & Reliability: Implements structured logging via winston with file rotation for persistent operational records.
• Configuration Security: Utilizes environment variables (dotenv) for managing sensitive settings, combined with input validation (sanitize-html) to mitigate XSS risks.

Initial Deployment Guide

1. Prerequisites Check: Ensure Node.js (version 16 or higher) and a package manager (npm/yarn) are available.
2. Acquisition:
   • Global Install (Recommended for CLI use): npm install -g mcp-notifier-gateway
   • Source Clone: Clone the repository, run npm install, and then npm run build.
3. Configuration Setup: Populate the .env file with your essential parameters, most critically NTFY_DEFAULT_TOPIC.
4. Activation: Initiate the service using npm start.
5. Client Integration: Register the running server endpoint within your designated MCP client application settings.

Configuration Variables (.env)

Variable	Purpose	Default	Notes
NTFY_BASE_URL	Root address for the ntfy instance.	https://ntfy.sh	Override for self-hosted instances.
NTFY_DEFAULT_TOPIC	The primary channel for untargeted broadcasts.	Required	Must be set.
LOG_LEVEL	Verbosity of the system output.	info	Options: debug, info, warn, error.

Tooling Reference: dispatch_alert

This function is the primary interface for sending notifications.

Parameter	Type	Necessity	Significance
topic	String	Mandatory	The destination channel identifier.
message	String	Mandatory	The core content payload (text body).
title	String	Optional	Headline for the alert box.
tags	String Array	Optional	Emojis/keywords for enhanced filtering (limit 5).
priority	Integer	Optional	Message urgency level (1=Lowest, 5=Urgent).
click	String	Optional	Destination URL activated upon tap/click.
actions	Array of Objects	Optional	Custom buttons that execute HTTP verbs or internal broadcasts (limit 3).
markdown	Boolean	Optional	Enables interpretation of inline Markdown syntax within the message field.

Advanced Payload Example (Triggering an API Call)

javascript { "topic": "system_events", "title": "Service Failure Detected", "message": "Critical resource exhaustion detected on node ALPHA-7.", "priority": 5, "tags": ["critical", "server_down"], "actions": [ { "id": "invoke_recovery", "label": "Initiate Failover", "action": "http", "method": "POST", "url": "https://internal-api.corp/failover-trigger", "headers": { "X-Auth-Key": "SECURE_TOKEN" } } ], "markdown": true }

Discovery Resource

Clients can query the built-in resource ntfy://default to dynamically retrieve the server's designated primary notification topic, ensuring smooth client configuration adaptability.

Project Inheritance Note

The structure and foundational concepts of this repository draw inspiration from established patterns in application logging, environment management (dotenv), and standardized communication protocols, while specifically tailoring the implementation for the ntfy service.