MCP Communication Conduit: Ntfy Dispatcher

This specialized MCP implementation functions as a conduit, translating generalized Model Context Protocol commands into specific interactions with the external ntfy.sh messaging infrastructure. It grants Large Language Models (LLMs) and autonomous agents the capability to dispatch richly parameterized, real-time alerts and informational broadcasts directly to user endpoints (mobile/desktop).

Table of Contents

• System Overview
• Core Capabilities
• Initial Deployment Guide
• Setup & Environment Variables
• Client Integration Schemas
• Available MCP Functionality
• Resource Access Points
• Operational Scenarios
• Maintenance Scripts
• Contribution Guidelines
• Legal Notice

System Overview

This backend service adheres strictly to the MCP specification, acting as a robust intermediary. Its sole purpose is to abstract the underlying HTTP mechanics of ntfy, allowing AI entities to concentrate on context and content rather than endpoint specifics. This abstraction is critical for maintaining standardized communication within AI tool-use frameworks.

graph TD
    A[AI/LLM Entity] -->|MCP Call| B(MCP Dispatcher Server);
    B -->|HTTP POST| C[ntfy Push Service];
    C --> D[User Device (Phone/Desktop)];
    subgraph Protocol Flow
        B
    end

Core Capabilities

• MCP Tool Integration: Leverages the official SDK for seamless, context-aware tool invocation (send_ntfy).
• Advanced Ntfy Parameterization: Supports granular control over message delivery, including:
  • Urgency Levels (Priority 1 through 5).
  • Payload enrichment via attachments (URLs).
  • User interaction elements (Clickable actions/buttons).
  • Content structure support (Markdown interpretation).
  • Time-based scheduling (delay) and message retention (cache/expires).
• Type Safety & Robustness: Developed in TypeScript, ensuring high code integrity and comprehensive logging via Winston for auditing.
• Context Discovery: Exposes the primary operational channel (topic) as a discoverable MCP resource.

Initial Deployment Guide

Prerequisites

1. Node.js runtime environment (version 16 or newer).
2. A package manager (npm/yarn).
3. An active ntfy instance (defaulting to https://ntfy.sh).

Execution Steps

1. Acquisition (Global Install - Preferred for System Tools): bash npm install -g ntfy-mcp-server
2. Configuration File Generation (Crucial): bash # Copy example variables cp .env.example .env # Populate NTFY_DEFAULT_TOPIC in the new .env file

3. Service Activation: bash ntfy-mcp-server start

4. Client Registration: Register the server endpoint within your LLM Orchestrator (e.g., Cline's settings file) pointing to the executable.

Setup & Environment Variables

Configuration relies on environment variables loaded from a .env file in the service root.

Variable	Default	Description
NTFY_BASE_URL	https://ntfy.sh	The root URI for the ntfy endpoint.
NTFY_DEFAULT_TOPIC	(None, Required)	The designated channel for routine broadcasts.
LOG_LEVEL	info	Verbosity setting for the logger (e.g., debug, warn).

Client Registration Snippets (Example for Cline/VSCode Integration)

When registering the service, ensure the command points correctly to the binary (ntfy-mcp-server) or the node execution path.

{
  "mcpServers": {
    "ntfy-gateway": {
      "command": "ntfy-mcp-server",
      "env": {
        "NTFY_DEFAULT_TOPIC": "ai_workflows_001",
        "NODE_ENV": "production"
      }
    }
  }
}

Available MCP Functionality

Tool: send_ntfy (Message Publication Utility)

This function sends structured payload data to the specified ntfy topic, allowing for detailed message construction.

Mandatory Parameters: topic (Target channel), message (Body text).

Optional Delivery Modifiers:

• priority (Numeric: 1-5 for urgency).
• tags (Array of string identifiers/emojis).
• click (URL redirection on tap).
• actions (Array of structured buttons for immediate interaction, supporting view, http, or broadcast types).
• attachment (Object detailing a file URL and filename to attach).
• delay / expires (Time strings like 1h, 2d, etc., for scheduling or TTL).

Usage Example (High Urgency Alert):

<use_mcp_tool>
<server_name>ntfy-mcp-server</server_name>
<tool_name>send_ntfy</tool_name>
<arguments>
{
  "topic": "critical_system_watch",
  "title": "Latency Spike Detected",
  "message": "P99 latency exceeded 500ms across primary microservices. Investigate immediately.",
  "priority": 5, 
  "tags": ["error", "fire"],
  "markdown": true
}
</arguments>
</use_mcp_tool>

Resource Access Points

1. Default Topic Discovery

Endpoint: ntfy://default

• Purpose: Clients can query this URI to dynamically retrieve the configured default channel name (NTFY_DEFAULT_TOPIC), promoting zero-configuration usage for standard flows.
• Response Schema: Returns metadata including the discovered topic string.

2. Specific Topic Metadata

Endpoint: ntfy://{topic_name}

• Purpose: Fetches confirmation metadata associated with any specified channel.

Operational Scenarios

1. Automated Reporting: Dispatching end-of-day summary reports from a backend process.
2. Error Interception: Using priority 5 alerts for immediate notification of service failures.
3. Interactive Workflows: Providing buttons within the alert itself (via actions) to trigger subsequent automated recovery steps (e.g., 'Acknowledge' or 'Force Reboot').

Maintenance Scripts

• npm run build: Transpiles source files into the distributable directory.
• npm run clean: Purges compiled artifacts and archival logs.
• npm run tree: Updates directory layout documentation (docs/tree.md).
• npm start: Initiates the primary MCP server process.

Contribution Guidelines

We welcome external enhancements. Please adhere to standard open-source contribution workflows: fork, branch, commit distinct changes, and submit a Pull Request against the main branch. Focus on maintaining strong typing and comprehensive test coverage for all new features or fixes.

Legal Notice

Distribution is governed by the Apache License, Version 2.0. Refer to the LICENSE file for complete terms and conditions.

---