Woodpecker MCP Server

Un servidor para gestionar pipelines de CI/CD de Woodpecker, construido con el framework MCP.

Documentación

Servidor de Pipeline MCP

Un servidor de Model Context Protocol (MCP) para el análisis automatizado de fallos en pipelines de CI/CD, diseñado específicamente para la integración con Woodpecker CI y soporte para IDE.

🚀 Descripción General

El Servidor de Pipeline MCP proporciona análisis inteligente de fallos en pipelines de CI con dos enfoques flexibles:

Análisis Directo de Pipelines: Analiza pipelines específicos usando el ID del repositorio y el número de pipeline
Análisis con Contexto Git: Resuelve y analiza automáticamente pipelines usando el nombre del repositorio, número de PR o información de la rama desde tu IDE

🛠️ Herramientas Disponibles

1. WoodpeckerCiPipelineReportGeneratorTool

Propósito: Análisis directo de pipelines con identificadores específicos Entrada:

repoId: ID del repositorio de Woodpecker CI (ej., "1")
pipelineNumber: Número de pipeline específico (ej., "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álisis inteligente de pipelines usando el contexto git del IDE Entrada:

repoName: Nombre del repositorio (ej., "my-project")
pullRequestNumber: Número de PR (ej., "123")
branchName: Nombre de la rama git (opcional)

Características:

Resuelve automáticamente el ID del repositorio desde el nombre
Encuentra el pipeline más reciente para el PR especificado
Maneja pipelines en ejecución de manera elegante
Se integra con el contexto git del IDE

📋 Prompts Disponibles

1. analyze-pipeline

Propósito: Análisis tradicional de pipelines con números específicos de repositorio/pipeline Mejor para: Análisis directo cuando tienes URLs de Woodpecker CI

2. analyze-pr-failures

Propósito: Análisis integrado con IDE usando contexto git Mejor para: Analizar fallos de PR directamente desde tu entorno de desarrollo

🔄 Flujo de Análisis

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]

🏗️ Arquitectura

Sistema de Inyección de Dependencias

El servidor utiliza un patrón de inyección de dependencias 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();
    }
}

Estrategia de Caché

Resolución de Repositorios: Caché de 24 horas para mapeos de nombre de repositorio → ID de repositorio
Análisis de Pipelines: Caché de 2 horas para resultados completos de análisis de pipelines
Sin Caché de Resolución de Pipelines: Siempre obtiene el pipeline más reciente para evitar datos obsoletos

Ciclo de Vida del Servicio

Inicio: ServiceManager se inicializa y descubre servicios @Injectable
Ejecución: Instanciación perezosa de servicios en el primer uso
Apagado: Limpieza adecuada de caché y liberación de recursos

🚦 Ejemplos de Uso

Integración con 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álisis Directo de Pipelines

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

📊 Formato de Salida

Informe Legible 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...

Archivo de escenario: features/login.feature:23 Causa raíz: El selector de elementos de UI actualizado no coincide Sugerencias de corrección: Actualizar el selector de elementos en 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"]
    }
  ]
}

🔧 Configuración e Instalación

Requisitos Previos

Node.js 18+
pnpm o npm
Acceso a la instancia de Woodpecker CI

Variables de Entorno

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

Instalación

Opción 1: Instalar desde npm (Recomendado)

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

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

Opción 2: Desarrollo Local

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

# Build
pnpm run build

# Start
pnpm start

Integración con Cliente MCP

Usando el paquete publicado:

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

Usando instalación global:

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

Usando compilación 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"
      }
    }
  }
}

🎯 Características Clave

Análisis Inteligente

Enfoque en el Intento Final: Solo analiza el último reintento de los pasos fallidos
Reconocimiento de Patrones: Identifica patrones de fallos recurrentes
Consciente del Contexto: Comprende el flujo de trabajo git y el contexto de PR

Integración con IDE

Resolución Automática de Repositorios: No es necesario buscar IDs de repositorios manualmente
Consciente de Ramas: Encuentra pipelines apropiados para la rama/PR actual
Estado en Tiempo Real: Maneja pipelines en ejecución de manera elegante

Experiencia del Desarrollador

Sugerencias Específicas de Archivos: Señala archivos y números de línea exactos
Correcciones Interactivas: Solicita confirmación antes de aplicar cualquier cambio
Salida Estructurada: Formatos legibles tanto para humanos como para máquinas

Rendimiento

Caché Inteligente: Estrategia de caché optimizada para diferentes tipos de datos
Carga Perezosa: Los servicios se instancian solo cuando se necesitan
Gestión de Recursos: Limpieza adecuada al apagar

🔍 Solución de Problemas

Problemas Comunes

Errores de servicio no encontrado: Asegúrate de que ServiceManager esté inicializado antes del uso de herramientas
Pipeline no encontrado: Verifica la ortografía del nombre del repositorio y el número de PR
Problemas de token: Comprueba que WOODPECKER_TOKEN tenga permisos suficientes

Registro de Depuración

El servidor proporciona registro detallado para el registro de servicios y la resolución de pipelines:

🔧 Service registered: WoodpeckerForgesService
Auto-registered services: WoodpeckerForgesService

🤝 Contribuciones

Sigue los patrones de inyección de dependencias estilo NestJS
Usa @Injectable() para servicios que serán inyectados
Implementa caché adecuada para llamadas a API externas
Agrega manejo integral de errores
Actualiza este README para nuevas herramientas/características

📚 Referencia de API

Consulta los archivos de herramientas individuales para esquemas de parámetros detallados:

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