mcp-server-circleci

Instructions

Implementation Reference

• src/tools/findUnderusedResourceClasses/handler.ts:6-25 (handler)

  The MCP tool handler function that extracts parameters, validates csvFilePath, calls the library analysis function, and returns the markdown report or error.
  export const findUnderusedResourceClasses: ToolCallback<{ params: typeof findUnderusedResourceClassesInputSchema }> = async (args) => { const { csvFilePath, threshold } = args.params ?? {}; if (!csvFilePath) { return mcpErrorOutput('ERROR: csvFilePath is required.'); } try { const { report } = await findUnderusedResourceClassesFromCSV({ csvFilePath, threshold }); return { content: [ { type: 'text', text: report }, ], }; } catch (e: any) { return mcpErrorOutput(`ERROR: ${e && e.message ? e.message : e}`); } };
• src/tools/findUnderusedResourceClasses/inputSchema.ts:3-14 (schema)

  Zod schema defining the tool's input parameters: required csvFilePath (string) and optional threshold (number, default 40).
  export const findUnderusedResourceClassesInputSchema = z.object({ csvFilePath: z .string() .describe('The path to the usage data CSV file to analyze.'), threshold: z .number() .optional() .default(40) .describe( 'The usage percentage threshold. Jobs with usage below this will be reported. Default is 40.', ), });
• src/tools/findUnderusedResourceClasses/tool.ts:3-19 (registration)

  Tool registration object defining the name 'find_underused_resource_classes', detailed description, and input schema reference.
  export const findUnderusedResourceClassesTool = { name: 'find_underused_resource_classes' as const, description: ` Analyzes a CircleCI usage data CSV file to find jobs/resource classes with average or max CPU/RAM usage below a given threshold (default 40%). This helps identify underused resource classes that may be oversized for their workload. Required parameter: - csvFilePath: Path to the usage data CSV file (string). IMPORTANT: This must be an absolute path. If you are given a relative path, you must resolve it to an absolute path before calling this tool. Optional parameter: - threshold: Usage percentage threshold (number, default 40) The tool expects the CSV to have columns: job_name, resource_class, median_cpu_utilization_pct, max_cpu_utilization_pct, median_ram_utilization_pct, max_ram_utilization_pct (case-insensitive). These required columns are a subset of the columns in the CircleCI usage API output and the tool will work with the full set of columns from the usage API CSV. It returns a summary report listing all jobs/resource classes where any of these metrics is below the threshold. `, inputSchema: findUnderusedResourceClassesInputSchema, };
• src/circleci-tools.ts:37-54 (registration)

  Central registration: the findUnderusedResourceClassesTool is included in the CCI_TOOLS array (line 50).
  export const CCI_TOOLS = [ getBuildFailureLogsTool, getFlakyTestLogsTool, getLatestPipelineStatusTool, getJobTestResultsTool, configHelperTool, createPromptTemplateTool, recommendPromptTemplateTestsTool, runPipelineTool, listFollowedProjectsTool, runEvaluationTestsTool, rerunWorkflowTool, downloadUsageApiDataTool, findUnderusedResourceClassesTool, analyzeDiffTool, runRollbackPipelineTool, listComponentVersionsTool, ];
• src/lib/usage-api/findUnderusedResourceClasses.ts:147-155 (helper)

  Core helper function that orchestrates CSV parsing, validation, grouping by job, analysis for underused resources based on threshold, and report generation.
  export async function findUnderusedResourceClassesFromCSV({ csvFilePath, threshold = 40 }: { csvFilePath: string, threshold?: number }) { const records = readAndParseCSV(csvFilePath); validateCSVColumns(records); const groupedRecords = groupRecordsByJob(records); const underusedJobs = analyzeJobGroups(groupedRecords, threshold); const report = generateReport(underusedJobs, threshold); return { report, underused: underusedJobs }; }