get_latest_pipeline_status

Retrieve the current status of the most recent pipeline for a CircleCI project to check build progress and view pipeline state.

Instructions

This tool retrieves the status of the latest pipeline for a CircleCI project. It can be used to check pipeline status, get latest build status, or view current pipeline state.

Common use cases:
- Check latest pipeline status
- Get current build status
- View pipeline state
- Check build progress
- Get pipeline information

Input options (EXACTLY ONE of these THREE options must be used):

Option 1 - Project Slug and branch (BOTH required):
- projectSlug: The project slug obtained from listFollowedProjects tool (e.g., "gh/organization/project")
- branch: The name of the branch (required when using projectSlug)

Option 2 - Direct URL (provide ONE of these):
- projectURL: The URL of the CircleCI project in any of these formats:
  * Project URL: https://app.circleci.com/pipelines/gh/organization/project
  * Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123
  * Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
  * Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/xyz
  * Legacy Job URL: https://circleci.com/gh/organization/project/123

Option 3 - Project Detection (ALL of these must be provided together):
- workspaceRoot: The absolute path to the workspace root
- gitRemoteURL: The URL of the git remote repository
- branch: The name of the current branch

Recommended Workflow:
1. Use listFollowedProjects tool to get a list of projects
2. Extract the projectSlug from the chosen project (format: "gh/organization/project")
3. Use that projectSlug with a branch name for this tool

Additional Requirements:
- Never call this tool with incomplete parameters
- If using Option 1, make sure to extract the projectSlug exactly as provided by listFollowedProjects
- If using Option 2, the URLs MUST be provided by the user - do not attempt to construct or guess URLs
- If using Option 3, ALL THREE parameters (workspaceRoot, gitRemoteURL, branch) must be provided
- If none of the options can be fully satisfied, ask the user for the missing information before making the tool call

Input Schema

TableJSON Schema

Name	Required	Description	Default
`params`	No

Implementation Reference

src/tools/getLatestPipelineStatus/handler.ts:12-62 (handler)

The main handler function for the get_latest_pipeline_status tool. It processes inputs to determine projectSlug and branch, fetches latest pipeline workflows, and formats the status output.

export const getLatestPipelineStatus: ToolCallback<{
  params: typeof getLatestPipelineStatusInputSchema;
}> = async (args) => {
  const {
    workspaceRoot,
    gitRemoteURL,
    branch,
    projectURL,
    projectSlug: inputProjectSlug,
  } = args.params ?? {};

  let projectSlug: string | null | undefined;
  let branchFromURL: string | null | undefined;

  if (inputProjectSlug) {
    if (!branch) {
      return mcpErrorOutput(
        'Branch not provided. When using projectSlug, a branch must also be specified.',
      );
    }
    projectSlug = inputProjectSlug;
  } else if (projectURL) {
    projectSlug = getProjectSlugFromURL(projectURL);
    branchFromURL = getBranchFromURL(projectURL);
  } else if (workspaceRoot && gitRemoteURL) {
    projectSlug = await identifyProjectSlug({
      gitRemoteURL,
    });
  } else {
    return mcpErrorOutput(
      'Missing required inputs. Please provide either: 1) projectSlug with branch, 2) projectURL, or 3) workspaceRoot with gitRemoteURL and branch.',
    );
  }

  if (!projectSlug) {
    return mcpErrorOutput(`
          Project not found. Ask the user to provide the inputs user can provide based on the tool description.

          Project slug: ${projectSlug}
          Git remote URL: ${gitRemoteURL}
          Branch: ${branch}
          `);
  }

  const latestPipelineWorkflows = await getLatestPipelineWorkflows({
    projectSlug,
    branch: branchFromURL ?? branch,
  });

  return formatLatestPipelineStatus(latestPipelineWorkflows);
};

src/tools/getLatestPipelineStatus/inputSchema.ts:7-37 (schema)

Zod input schema defining optional parameters: projectSlug, branch, projectURL, workspaceRoot, gitRemoteURL with descriptions.

