MicroShift Test Analyzer

Analisa falhas de teste do MicroShift a partir do Google Sheets para correlacioná-las com versões específicas do MicroShift.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP MicroShift Test Analyzer

Um servidor MCP (Model Context Protocol) baseado em Python que analisa falhas de testes do MicroShift a partir do Google Sheets, fornecendo ferramentas especializadas para correlacionar falhas de testes com versões do MicroShift.

Recursos

  • Pipelines com Falhas por Versão: Obtenha pipelines de teste com falhas agrupados por versão do MicroShift
  • Resumo de Falhas: Obtenha estatísticas agregadas de falhas de testes em todas as versões
  • Tendências de Falhas em Pipelines: Analise tendências de falhas para pipelines de teste específicos ao longo do tempo
  • Buscar Motivos de Falhas: Busque motivos específicos de falhas em todos os testes
  • Comparação de Versões: Compare resultados de testes entre diferentes versões do MicroShift
  • Dados em Tempo Real: Busca dados diretamente do Google Sheets

Configuração

1. Instalar Dependências

pip install -r requirements.txt

2. Configuração da API do Google Sheets

Opção A: Conta de Serviço (Recomendado)

  1. Acesse o Google Cloud Console
  2. Crie um novo projeto ou selecione um existente
  3. Ative a API do Google Sheets
  4. Crie uma conta de serviço:
    • Vá para IAM & Admin > Service Accounts
    • Clique em "Create Service Account"
    • Preencha os detalhes e clique em "Create"
    • Pule a atribuição de função por enquanto
    • Clique em "Done"
  5. Gere uma chave para a conta de serviço:
    • Clique na conta de serviço criada
    • Vá para a aba "Keys"
    • Clique em "Add Key" > "Create New Key"
    • Escolha o formato JSON
    • Baixe o arquivo e salve-o com segurança
  6. Compartilhe sua planilha do Google com o e-mail da conta de serviço:
    • Abra sua planilha do Google
    • Clique em "Share"
    • Adicione o e-mail da conta de serviço (encontrado no arquivo JSON como client_email)
    • Dê permissão de "Viewer"

3. Configurar Variáveis de Ambiente

Copie o arquivo de ambiente de exemplo:

cp env.example .env

Edite .env e defina suas credenciais do Google usando os valores do arquivo JSON da sua conta de serviço:

GOOGLE_CLIENT_EMAIL=your-service-account@your-project.iam.gserviceaccount.com
GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour private key content\n-----END PRIVATE KEY-----\n"

Nota: Copie os valores de client_email e private_key diretamente do arquivo JSON baixado. Certifique-se de incluir as aspas ao redor da chave privada e preserve os caracteres \n.

4. Atualizar Configuração da Planilha

O servidor está configurado para ler o ID da planilha da URL que você forneceu. Se precisar alterar isso:

  1. Abra server.py
  2. Encontre a constante SPREADSHEET_ID perto do topo do arquivo
  3. Substitua pelo ID da sua planilha

Você também pode precisar ajustar o nome da planilha e o intervalo na função get_sheets_data() (atualmente definido como '2025_06!A:ZZ').

Uso

Executando o Servidor

python server.py

O servidor iniciará e aguardará conexões MCP via stdio.

Modo de Desenvolvimento

python server.py

Ferramentas Disponíveis

O servidor MCP fornece as seguintes ferramentas especializadas para análise de testes do MicroShift:

1. get_failed_pipelines_by_version

Obtenha pipelines de teste com falhas agrupados por versão do MicroShift.

Parâmetros:

  • version (opcional): Versão específica do MicroShift para filtrar
  • limit (opcional): Número máximo de resultados a retornar (padrão: 50)

2. get_failure_summary

Obtenha um resumo das falhas de testes em todas as versões do MicroShift.

Parâmetros:

  • group_by (opcional): Agrupe falhas por "version", "pipeline" ou "reason" (padrão: "version")

3. get_pipeline_failure_trends

Analise tendências de falhas para pipelines de teste específicos ao longo do tempo.

