OnSecurity MCP Server

Instructions

Implementation Reference

• src/index.ts:533-585 (handler)

  The main execution logic for the get-notifications tool. It processes input parameters, applies filters, fetches notification data from the OnSecurity API via fetchPage, formats the results using formatNotification and formatPaginationInfo, and returns a structured markdown text response.

  async (params) => {
      const filters: Record<string, string | number> = {};
      
      // Add additional filters if provided
      if (params.filters) {
          Object.entries(params.filters).forEach(([key, value]) => {
              filters[key] = value;
          });
      }
      
      const response = await fetchPage<ApiResponse<NotificationFeature>>(
          'notifications', 
          params.page || 1, 
          filters, 
          params.sort, 
          params.includes, 
          params.fields, 
          params.limit
      );
      
      if (!response) {
          return {
              content: [
                  {
                      type: "text",
                      text: "Error fetching notifications data. Please try again."
                  }
              ]
          };
      }
      
      const paginationInfo = formatPaginationInfo(response);
      const formattedNotifications = response.result.map(formatNotification);
      
      const responseText = [
          "# Notifications Summary",
          "",
          "## Pagination Information",
          paginationInfo,
          "",
          "## Notifications Data",
          ...formattedNotifications
      ].join('\n');
  
      return {
          content: [
              {
                  type: "text",
                  text: responseText
              }
          ]
      };
  }

• src/index.ts:525-532 (schema)

  Zod schema defining the input parameters for the get-notifications tool, including pagination, sorting, filtering, and field selection options.

  {
      sort: z.string().optional().describe("Optional sort parameter (e.g. 'created_at-desc' for newest first)"),
      limit: z.number().optional().describe("Optional limit parameter (e.g. 10 for 10 notifications per page)"),
      page: z.number().optional().describe("Optional page number to fetch (default: 1)"),
      includes: z.string().optional().describe("Optional related data to include"),
      fields: z.string().optional().describe("Optional comma-separated list of fields to return (e.g. 'heading,created_at')"),
      filters: FilterSchema,
  },

• src/index.ts:522-586 (registration)

  The server.tool call that registers the 'get-notifications' tool with the MCP server, including its name, description, input schema, and handler function.

  server.tool(
      "get-notifications",
      "Get all notifications data from OnSecurity from client in a high level summary, only include the summary, not the raw data and be sure to present the data in a way that is easy to understand for the client.",
      {
          sort: z.string().optional().describe("Optional sort parameter (e.g. 'created_at-desc' for newest first)"),
          limit: z.number().optional().describe("Optional limit parameter (e.g. 10 for 10 notifications per page)"),
          page: z.number().optional().describe("Optional page number to fetch (default: 1)"),
          includes: z.string().optional().describe("Optional related data to include"),
          fields: z.string().optional().describe("Optional comma-separated list of fields to return (e.g. 'heading,created_at')"),
          filters: FilterSchema,
      },
      async (params) => {
          const filters: Record<string, string | number> = {};
          
          // Add additional filters if provided
          if (params.filters) {
              Object.entries(params.filters).forEach(([key, value]) => {
                  filters[key] = value;
              });
          }
          
          const response = await fetchPage<ApiResponse<NotificationFeature>>(
              'notifications', 
              params.page || 1, 
              filters, 
              params.sort, 
              params.includes, 
              params.fields, 
              params.limit
          );
          
          if (!response) {
              return {
                  content: [
                      {
                          type: "text",
                          text: "Error fetching notifications data. Please try again."
                      }
                  ]
              };
          }
          
          const paginationInfo = formatPaginationInfo(response);
          const formattedNotifications = response.result.map(formatNotification);
          
          const responseText = [
              "# Notifications Summary",
              "",
              "## Pagination Information",
              paginationInfo,
              "",
              "## Notifications Data",
              ...formattedNotifications
          ].join('\n');
  
          return {
              content: [
                  {
                      type: "text",
                      text: responseText
                  }
              ]
          };
      }
  );

• src/index.ts:302-308 (helper)

  Utility function specifically used by the get-notifications handler to format individual notification data into a readable string.

  function formatNotification(notification: NotificationFeature): string {
      return [
          `Content: ${notification.heading}`,
          `Created At: ${notification.created_at}`,
          `Updated At: ${notification.updated_at}`,
          `--------------------------------`,
      ].join('\n');

• src/index.ts:84-105 (schema)

  TypeScript interfaces defining the structure of NotificationFeature (single notification) and NotificationResponse (paginated API response), used for type safety in the tool implementation.

  export interface NotificationFeature {
      heading?: string;
      created_at?: string;
      updated_at?: string;
  }
  
  export interface NotificationResponse {
      links: {
          self: string;
          first: string;
          next: string | null;
          previous: string | null;
          last: string;
      };
      limit: number;
      sort: null;
      includes: any[];
      total_results: number;
      total_pages: number;
      page: number;
      result: NotificationFeature[];
  }