ntfy-mcp-server 1.0.0

package/dist/config/index.js

@@ -0,0 +1,111 @@
+import dotenv from 'dotenv';
+import { createRequestContext } from '../utils/requestContext.js';
+import { logger } from '../utils/logger.js';
+// Initialize environment variables from .env file
+dotenv.config();
+// Create a request context for logging
+const configContext = createRequestContext({
+    operation: 'ConfigInit',
+    component: 'Config',
+});
+// Create a logger specific to config
+const configLogger = logger.createChildLogger({
+    module: 'Config',
+    service: 'Config',
+    requestId: configContext.requestId,
+});
+/**
+ * Environment validation and parsing utilities
+ */
+const parsers = {
+    /**
+     * Parse environment string to number with validation
+     *
+     * @param value - String value from environment
+     * @param defaultValue - Default value to use if parsing fails
+     * @returns Parsed number value
+     */
+    number: (value, defaultValue) => {
+        if (!value)
+            return defaultValue;
+        const parsed = parseInt(value, 10);
+        if (isNaN(parsed)) {
+            configLogger.warn(`Invalid number for environment variable, using default: ${defaultValue}`, {
+                value,
+                defaultValue
+            });
+            return defaultValue;
+        }
+        return parsed;
+    },
+    /**
+     * Parse environment string to boolean
+     *
+     * @param value - String value from environment
+     * @param defaultValue - Default value to use if parsing fails
+     * @returns Parsed boolean value
+     */
+    boolean: (value, defaultValue) => {
+        if (!value)
+            return defaultValue;
+        const normalized = value.toLowerCase().trim();
+        if (['true', '1', 'yes', 'y'].includes(normalized))
+            return true;
+        if (['false', '0', 'no', 'n'].includes(normalized))
+            return false;
+        configLogger.warn(`Invalid boolean for environment variable, using default: ${defaultValue}`, {
+            value,
+            defaultValue
+        });
+        return defaultValue;
+    },
+    /**
+     * Parse environment string to an array of strings
+     *
+     * @param value - Comma-separated string value from environment
+     * @param defaultValue - Default value to use if parsing fails
+     * @returns Array of parsed string values
+     */
+    array: (value, defaultValue = []) => {
+        if (!value)
+            return defaultValue;
+        return value.split(',').map(item => item.trim()).filter(Boolean);
+    }
+};
+/**
+ * Environment variable configuration
+ */
+export const config = {
+    environment: process.env.NODE_ENV || 'development',
+    logLevel: process.env.LOG_LEVEL || 'info',
+    // HTTP server configuration
+    server: {
+        port: parsers.number(process.env.PORT, 3000),
+        host: process.env.HOST || 'localhost',
+    },
+    // Rate limiting settings
+    rateLimit: {
+        windowMs: parsers.number(process.env.RATE_LIMIT_WINDOW_MS, 60000),
+        maxRequests: parsers.number(process.env.RATE_LIMIT_MAX_REQUESTS, 100),
+    },
+    // Ntfy notification service configuration
+    ntfy: {
+        baseUrl: process.env.NTFY_BASE_URL || 'https://ntfy.sh',
+        defaultTopic: process.env.NTFY_DEFAULT_TOPIC || '',
+        apiKey: process.env.NTFY_API_KEY || '',
+        maxMessageSize: parsers.number(process.env.NTFY_MAX_MESSAGE_SIZE, 4096),
+        maxRetries: parsers.number(process.env.NTFY_MAX_RETRIES, 3),
+    },
+};
+// Log the loaded configuration (excluding sensitive values)
+configLogger.info('Configuration loaded', {
+    environment: config.environment,
+    logLevel: config.logLevel,
+    server: config.server,
+    ntfy: {
+        baseUrl: config.ntfy.baseUrl,
+        defaultTopic: config.ntfy.defaultTopic || '(not set)',
+        hasApiKey: !!config.ntfy.apiKey,
+    },
+});
+export default config;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Ntfy MCP Server - Main Entry Point
+ *
+ * This is the main entry point for the Ntfy MCP server. It initializes the
+ * server, sets up signal handlers for graceful shutdown, and manages the
+ * application lifecycle.
+ */
+import { config } from "./config/index.js";
+import { createMcpServer } from "./mcp-server/server.js";
+import { logger } from "./utils/logger.js";
+import { createRequestContext } from "./utils/requestContext.js";
+// Create main application logger
+const appLogger = logger.createChildLogger({
+    module: 'NtfyMcpServer',
+    service: 'NtfyMcpServer',
+    component: 'Main',
+    environment: config.environment
+});
+/**
+ * Graceful shutdown handler
+ * @param signal The signal that triggered the shutdown
+ */
+const shutdown = async (signal) => {
+    appLogger.info(`Shutting down due to ${signal} signal...`);
+    try {
+        if (mcpServer) {
+            appLogger.info('Closing MCP server...');
+            await mcpServer.close();
+            appLogger.info('MCP server closed successfully');
+        }
+        appLogger.info('Shutdown complete. Exiting process.');
+        process.exit(0);
+    }
+    catch (error) {
+        appLogger.error('Error during shutdown', {
+            error: error instanceof Error ? error.message : String(error),
+            signal
+        });
+        process.exit(1);
+    }
+};
+// Variable to hold server instance
+let mcpServer;
+/**
+ * Main startup function
+ */
+const start = async () => {
+    // Create startup context
+    const startupContext = createRequestContext({
+        operation: "ServerStartup",
+        appName: "ntfy-mcp-server",
+        environment: config.environment,
+    });
+    appLogger.info("Starting ntfy-mcp-server...", {
+        environment: config.environment,
+        logLevel: config.logLevel,
+        requestId: startupContext.requestId
+    });
+    try {
+        // Validate ntfy configuration
+        const ntfyConfig = config.ntfy;
+        if (!ntfyConfig.baseUrl) {
+            appLogger.warn("Ntfy base URL not configured. Using default https://ntfy.sh");
+        }
+        if (!ntfyConfig.defaultTopic) {
+            appLogger.warn("No default ntfy topic configured. Some functionality may be limited.");
+        }
+        // Create main MCP server
+        appLogger.info("Creating MCP server...");
+        mcpServer = await createMcpServer();
+        appLogger.info("MCP server created and connected successfully");
+        // Register signal handlers for graceful shutdown
+        process.on("SIGTERM", () => shutdown("SIGTERM"));
+        process.on("SIGINT", () => shutdown("SIGINT"));
+        // Handle uncaught exceptions
+        process.on("uncaughtException", (error) => {
+            appLogger.error("Uncaught exception", {
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined
+            });
+        });
+        // Handle unhandled promise rejections
+        process.on("unhandledRejection", (reason) => {
+            appLogger.error("Unhandled promise rejection", {
+                reason: reason instanceof Error ? reason.message : String(reason),
+                stack: reason instanceof Error ? reason.stack : undefined
+            });
+        });
+        appLogger.info("Server startup complete. Ready to handle requests.");
+    }
+    catch (error) {
+        appLogger.error("Failed to start server", {
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined
+        });
+        // Exit with non-zero code to indicate error
+        process.exit(1);
+    }
+};
+// Start the application
+start().catch((error) => {
+    appLogger.error("Fatal error during startup", {
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined
+    });
+    process.exit(1);
+});

