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;