export const getLatestPipelineStatusInputSchema = z.object({
  projectSlug: z.string().describe(projectSlugDescription).optional(),
  branch: z.string().describe(branchDescription).optional(),
  projectURL: z
    .string()
    .describe(
      'The URL of the CircleCI project. Can be any of these formats:\n' +
        '- Project URL with branch: https://app.circleci.com/pipelines/gh/organization/project?branch=feature-branch\n' +
        '- Legacy Pipeline URL: https://circleci.com/gh/organization/project/123\n' +
        '- Legacy Pipeline URL with branch: https://circleci.com/gh/organization/project/123?branch=feature-branch\n' +
        '- Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123\n' +
        '- Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def\n' +
        '- Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/xyz',
    )
    .optional(),
  workspaceRoot: z
    .string()
    .describe(
      'The absolute path to the root directory of your project workspace. ' +
        'This should be the top-level folder containing your source code, configuration files, and dependencies. ' +
        'For example: "/home/user/my-project" or "C:\\Users\\user\\my-project"',
    )
    .optional(),
  gitRemoteURL: z
    .string()
    .describe(
      'The URL of the remote git repository. This should be the URL of the repository that you cloned to your local workspace. ' +
        'For example: "https://github.com/user/my-project.git"',
    )
    .optional(),
});

src/tools/getLatestPipelineStatus/tool.ts:4-46 (registration)

Tool registration object defining name, description, and inputSchema for get_latest_pipeline_status.

export const getLatestPipelineStatusTool = {
  name: 'get_latest_pipeline_status' as const,
  description: `
    This tool retrieves the status of the latest pipeline for a CircleCI project. It can be used to check pipeline status, get latest build status, or view current pipeline state.

    Common use cases:
    - Check latest pipeline status
    - Get current build status
    - View pipeline state
    - Check build progress
    - Get pipeline information

    Input options (EXACTLY ONE of these THREE options must be used):

    ${option1DescriptionBranchRequired}

    Option 2 - Direct URL (provide ONE of these):
    - projectURL: The URL of the CircleCI project in any of these formats:
      * Project URL: https://app.circleci.com/pipelines/gh/organization/project
      * Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123
      * Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
      * Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/xyz
      * Legacy Job URL: https://circleci.com/gh/organization/project/123

    Option 3 - Project Detection (ALL of these must be provided together):
    - workspaceRoot: The absolute path to the workspace root
    - gitRemoteURL: The URL of the git remote repository
    - branch: The name of the current branch
    
    Recommended Workflow:
    1. Use listFollowedProjects tool to get a list of projects
    2. Extract the projectSlug from the chosen project (format: "gh/organization/project")
    3. Use that projectSlug with a branch name for this tool

    Additional Requirements:
    - Never call this tool with incomplete parameters
    - If using Option 1, make sure to extract the projectSlug exactly as provided by listFollowedProjects
    - If using Option 2, the URLs MUST be provided by the user - do not attempt to construct or guess URLs
    - If using Option 3, ALL THREE parameters (workspaceRoot, gitRemoteURL, branch) must be provided
    - If none of the options can be fully satisfied, ask the user for the missing information before making the tool call
  `,
  inputSchema: getLatestPipelineStatusInputSchema,
};

src/circleci-tools.ts:68-85 (registration)

Higher-level registration mapping tool name to handler function in CCI_HANDLERS object.

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;

src/circleci-tools.ts:37-54 (registration)

Array of all CircleCI tools including getLatestPipelineStatusTool for top-level export.

export const CCI_TOOLS = [
  getBuildFailureLogsTool,
  getFlakyTestLogsTool,
  getLatestPipelineStatusTool,
  getJobTestResultsTool,
  configHelperTool,
  createPromptTemplateTool,
  recommendPromptTemplateTestsTool,
  runPipelineTool,
  listFollowedProjectsTool,
  runEvaluationTestsTool,
  rerunWorkflowTool,
  downloadUsageApiDataTool,
  findUnderusedResourceClassesTool,
  analyzeDiffTool,
  runRollbackPipelineTool,
  listComponentVersionsTool,
];

mcp-server-circleci