package/dist/mcp-server/resources/ntfyResource/getNtfyTopic.d.ts

@@ -0,0 +1,2 @@
+import { NtfyResourceResponse } from './types.js';
+export declare const getNtfyTopic: (uri: URL) => Promise<NtfyResourceResponse>;

package/dist/mcp-server/resources/ntfyResource/getNtfyTopic.js

@@ -0,0 +1,111 @@
+import { config } from '../../../config/index.js';
+import { BaseErrorCode, McpError } from '../../../types-global/errors.js';
+import { ErrorHandler } from '../../../utils/errorHandler.js';
+import { logger } from '../../../utils/logger.js';
+import { createRequestContext } from '../../../utils/security.js';
+// Create resource-specific logger
+const resourceLogger = logger.createChildLogger({
+    module: 'NtfyResource',
+    service: 'NtfyResource'
+});
+export const getNtfyTopic = async (uri) => {
+    // Create a request context with unique ID
+    const requestContext = createRequestContext({
+        operation: 'getNtfyTopic',
+        uri: uri.toString()
+    });
+    const requestId = requestContext.requestId;
+    // Extract the topic from the URI pathname
+    const topic = uri.hostname || "";
+    resourceLogger.info("Ntfy resource request received", {
+        requestId,
+        uri: uri.href,
+        topic
+    });
+    return ErrorHandler.tryCatch(async () => {
+        // Get the default topic from configuration
+        const ntfyConfig = config.ntfy;
+        let defaultTopic = ntfyConfig.defaultTopic;
+        if (!defaultTopic) {
+            resourceLogger.warn("Default ntfy topic is not configured, using fallback value", {
+                requestId,
+                uri: uri.href
+            });
+            // Provide a fallback value instead of failing
+            defaultTopic = "ATLAS";
+        }
+        // Get recent messages asynchronously for this topic
+        let recentMessages = [];
+        try {
+            // Use a different topic for actual fetching based on whether this is default or not
+            const topicToFetch = topic === "default" ? defaultTopic : topic;
+            // Attempt to fetch the 10 most recent messages
+            const response = await fetch(`${config.ntfy.baseUrl || 'https://ntfy.sh'}/${topicToFetch}/json?poll=1&since=30d`, {
+                method: 'GET',
+                headers: {
+                    'Accept': 'application/json'
+                }
+            });
+            if (response.ok) {
+                // Parse response - each line is a separate JSON object
+                const text = await response.text();
+                const lines = text.split('\n').filter(line => line.trim());
+                // Parse each line as a JSON object and add to recent messages
+                recentMessages = lines.map(line => JSON.parse(line))
+                    .filter(msg => msg.event === 'message')
+                    .slice(0, 10); // Keep only the 10 most recent
+                resourceLogger.info(`Retrieved ${recentMessages.length} recent messages`, {
+                    topic: topicToFetch,
+                    requestId
+                });
+            }
+        }
+        catch (error) {
+            // Just log the error but don't fail the request
+            resourceLogger.warn(`Failed to fetch recent messages for topic`, {
+                topic,
+                error: error instanceof Error ? error.message : String(error),
+                requestId
+            });
+        }
+        // Handle the "default" topic case specially
+        const responseData = topic === "default" ?
+            {
+                defaultTopic,
+                timestamp: new Date().toISOString(),
+                requestUri: uri.href,
+                requestId,
+                recentMessages: recentMessages.length > 0 ? recentMessages : undefined
+            } :
+            {
+                topic,
+                timestamp: new Date().toISOString(),
+                requestUri: uri.href,
+                requestId,
+                recentMessages: recentMessages.length > 0 ? recentMessages : undefined
+            };
+        resourceLogger.info("Ntfy resource response data prepared", {
+            requestId,
+            responseData
+        });
+        // Return in the standard MCP format 
+        const response = {
+            contents: [{
+                    uri: uri.href,
+                    text: JSON.stringify(responseData, null, 2),
+                    mimeType: "application/json"
+                }]
+        };
+        return response;
+    }, {
+        context: {
+            requestId,
+            uri: uri.toString()
+        },
+        operation: 'processing ntfy resource request',
+        errorMapper: (error) => {
+            return new McpError(BaseErrorCode.INTERNAL_ERROR, `Error processing ntfy resource request: ${error instanceof Error ? error.message : 'Unknown error'}`, { requestId, uri: uri.toString() });
+        },
+        rethrow: true
+    });
+};

