CircleCI MCP Server

Instructions

This tool triggers a new CircleCI pipeline and returns the URL to monitor its progress.

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 with branch: https://app.circleci.com/pipelines/gh/organization/project?branch=feature-branch
  * Pipeline URL: https://app.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

Configuration:
- an optional configContent parameter can be provided to override the default pipeline configuration

Pipeline Selection:
- If the project has multiple pipeline definitions, the tool will return a list of available pipelines
- You must then make another call with the chosen pipeline name using the pipelineChoiceName parameter
- The pipelineChoiceName must exactly match one of the pipeline names returned by the tool
- If the project has only one pipeline definition, pipelineChoiceName is not needed

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

Returns:
- A URL to the newly triggered pipeline that can be used to monitor its progress

Implementation Reference

• src/tools/runPipeline/handler.ts:12-131 (handler)

  The main execution logic for the 'run_pipeline' MCP tool. This async function processes inputs to identify project slug and branch, fetches pipeline definitions, handles selection if multiple, and triggers the pipeline via CircleCI client, returning the pipeline URL.

  export const runPipeline: ToolCallback<{
    params: typeof runPipelineInputSchema;
  }> = async (args) => {
    const {
      workspaceRoot,
      gitRemoteURL,
      branch,
      configContent,
      projectURL,
      pipelineChoiceName,
      projectSlug: inputProjectSlug,
    } = args.params;
  
    let projectSlug: string | undefined;
    let branchFromURL: string | undefined;
    const baseURL = getAppURL();
    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);
      branchFromURL = getBranchFromURL(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 foundBranch = branchFromURL || branch;
    if (!foundBranch) {
      return mcpErrorOutput(
        'No branch provided. Ask the user to provide the branch.',
      );
    }
  
    const circleci = getCircleCIClient();
    const { id: projectId } = await circleci.projects.getProject({
      projectSlug,
    });
    const pipelineDefinitions = await circleci.pipelines.getPipelineDefinitions({
      projectId,
    });
  
    const pipelineChoices = [
      ...pipelineDefinitions.map((definition) => ({
        name: definition.name,
        definitionId: definition.id,
      })),
    ];
  
    if (pipelineChoices.length === 0) {
      return mcpErrorOutput(
        'No pipeline definitions found. Please make sure your project is set up on CircleCI to run pipelines.',
      );
    }
  
    const formattedPipelineChoices = pipelineChoices
      .map(
        (pipeline, index) =>
          `${index + 1}. ${pipeline.name} (definitionId: ${pipeline.definitionId})`,
      )
      .join('\n');
  
    if (pipelineChoices.length > 1 && !pipelineChoiceName) {
      return {
        content: [
          {
            type: 'text',
            text: `Multiple pipeline definitions found. Please choose one of the following:\n${formattedPipelineChoices}`,
          },
        ],
      };
    }
  
    const chosenPipeline = pipelineChoiceName
      ? pipelineChoices.find((pipeline) => pipeline.name === pipelineChoiceName)
      : undefined;
  
    if (pipelineChoiceName && !chosenPipeline) {
      return mcpErrorOutput(
        `Pipeline definition with name ${pipelineChoiceName} not found. Please choose one of the following:\n${formattedPipelineChoices}`,
      );
    }
  
    const runPipelineDefinitionId =
      chosenPipeline?.definitionId || pipelineChoices[0].definitionId;
  
    const runPipelineResponse = await circleci.pipelines.runPipeline({
      projectSlug,
      branch: foundBranch,
      definitionId: runPipelineDefinitionId,
      configContent,
    });
  
    return {
      content: [
        {
          type: 'text',
          text: `Pipeline run successfully. View it at: ${baseURL}/pipelines/${projectSlug}/${runPipelineResponse.number}`,
        },
      ],
    };
  };

• src/tools/runPipeline/inputSchema.ts:7-49 (schema)

  Zod input schema definition for the 'run_pipeline' tool, defining optional parameters like projectSlug, branch, workspaceRoot, gitRemoteURL, projectURL, pipelineChoiceName, and configContent with descriptions.

  export const runPipelineInputSchema = z.object({
    projectSlug: z.string().describe(projectSlugDescription).optional(),
    branch: z.string().describe(branchDescription).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(),
    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(),
    pipelineChoiceName: z
      .string()
      .describe(
        'The name of the pipeline to run. This parameter is only needed if the project has multiple pipeline definitions. ' +
          'If not provided and multiple pipelines exist, the tool will return a list of available pipelines for the user to choose from. ' +
          'If provided, it must exactly match one of the pipeline names returned by the tool.',
      )
      .optional(),
    configContent: z
      .string()
      .describe(
        'The content of the CircleCI YAML configuration file for the pipeline.',
      )
      .optional(),
  });

