Apresentação do Projeto do Servidor MCP do CircleCI

Visão Geral do Projeto

O servidor MCP do CircleCI é uma implementação de servidor especializada projetada para o Protocolo de Contexto de Modelo (MCP), com o objetivo de integrar os fluxos de trabalho de desenvolvimento do CircleCI. Este projeto serve como uma ponte entre a infraestrutura do CircleCI e o Protocolo de Contexto de Modelo, proporcionando uma experiência de desenvolvimento aprimorada impulsionada por IA.

Este servidor permite que ferramentas de IA como Cursor, Claude Code, Windsurf, etc., compreendam o seu sistema de construção. Ele é construído com base no Protocolo de Contexto de Modelo (MCP), um padrão leve que permite que agentes impulsionados por LLM obtenham dados estruturados de sistemas externos.

Funcionalidades Principais

Principais Ferramentas e Funcionalidades

1. get_build_failure_logs

Recupera logs de falha detalhados de construções do CircleCI. Esta ferramenta suporta duas formas de uso:

Usando o URL do CircleCI:

• Forneça diretamente o URL do trabalho com falha ou o URL do pipeline
• Exemplo: "Obter os logs de https://app.circleci.com/pipelines/github/org/repo/123"

Usando o contexto do projeto local:

• Trabalhe a partir do seu espaço de trabalho local fornecendo as seguintes informações:
  • Caminho raiz do espaço de trabalho
  • URL remoto do Git
  • Nome da branch
• Exemplo: "Encontrar o pipeline com falha mais recente na minha branch atual"

Os logs formatados retornados incluem:

• Nome do trabalho
• Detalhes da execução passo a passo
• Mensagens de falha e contexto

2. find_flaky_tests

Identifica testes instáveis em projetos CircleCI analisando o histórico de execução de testes. Suporta duas formas de uso:

Usando o URL do projeto CircleCI:

• Forneça diretamente o URL do projeto do CircleCI
• Exemplo: "Encontrar testes instáveis em https://app.circleci.com/pipelines/github/org/repo"

Usando o contexto do projeto local:

• Trabalhe a partir do seu espaço de trabalho local fornecendo o caminho raiz do espaço de trabalho e o URL remoto do Git

Retorna informações detalhadas sobre testes instáveis, incluindo:

• Nome do teste e localização do arquivo
• Mensagens de falha e contexto

3. get_latest_pipeline_status

Recupera o status do pipeline mais recente para uma branch fornecida. A ferramenta retorna um status formatado do pipeline mais recente:

• Nome do workflow e seu status atual
• Duração de cada workflow
• Timestamps de criação e conclusão
• Saúde geral do pipeline

Exemplo de saída:

--- 
Workflow: build 
Status: success 
Duration: 5 minutes 
Created: 20/04/2025, 10:15:30 AM 
Stopped: 20/04/2025, 10:20:45 AM 
--- 
Workflow: test 
Status: running 
Duration: unknown 
Created: 20/04/2025, 10:21:00 AM 
Stopped: in progress

4. get_job_test_results

Recupera metadados de teste de um trabalho do CircleCI, permitindo que você analise os resultados dos testes sem sair do seu IDE.

Retorna informações detalhadas sobre os resultados dos testes:

• Resumo de todos os testes (total, sucesso, falha)
• Detalhes sobre testes com falha, incluindo:
  • Nome do teste e classe
  • Localização do arquivo
  • Mensagem de erro
  • Duração do tempo de execução
• Lista de testes bem-sucedidos com informações de tempo

5. config_helper

Auxilia em tarefas de configuração do CircleCI, fornecendo orientação e validação. Esta ferramenta ajuda você a:

• Validar a configuração do CircleCI:
  • Verifica se há erros de sintaxe e semântica em seu .circleci/config.yml
  • Exemplo: "Validar minha configuração do CircleCI"

Fornece:

• Resultados de validação detalhados
• Recomendações de configuração

6. create_prompt_template

Gera modelos de prompt estruturados com base em requisitos de funcionalidade para aplicativos habilitados para IA. Esta ferramenta:

