CircleCI MCP Server

Instructions

This tool helps debug CircleCI build failures by retrieving failure logs.

CRITICAL REQUIREMENTS:
1. Truncation Handling (HIGHEST PRIORITY):
   - ALWAYS check for <MCPTruncationWarning> in the output
   - When present, you MUST start your response with:
     "WARNING: The logs have been truncated. Only showing the most recent entries. Earlier build failures may not be visible."
   - Only proceed with log analysis after acknowledging the truncation

Input options (EXACTLY ONE of these THREE options must be used):

Option 1 - Project Slug and branch (BOTH required):
- projectSlug: The project slug obtained from listFollowedProjects tool (e.g., "gh/organization/project")
- branch: The name of the branch (required when using projectSlug)

Option 2 - Direct URL (provide ONE of these):
- projectURL: The URL of the CircleCI project in any of these formats:
  * Project URL: https://app.circleci.com/pipelines/gh/organization/project
  * Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123
  * Legacy Job URL: https://circleci.com/pipelines/gh/organization/project/123
  * Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
  * Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/xyz

Option 3 - Project Detection (ALL of these must be provided together):
- workspaceRoot: The absolute path to the workspace root
- gitRemoteURL: The URL of the git remote repository
- branch: The name of the current branch

Recommended Workflow:
1. Use listFollowedProjects tool to get a list of projects
2. Extract the projectSlug from the chosen project (format: "gh/organization/project")
3. Use that projectSlug with a branch name for this tool

Additional Requirements:
- Never call this tool with incomplete parameters
- If using Option 1, make sure to extract the projectSlug exactly as provided by listFollowedProjects
- If using Option 2, the URLs MUST be provided by the user - do not attempt to construct or guess URLs
- If using Option 3, ALL THREE parameters (workspaceRoot, gitRemoteURL, branch) must be provided
- If none of the options can be fully satisfied, ask the user for the missing information before making the tool call

Implementation Reference

• src/tools/getBuildFailureLogs/handler.ts:13-69 (handler)

  The main handler function that implements the get_build_failure_logs tool logic, extracting project details and fetching/formatting CircleCI pipeline job logs.

  export const getBuildFailureLogs: ToolCallback<{
    params: typeof getBuildFailureOutputInputSchema;
  }> = async (args) => {
    const {
      workspaceRoot,
      gitRemoteURL,
      branch,
      projectURL,
      projectSlug: inputProjectSlug,
    } = args.params;
  
    let projectSlug: string | undefined;
    let pipelineNumber: number | undefined;
    let branchFromURL: string | undefined;
    let jobNumber: number | undefined;
  
    if (inputProjectSlug) {
      if (!branch) {
        return mcpErrorOutput(
          'Branch not provided. When using projectSlug, a branch must also be specified.',
        );
      }
      projectSlug = inputProjectSlug;
    } else if (projectURL) {
      projectSlug = getProjectSlugFromURL(projectURL);
      pipelineNumber = getPipelineNumberFromURL(projectURL);
      branchFromURL = getBranchFromURL(projectURL);
      jobNumber = getJobNumberFromURL(projectURL);
    } else if (workspaceRoot && gitRemoteURL && branch) {
      projectSlug = await identifyProjectSlug({
        gitRemoteURL,
      });
    } else {
      return mcpErrorOutput(
        'Missing required inputs. Please provide either: 1) projectSlug with branch, 2) projectURL, or 3) workspaceRoot with gitRemoteURL and branch.',
      );
    }
  
    if (!projectSlug) {
      return mcpErrorOutput(`
            Project not found. Ask the user to provide the inputs user can provide based on the tool description.
  
            Project slug: ${projectSlug}
            Git remote URL: ${gitRemoteURL}
            Branch: ${branch}
            `);
    }
  
    const logs = await getPipelineJobLogs({
      projectSlug,
      branch: branchFromURL || branch,
      pipelineNumber,
      jobNumber,
    });
  
    return formatJobLogs(logs);
  };

