CircleCI MCP Server

Instructions

Implementation Reference

• src/tools/rerunWorkflow/handler.ts:8-54 (handler)

  The main asynchronous handler function for the 'rerun_workflow' tool. It resolves the workflow ID from URL if provided, fetches the workflow status, validates conditions, and calls the CircleCI client to rerun the workflow, returning a message with the new workflow ID and URL.
  export const rerunWorkflow: ToolCallback<{ params: typeof rerunWorkflowInputSchema; }> = async (args) => { let { workflowId } = args.params; const { fromFailed, workflowURL } = args.params; const baseURL = getAppURL(); const circleci = getCircleCIClient(); if (workflowURL) { workflowId = getWorkflowIdFromURL(workflowURL); } if (!workflowId) { return mcpErrorOutput( 'workflowId is required and could not be determined from workflowURL.', ); } const workflow = await circleci.workflows.getWorkflow({ workflowId, }); if (!workflow) { return mcpErrorOutput('Workflow not found'); } const workflowFailed = workflow?.status?.toLowerCase() === 'failed'; if (fromFailed && !workflowFailed) { return mcpErrorOutput('Workflow is not failed, cannot rerun from failed'); } const newWorkflow = await circleci.workflows.rerunWorkflow({ workflowId, fromFailed: fromFailed !== undefined ? fromFailed : workflowFailed, }); const workflowUrl = `${baseURL}/pipelines/workflows/${newWorkflow.workflow_id}`; return { content: [ { type: 'text', text: `New workflowId is ${newWorkflow.workflow_id} and [View Workflow in CircleCI](${workflowUrl})`, }, ], }; };
• src/tools/rerunWorkflow/inputSchema.ts:4-18 (schema)

  Zod schema defining the input parameters for the rerun_workflow tool: optional workflowId (UUID string), optional fromFailed (boolean), optional workflowURL (string).
  export const rerunWorkflowInputSchema = z.object({ workflowId: z .string() .describe( 'This should be the workflowId of the workflow that need rerun. The workflowId is an UUID. An example workflowId is a12145c5-90f8-4cc9-98f2-36cb85db9e4b', ) .optional(), fromFailed: z .boolean() .describe( 'If true, reruns the workflow from failed. If false, reruns the workflow from the start. If omitted, the rerun behavior is based on the workflow status.', ) .optional(), workflowURL: z.string().describe(workflowUrlDescription).optional(), });
• src/tools/rerunWorkflow/tool.ts:3-25 (registration)

  MCP tool object registration exporting the tool definition with name 'rerun_workflow', detailed description of usage, and reference to the input schema.
  export const rerunWorkflowTool = { name: 'rerun_workflow' as const, description: ` This tool is used to rerun a workflow from start or from the failed job. Common use cases: - Rerun a workflow from a failed job - Rerun a workflow from start Input options (EXACTLY ONE of these TWO options must be used): Option 1 - Workflow ID: - workflowId: The ID of the workflow to rerun - fromFailed: true to rerun from failed, false to rerun from start. If omitted, behavior is based on workflow status. (optional) Option 2 - Workflow URL: - workflowURL: The URL of the workflow to rerun * Workflow URL: https://app.circleci.com/pipelines/:vcsType/:orgName/:projectName/:pipelineNumber/workflows/:workflowId * Workflow Job URL: https://app.circleci.com/pipelines/:vcsType/:orgName/:projectName/:pipelineNumber/workflows/:workflowId/jobs/:buildNumber - fromFailed: true to rerun from failed, false to rerun from start. If omitted, behavior is based on workflow status. (optional) `, inputSchema: rerunWorkflowInputSchema, };
• src/circleci-tools.ts:30-72 (registration)

  Collection of all CircleCI tools including rerunWorkflowTool in CCI_TOOLS array (line 41) and handler mapping rerun_workflow: rerunWorkflow in CCI_HANDLERS object (line 69). This aggregates tools for MCP server registration.
  export const CCI_TOOLS = [ getBuildFailureLogsTool, getFlakyTestLogsTool, getLatestPipelineStatusTool, getJobTestResultsTool, configHelperTool, createPromptTemplateTool, recommendPromptTemplateTestsTool, runPipelineTool, listFollowedProjectsTool, runEvaluationTestsTool, rerunWorkflowTool, analyzeDiffTool, runRollbackPipelineTool, ]; // 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, analyze_diff: analyzeDiff, run_rollback_pipeline: runRollbackPipeline, } satisfies ToolHandlers;