Woodpecker MCP Server

Um servidor para gerenciar pipelines CI/CD do Woodpecker, construído com o framework MCP.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Verified on MseeP

Servidor de Pipeline MCP

Um servidor Model Context Protocol (MCP) para análise automatizada de falhas em pipelines de CI/CD, projetado especificamente para integração com Woodpecker CI e suporte a IDEs.

🚀 Visão Geral

O Servidor de Pipeline MCP fornece análise inteligente de falhas em pipelines de CI com duas abordagens flexíveis:

  • Análise Direta de Pipeline: Analise pipelines específicos usando ID do repositório e número do pipeline
  • Análise com Contexto Git: Resolva e analise pipelines automaticamente usando nome do repositório, número do PR ou informações de branch da sua IDE

🛠️ Ferramentas Disponíveis

1. WoodpeckerCiPipelineReportGeneratorTool

Propósito: Análise direta de pipeline com identificadores específicos Entrada:

  • repoId: ID do repositório Woodpecker CI (ex.: "1")
  • pipelineNumber: Número específico do pipeline (ex.: "100577")

Uso:

# Example URLs to extract info from:
# https://woodpecker.orgName.dev/repos/1/pipeline/100577
# repoId = "1", pipelineNumber = "100577"

2. GitBasedPipelineAnalyzerTool

Propósito: Análise inteligente de pipeline usando contexto git da IDE Entrada:

  • repoName: Nome do repositório (ex.: "my-project")
  • pullRequestNumber: Número do PR (ex.: "123")
  • branchName: Nome do branch git (opcional)

Recursos:

  • Resolve automaticamente o ID do repositório a partir do nome
  • Encontra o pipeline mais recente para o PR especificado
  • Lida com pipelines em execução de forma graciosa
  • Integra-se com o contexto git da IDE

📋 Prompts Disponíveis

1. analyze-pipeline

Propósito: Análise tradicional de pipeline com números específicos de repositório/pipeline Melhor para: Análise direta quando você tem URLs do Woodpecker CI

2. analyze-pr-failures

Propósito: Análise integrada à IDE usando contexto git Melhor para: Analisar falhas de PR diretamente do seu ambiente de desenvolvimento

🔄 Fluxo de Análise

flowchart TD
    A[User Request] --> B{Input Type?}
    B -->|RepoID + Pipeline| C[WoodpeckerCiPipelineReportGeneratorTool]
    B -->|Repo Name + PR| D[GitBasedPipelineAnalyzerTool]
    D --> E[Resolve Repository ID]
    E --> F[Find Latest Pipeline]
    F --> C
    C --> G[Fetch Pipeline Details]
    G --> H[Get Failed Step Logs]
    H --> I[Analyze Final Attempts Only]
    I --> J[Generate Structured Report]
    J --> K[Markdown + JSON Output]
    K --> L[File-by-File Fix Suggestions]

🏗️ Arquitetura

Sistema de Injeção de Dependência

O servidor usa um padrão de injeção de dependência estilo NestJS:

// Services are auto-registered with @Injectable()
@Injectable()
class WoodpeckerForgesService {
    // Service implementation
}

// Tools inject services via constructor
export class GitBasedPipelineAnalyzerTool extends MCPTool<Input> {
    constructor(
        private woodpeckerForges: WoodpeckerForgesService = inject('WoodpeckerForgesService')
    ) {
        super();
    }
}

Estratégia de Cache

  • Resolução de Repositório: Cache de 24 horas para mapeamentos nome do repositório → ID do repositório
  • Análise de Pipeline: Cache de 2 horas para resultados completos de análise de pipeline
  • Sem Cache de Resolução de Pipeline: Sempre busca o pipeline mais recente para evitar dados desatualizados

Ciclo de Vida do Serviço

  1. Inicialização: ServiceManager inicializa e descobre serviços @Injectable
  2. Tempo de Execução: Instanciação preguiçosa de serviços no primeiro uso
  3. Desligamento: Limpeza adequada de cache e liberação de recursos

🚦 Exemplos de Uso

Integração com IDE (Recomendado)

# Analyze current PR failures
"Analyze PR failures for #123"

# Analyze by repository name
"Check CI issues for my-project repository"

# Analyze specific branch
"Analyze failures on feature/new-ui branch"

# Context-aware analysis
"Review CI problems"  # Uses current git context

Análise Direta de Pipeline

# Using specific Woodpecker CI identifiers
woodpecker-ci-pipeline-report-generator --repoId="1" --pipelineNumber="100577"

📊 Formato de Saída

Relatório Legível para Humanos

## CI Failure Analysis – pipeline #100577 | repo: my-project | PR #123
| # | Scenario | Scenario File | Code File | Failure Type | Brief Cause | Proposed Fix |
|---|----------|---------------|-----------|--------------|-------------|--------------|
| 1 | Login Flow | features/login.feature:23 | src/auth.js:45 | assertion | Element not found | Update selector |