• src/tools/getBuildFailureLogs/inputSchema.ts:7-35 (schema)

  Zod input schema defining parameters for the tool: projectSlug, branch, projectURL, workspaceRoot, gitRemoteURL.

  export const getBuildFailureOutputInputSchema = z.object({
    projectSlug: z.string().describe(projectSlugDescription).optional(),
    branch: z.string().describe(branchDescription).optional(),
    projectURL: z
      .string()
      .describe(
        'The URL of the CircleCI project. Can be any of these formats:\n' +
          '- Project URL with branch: https://app.circleci.com/pipelines/gh/organization/project?branch=feature-branch\n' +
          '- Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123\n' +
          '- Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def\n' +
          '- Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/xyz',
      )
      .optional(),
    workspaceRoot: z
      .string()
      .describe(
        'The absolute path to the root directory of your project workspace. ' +
          'This should be the top-level folder containing your source code, configuration files, and dependencies. ' +
          'For example: "/home/user/my-project" or "C:\\Users\\user\\my-project"',
      )
      .optional(),
    gitRemoteURL: z
      .string()
      .describe(
        'The URL of the remote git repository. This should be the URL of the repository that you cloned to your local workspace. ' +
          'For example: "https://github.com/user/my-project.git"',
      )
      .optional(),
  });

• src/tools/getBuildFailureLogs/tool.ts:4-46 (registration)

  Tool object registration defining the name 'get_build_failure_logs', detailed description, and references the input schema.

  export const getBuildFailureLogsTool = {
    name: 'get_build_failure_logs' as const,
    description: `
      This tool helps debug CircleCI build failures by retrieving failure logs.
  
      CRITICAL REQUIREMENTS:
      1. Truncation Handling (HIGHEST PRIORITY):
         - ALWAYS check for <MCPTruncationWarning> in the output
         - When present, you MUST start your response with:
           "WARNING: The logs have been truncated. Only showing the most recent entries. Earlier build failures may not be visible."
         - Only proceed with log analysis after acknowledging the truncation
  
      Input options (EXACTLY ONE of these THREE options must be used):
  
      ${option1DescriptionBranchRequired}
  
      Option 2 - Direct URL (provide ONE of these):
      - projectURL: The URL of the CircleCI project in any of these formats:
        * Project URL: https://app.circleci.com/pipelines/gh/organization/project
        * Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123
        * Legacy Job URL: https://circleci.com/pipelines/gh/organization/project/123
        * Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
        * Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/xyz
  
      Option 3 - Project Detection (ALL of these must be provided together):
      - workspaceRoot: The absolute path to the workspace root
      - gitRemoteURL: The URL of the git remote repository
      - branch: The name of the current branch
      
      Recommended Workflow:
      1. Use listFollowedProjects tool to get a list of projects
      2. Extract the projectSlug from the chosen project (format: "gh/organization/project")
      3. Use that projectSlug with a branch name for this tool
  
      Additional Requirements:
      - Never call this tool with incomplete parameters
      - If using Option 1, make sure to extract the projectSlug exactly as provided by listFollowedProjects
      - If using Option 2, the URLs MUST be provided by the user - do not attempt to construct or guess URLs
      - If using Option 3, ALL THREE parameters (workspaceRoot, gitRemoteURL, branch) must be provided
      - If none of the options can be fully satisfied, ask the user for the missing information before making the tool call
      `,
    inputSchema: getBuildFailureOutputInputSchema,
  };

• src/circleci-tools.ts:30-44 (registration)

  Registration of the tool in the main CCI_TOOLS array export.

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

• src/circleci-tools.ts:58-72 (registration)

  Mapping of the tool name to its handler function in the CCI_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,
    analyze_diff: analyzeDiff,
    run_rollback_pipeline: runRollbackPipeline,
  } satisfies ToolHandlers;