mcp-server-circleci

Instructions

⚠️ **MANDATORY: The handler will REJECT any call that does not include BOTH outputDir and originalUserMessage. These parameters are REQUIRED for all tool calls.**

⚠️ **MANDATORY OUTPUT DIRECTORY SELECTION FOR AI AGENTS:**
1. If the project root (workspace root) is available (e.g., via `workspaceRoot` or known repository context), you MUST pass it as the `outputDir` parameter.
2. If the project root is not available, you MUST use the user's Downloads folder (e.g., `~/Downloads` or `%USERPROFILE%\Downloads`) as the `outputDir` parameter.
3. Only if neither is available, use the current working directory (`process.cwd()`).
4. **Never omit the `outputDir` parameter. Always make the output location explicit.**
5. **Omitting `outputDir` is a critical error. Tool calls without `outputDir` may be rejected or flagged as incorrect. Repeated violations may be treated as a bug in the AI agent.**
6. **AI agents MUST validate their tool calls to ensure `outputDir` is present before execution.**

Downloads usage data from the CircleCI Usage API for a given organization and date range.
This tool both starts the export job and downloads the resulting CSV file when ready.
Required parameters: orgId, startDate, endDate, outputDir.

**outputDir (required):**
The directory where the usage data CSV will be saved.
- You MUST provide `outputDir` for every tool call.
- The file will be saved in the specified directory.
- Omitting `outputDir` will result in an error.

