mcp-server-circleci

Instructions

Implementation Reference

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

  The main handler function that implements the logic for the 'rerun_workflow' tool. It extracts workflow ID from input or URL, checks status, and uses CircleCI client to rerun the workflow from start or failed jobs, returning 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 input schema defining parameters for the rerun_workflow tool: workflowId (optional UUID), fromFailed (optional boolean), workflowURL (optional 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)

  Defines the tool specification including name 'rerun_workflow', detailed description, and references 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:22-85 (registration)

  Registers the rerunWorkflowTool in the CCI_TOOLS array and the rerunWorkflow handler in the CCI_HANDLERS object for the CircleCI tools.

  import { rerunWorkflowTool } from './tools/rerunWorkflow/tool.js';
  import { rerunWorkflow } from './tools/rerunWorkflow/handler.js';
  import { downloadUsageApiDataTool } from './tools/downloadUsageApiData/tool.js';
  import { downloadUsageApiData } from './tools/downloadUsageApiData/handler.js';
  import { findUnderusedResourceClassesTool } from './tools/findUnderusedResourceClasses/tool.js';
  import { findUnderusedResourceClasses } from './tools/findUnderusedResourceClasses/handler.js';
  import { analyzeDiffTool } from './tools/analyzeDiff/tool.js';
  import { analyzeDiff } from './tools/analyzeDiff/handler.js';
  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;