mcp-server-circleci

Instructions

Run a rollback pipeline for a CircleCI project. This tool guides you through the full rollback process, adapting to the information you provide and prompting for any missing details.

**Initial Requirements:**
- You need either a `projectSlug` (from `listFollowedProjects`) or a `projectID`. The tool will automatically resolve the project information from either of these.

**Typical Flow:**
1. **Start:** User initiates a rollback request.
2. **Project Selection:** If project id or project slug are not provided, call `listFollowedProjects` to get the list of projects the user follows and present the full list of projects to the user so that they can select the project they want to rollback.
3. **Project Information:** Provide either `projectSlug` or `projectID`. The tool will automatically resolve the project information as needed.
4. **Version Selection:** If component environment and version are not provided, call `listComponentVersions` to get the list of versions for the selected component and environment. If there is only one version, proceed automatically and do not ask the user to select a version. Otherwise, present the user with the full list of versions and ask them to select one. Always return all available values without categorizing them.
5. **Rollback Reason** ask the user for an optional reason for the rollback (e.g., "Critical bug fix"). Skip this step is the user explicitly requests a rollback by workflow rerun.
6. **Rollback pipeline check** if the tool reports that no rollback pipeline is defined, ask the user if they want to trigger a rollback by workflow rerun or suggest to setup a rollback pipeline following the documentation at https://circleci.com/docs/deploy/rollback-a-project-using-the-rollback-pipeline/.
7. **Confirmation:** Summarize the rollback request and confirm with the user before submitting.
8. **Pipeline Rollback:**  if the user requested a rollback by pipeline, call `runRollbackPipeline` passing all parameters including the namespace associated with the version to the tool.
9. **Workflow Rerun** If the user requested a rollback by workflow rerun, call `rerunWorkflow` passing the workflow ID of the selected version to the tool.
10.**Completion:** Report the outcome of the operation.

**Parameters:**
- `projectSlug` (optional): The project slug from `listFollowedProjects` (e.g., "gh/organization/project"). Either this or `projectID` must be provided.
- `projectID` (optional): The CircleCI project ID (UUID). Either this or `projectSlug` must be provided.
- `environmentName` (required): The target environment (e.g., "production", "staging").
- `componentName` (required): The component to rollback (e.g., "frontend", "backend").
- `currentVersion` (required): The currently deployed version.
- `targetVersion` (required): The version to rollback to.
- `namespace` (required): The namespace of the component.
- `reason` (optional): Reason for the rollback.
- `parameters` (optional): Additional rollback parameters as key-value pairs.

**Behavior:**
- If there are more than 20 environments or components, ask the user to refine their selection.
- Never attempt to guess or construct project slugs or URLs; always use values provided by the user or from `listFollowedProjects`.
- Do not prompt for missing parameters until versions have been listed.
- Do not call this tool with incomplete parameters.
- If the selected project lacks rollback pipeline configuration, provide a definitive error message without suggesting alternative projects.

**Returns:**
- On success: The rollback ID or a confirmation in case of workflow rerun.
- On error: A clear message describing what is missing or what went wrong.
- If the selected project does not have a rollback pipeline configured: The tool will provide a clear error message specific to that project and will NOT suggest trying another project.

**Important Note:**
- This tool is designed to work only with the specific project provided by the user.
- If a project does not have rollback capability configured, the tool will NOT recommend trying other projects.
- The assistant should NOT suggest trying different projects when a project lacks rollback configuration.
- Each project must have its own rollback pipeline configuration to be eligible for rollback operations.
- When a project cannot be rolled back, provide only the configuration guidance for THAT specific project.
- The tool automatically resolves project information from either `projectSlug` or `projectID`.
If no version is found, the tool will suggest the user to set up deploy markers following the documentation at:
https://circleci.com/docs/deploy/configure-deploy-markers/

Implementation Reference

