mcp-server-circleci

Instructions

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.

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