mcp-server-circleci

Instructions

 This tool lists all versions for a CircleCI component. It guides you through a multi-step process to gather the required information and provides lists of available options when parameters are missing.

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

 **Typical Flow:**
 1. **Start:** User requests component versions or deployment information.
 2. **Project Information:** Provide either `projectSlug` or `projectID`. The tool will automatically resolve the `orgID` and `projectID` as needed.
 3. **Environment Selection:** If `environmentID` is not provided, the tool will list all available environments for the organization and prompt the user to select one. Always return all available values without categorizing them.
 4. **Component Selection:** If `componentID` is not provided, the tool will list all available components for the project and prompt the user to select one. Always return all available values without categorizing them.
 5. **Version Listing:** Once both `environmentID` and `componentID` are provided, the tool will list all versions for that component in the specified environment.
 6. **Selection:** User selects a version from the list for subsequent operations.

 **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.
 - `orgID` (optional): The organization ID. If not provided, it will be automatically resolved from `projectSlug` or `projectID`.
 - `environmentID` (optional): The environment ID. If not provided, available environments will be listed.
 - `componentID` (optional): The component ID. If not provided, available components will be listed.

 **Behavior:**
 - The tool will guide you through the selection process step by step.
 - Automatically resolves `orgID` from `projectSlug` or `projectID` when needed.
 - When `environmentID` is missing, it lists environments and waits for user selection.
 - When `componentID` is missing (but `environmentID` is provided), it lists components and waits for user selection.
 - Only when both `environmentID` and `componentID` are provided will it list the actual component versions.
 - Make multiple calls to this tool as you gather the required parameters.

 **Common Use Cases:**
 - Identify which versions were deployed for a component
 - Identify which versions are live for a component
 - Identify which versions were deployed to an environment for a component
 - Identify which versions are not live for a component in an environment
 - Select a version for rollback or deployment operations
 - Obtain version name, namespace, and environment details for other CircleCI tools

 **Returns:**
 - When missing `environmentID`: A list of available environments with their IDs
 - When missing `componentID`: A list of available components with their IDs  
 - When both `environmentID` and `componentID` provided: A list of component versions with version name, namespace, environment ID, and is_live status

 **Important Notes:**
 - This tool requires multiple calls to gather all necessary information.
 - Either `projectSlug` or `projectID` must be provided; the tool will resolve the missing project information automatically.
 - The tool will prompt for missing `environmentID` and `componentID` by providing selection lists.
 - Always use the exact IDs returned by the tool in subsequent calls.
 - If pagination limits are reached, the tool will indicate that not all items could be displayed.

 **IMPORTANT:** Do not automatically run additional tools after this tool is called. Wait for explicit user instruction before executing further tool calls. The LLM MUST NOT invoke other CircleCI tools until receiving clear instruction from the user about what to do next, even if the user selects an option. It is acceptable to list out tool call options for the user to choose from, but do not execute them until instructed.
 

Implementation Reference

• src/tools/listComponentVersions/handler.ts:12-51 (handler)

  Main handler function that orchestrates the listing of component versions, environments, or components based on provided parameters using CircleCI API.

  export const listComponentVersions: ToolCallback<{
    params: typeof listComponentVersionsInputSchema;
  }> = async (args) => {
    const {
      projectSlug,
      projectID: providedProjectID,
      orgID: providedOrgID,
      componentID,
      environmentID,
    } = args.params ?? {};
  
    try {
      // Resolve project and organization information
      const projectInfoResult = await resolveProjectInfo(projectSlug, providedProjectID, providedOrgID);
      
      if (!projectInfoResult.success) {
        return projectInfoResult.error;
      }
  
      const { projectID, orgID } = projectInfoResult.data;
  
      // If environmentID is not provided, list environments
      if (!environmentID) {
        return await listEnvironments(orgID);
      }
  
      // If componentID is not provided, list components
      if (!componentID) {
        return await listComponents(projectID, orgID);
      }
  
      // If both componentID and environmentID are provided, list component versions
      return await fetchComponentVersions(componentID, environmentID);
  
    } catch (error) {
      return mcpErrorOutput(
        `Failed to list component versions: ${error instanceof Error ? error.message : 'Unknown error'}`,
      );
    }
  };

• src/tools/listComponentVersions/handler.ts:194-221 (helper)

  Helper function to fetch and return component versions for a given componentID and environmentID using CircleCI deploys API.

  async function fetchComponentVersions(componentID: string, environmentID: string) {
    const circleci = getCircleCIClient();
  
    const componentVersions = await circleci.deploys.fetchComponentVersions({
      componentID,
      environmentID,
    });
  
    if (componentVersions.items.length === 0) {
      return {
        content: [
          {
            type: 'text',
            text: `No component versions found`,
          },
        ],
      };
    }
  
    return {
      content: [
        {
          type: 'text',
          text: `Versions for the component: ${JSON.stringify(componentVersions)}`,
        },
      ],
    };
  }

