mcp-server-circleci

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/tools/getBuildFailureLogs/handler.ts:13-69 (handler)

  The main handler function that executes the tool logic: determines project details from inputs, fetches pipeline job logs, and formats them for output.
  export const getBuildFailureLogs: ToolCallback<{ params: typeof getBuildFailureOutputInputSchema; }> = async (args) => { const { workspaceRoot, gitRemoteURL, branch, projectURL, projectSlug: inputProjectSlug, } = args.params ?? {}; let projectSlug: string | undefined; let pipelineNumber: number | undefined; let branchFromURL: string | undefined; let jobNumber: number | 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); pipelineNumber = getPipelineNumberFromURL(projectURL); branchFromURL = getBranchFromURL(projectURL); jobNumber = getJobNumberFromURL(projectURL); } else if (workspaceRoot && gitRemoteURL && branch) { 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 logs = await getPipelineJobLogs({ projectSlug, branch: branchFromURL || branch, pipelineNumber, jobNumber, }); return formatJobLogs(logs); };
• src/tools/getBuildFailureLogs/inputSchema.ts:7-35 (schema)

  Zod input schema defining optional parameters for project identification: projectSlug, branch, projectURL, workspaceRoot, gitRemoteURL.
  export const getBuildFailureOutputInputSchema = 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' + '- 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/getBuildFailureLogs/tool.ts:4-46 (registration)

  Tool registration object defining name 'get_build_failure_logs', detailed description, and references the input schema.
  export const getBuildFailureLogsTool = { name: 'get_build_failure_logs' as const, description: ` This tool helps debug CircleCI build failures by retrieving failure logs. CRITICAL REQUIREMENTS: 1. Truncation Handling (HIGHEST PRIORITY): - ALWAYS check for <MCPTruncationWarning> in the output - When present, you MUST start your response with: "WARNING: The logs have been truncated. Only showing the most recent entries. Earlier build failures may not be visible." - Only proceed with log analysis after acknowledging the truncation 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 * Legacy Job URL: https://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 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: getBuildFailureOutputInputSchema, };
• src/circleci-tools.ts:37-54 (registration)

  Top-level registration: adds getBuildFailureLogsTool to the CCI_TOOLS array for MCP toolset.
  export const CCI_TOOLS = [ getBuildFailureLogsTool, getFlakyTestLogsTool, getLatestPipelineStatusTool, getJobTestResultsTool, configHelperTool, createPromptTemplateTool, recommendPromptTemplateTestsTool, runPipelineTool, listFollowedProjectsTool, runEvaluationTestsTool, rerunWorkflowTool, downloadUsageApiDataTool, findUnderusedResourceClassesTool, analyzeDiffTool, runRollbackPipelineTool, listComponentVersionsTool, ];
• src/circleci-tools.ts:68-85 (registration)

  Maps tool name 'get_build_failure_logs' to its handler function in the 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;