send_notification

Instructions

Implementation Reference

• src/index.ts:113-174 (handler)

  MCP tool handler for send_notification: validates inputs, handles tmux current/useCurrent logic, session validation, and calls notifier.sendNotification

  case 'send_notification': {
    // Safely extract properties from args
    const notificationArgs = args as Record<string, unknown>
  
    // Validate message is provided
    if (!notificationArgs.message) {
      throw new Error('Message is required')
    }
  
    const options: NotificationOptions = {
      message: String(notificationArgs.message),
      title: notificationArgs.title
        ? String(notificationArgs.title)
        : undefined,
      sound: notificationArgs.sound
        ? String(notificationArgs.sound)
        : undefined,
    }
  
    if (notificationArgs.useCurrent) {
      const current = await notifier.getCurrentTmuxInfo()
      if (current) {
        options.session = current.session
        options.window = current.window
        options.pane = current.pane
      }
    } else {
      if (notificationArgs.session)
        options.session = String(notificationArgs.session)
      if (notificationArgs.window)
        options.window = String(notificationArgs.window)
      if (notificationArgs.pane)
        options.pane = String(notificationArgs.pane)
    }
  
    // Validate session if specified
    if (options.session) {
      const exists = await notifier.sessionExists(options.session)
      if (!exists) {
        const sessions = await notifier.listSessions()
        return {
          content: [
            {
              type: 'text',
              text: `Error: Session '${options.session}' does not exist. Available sessions: ${sessions.join(', ')}`,
            },
          ],
        }
      }
    }
  
    await notifier.sendNotification(options)
  
    return {
      content: [
        {
          type: 'text',
          text: `Notification sent: "${options.message}"${options.session ? ` (tmux: ${options.session})` : ''}`,
        },
      ],
    }
  }

• src/index.ts:48-81 (schema)

  Input schema for the send_notification tool defining parameters and validation rules

  inputSchema: {
    type: 'object',
    properties: {
      message: {
        type: 'string',
        description: 'The notification message',
      },
      title: {
        type: 'string',
        description: 'The notification title (default: "Claude Code")',
      },
      sound: {
        type: 'string',
        description: 'The notification sound (default: "Glass")',
      },
      session: {
        type: 'string',
        description: 'tmux session name',
      },
      window: {
        type: 'string',
        description: 'tmux window number',
      },
      pane: {
        type: 'string',
        description: 'tmux pane number',
      },
      useCurrent: {
        type: 'boolean',
        description: 'Use current tmux location',
      },
    },
    required: ['message'],
  },

• src/index.ts:45-82 (registration)

  Registration of the send_notification tool in the MCP tools list response

  {
    name: 'send_notification',
    description: 'Send a macOS notification with optional tmux integration',
    inputSchema: {
      type: 'object',
      properties: {
        message: {
          type: 'string',
          description: 'The notification message',
        },
        title: {
          type: 'string',
          description: 'The notification title (default: "Claude Code")',
        },
        sound: {
          type: 'string',
          description: 'The notification sound (default: "Glass")',
        },
        session: {
          type: 'string',
          description: 'tmux session name',
        },
        window: {
          type: 'string',
          description: 'tmux window number',
        },
        pane: {
          type: 'string',
          description: 'tmux pane number',
        },
        useCurrent: {
          type: 'boolean',
          description: 'Use current tmux location',
        },
      },
      required: ['message'],
    },
  },

• src/notifier.ts:452-497 (helper)

  Helper function implementing the actual notification sending logic via MacOSNotifyMCP.app, including terminal detection and tmux targeting

    async sendNotification(options: NotificationOptions): Promise<void> {
      const {
        title = this.defaultTitle,
        message,
        sound = 'Glass',
        session,
        window,
        pane,
      } = options
  
      // Check if app path is valid
      if (!this.appPath) {
        throw new Error('MacOSNotifyMCP.app not found')
      }
  
      // Always detect terminal emulator to pass to notification app
      const terminal = await this.detectTerminalEmulator()
  
      // Use MacOSNotifyMCP.app for notifications
      const args = [
        '-n',
        this.appPath,
        '--args',
        '-t',
        title,
        '-m',
        message,
        '--sound',
        sound,
        '--terminal',
        terminal,
      ]
  
      if (session) {
        args.push('-s', session)
        if (window !== undefined && window !== '') {
          args.push('-w', window)
        }
        if (pane !== undefined && pane !== '') {
          args.push('-p', pane)
        }
      }
  
      await this.runCommand('/usr/bin/open', args)
    }
  }

• src/index.ts:12-19 (schema)

  Type definition for NotificationOptions used in the handler

  interface NotificationOptions {
    message: string
    title?: string
    sound?: string
    session?: string
    window?: string
    pane?: string
  }