• Converte requisitos de funcionalidade em prompts estruturados:
  • Traduz as necessidades do usuário em modelos de prompt otimizados
  • Exemplo: "Criar um modelo de prompt para gerar histórias para dormir por idade e tema"

7. recommend_prompt_template_tests

Gera casos de teste para modelos de prompt, garantindo que eles produzam os resultados esperados.

Instalação e Configuração

Requisitos do Sistema

• Gerenciador de pacotes pnpm - Saiba mais
• Node.js >= v18.0.0
• Token da API do CircleCI - Você pode gerar um através do CircleCI. Saiba mais ou clique aqui para acesso rápido

IDEs e Ferramentas Suportadas

Cursor IDE

Adicione o seguinte à sua configuração MCP do Cursor:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Opcional - Necessário apenas para clientes com implantações locais
      }
    }
  }
}

VS Code

Instale o servidor MCP do CircleCI em .vscode/mcp.json:

{
  // 💡 A entrada é solicitada na primeira inicialização do servidor e, em seguida, armazenada com segurança pelo VS Code
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}"
      }
    }
  }
}

Claude Desktop

Adicione o seguinte ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Opcional - Necessário apenas para clientes com implantações locais
      }
    }
  }
}

Localização do arquivo de configuração:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code

Após instalar o Claude Code, execute o seguinte comando:

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci

Windsurf

Adicione o seguinte ao seu mcp_config.json do Windsurf:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Opcional - Necessário apenas para clientes com implantações locais
      }
    }
  }
}

Instalação Automática

Instale automaticamente o servidor MCP do CircleCI para o Claude Desktop via Smithery:

npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude

Desenvolvimento e Contribuição

Configuração de Desenvolvimento Local

1. Clone o repositório:

git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
cd mcp-server-circleci

2. Instale as dependências:

pnpm install

3. Construa o projeto:

pnpm build

Desenvolvendo com o MCP Inspector

A maneira mais fácil de iterar no servidor MCP é usando o MCP Inspector.

1. Inicie o servidor de desenvolvimento:

pnpm watch # Mantenha em execução em um terminal

2. Inicie o inspector em um terminal separado:

pnpm inspector

3. Configure o ambiente:
   • Adicione seu CIRCLECI_TOKEN na seção de variáveis de ambiente na UI do inspector
   • O token precisa de permissões de leitura para seus projetos CircleCI
   • Opcionalmente, defina seu CircleCI Base URL, que por padrão é https://circleci.com

Testes

Execute o conjunto de testes:

pnpm test

Execute os testes no modo de observação durante o desenvolvimento:

pnpm test:watch

Casos de Uso

Esta ferramenta é particularmente útil para:

• Depurar construções com falha
• Analisar falhas de teste
• Investigar problemas de implantação
• Acessar rapidamente logs de construção sem sair do IDE
• Verificar o status dos pipelines mais recentes
• Identificar testes não confiáveis em um conjunto de testes
• Tomar decisões orientadas por dados sobre melhorias de teste

Vantagens do Projeto

O servidor MCP do CircleCI foi projetado para suportar momentos práticos no ciclo de vida do desenvolvimento. Esteja você revisando uma construção com falha, depurando uma implantação com falha ou monitorando branches críticas, ele ajuda seu assistente a entender as falhas e sugerir correções em segundos - sem alternância de contexto.

Ao integrar este servidor MCP, os desenvolvedores podem:

• Interagir com o CircleCI usando linguagem natural
• Obter informações de construção em um ambiente de desenvolvimento familiar
• Diagnosticar e resolver rapidamente problemas de CI/CD
• Aumentar a eficiência do fluxo de trabalho de desenvolvimento

Recursos Relacionados

• Introdução ao Protocolo de Contexto de Modelo
• Documentação do CircleCI
• Guia de Coleta de Dados de Teste
• Gerenciamento de Tokens da API do CircleCI

Para obter um guia de contribuição mais detalhado, consulte o arquivo CONTRIBUTING.md no projeto.