package/dist/mcp-server/resources/ntfyResource/index.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register the ntfy resource with the MCP server
+ *
+ * This function creates and registers the ntfy resource which returns the default
+ * ntfy topic configured in the environment variables. It provides access to this
+ * configuration through a resource URI.
+ *
+ * @param server - The MCP server instance to register the resource with
+ * @returns Promise resolving when registration is complete
+ */
+export declare const registerNtfyResource: (server: McpServer) => Promise<void>;

package/dist/mcp-server/resources/ntfyResource/index.js

@@ -0,0 +1,72 @@
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BaseErrorCode, McpError } from '../../../types-global/errors.js';
+import { registerResource } from '../../utils/registrationHelper.js';
+import { getNtfyTopic } from './getNtfyTopic.js';
+/**
+ * Register the ntfy resource with the MCP server
+ *
+ * This function creates and registers the ntfy resource which returns the default
+ * ntfy topic configured in the environment variables. It provides access to this
+ * configuration through a resource URI.
+ *
+ * @param server - The MCP server instance to register the resource with
+ * @returns Promise resolving when registration is complete
+ */
+export const registerNtfyResource = async (server) => {
+    return registerResource(server, { name: "ntfy-resource" }, async (server, resourceLogger) => {
+        // Create resource template
+        const template = new ResourceTemplate("ntfy://{topic}", {
+            // Simple list implementation
+            list: async () => ({
+                resources: [{
+                        uri: "ntfy://default",
+                        name: "Default Ntfy Topic",
+                        description: "Returns the default ntfy topic configured in environment variables"
+                    }]
+            }),
+            // No completion needed for this resource
+            complete: {}
+        });
+        // Register the resource
+        server.resource(
+        // Resource name
+        "ntfy-resource", 
+        // Resource template
+        template, 
+        // Resource metadata
+        {
+            name: "Ntfy Default Topic",
+            description: "Returns the default ntfy topic configured in environment variables",
+            mimeType: "application/json",
+            // No query parameters needed for this resource
+            // Examples
+            examples: [
+                {
+                    name: "Default topic",
+                    uri: "ntfy://default",
+                    description: "Get the default ntfy topic"
+                }
+            ],
+        }, 
+        // Resource handler
+        async (uri, params) => {
+            // Extract the topic from the URI
+            const topic = params.topic;
+            resourceLogger.info(`Processing ntfy resource request for topic: ${topic}`, {
+                topic,
+                href: uri.href
+            });
+            // Check if the topic is valid
+            if (!topic) {
+                resourceLogger.error(`Missing topic in ntfy resource uri: ${uri.href}`, {
+                    href: uri.href,
+                    protocol: uri.protocol
+                });
+                throw new McpError(BaseErrorCode.NOT_FOUND, `Resource not found: ${uri.href}`, { uri: uri.href });
+            }
+            // Process the request using our dedicated handler
+            return await getNtfyTopic(uri);
+        });
+        resourceLogger.info("Ntfy resource handler registered");
+    });
+};

