mcp-server-circleci

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 fetches followed projects using CircleCI client, formats them with sluginfo, and returns formatted text list.

  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 (empty object as it takes no parameters).

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

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

  Tool registration object defining name, description, and 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:37-54 (registration)

  Addition of listFollowedProjectsTool to the main CCI_TOOLS array.

  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)

  Mapping of 'list_followed_projects' to its handler in the main 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;