OnSecurity MCP Server

Instructions

Implementation Reference

• src/index.ts:455-518 (handler)

  The handler function that executes the logic for the 'get-findings' tool. It constructs filters from parameters, fetches paginated findings data via fetchPage, handles errors, formats the response using formatFinding and formatPaginationInfo, and returns a structured markdown summary.

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

• src/index.ts:444-454 (schema)

  Zod schema for input parameters of the 'get-findings' tool, including optional filters, pagination, sorting, and search options.

  {
      round_id: z.number().optional().describe("Optional round ID to filter findings"),
      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, round_id-asc, created_at-asc, updated_at-asc, name-desc, round_id-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,round,target_components')"),
      fields: z.string().optional().describe("Optional comma-separated list of fields to return (e.g. 'id,name'). Use * as wildcard."),
      filters: FilterSchema,
      search: z.string().optional().describe("Search term to find findings by name of finding or related content")
  },

• src/index.ts:442-519 (registration)

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

      "get-findings",
      "Get all findings 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. You can optionally filter findings by round_id. HOWEVER ONLY USE THIS TOOL WHEN ASKED FOR FINDINGS RELATED TO A CLIENT OR MY FINDINGS, NOT THE BLOCKS TOOL.",
      {
          round_id: z.number().optional().describe("Optional round ID to filter findings"),
          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, round_id-asc, created_at-asc, updated_at-asc, name-desc, round_id-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,round,target_components')"),
          fields: z.string().optional().describe("Optional comma-separated list of fields to return (e.g. 'id,name'). Use * as wildcard."),
          filters: FilterSchema,
          search: z.string().optional().describe("Search term to find findings by name of finding or related 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_id filter if provided
          if (params.round_id) {
              filters['round_id-eq'] = params.round_id;
          }
          
          // Add round_type filter if provided
          if (params.round_type) {
              filters['round_type_id-eq'] = params.round_type;
          }
          
          const response = await fetchPage<ApiResponse<FindingFeature>>(
              'findings', 
              params.page || 1, 
              filters, 
              params.sort, 
              params.includes, 
              params.fields, 
              params.limit,
              params.search
          );
          
          if (!response) {
              return {
                  content: [
                      {
                          type: "text",
                          text: "Error fetching findings data. Please try again."
                      }
                  ]
              };
          }
          
          const paginationInfo = formatPaginationInfo(response);
          const formattedFindings = response.result.map(formatFinding);
          
          const responseText = [
              "# Findings Summary",
              "",
              "## Pagination Information",
              paginationInfo,
              "",
              "## Findings Data",
              ...formattedFindings
          ].join('\n');
  
          return {
              content: [
                  {
                      type: "text",
                      text: responseText
                  }
              ]
          };
      }
  );

• src/index.ts:279-299 (helper)

  Helper function to format individual finding data into a readable string summary, used by the get-findings handler.

  function formatFinding(finding: FindingFeature): string {
      return [
          `Finding ID: ${finding.id}`,
          `Display ID: ${finding.display_id}`,
          `Name: ${finding.name}`,
          `Client ID: ${finding.client_id}`,
          `Round ID: ${finding.round_id}`,
          `CVSS Score: ${finding.cvss?.score || "N/A"}`,
          `Severity: ${finding.cvss?.severity_label || "N/A"}`,
          `Status: ${finding.status?.label || "Unknown"} (${finding.status?.description || "No description"})`,
          `Published: ${finding.published}`,
          `Remediation Complexity: ${finding.remediation_complexity || "N/A"}`,
          `Executive Description: ${finding.executive_description || "N/A"}`,
          `Executive Risk: ${finding.executive_risk || "N/A"}`,
          `Executive Recommendation: ${finding.executive_recommendation || "N/A"}`,
          `Description: ${finding.description || "N/A"}`,
          `Evidence: ${finding.evidence || "N/A"}`,
          `Recommendation: ${finding.recommendation || "N/A"}`,
          `--------------------------------`,
      ].join('\n');
  }