Parâmetros:

  • pipeline_name (opcional): Nome do pipeline de teste a ser analisado
  • days (opcional): Número de dias para retroceder (padrão: 30)

4. search_failure_reasons

Busque motivos específicos de falhas em todos os testes.

Parâmetros:

  • search_term (obrigatório): Termo de busca para encontrar nos motivos de falhas
  • version (opcional): Filtrar por versão específica do MicroShift

5. get_version_comparison

Compare resultados de testes entre diferentes versões do MicroShift.

Parâmetros:

  • version1 (obrigatório): Primeira versão do MicroShift para comparar
  • version2 (obrigatório): Segunda versão do MicroShift para comparar

Formato da Planilha

O servidor espera que sua planilha do Google tenha a seguinte estrutura de colunas:

  • Coluna A: Data (ex.: "21/06/2025_04:52:27")
  • Coluna B: ID (ex.: "1233")
  • Coluna C: MICROSHIFT_TARGET (ex.: "4.18.0~0.nightly")
  • Coluna D: BREW_VERSION (ex.: "microshift-4.18.0~0.nightly_2025_06_20_030312...")
  • Coluna E: Versão do MicroShift (ex.: "4.18.0~0.nightly")
  • Colunas F+: Imagens de build e pipelines de teste com formato multilinha contendo:
    • Arquitetura (x86_64, aarch64, x86)
    • Tipo de teste (install, upgrade, etc.)
    • Framework (RobotFramework, Ginkgo)
    • Status (SUCCESS, FAILURE)
    • Motivo da falha (se o status for FAILURE)

Integração com Clientes MCP

Este servidor segue o padrão oficial do MCP Python SDK usando FastMCP. Pode ser usado com qualquer cliente compatível com MCP, como o Claude for Desktop.

Configuração do Claude for Desktop

Adicione isto ao arquivo de configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "microshift-test-analyzer": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-test-scenarios-server/server.py"],
      "cwd": "/absolute/path/to/mcp-test-scenarios-server"
    }
  }
}

Exemplo de Uso

Uma vez conectado ao Claude for Desktop, você pode fazer perguntas como:

  • "Quais pipelines de teste falharam para a versão 4.18.0 do MicroShift?"
  • "Mostre-me todas as falhas relacionadas a 'ssh connection failed'"
  • "Compare os resultados de testes entre as versões 4.18.0 e 4.17.0"
  • "Quais são as tendências de falhas para o pipeline de atualização rpm?"
  • "Dê-me um resumo de todas as falhas de testes agrupadas por motivo"

Solução de Problemas

Problemas de Autenticação

  • Certifique-se de que suas variáveis de ambiente GOOGLE_CLIENT_EMAIL e GOOGLE_PRIVATE_KEY estão configuradas corretamente
  • Verifique se a conta de serviço tem acesso à planilha do Google
  • Confirme que a API do Google Sheets está ativada no seu projeto do Google Cloud
  • Certifique-se de que o formato da chave privada está correto (incluindo caracteres \n)

Problemas de Análise de Dados

  • Verifique se sua planilha segue a estrutura de colunas esperada
  • Certifique-se de que os dados do pipeline estão formatados com quebras de linha adequadas separando os diferentes componentes
  • Confirme que os valores de status são um dos: SUCCESS, FAILURE, FAILED, PASS, PASSED

Problemas de Conexão do Servidor

  • Certifique-se de que o caminho do script do servidor na sua configuração MCP está correto
  • Verifique se todas as dependências Python necessárias estão instaladas
  • Confirme que o ID do Google Sheets no código do servidor corresponde à sua planilha real

Mensagens de Erro Comuns

  • "No data available": A planilha está vazia ou a análise falhou
  • "Invalid credentials": A autenticação da conta de serviço falhou
  • "Permission denied": A conta de serviço não tem acesso à planilha
  • "Column index out of range": A estrutura da planilha não corresponde ao formato esperado

Exemplos de API

Usando curl para testar o servidor diretamente