apple-notifier-mcp

Instructions

Implementation Reference

• src/features/notification.ts:52-81 (handler)

  Main handler function for send_notification tool. Validates input parameters, constructs AppleScript for osascript to display macOS notification, executes the command, and handles errors appropriately.

  export async function sendNotification(params: NotificationParams): Promise<void> {
    try {
      validateParams(params);
      const command = buildNotificationCommand(params);
      await execAsync(command);
    } catch (error) {
      if (error instanceof NotificationError) {
        throw error;
      }
  
      // Handle different types of system errors
      const err = error as Error;
      if (err.message.includes('execution error')) {
        throw new NotificationError(
          NotificationErrorType.COMMAND_FAILED,
          'Failed to execute notification command'
        );
      } else if (err.message.includes('permission')) {
        throw new NotificationError(
          NotificationErrorType.PERMISSION_DENIED,
          'Permission denied when trying to send notification'
        );
      } else {
        throw new NotificationError(
          NotificationErrorType.UNKNOWN,
          `Unexpected error: ${err.message}`
        );
      }
    }
  }

• src/types.ts:4-13 (schema)

  TypeScript interface defining the input parameters (NotificationParams) used by the send_notification handler.

  export interface NotificationParams {
    /** Title of the notification */
    title: string;
    /** Main message content */
    message: string;
    /** Optional subtitle */
    subtitle?: string;
    /** Whether to play the default notification sound */
    sound?: boolean;
  }

• src/index.ts:59-85 (registration)

  Tool registration in the MCP server's listTools handler, including name, description, and input schema matching NotificationParams.

    name: 'send_notification',
    description: 'Send a notification on macOS using osascript',
    inputSchema: {
      type: 'object',
      properties: {
        title: {
          type: 'string',
          description: 'Title of the notification',
        },
        message: {
          type: 'string',
          description: 'Main message content',
        },
        subtitle: {
          type: 'string',
          description: 'Optional subtitle',
        },
        sound: {
          type: 'boolean',
          description: 'Whether to play the default notification sound',
          default: true,
        },
      },
      required: ['title', 'message'],
      additionalProperties: false,
    },
  },

• src/index.ts:223-246 (handler)

  MCP CallToolRequestSchema dispatch handler for 'send_notification': parses arguments, validates basics, constructs NotificationParams, calls sendNotification, and returns success response.

  case 'send_notification': {
    const { title, message, subtitle, sound } = request.params.arguments as Record<string, unknown>;
    
    if (typeof title !== 'string' || typeof message !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Title and message must be strings');
    }
  
    const params: NotificationParams = {
      title,
      message,
      subtitle: typeof subtitle === 'string' ? subtitle : undefined,
      sound: typeof sound === 'boolean' ? sound : undefined
    };
  
    await sendNotification(params);
    return {
      content: [
        {
          type: 'text',
          text: 'Notification sent successfully',
        },
      ],
    };
  }

• src/features/notification.ts:7-28 (helper)

  Helper function to validate NotificationParams inputs before sending the notification.

  function validateParams(params: NotificationParams): void {
    if (!params.title || typeof params.title !== 'string') {
      throw new NotificationError(
        NotificationErrorType.INVALID_PARAMS,
        'Title is required and must be a string'
      );
    }
  
    if (!params.message || typeof params.message !== 'string') {
      throw new NotificationError(
        NotificationErrorType.INVALID_PARAMS,
        'Message is required and must be a string'
      );
    }
  
    if (params.subtitle && typeof params.subtitle !== 'string') {
      throw new NotificationError(
        NotificationErrorType.INVALID_PARAMS,
        'Subtitle must be a string'
      );
    }
  }