CircleCI MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/tools/listFollowedProjects/handler.ts:7-42 (handler)

  The main handler function that executes the tool logic: fetches followed projects from CircleCI API, formats them with project slugs, and returns a text response instructing on usage.
  export const listFollowedProjects: ToolCallback<{ params: typeof listFollowedProjectsInputSchema; }> = async () => { const circleciPrivate = getCircleCIPrivateClient(); const followedProjects = await circleciPrivate.me.getFollowedProjects(); const { projects, reachedMaxPagesOrTimeout } = followedProjects; if (projects.length === 0) { return mcpErrorOutput( 'No projects found. Please make sure you have access to projects and have followed them.', ); } const formattedProjectChoices = projects .map( (project, index) => `${index + 1}. ${project.name} (projectSlug: ${project.slug})`, ) .join('\n'); let resultText = `Projects followed:\n${formattedProjectChoices}\n\nPlease have the user choose one of these projects by name or number. When they choose, you (the LLM) should extract and use the projectSlug (not the project name) associated with their chosen project for subsequent tool calls. This projectSlug is required for tools like get_build_failure_logs, getFlakyTests, and get_job_test_results.`; if (reachedMaxPagesOrTimeout) { resultText = `WARNING: Not all projects were included due to pagination limits or timeout.\n\n${resultText}`; } return { content: [ { type: 'text', text: resultText, }, ], }; };
• src/tools/listFollowedProjects/inputSchema.ts:3-3 (schema)

  Zod input schema for the tool, defined as an empty object since no input parameters are required.
  export const listFollowedProjectsInputSchema = z.object({});
• src/tools/listFollowedProjects/tool.ts:3-28 (registration)

  Tool metadata definition including name, detailed description, and reference to input schema. This object is imported and registered elsewhere.
  export const listFollowedProjectsTool = { name: 'list_followed_projects' as const, description: ` This tool lists all projects that the user is following on CircleCI. Common use cases: - Identify which CircleCI projects are available to the user - Select a project for subsequent operations - Obtain the projectSlug needed for other CircleCI tools Returns: - A list of projects that the user is following on CircleCI - Each entry includes the project name and its projectSlug Workflow: 1. Run this tool to see available projects 2. User selects a project from the list 3. The LLM should extract and use the projectSlug (not the project name) from the selected project for subsequent tool calls 4. The projectSlug is required for many other CircleCI tools, and will be used for those tool calls after a project is selected Note: If pagination limits are reached, the tool will indicate that not all projects could be displayed. IMPORTANT: Do not automatically run any additional tools after this tool is called. Wait for explicit user instruction before executing further tool calls. The LLM MUST NOT invoke any other CircleCI tools until receiving a clear instruction from the user about what to do next, even if the user selects a project. It is acceptable to list out tool call options for the user to choose from, but do not execute them until instructed. `, inputSchema: listFollowedProjectsInputSchema, };
• src/circleci-tools.ts:1-73 (registration)

  Imports the tool metadata and handler, then registers them in CCI_TOOLS array (line 39) and CCI_HANDLERS object (line 67) for use in the MCP server.
  import { ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js'; import { getBuildFailureLogsTool } from './tools/getBuildFailureLogs/tool.js'; import { getBuildFailureLogs } from './tools/getBuildFailureLogs/handler.js'; import { getFlakyTestLogsTool } from './tools/getFlakyTests/tool.js'; import { getFlakyTestLogs } from './tools/getFlakyTests/handler.js'; import { getLatestPipelineStatusTool } from './tools/getLatestPipelineStatus/tool.js'; import { getLatestPipelineStatus } from './tools/getLatestPipelineStatus/handler.js'; import { getJobTestResultsTool } from './tools/getJobTestResults/tool.js'; import { getJobTestResults } from './tools/getJobTestResults/handler.js'; import { configHelper } from './tools/configHelper/handler.js'; import { configHelperTool } from './tools/configHelper/tool.js'; import { createPromptTemplate } from './tools/createPromptTemplate/handler.js'; import { createPromptTemplateTool } from './tools/createPromptTemplate/tool.js'; import { recommendPromptTemplateTestsTool } from './tools/recommendPromptTemplateTests/tool.js'; import { recommendPromptTemplateTests } from './tools/recommendPromptTemplateTests/handler.js'; import { runPipeline } from './tools/runPipeline/handler.js'; import { runPipelineTool } from './tools/runPipeline/tool.js'; import { listFollowedProjectsTool } from './tools/listFollowedProjects/tool.js'; import { listFollowedProjects } from './tools/listFollowedProjects/handler.js'; import { runEvaluationTestsTool } from './tools/runEvaluationTests/tool.js'; import { runEvaluationTests } from './tools/runEvaluationTests/handler.js'; import { rerunWorkflowTool } from './tools/rerunWorkflow/tool.js'; import { rerunWorkflow } from './tools/rerunWorkflow/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'; // Define the tools with their configurations 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;