Message MCP

Instructions

Implementation Reference

• src/index.ts:82-222 (handler)

  The asynchronous handler function for the 'notify' tool. It processes the title and message inputs, constructs notification content, and dispatches notifications across multiple channels including NTFY, email (via nodemailer), custom API, sound playback, and desktop notifications (via node-notifier). It awaits all promises and returns a content array with results from each channel.

    async ({ title, message }) => {
      const notifyTitle = title || 'Message MCP'
      const notifyMessage = message || 'Task completed, please review.'
      const allNotifyPromise: { [key: string]: Promise<unknown> } = {}
  
      // NTFY notification
      if (config.ntfyTopic) {
        const safeTopic = encodeURIComponent(config.ntfyTopic)
        allNotifyPromise.ntfy = upfetch(`https://ntfy.sh/${safeTopic}`, {
          method: 'POST',
          body: notifyMessage,
          headers: {
            Title: rfc2047.encode(notifyTitle),
            Priority: 'urgent',
          },
        })
      }
  
      // Email notification
      if (config.smtpHost && config.smtpUser && config.smtpPass) {
        const transporter = nodemailer.createTransport({
          host: config.smtpHost,
          port: config.smtpPort,
          secure: config.smtpSecure,
          auth: {
            user: config.smtpUser,
            pass: config.smtpPass,
          },
          pool: true,
          maxConnections: 5,
        })
  
        const mailOptions = {
          from: config.smtpUser,
          to: config.smtpUser,
          subject: notifyTitle,
          text: notifyMessage,
        }
  
        allNotifyPromise.nodemailer = transporter.sendMail(mailOptions)
      }
  
      // API notification
      if (config.apiUrl) {
        allNotifyPromise.api = upfetch(config.apiUrl, {
          method: config.apiMethod,
          headers: config.apiHeaders,
          body: {
            title: notifyTitle,
            message: notifyMessage,
          },
        })
      }
  
      // Desktop play sound notification
      if (!config.disableDesktop) {
        // Sound notification
        const player = play({})
        const internalSoundPath = join(__dirname, 'assets', 'notify.mp3')
        const soundPath = config.soundPath || internalSoundPath
  
        allNotifyPromise.sound = new Promise((resolve, reject) => {
          player.play(soundPath, (error) => {
            if (error) {
              reject(error)
            }
          })
          setTimeout(() => {
            resolve({
              message: 'Sound notification played successfully!',
            })
          }, 1500)
        })
  
        // Desktop notification
        allNotifyPromise.desktop = new Promise((resolve, reject) => {
          notifier.notify(
            {
              title: notifyTitle,
              message: notifyMessage,
              sound: false,
            },
            (error) => {
              if (error) {
                reject(error)
              }
            },
          )
  
          setTimeout(() => {
            resolve({
              message: 'Desktop notification sent successfully!',
            })
          }, 1500)
        })
      }
  
      // Wait for all notifications to complete
      if (Object.keys(allNotifyPromise).length === 0) {
        return {
          content: [
            {
              type: 'text' as const,
              text: 'No notification channels configured.',
            },
          ],
        }
      }
  
      // Collect results from all notifications
      const entries = Object.entries(allNotifyPromise)
      const results = await Promise.allSettled(entries.map(([, p]) => p))
      const content: { type: 'text'; text: string }[] = []
  
      results.forEach((result, i) => {
        const [name] = entries[i]
        let message = ''
  
        if (result.status === 'fulfilled') {
          message =
            typeof result.value === 'object'
              ? `successfully! ${JSON.stringify(result.value)}`
              : 'successfully!'
        } else {
          message =
            result.reason instanceof Error
              ? `failed! ${result.reason.message}`
              : 'failed!'
        }
  
        content.push({
          type: 'text' as const,
          text: `${name} ${message}`,
        })
      })
  
      return {
        content,
      }
    },
  )

• src/index.ts:74-80 (schema)

  Zod input schema definition for the 'notify' tool, defining optional 'title' and 'message' string parameters with descriptions.

  inputSchema: {
    title: z.string().optional().describe('The title of the notification'),
    message: z
      .string()
      .optional()
      .describe('The main content of the notification message'),
  },

