OnSecurity MCP Server

Instructions

Implementation Reference

• src/index.ts:379-437 (handler)

  The main handler function for the 'get-rounds' tool. Processes input parameters to build filters, fetches paginated rounds data from the OnSecurity API using fetchPage, formats the results using formatRound and formatPaginationInfo, constructs a markdown summary, and returns it as MCP text content.

  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;
          });
      }
      
      // Add round_type filter if provided
      if (params.round_type) {
          filters['round_type_id-eq'] = params.round_type;
      }
      
      const response = await fetchPage<ApiResponse<RoundFeature>>(
          'rounds', 
          params.page || 1, 
          filters, 
          params.sort, 
          params.includes, 
          params.fields, 
          params.limit,
          params.search
      );
      
      if (!response) {
          return {
              content: [
                  {
                      type: "text",
                      text: "Error fetching rounds data. Please try again."
                  }
              ]
          };
      }
      
      const paginationInfo = formatPaginationInfo(response);
      const formattedRounds = response.result.map(formatRound);
      
      const responseText = [
          "# Rounds Summary",
          "",
          "## Pagination Information",
          paginationInfo,
          "",
          "## Rounds Data",
          ...formattedRounds
      ].join('\n');
  
      return {
          content: [
              {
                  type: "text",
                  text: responseText
              }
          ]
      };
  }

• src/index.ts:370-378 (schema)

  Zod input schema defining optional parameters for filtering, sorting, pagination, includes, fields, custom filters, and search for the 'get-rounds' tool.

      round_type: z.number().optional().describe("Optional round type to filter rounds, 1 = pentest round, 3 = scan round"),
      sort: z.string().optional().describe("Optional sort parameter in format 'field-direction'. Available values: name-asc, start_date-asc, end_date-asc, authorisation_date-asc, hours_estimate-asc, created_at-asc, updated_at-asc, name-desc, start_date-desc, end_date-desc, authorisation_date-desc, hours_estimate-desc, created_at-desc, updated_at-desc. Default: id-asc"),
      limit: z.number().optional().describe("Optional limit parameter for max results per page (e.g. 15)"),
      page: z.number().optional().describe("Optional page number to fetch (default: 1)"),
      includes: z.string().optional().describe("Optional related data to include as comma-separated values (e.g. 'client,findings,targets')"),
      fields: z.string().optional().describe("Optional comma-separated list of fields to return (e.g. 'id,name,started'). Use * as wildcard."),
      filters: FilterSchema,
      search: z.string().optional().describe("Search term to find rounds by name of round or name of client")
  },

• src/index.ts:366-438 (registration)

  Registration of the 'get-rounds' tool using server.tool(), including name, description, input schema, and inline handler function.

  server.tool(
      "get-rounds",
      "Get all rounds data from OnSecurity from client in a high level summary. When replying, 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. Rounds can be pentest rounds, scan rounds, or radar rounds.",
      {
          round_type: z.number().optional().describe("Optional round type to filter rounds, 1 = pentest round, 3 = scan round"),
          sort: z.string().optional().describe("Optional sort parameter in format 'field-direction'. Available values: name-asc, start_date-asc, end_date-asc, authorisation_date-asc, hours_estimate-asc, created_at-asc, updated_at-asc, name-desc, start_date-desc, end_date-desc, authorisation_date-desc, hours_estimate-desc, created_at-desc, updated_at-desc. Default: id-asc"),
          limit: z.number().optional().describe("Optional limit parameter for max results per page (e.g. 15)"),
          page: z.number().optional().describe("Optional page number to fetch (default: 1)"),
          includes: z.string().optional().describe("Optional related data to include as comma-separated values (e.g. 'client,findings,targets')"),
          fields: z.string().optional().describe("Optional comma-separated list of fields to return (e.g. 'id,name,started'). Use * as wildcard."),
          filters: FilterSchema,
          search: z.string().optional().describe("Search term to find rounds by name of round or name of client")
      },
      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;
              });
          }
          
          // Add round_type filter if provided
          if (params.round_type) {
              filters['round_type_id-eq'] = params.round_type;
          }
          
          const response = await fetchPage<ApiResponse<RoundFeature>>(
              'rounds', 
              params.page || 1, 
              filters, 
              params.sort, 
              params.includes, 
              params.fields, 
              params.limit,
              params.search
          );
          
          if (!response) {
              return {
                  content: [
                      {
                          type: "text",
                          text: "Error fetching rounds data. Please try again."
                      }
                  ]
              };
          }
          
          const paginationInfo = formatPaginationInfo(response);
          const formattedRounds = response.result.map(formatRound);
          
          const responseText = [
              "# Rounds Summary",
              "",
              "## Pagination Information",
              paginationInfo,
              "",
              "## Rounds Data",
              ...formattedRounds
          ].join('\n');
  
          return {
              content: [
                  {
                      type: "text",
                      text: responseText
                  }
              ]
          };
      }
  );

• src/index.ts:262-275 (helper)

  Helper function used by the handler to format individual RoundFeature objects into readable multi-line strings.

  function formatRound(round: RoundFeature): string {
      return [
          `Round ID: ${round.id}`,
          `Client ID: ${round.client_id}`,
          `Round Type: ${round.round_type_id === 1 ? "pentest round" : round.round_type_id === 3 ? "scan round" : round.round_type_id}`,
          `Estimated: ${round.estimate.time} ${round.estimate.period}`,
          `Start Date: ${round.start_date || "Unknown"}`,
          `End Date: ${round.end_date || "Unknown"}`,
          `Started: ${round.started}`,
          `Completed: ${round.finished}`,
          `Name: ${round.name}`,
          `Executive Summary Published: ${round.executive_summary_published}`,
          `--------------------------------`,
      ].join('\n');

• src/index.ts:221-258 (helper)

  Generic helper function used by the handler to fetch a paginated page of data from the OnSecurity API, building query parameters from inputs.

  async function fetchPage<T>(
    basePath: string,
    page: number = 1,
    filters: Record<string, string | number> = {},
    sort?: string,
    includes?: string,
    fields?: string,
    limit?: number,
    search?: string
  ): Promise<T | null> {
    // Build query parameters
    const queryParams = new URLSearchParams();
    
    // Add page parameter
    queryParams.append('page', page.toString());
    
    // Add limit if provided
    if (limit) queryParams.append('limit', limit.toString());
    
    // Add sort if provided
    if (sort) queryParams.append('sort', sort);
    
    // Add includes if provided
    if (includes) queryParams.append('include', includes);
    
    // Add fields if provided
    if (fields) queryParams.append('fields', fields);
    
    // Add search if provided
    if (search) queryParams.append('search', search);
    
    // Add filters
    Object.entries(filters).forEach(([key, value]) => {
      queryParams.append(`filter[${key}]`, value.toString());
    });
    
    const url = `${ONSECURITY_API_BASE}/${basePath}?${queryParams.toString()}`;
    return await makeOnSecurityRequest<T>(url);