package/dist/mcp-server/resources/ntfyResource/types.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+/**
+ * Schema for validating ntfy resource query parameters
+ */
+export declare const NtfyResourceQuerySchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export type NtfyResourceQuery = z.infer<typeof NtfyResourceQuerySchema>;
+/**
+ * Response type for the ntfy resource, matching MCP SDK expectations
+ */
+export interface NtfyResourceResponse {
+    [key: string]: unknown;
+    contents: [
+        {
+            uri: string;
+            text: string;
+            mimeType: "application/json";
+        }
+    ];
+}
+/**
+ * Data structure for the ntfy response
+ */
+export interface NtfyData {
+    defaultTopic: string;
+    timestamp: string;
+    requestUri: string;
+}

package/dist/mcp-server/resources/ntfyResource/types.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+/**
+ * Schema for validating ntfy resource query parameters
+ */
+export const NtfyResourceQuerySchema = z.object({
+// No parameters needed for default topic
+}).describe('Query parameters for the ntfy resource.\n' +
+    'URI Format: ntfy://default');

package/dist/mcp-server/server.d.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Server state management interface
+ */
+export interface ServerState {
+    status: 'initializing' | 'running' | 'error' | 'degraded' | 'shutting_down' | 'shutdown';
+    startTime: Date;
+    lastHealthCheck: Date;
+    activeOperations: Map<string, {
+        operation: string;
+        startTime: Date;
+    }>;
+    errors: Array<{
+        timestamp: Date;
+        message: string;
+        code?: string;
+    }>;
+    registeredTools: Set<string>;
+    registeredResources: Set<string>;
+    failedRegistrations: Array<{
+        type: 'tool' | 'resource';
+        name: string;
+        error: any;
+        attempts: number;
+    }>;
+    requiredTools: Set<string>;
+    requiredResources: Set<string>;
+}
+/**
+ * Create and initialize an MCP server instance with all tools and resources
+ *
+ * This function configures the MCP server with security settings, tools, and resources.
+ * It connects the server to a transport (currently stdio) and returns the initialized
+ * server instance.
+ *
+ * @returns A promise that resolves to the initialized McpServer instance
+ * @throws {McpError} If the server fails to initialize
+ */
+export declare const createMcpServer: () => Promise<McpServer>;