### Details
#### Login Flow Test Failure
```log
Key failure indicators...

Arquivo de cenário: features/login.feature:23 Causa raiz: Seletor de elemento de UI atualizado não correspondente Sugestões de correção: Atualizar seletor de elemento em auth.js


### Machine-Readable JSON
```json
{
  "pipeline": "100577",
  "repoId": "1", 
  "context": {
    "repoName": "my-project",
    "prNumber": "123"
  },
  "analysedAt": "2024-08-11T10:30:00Z",
  "failures": [
    {
      "scenario": "Login Flow",
      "scenarioFile": "features/login.feature:23",
      "failureType": "assertion",
      "rootIndicators": ["Element not found", "Timeout"],
      "proposedFix": "Update element selector",
      "relatedFiles": ["src/auth.js:45"]
    }
  ]
}

🔧 Configuração e Instalação

Pré-requisitos

  • Node.js 18+
  • pnpm ou npm
  • Acesso à instância Woodpecker CI

Variáveis de Ambiente

WOODPECKER_SERVER=https://woodpecker.your-domain.com
WOODPECKER_TOKEN=your_woodpecker_token

Instalação

Opção 1: Instalar do npm (Recomendado)

# Install globally
npm install -g woodpecker-ci-mcp

# Or install locally in your project
npm install woodpecker-ci-mcp

Opção 2: Desenvolvimento Local

# Clone and install
git clone <repository-url>
cd mcp-pipeline-server
pnpm install

# Build
pnpm run build

# Start
pnpm start

Integração com Cliente MCP

Usando o pacote publicado:

{
  "mcpServers": {
    "woodpecker-ci": {
      "command": "npx",
      "args": ["woodpecker-ci-mcp"],
      "env": {
        "WOODPECKER_SERVER": "https://woodpecker.your-domain.com",
        "WOODPECKER_TOKEN": "your_token"
      }
    }
  }
}

Usando instalação global:

{
  "mcpServers": {
    "woodpecker-ci": {
      "command": "woodpecker-ci-mcp",
      "env": {
        "WOODPECKER_SERVER": "https://woodpecker.your-domain.com",
        "WOODPECKER_TOKEN": "your_token"
      }
    }
  }
}

Usando build local:

{
  "mcpServers": {
    "woodpecker-ci": {
      "command": "node",
      "args": ["path/to/mcp-pipeline-server/dist/index.js"],
      "env": {
        "WOODPECKER_SERVER": "https://woodpecker.your-domain.com",
        "WOODPECKER_TOKEN": "your_token"
      }
    }
  }
}

🎯 Recursos Principais

Análise Inteligente

  • Foco na Tentativa Final: Analisa apenas a última tentativa de etapas com falha
  • Reconhecimento de Padrões: Identifica padrões recorrentes de falha
  • Consciente do Contexto: Entende o fluxo de trabalho git e o contexto do PR

Integração com IDE

  • Resolução Automática de Repositório: Sem necessidade de consultar IDs de repositório manualmente
  • Consciente do Branch: Encontra pipelines apropriados para o branch/PR atual
  • Status em Tempo Real: Lida com pipelines em execução de forma graciosa

Experiência do Desenvolvedor

  • Sugestões Específicas de Arquivo: Aponta arquivos e números de linha exatos
  • Correções Interativas: Solicita confirmação antes de aplicar qualquer alteração
  • Saída Estruturada: Formatos legíveis para humanos e máquinas

Desempenho

  • Cache Inteligente: Estratégia de cache otimizada para diferentes tipos de dados
  • Carregamento Preguiçoso: Serviços instanciados apenas quando necessário
  • Gerenciamento de Recursos: Limpeza adequada no desligamento

🔍 Solução de Problemas

Problemas Comuns

  1. Erros de serviço não encontrado: Certifique-se de que o ServiceManager está inicializado antes do uso das ferramentas
  2. Pipeline não encontrado: Verifique a grafia do nome do repositório e o número do PR
  3. Problemas de token: Verifique se o WOODPECKER_TOKEN tem permissões suficientes

Log de Depuração

O servidor fornece logs detalhados para registro de serviços e resolução de pipelines:

🔧 Service registered: WoodpeckerForgesService
Auto-registered services: WoodpeckerForgesService

🤝 Contribuindo

  1. Siga os padrões de injeção de dependência estilo NestJS
  2. Use @Injectable() para serviços que serão injetados
  3. Implemente cache adequado para chamadas de API externas
  4. Adicione tratamento abrangente de erros
  5. Atualize este README para novas ferramentas/recursos

📚 Referência da API

Consulte os arquivos individuais das ferramentas para esquemas detalhados de parâmetros:

  • src/tools/WoodpeckerCiPipelineReportGeneratorTool.ts
  • src/tools/GitBasedPipelineAnalyzerTool.ts
  • src/prompts/CiPipelinePrompt.ts
  • src/prompts/GitBasedCiAnalysisPrompt.ts