• src/tools/listComponentVersions/inputSchema.ts:4-34 (schema)

  Zod schema for input validation, requiring either projectSlug or projectID, with optional orgID, componentID, environmentID.

  export const listComponentVersionsInputSchema = z.object({
    projectSlug: z
      .string()
      .describe(projectSlugDescriptionNoBranch)
      .optional(),
    projectID: z
      .string()
      .uuid()
      .describe('The ID of the CircleCI project (UUID)')
      .optional(),
    orgID: z
      .string()
      .describe(
        'The ID of the organization. This is the ID of the organization that the components and environments belong to. If not provided, it will be resolved from projectSlug or projectID.',
      )
      .optional(),
    componentID: z
      .string()
      .optional()
      .describe('The ID of the component to list versions for. If not provided, available components will be listed.'),
    environmentID: z
      .string()
      .optional()
      .describe('The ID of the environment to list versions for. If not provided, available environments will be listed.'),
  }).refine(
    (data) => data.projectSlug || data.projectID,
    {
      message: "Either projectSlug or projectID must be provided",
      path: ["projectSlug", "projectID"],
    }
  );

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

  Tool registration object defining name 'list_component_versions', detailed description, and references inputSchema.

  export const listComponentVersionsTool = {
     name: 'list_component_versions' as const,
     description: `
       This tool lists all versions for a CircleCI component. It guides you through a multi-step process to gather the required information and provides lists of available options when parameters are missing.
  
       **Initial Requirements:**
       - You need either a \`projectSlug\` (from \`listFollowedProjects\`) or a \`projectID\`. The tool will automatically resolve the \`orgID\` from either of these.
  
       **Typical Flow:**
       1. **Start:** User requests component versions or deployment information.
       2. **Project Information:** Provide either \`projectSlug\` or \`projectID\`. The tool will automatically resolve the \`orgID\` and \`projectID\` as needed.
       3. **Environment Selection:** If \`environmentID\` is not provided, the tool will list all available environments for the organization and prompt the user to select one. Always return all available values without categorizing them.
       4. **Component Selection:** If \`componentID\` is not provided, the tool will list all available components for the project and prompt the user to select one. Always return all available values without categorizing them.
       5. **Version Listing:** Once both \`environmentID\` and \`componentID\` are provided, the tool will list all versions for that component in the specified environment.
       6. **Selection:** User selects a version from the list for subsequent operations.
  
       **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.
       - \`orgID\` (optional): The organization ID. If not provided, it will be automatically resolved from \`projectSlug\` or \`projectID\`.
       - \`environmentID\` (optional): The environment ID. If not provided, available environments will be listed.
       - \`componentID\` (optional): The component ID. If not provided, available components will be listed.
  
       **Behavior:**
       - The tool will guide you through the selection process step by step.
       - Automatically resolves \`orgID\` from \`projectSlug\` or \`projectID\` when needed.
       - When \`environmentID\` is missing, it lists environments and waits for user selection.
       - When \`componentID\` is missing (but \`environmentID\` is provided), it lists components and waits for user selection.
       - Only when both \`environmentID\` and \`componentID\` are provided will it list the actual component versions.
       - Make multiple calls to this tool as you gather the required parameters.
  
       **Common Use Cases:**
       - Identify which versions were deployed for a component
       - Identify which versions are live for a component
       - Identify which versions were deployed to an environment for a component
       - Identify which versions are not live for a component in an environment
       - Select a version for rollback or deployment operations
       - Obtain version name, namespace, and environment details for other CircleCI tools
  
       **Returns:**
       - When missing \`environmentID\`: A list of available environments with their IDs
       - When missing \`componentID\`: A list of available components with their IDs  
       - When both \`environmentID\` and \`componentID\` provided: A list of component versions with version name, namespace, environment ID, and is_live status
  
       **Important Notes:**
       - This tool requires multiple calls to gather all necessary information.
       - Either \`projectSlug\` or \`projectID\` must be provided; the tool will resolve the missing project information automatically.
       - The tool will prompt for missing \`environmentID\` and \`componentID\` by providing selection lists.
       - Always use the exact IDs returned by the tool in subsequent calls.
       - If pagination limits are reached, the tool will indicate that not all items could be displayed.
  
       **IMPORTANT:** Do not automatically run additional tools after this tool is called. Wait for explicit user instruction before executing further tool calls. The LLM MUST NOT invoke other CircleCI tools until receiving clear instruction from the user about what to do next, even if the user selects an option. It is acceptable to list out tool call options for the user to choose from, but do not execute them until instructed.
       `,
     inputSchema: listComponentVersionsInputSchema,
   };

• src/circleci-tools.ts:33-86 (registration)

  Top-level registration: imports tool and handler, adds to CCI_TOOLS array and CCI_HANDLERS map for MCP server.

  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;