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