• src/tools/runRollbackPipeline/handler.ts:6-99 (handler)

  The handler function that executes the run_rollback_pipeline tool logic: resolves project ID, checks for rollback pipeline configuration, constructs rollback request, and calls the CircleCI deploys API.

  export const runRollbackPipeline: ToolCallback<{
    params: typeof runRollbackPipelineInputSchema;
  }> = async (args: any) => {
    const {
      projectSlug,
      projectID: providedProjectID,
      environmentName,
      componentName,
      currentVersion,
      targetVersion,
      namespace,
      reason,
      parameters,
    } = args.params ?? {};
  
  
    // Init the client and get the base URL
    const circleci = getCircleCIClient();
    
    // Resolve project ID from projectSlug or use provided projectID
    let projectID: string;
    try {
      if (providedProjectID) {
        projectID = providedProjectID;
      } else if (projectSlug) {
        const { id: resolvedProjectId } = await circleci.projects.getProject({
          projectSlug,
        });
        projectID = resolvedProjectId;
      } else {
        return mcpErrorOutput('Either projectSlug or projectID must be provided');
      }
    } catch (error) {
      const errorMessage = projectSlug
        ? `Failed to resolve project information for ${projectSlug}. Please verify the project slug is correct.`
        : `Failed to resolve project information for project ID ${providedProjectID}. Please verify the project ID is correct.`;
      
      return mcpErrorOutput(`${errorMessage} ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
    
    // First, check if the project has a rollback pipeline definition configured
    try {
      const deploySettings = await circleci.deploys.fetchProjectDeploySettings({
        projectID,
      });
  
      if (!deploySettings.rollback_pipeline_definition_id) {
        return {
          content: [
            {
              type: 'text',
              text: 'No rollback pipeline definition found for this project. You may need to configure a rollback pipeline first using https://circleci.com/docs/deploy/rollback-a-project-using-the-rollback-pipeline/ or you can trigger a rollback by workflow rerun.',
            },
          ],
        };
      }
    } catch (error) {
      return mcpErrorOutput(
        `Failed to fetch rollback pipeline definition: ${error instanceof Error ? error.message : 'Unknown error'}`,
      );
    }
    
    // Check if this is a new rollback request with required fields
  
    const rollbackRequest = {
      environment_name: environmentName,
      component_name: componentName,
      current_version: currentVersion,
      target_version: targetVersion,
      ...(namespace && { namespace }),
      ...(reason && { reason }),
      ...(parameters && { parameters }),
    };
  
    try {
      const rollbackResponse = await circleci.deploys.runRollbackPipeline({
        projectID,
        rollbackRequest,
      });
  
      return {
        content: [
          {
            type: 'text',
            text: `Rollback initiated successfully. ID: ${rollbackResponse.id}, Type: ${rollbackResponse.rollback_type}`,
          },
        ],
      };
    } catch (error) {
      return mcpErrorOutput(
        `Failed to initiate rollback: ${error instanceof Error ? error.message : 'Unknown error'}`,
      );
    }
  };

• src/tools/runRollbackPipeline/inputSchema.ts:4-43 (schema)

  Input schema using Zod for validating parameters of the run_rollback_pipeline tool.

  export const runRollbackPipelineInputSchema = z.object({
    projectSlug: z
      .string()
      .describe(projectSlugDescriptionNoBranch)
      .optional(),
    projectID: z
      .string()
      .uuid()
      .describe('The ID of the CircleCI project (UUID)')
      .optional(),
    environmentName: z
      .string()
      .describe('The environment name'),
    componentName: z
      .string()
      .describe('The component name'),
    currentVersion: z
      .string()
      .describe('The current version'),
    targetVersion: z
      .string()
      .describe('The target version'),
    namespace: z
      .string()
      .describe('The namespace of the component'),
    reason: z
      .string()
      .describe('The reason for the rollback')
      .optional(),
    parameters: z
      .record(z.any())
      .describe('The extra parameters for the rollback pipeline')
      .optional(),
  }).refine(
    (data) => data.projectSlug || data.projectID,
    {
      message: "Either projectSlug or projectID must be provided",
      path: ["projectSlug", "projectID"],
    }
  );

• src/tools/runRollbackPipeline/tool.ts:3-57 (registration)

  Registers the tool definition with name, description, and schema reference.

  export const runRollbackPipelineTool = {
    name: 'run_rollback_pipeline' as const,
    description: `
      Run a rollback pipeline for a CircleCI project. This tool guides you through the full rollback process, adapting to the information you provide and prompting for any missing details.
  
      **Initial Requirements:**
      - You need either a \`projectSlug\` (from \`listFollowedProjects\`) or a \`projectID\`. The tool will automatically resolve the project information from either of these.
  
      **Typical Flow:**
      1. **Start:** User initiates a rollback request.
      2. **Project Selection:** If project id or project slug are not provided, call \`listFollowedProjects\` to get the list of projects the user follows and present the full list of projects to the user so that they can select the project they want to rollback.
      3. **Project Information:** Provide either \`projectSlug\` or \`projectID\`. The tool will automatically resolve the project information as needed.
      4. **Version Selection:** If component environment and version are not provided, call \`listComponentVersions\` to get the list of versions for the selected component and environment. If there is only one version, proceed automatically and do not ask the user to select a version. Otherwise, present the user with the full list of versions and ask them to select one. Always return all available values without categorizing them.
      5. **Rollback Reason** ask the user for an optional reason for the rollback (e.g., "Critical bug fix"). Skip this step is the user explicitly requests a rollback by workflow rerun.
      6. **Rollback pipeline check** if the tool reports that no rollback pipeline is defined, ask the user if they want to trigger a rollback by workflow rerun or suggest to setup a rollback pipeline following the documentation at https://circleci.com/docs/deploy/rollback-a-project-using-the-rollback-pipeline/.
      7. **Confirmation:** Summarize the rollback request and confirm with the user before submitting.
      8. **Pipeline Rollback:**  if the user requested a rollback by pipeline, call \`runRollbackPipeline\` passing all parameters including the namespace associated with the version to the tool.
      9. **Workflow Rerun** If the user requested a rollback by workflow rerun, call \`rerunWorkflow\` passing the workflow ID of the selected version to the tool.
      10.**Completion:** Report the outcome of the operation.
  
      **Parameters:**
      - \`projectSlug\` (optional): The project slug from \`listFollowedProjects\` (e.g., "gh/organization/project"). Either this or \`projectID\` must be provided.
      - \`projectID\` (optional): The CircleCI project ID (UUID). Either this or \`projectSlug\` must be provided.
      - \`environmentName\` (required): The target environment (e.g., "production", "staging").
      - \`componentName\` (required): The component to rollback (e.g., "frontend", "backend").
      - \`currentVersion\` (required): The currently deployed version.
      - \`targetVersion\` (required): The version to rollback to.
      - \`namespace\` (required): The namespace of the component.
      - \`reason\` (optional): Reason for the rollback.
      - \`parameters\` (optional): Additional rollback parameters as key-value pairs.
  
      **Behavior:**
      - If there are more than 20 environments or components, ask the user to refine their selection.
      - Never attempt to guess or construct project slugs or URLs; always use values provided by the user or from \`listFollowedProjects\`.
      - Do not prompt for missing parameters until versions have been listed.
      - Do not call this tool with incomplete parameters.
      - If the selected project lacks rollback pipeline configuration, provide a definitive error message without suggesting alternative projects.
  
      **Returns:**
      - On success: The rollback ID or a confirmation in case of workflow rerun.
      - On error: A clear message describing what is missing or what went wrong.
      - If the selected project does not have a rollback pipeline configured: The tool will provide a clear error message specific to that project and will NOT suggest trying another project.
  
      **Important Note:**
      - This tool is designed to work only with the specific project provided by the user.
      - If a project does not have rollback capability configured, the tool will NOT recommend trying other projects.
      - The assistant should NOT suggest trying different projects when a project lacks rollback configuration.
      - Each project must have its own rollback pipeline configuration to be eligible for rollback operations.
      - When a project cannot be rolled back, provide only the configuration guidance for THAT specific project.
      - The tool automatically resolves project information from either \`projectSlug\` or \`projectID\`.
      If no version is found, the tool will suggest the user to set up deploy markers following the documentation at:
      https://circleci.com/docs/deploy/configure-deploy-markers/
    `,
    inputSchema: runRollbackPipelineInputSchema,
  };

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

  Main registration: imports the tool and handler, adds to CCI_TOOLS array and CCI_HANDLERS map for MCP server.

  import { runRollbackPipelineTool } from './tools/runRollbackPipeline/tool.js';
  import { runRollbackPipeline } from './tools/runRollbackPipeline/handler.js';
  
  import { listComponentVersionsTool } from './tools/listComponentVersions/tool.js';
  import { listComponentVersions } from './tools/listComponentVersions/handler.js';
  
  // Define the tools with their configurations
  export const CCI_TOOLS = [
    getBuildFailureLogsTool,
    getFlakyTestLogsTool,
    getLatestPipelineStatusTool,
    getJobTestResultsTool,
    configHelperTool,
    createPromptTemplateTool,
    recommendPromptTemplateTestsTool,
    runPipelineTool,
    listFollowedProjectsTool,
    runEvaluationTestsTool,
    rerunWorkflowTool,
    downloadUsageApiDataTool,
    findUnderusedResourceClassesTool,
    analyzeDiffTool,
    runRollbackPipelineTool,
    listComponentVersionsTool,
  ];
  
  // Extract the tool names as a union type
  type CCIToolName = (typeof CCI_TOOLS)[number]['name'];
  
  export type ToolHandler<T extends CCIToolName> = ToolCallback<{
    params: Extract<(typeof CCI_TOOLS)[number], { name: T }>['inputSchema'];
  }>;
  
  // Create a type for the tool handlers that directly maps each tool to its appropriate input schema
  type ToolHandlers = {
    [K in CCIToolName]: ToolHandler<K>;
  };
  
  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;