• src/tools/runPipeline/tool.ts:4-45 (registration)

  Tool registration object 'runPipelineTool' defining the name 'run_pipeline', detailed description of usage options and requirements, and references the inputSchema.

  export const runPipelineTool = {
    name: 'run_pipeline' as const,
    description: `
      This tool triggers a new CircleCI pipeline and returns the URL to monitor its progress.
  
      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 with branch: https://app.circleci.com/pipelines/gh/organization/project?branch=feature-branch
        * Pipeline URL: https://app.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
  
      Configuration:
      - an optional configContent parameter can be provided to override the default pipeline configuration
  
      Pipeline Selection:
      - If the project has multiple pipeline definitions, the tool will return a list of available pipelines
      - You must then make another call with the chosen pipeline name using the pipelineChoiceName parameter
      - The pipelineChoiceName must exactly match one of the pipeline names returned by the tool
      - If the project has only one pipeline definition, pipelineChoiceName is not needed
  
      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
  
      Returns:
      - A URL to the newly triggered pipeline that can be used to monitor its progress
      `,
    inputSchema: runPipelineInputSchema,
  };

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

  Top-level registration of all CircleCI tools, including 'run_pipeline' handler mapping in CCI_HANDLERS (line 66) and inclusion of runPipelineTool in CCI_TOOLS array (line 38).

  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;

• src/clients/schemas.ts:161-263 (schema)

  Response schema RunPipelineResponseSchema for the runPipeline operation, exported as type.

  const RunPipelineResponseSchema = z.object({
    number: z.number(),
  });
  
  const RollbackProjectRequestSchema = z.object({
    component_name: z.string().describe('The component name'),
    current_version: z.string().describe('The current version'),
    environment_name: z.string().describe('The environment name'),
    namespace: z.string().describe('The namespace').optional(),
    parameters: z.record(z.any()).describe('The extra parameters for the rollback pipeline').optional(),
    reason: z.string().describe('The reason for the rollback').optional(),
    target_version: z.string().describe('The target version'),
  });
  
  const RollbackProjectResponseSchema = z.object({
    id: z.string().describe('The ID of the rollback pipeline or the command created to handle the rollback'),
    rollback_type: z.string().describe('The type of the rollback'),
  });
  
  const DeploySettingsResponseSchema = z.object({
    create_autogenerated_releases: z.boolean().optional().describe('Whether to create autogenerated releases'),
    rollback_pipeline_definition_id: z.string().optional().describe('The rollback pipeline definition ID, if configured for this project'),
  }).passthrough(); // Allow additional properties we might not know about
  
  const DeployComponentsResponseSchema = z.object({
    items: z.array(z.object({
      id: z.string(),
      project_id: z.string(),
      name: z.string(),
      release_count: z.number(),
      labels: z.array(z.string()),
      created_at: z.string(),
      updated_at: z.string(),
    })),
    next_page_token: z.string().nullable(),
  });
  
  const DeployComponentVersionsResponseSchema = z.object({
    items: z.array(z.object({
      name: z.string(),
      namespace: z.string(),
      environment_id: z.string(),
      is_live: z.boolean(),
      pipeline_id: z.string(),
      workflow_id: z.string(),
      job_id: z.string(),
      job_number: z.number(),
      last_deployed_at: z.string(),
    })),
    next_page_token: z.string().nullable(),
  });
  
  export const DeployEnvironmentResponseSchema = z.object({
    items: z.array(z.object({
    id: z.string(),
    name: z.string(),
    created_at: z.string(),
    updated_at: z.string(),
    labels: z.array(z.string()),
    })),
    next_page_token: z.string().nullable(),
  });
  
  const ProjectSchema = z.object({
    id: z.string(),
    organization_id: z.string(),
  });
  
  const PipelineDefinitionSchema = z.object({
    id: z.string(),
    name: z.string(),
  });
  
  const PipelineDefinitionsResponseSchema = z.object({
    items: z.array(PipelineDefinitionSchema),
  });
  
  export const PipelineDefinition = PipelineDefinitionSchema;
  export type PipelineDefinition = z.infer<typeof PipelineDefinitionSchema>;
  
  export const PipelineDefinitionsResponse = PipelineDefinitionsResponseSchema;
  export type PipelineDefinitionsResponse = z.infer<
    typeof PipelineDefinitionsResponseSchema
  >;
  
  export const Test = TestSchema;
  export type Test = z.infer<typeof TestSchema>;
  
  export const PaginatedTestResponse = PaginatedTestResponseSchema;
  export type PaginatedTestResponse = z.infer<typeof PaginatedTestResponseSchema>;
  
  export const FlakyTest = FlakyTestSchema;
  export type FlakyTest = z.infer<typeof FlakyTestSchema>;
  
  export const ConfigValidate = ConfigValidateSchema;
  export type ConfigValidate = z.infer<typeof ConfigValidateSchema>;
  
  // Export the schemas and inferred types with the same names as the original types
  export const Pipeline = PipelineSchema;
  export type Pipeline = z.infer<typeof PipelineSchema>;
  
  export const RunPipelineResponse = RunPipelineResponseSchema;
  export type RunPipelineResponse = z.infer<typeof RunPipelineResponseSchema>;