• src/index.ts:68-222 (registration)

  Registration of the 'notify' tool on the McpServer instance, specifying the tool name, metadata (title, description, inputSchema), and the handler function.

  server.registerTool(
    'notify',
    {
      title: 'Send Message Notification',
      description:
        'Send notifications and messages through multiple channels (desktop, email, API). Use this tool to notify users about any important information, progress updates, task completions, alerts, or any other communication needs.',
      inputSchema: {
        title: z.string().optional().describe('The title of the notification'),
        message: z
          .string()
          .optional()
          .describe('The main content of the notification message'),
      },
    },
    async ({ title, message }) => {
      const notifyTitle = title || 'Message MCP'
      const notifyMessage = message || 'Task completed, please review.'
      const allNotifyPromise: { [key: string]: Promise<unknown> } = {}
  
      // NTFY notification
      if (config.ntfyTopic) {
        const safeTopic = encodeURIComponent(config.ntfyTopic)
        allNotifyPromise.ntfy = upfetch(`https://ntfy.sh/${safeTopic}`, {
          method: 'POST',
          body: notifyMessage,
          headers: {
            Title: rfc2047.encode(notifyTitle),
            Priority: 'urgent',
          },
        })
      }
  
      // Email notification
      if (config.smtpHost && config.smtpUser && config.smtpPass) {
        const transporter = nodemailer.createTransport({
          host: config.smtpHost,
          port: config.smtpPort,
          secure: config.smtpSecure,
          auth: {
            user: config.smtpUser,
            pass: config.smtpPass,
          },
          pool: true,
          maxConnections: 5,
        })
  
        const mailOptions = {
          from: config.smtpUser,
          to: config.smtpUser,
          subject: notifyTitle,
          text: notifyMessage,
        }
  
        allNotifyPromise.nodemailer = transporter.sendMail(mailOptions)
      }
  
      // API notification
      if (config.apiUrl) {
        allNotifyPromise.api = upfetch(config.apiUrl, {
          method: config.apiMethod,
          headers: config.apiHeaders,
          body: {
            title: notifyTitle,
            message: notifyMessage,
          },
        })
      }
  
      // Desktop play sound notification
      if (!config.disableDesktop) {
        // Sound notification
        const player = play({})
        const internalSoundPath = join(__dirname, 'assets', 'notify.mp3')
        const soundPath = config.soundPath || internalSoundPath
  
        allNotifyPromise.sound = new Promise((resolve, reject) => {
          player.play(soundPath, (error) => {
            if (error) {
              reject(error)
            }
          })
          setTimeout(() => {
            resolve({
              message: 'Sound notification played successfully!',
            })
          }, 1500)
        })
  
        // Desktop notification
        allNotifyPromise.desktop = new Promise((resolve, reject) => {
          notifier.notify(
            {
              title: notifyTitle,
              message: notifyMessage,
              sound: false,
            },
            (error) => {
              if (error) {
                reject(error)
              }
            },
          )
  
          setTimeout(() => {
            resolve({
              message: 'Desktop notification sent successfully!',
            })
          }, 1500)
        })
      }
  
      // Wait for all notifications to complete
      if (Object.keys(allNotifyPromise).length === 0) {
        return {
          content: [
            {
              type: 'text' as const,
              text: 'No notification channels configured.',
            },
          ],
        }
      }
  
      // Collect results from all notifications
      const entries = Object.entries(allNotifyPromise)
      const results = await Promise.allSettled(entries.map(([, p]) => p))
      const content: { type: 'text'; text: string }[] = []
  
      results.forEach((result, i) => {
        const [name] = entries[i]
        let message = ''
  
        if (result.status === 'fulfilled') {
          message =
            typeof result.value === 'object'
              ? `successfully! ${JSON.stringify(result.value)}`
              : 'successfully!'
        } else {
          message =
            result.reason instanceof Error
              ? `failed! ${result.reason.message}`
              : 'failed!'
        }
  
        content.push({
          type: 'text' as const,
          text: `${name} ${message}`,
        })
      })
  
      return {
        content,
      }
    },
  )

• src/index.ts:49-61 (helper)

  Configuration object for the notify tool, loaded from environment variables using utility functions for various notification channels.

  const config: MessageMcpConfig = {
    disableDesktop: getBoolean(options.shttp || process.env.DISABLE_DESKTOP),
    soundPath: process.env.SOUND_PATH,
    ntfyTopic: process.env.NTFY_TOPIC,
    smtpHost: process.env.SMTP_HOST,
    smtpPort: Number(process.env.SMTP_PORT) || 587,
    smtpSecure: getBoolean(process.env.SMTP_SECURE),
    smtpUser: process.env.SMTP_USER,
    smtpPass: process.env.SMTP_PASS,
    apiUrl: process.env.API_URL,
    apiHeaders: getHeaders(process.env.API_HEADERS),
    apiMethod: getApiMethod(process.env.API_METHOD),
  }

• src/utils.ts:1-9 (helper)

  Utility function getBoolean used to parse boolean config values like disableDesktop from env vars or options.

  export function getBoolean(value?: string | boolean): boolean {
    if (typeof value === 'boolean') {
      return value
    }
    if (typeof value === 'string') {
      return value.toLowerCase() === 'true' || value === '1'
    }
    return false
  }