CircleCI MCP Server

Instructions

Implementation Reference

• src/tools/configHelper/handler.ts:5-34 (handler)

  The main handler function for the 'config_helper' tool. It validates the provided CircleCI config file content using the CircleCI client's configValidate method and returns a success or error message.

  export const configHelper: ToolCallback<{
    params: typeof configHelperInputSchema;
  }> = async (args) => {
    const { configFile } = args.params;
  
    const circleci = getCircleCIClient();
    const configValidate = await circleci.configValidate.validateConfig({
      config: configFile,
    });
  
    if (configValidate.valid) {
      return {
        content: [
          {
            type: 'text',
            text: 'Your config is valid!',
          },
        ],
      };
    }
  
    return {
      content: [
        {
          type: 'text',
          text: `There are some issues with your config: ${configValidate.errors?.map((error) => error.message).join('\n') ?? 'Unknown error'}`,
        },
      ],
    };
  };

• src/tools/configHelper/inputSchema.ts:3-9 (schema)

  Zod input schema for the config_helper tool, defining the 'configFile' parameter as a string.

  export const configHelperInputSchema = z.object({
    configFile: z
      .string()
      .describe(
        'The contents of the circleci config file. This should be the contents of the circleci config file, not the path to the file. Typically located at .circleci/config.yml',
      ),
  });

• src/tools/configHelper/tool.ts:3-26 (registration)

  Tool registration object defining the 'config_helper' tool's metadata: name, description, and input schema reference.

  export const configHelperTool = {
    name: 'config_helper' as const,
    description: `
    This tool helps analyze and validate and fix CircleCI configuration files.
  
    Parameters:
    - params: An object containing:
      - configFile: string - The full contents of the CircleCI config file as a string. This should be the raw YAML content, not a file path.
  
    Example usage:
    {
      "params": {
        "configFile": "version: 2.1\norbs:\n  node: circleci/node@7\n..."
      }
    }
  
    Note: The configFile content should be provided as a properly escaped string with newlines represented as \n.
  
    Tool output instructions:
      - If the config is invalid, the tool will return the errors and the original config. Use the errors to fix the config.
      - If the config is valid, do nothing.
    `,
    inputSchema: configHelperInputSchema,
  };

• src/circleci-tools.ts:30-44 (registration)

  Registration of config_helper tool (as configHelperTool) in the main CCI_TOOLS array.

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

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

  Maps the 'config_helper' name to its handler function (configHelper) 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;