OnSecurity MCP Server

Instructions

Implementation Reference

• src/index.ts:673-741 (handler)

  The main execution logic for the 'get-blocks' tool: constructs filters from parameters, fetches paginated blocks data via API, handles errors, formats output with pagination and block summaries, returns 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;
          });
      }
      
      // Add round_type_id filter if provided
      if (params.round_type_id) {
          filters['round_type_id-eq'] = params.round_type_id;
      }
      
      // Add approved filter if provided
      if (params.approved !== undefined) {
          filters['approved-eq'] = params.approved ? 1 : 0;
      }
      
      // Add automation_approved filter if provided
      if (params.automation_approved !== undefined) {
          filters['automation_approved-eq'] = params.automation_approved ? 1 : 0;
      }
      
      const response = await fetchPage<ApiResponse<BlockFeature>>(
          'blocks', 
          params.page || 1, 
          filters, 
          params.sort, 
          params.includes, 
          params.fields, 
          params.limit,
          params.search
      );
      
      if (!response) {
          return {
              content: [
                  {
                      type: "text",
                      text: "Error fetching blocks data. Please try again."
                  }
              ]
          };
      }
      
      const paginationInfo = formatPaginationInfo(response);
      const formattedBlocks = response.result.map(formatBlock);
      
      const responseText = [
          "# Blocks Summary",
          "",
          "## Pagination Information",
          paginationInfo,
          "",
          "## Blocks Data",
          ...formattedBlocks
      ].join('\n');
  
      return {
          content: [
              {
                  type: "text",
                  text: responseText
              }
          ]
      };
  }

• src/index.ts:661-672 (schema)

  Input validation schema using Zod for 'get-blocks' tool parameters: pagination (page, limit), sorting, filtering (round_type_id, approved, automation_approved, filters), includes, fields, search.

  {
      round_type_id: z.number().optional().describe("Optional round type ID to filter blocks, 1 = pentest round, 3 = scan round"),
      approved: z.boolean().optional().describe("Optional filter for approved blocks only"),
      automation_approved: z.boolean().optional().describe("Optional filter for automation approved blocks only"),
      sort: z.string().optional().describe("Optional sort parameter in format 'field-direction'. Available values: id-asc, round_type_id-asc, name-asc, approved-asc, used_count-asc, created_at-asc, updated_at-asc, id-desc, round_type_id-desc, name-desc, approved-desc, used_count-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. Available: block_business_risks, block_field_variants, block_imports, block_references, block_remediations, block_target_types, block_variables, business_risks, remediations, revisions (e.g. 'block_business_risks,block_remediations')"),
      fields: z.string().optional().describe("Optional comma-separated list of fields to return (e.g. 'id,name,approved'). Use * as wildcard."),
      filters: FilterSchema,
      search: z.string().optional().describe("Optional search term to filter blocks by matching text")
  },

• src/index.ts:658-742 (registration)

  Registration of the 'get-blocks' tool on the MCP server, specifying name, description, input schema, and handler function.

  server.tool(
      "get-blocks",
      "Get all blocks data from OnSecurity. Blocks are reusable security finding templates that can be used across different assessments. They contain standardized vulnerability descriptions, risks, and recommendations. Note that you can get how often a block is used, which is a way to get the most common findings ACROSS ALL CLIENTS ONLY as blocks are the basis of findings across pentests and scans. ",
      {
          round_type_id: z.number().optional().describe("Optional round type ID to filter blocks, 1 = pentest round, 3 = scan round"),
          approved: z.boolean().optional().describe("Optional filter for approved blocks only"),
          automation_approved: z.boolean().optional().describe("Optional filter for automation approved blocks only"),
          sort: z.string().optional().describe("Optional sort parameter in format 'field-direction'. Available values: id-asc, round_type_id-asc, name-asc, approved-asc, used_count-asc, created_at-asc, updated_at-asc, id-desc, round_type_id-desc, name-desc, approved-desc, used_count-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. Available: block_business_risks, block_field_variants, block_imports, block_references, block_remediations, block_target_types, block_variables, business_risks, remediations, revisions (e.g. 'block_business_risks,block_remediations')"),
          fields: z.string().optional().describe("Optional comma-separated list of fields to return (e.g. 'id,name,approved'). Use * as wildcard."),
          filters: FilterSchema,
          search: z.string().optional().describe("Optional search term to filter blocks by matching text")
      },
      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_id filter if provided
          if (params.round_type_id) {
              filters['round_type_id-eq'] = params.round_type_id;
          }
          
          // Add approved filter if provided
          if (params.approved !== undefined) {
              filters['approved-eq'] = params.approved ? 1 : 0;
          }
          
          // Add automation_approved filter if provided
          if (params.automation_approved !== undefined) {
              filters['automation_approved-eq'] = params.automation_approved ? 1 : 0;
          }
          
          const response = await fetchPage<ApiResponse<BlockFeature>>(
              'blocks', 
              params.page || 1, 
              filters, 
              params.sort, 
              params.includes, 
              params.fields, 
              params.limit,
              params.search
          );
          
          if (!response) {
              return {
                  content: [
                      {
                          type: "text",
                          text: "Error fetching blocks data. Please try again."
                      }
                  ]
              };
          }
          
          const paginationInfo = formatPaginationInfo(response);
          const formattedBlocks = response.result.map(formatBlock);
          
          const responseText = [
              "# Blocks Summary",
              "",
              "## Pagination Information",
              paginationInfo,
              "",
              "## Blocks Data",
              ...formattedBlocks
          ].join('\n');
  
          return {
              content: [
                  {
                      type: "text",
                      text: responseText
                  }
              ]
          };
      }
  );

• src/index.ts:327-347 (helper)

  Supporting function to format a single BlockFeature object into a human-readable markdown summary used in the tool's response.

  function formatBlock(block: BlockFeature): string {
      return [
          `Block ID: ${block.id}`,
          `Name: ${block.name}`,
          `Round Type ID: ${block.round_type_id}`,
          `Approved: ${block.approved}`,
          `Automation Approved: ${block.automation_approved}`,
          `Used Count: ${block.used_count}`,
          `Remediation Complexity: ${block.remediation_complexity || "N/A"}`,
          `CVSS Score: ${block.ratings?.cvss?.score || block.cvss?.score || "N/A"}`,
          `Executive Description: ${block.executive_description ? block.executive_description.substring(0, 200) + "..." : "N/A"}`,
          `Executive Risk: ${block.executive_risk ? block.executive_risk.substring(0, 200) + "..." : "N/A"}`,
          `Executive Recommendation: ${block.executive_recommendation ? block.executive_recommendation.substring(0, 200) + "..." : "N/A"}`,
          `Description: ${block.description ? block.description.substring(0, 200) + "..." : "N/A"}`,
          `Evidence: ${block.evidence ? block.evidence.substring(0, 200) + "..." : "N/A"}`,
          `Recommendation: ${block.recommendation ? block.recommendation.substring(0, 200) + "..." : "N/A"}`,
          `Created At: ${block.created_at}`,
          `Updated At: ${block.updated_at}`,
          `--------------------------------`,
      ].join('\n');
  }

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

  Generic helper function for fetching paginated data from the OnSecurity API, constructing query parameters for filters, pagination, sorting, includes, fields, and search. Used by get-blocks handler.

  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);
  }