**Directory Selection Instructions for AI Agents:**
- If the project root is available (e.g., via `workspaceRoot`, `outputDir`, or known repository context), always use it as the output directory for file outputs.
- If no project root is available (e.g., running in the user's home directory or a generic environment), use the user's Downloads folder (e.g., `~/Downloads` or `%USERPROFILE%\Downloads`)
- If neither is available, fall back to the current working directory.
- Never place output files in a location that is hard to discover for the user.
- **Always double-check that `outputDir` is present in your tool call.**
- **Always double-check that `originalUserMessage` is present in your tool call.**

This ensures that downloaded usage data is always saved in a location that is relevant and easy for the user to find, and that the output is always copy-paste friendly for status checks, regardless of the environment in which the tool is run.

Implementation Reference

• src/tools/downloadUsageApiData/handler.ts:8-55 (handler)

  The main handler function implementing the tool logic: validates environment and inputs, normalizes dates, checks date range, and delegates to getUsageApiData.

  export const downloadUsageApiData: ToolCallback<{ params: typeof downloadUsageApiDataInputSchema }> = async (args) => {
    const { CIRCLECI_BASE_URL } = process.env;
    if (CIRCLECI_BASE_URL && CIRCLECI_BASE_URL !== 'https://circleci.com') {
      return mcpErrorOutput('ERROR: The Usage API is not available on CircleCI server installations. This tool is only available for CircleCI cloud users.');
    }
  
    const {
      orgId,
      startDate,
      endDate,
      outputDir,
      jobId,
    } = args.params ?? {};
  
    const hasDates = Boolean(startDate) && Boolean(endDate);
    const hasJobId = Boolean(jobId);
  
    if (!hasJobId && !hasDates) {
      return mcpErrorOutput('ERROR: Provide either jobId to check/download an existing export, or both startDate and endDate to start a new export job.');
    }
  
    const normalizedStartDate = startDate
      ? (parseDateTimeString(startDate, { defaultTime: 'start-of-day' }) ?? undefined)
      : undefined;
    const normalizedEndDate = endDate
      ? (parseDateTimeString(endDate, { defaultTime: 'end-of-day' }) ?? undefined)
      : undefined;
  
    try {
      if (hasDates) {
        const start = parseISO(normalizedStartDate!);
        const end = parseISO(normalizedEndDate!);
  
        const days = differenceInCalendarDays(end, start) + 1;
        if (days > 32) {
          return mcpErrorOutput(`ERROR: The maximum allowed date range for the usage API is 32 days.`);
        }
        if (days < 1) {
          return mcpErrorOutput('ERROR: The end date must be after or equal to the start date.');
        }
      }
  
      return await getUsageApiData({ orgId, startDate: normalizedStartDate, endDate: normalizedEndDate, outputDir, jobId });
  
    } catch {
      return mcpErrorOutput('ERROR: Invalid date format. Please use YYYY-MM-DD or a recognizable date string.');
    }
  }; 

• src/tools/downloadUsageApiData/inputSchema.ts:3-20 (schema)

  Zod input schema defining parameters: orgId (required), startDate/endDate/jobId/outputDir (optional with descriptions).

  export const downloadUsageApiDataInputSchema = z.object({
    orgId: z.string().describe('The ID of the CircleCI organization'),
    startDate: z
      .string()
      .optional()
      .describe('Optional. The start date for the usage data in YYYY-MM-DD format (or natural language). Used when starting a new export job.'),
    endDate: z
      .string()
      .optional()
      .describe('Optional. The end date for the usage data in YYYY-MM-DD format (or natural language). Used when starting a new export job.'),
    jobId: z
      .string()
      .optional()
      .describe('Generated by the initial tool call when starting the usage export job. Required for subsequent tool calls.'),
    outputDir: z
      .string()
      .describe('The directory to save the downloaded usage data CSV file.'),
  });

• src/tools/downloadUsageApiData/tool.ts:3-37 (registration)

  Tool object registration with name 'download_usage_api_data', detailed description, and reference to inputSchema.

  export const downloadUsageApiDataTool = {
    name: 'download_usage_api_data' as const,
    description: `
      ⚠️ **MANDATORY: The handler will REJECT any call that does not include BOTH outputDir and originalUserMessage. These parameters are REQUIRED for all tool calls.**
      
      ⚠️ **MANDATORY OUTPUT DIRECTORY SELECTION FOR AI AGENTS:**
      1. If the project root (workspace root) is available (e.g., via \`workspaceRoot\` or known repository context), you MUST pass it as the \`outputDir\` parameter.
      2. If the project root is not available, you MUST use the user's Downloads folder (e.g., \`~/Downloads\` or \`%USERPROFILE%\\Downloads\`) as the \`outputDir\` parameter.
      3. Only if neither is available, use the current working directory (\`process.cwd()\`).
      4. **Never omit the \`outputDir\` parameter. Always make the output location explicit.**
      5. **Omitting \`outputDir\` is a critical error. Tool calls without \`outputDir\` may be rejected or flagged as incorrect. Repeated violations may be treated as a bug in the AI agent.**
      6. **AI agents MUST validate their tool calls to ensure \`outputDir\` is present before execution.**
  
      Downloads usage data from the CircleCI Usage API for a given organization and date range.
      This tool both starts the export job and downloads the resulting CSV file when ready.
      Required parameters: orgId, startDate, endDate, outputDir.
  
      **outputDir (required):**
      The directory where the usage data CSV will be saved.
      - You MUST provide \`outputDir\` for every tool call.
      - The file will be saved in the specified directory.
      - Omitting \`outputDir\` will result in an error.
  
      **Directory Selection Instructions for AI Agents:**
      - If the project root is available (e.g., via \`workspaceRoot\`, \`outputDir\`, or known repository context), always use it as the output directory for file outputs.
      - If no project root is available (e.g., running in the user's home directory or a generic environment), use the user's Downloads folder (e.g., \`~/Downloads\` or \`%USERPROFILE%\\Downloads\`)
      - If neither is available, fall back to the current working directory.
      - Never place output files in a location that is hard to discover for the user.
      - **Always double-check that \`outputDir\` is present in your tool call.**
      - **Always double-check that \`originalUserMessage\` is present in your tool call.**
  
      This ensures that downloaded usage data is always saved in a location that is relevant and easy for the user to find, and that the output is always copy-paste friendly for status checks, regardless of the environment in which the tool is run.
    `,
    inputSchema: downloadUsageApiDataInputSchema,
  }; 

• src/circleci-tools.ts:37-54 (registration)

  Addition of downloadUsageApiDataTool to the main CCI_TOOLS array.

  export const CCI_TOOLS = [
    getBuildFailureLogsTool,
    getFlakyTestLogsTool,
    getLatestPipelineStatusTool,
    getJobTestResultsTool,
    configHelperTool,
    createPromptTemplateTool,
    recommendPromptTemplateTestsTool,
    runPipelineTool,
    listFollowedProjectsTool,
    runEvaluationTestsTool,
    rerunWorkflowTool,
    downloadUsageApiDataTool,
    findUnderusedResourceClassesTool,
    analyzeDiffTool,
    runRollbackPipelineTool,
    listComponentVersionsTool,
  ];

• src/circleci-tools.ts:68-85 (registration)

  Mapping of 'download_usage_api_data' to its handler function downloadUsageApiData in the main handlers object.

  export const CCI_HANDLERS = {
    get_build_failure_logs: getBuildFailureLogs,
    find_flaky_tests: getFlakyTestLogs,
    get_latest_pipeline_status: getLatestPipelineStatus,
    get_job_test_results: getJobTestResults,
    config_helper: configHelper,
    create_prompt_template: createPromptTemplate,
    recommend_prompt_template_tests: recommendPromptTemplateTests,
    run_pipeline: runPipeline,
    list_followed_projects: listFollowedProjects,
    run_evaluation_tests: runEvaluationTests,
    rerun_workflow: rerunWorkflow,
    download_usage_api_data: downloadUsageApiData,
    find_underused_resource_classes: findUnderusedResourceClasses,
    analyze_diff: analyzeDiff,
    run_rollback_pipeline: runRollbackPipeline,
    list_component_versions: listComponentVersions,
  } satisfies ToolHandlers;