mcp-server-circleci

Instructions

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;