CircleCI MCP Server

Instructions

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.

Implementation Reference

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

  The main handler function that implements the core logic of the 'list_followed_projects' tool. It fetches the list of followed projects from CircleCI using the private client, formats them with indices and projectSlugs, handles empty lists and pagination warnings, and returns a formatted text response instructing the user on next steps.

  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-4 (schema)

  Zod input schema for the tool, which is an empty object as the tool requires no input parameters.

  export const listFollowedProjectsInputSchema = z.object({});

• src/tools/listFollowedProjects/tool.ts:3-28 (registration)

  Tool object registration defining the name 'list_followed_projects', detailed description, and reference to the input schema.

  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:30-44 (registration)

  Inclusion of listFollowedProjectsTool in the main CCI_TOOLS array for global tool registration.

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

• src/circleci-tools.ts:58-73 (registration)

  Mapping of tool name 'list_followed_projects' to its handler function listFollowedProjects 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,
    analyze_diff: analyzeDiff,
    run_rollback_pipeline: runRollbackPipeline,
  } satisfies ToolHandlers;