How do I use Woodpecker CI Pipeline Analyzer?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Woodpecker CI Pipeline Analyzer analyze PR failures for #123 in my-project" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Pipeline Server

A Model Context Protocol (MCP) server for automated CI/CD pipeline failure analysis, specifically designed for Woodpecker CI integration with IDE support.

🚀 Overview

The MCP Pipeline Server provides intelligent CI pipeline failure analysis with two flexible approaches:

Direct Pipeline Analysis: Analyze specific pipelines using repository ID and pipeline number
Git-Context Analysis: Automatically resolve and analyze pipelines using repository name, PR number, or branch information from your IDE

🛠️ Available Tools

1. WoodpeckerCiPipelineReportGeneratorTool

Purpose: Direct pipeline analysis with specific identifiers Input:

repoId: Woodpecker CI repository ID (e.g., "1")
pipelineNumber: Specific pipeline number (e.g., "100577")

Usage:

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

2. GitBasedPipelineAnalyzerTool

Purpose: Intelligent pipeline analysis using git context from IDE Input:

repoName: Repository name (e.g., "my-project")
pullRequestNumber: PR number (e.g., "123")
branchName: Git branch name (optional)

Features:

Auto-resolves repository ID from name
Finds latest pipeline for the specified PR
Handles running pipelines gracefully
Integrates with IDE git context

📋 Available Prompts

1. analyze-pipeline

Purpose: Traditional pipeline analysis with specific repo/pipeline numbers Best for: Direct analysis when you have Woodpecker CI URLs

2. analyze-pr-failures

Purpose: IDE-integrated analysis using git context Best for: Analyzing PR failures directly from your development environment

🔄 Analysis Flow

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]

🏗️ Architecture

Dependency Injection System

The server uses a NestJS-style dependency injection pattern:

// 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(); } }

Caching Strategy

Repository Resolution: 24-hour cache for repo name → repo ID mappings
Pipeline Analysis: 2-hour cache for complete pipeline analysis results
No Pipeline Resolution Cache: Always fetches latest pipeline to avoid stale data

Service Lifecycle

Startup: ServiceManager initializes and discovers @Injectable services
Runtime: Lazy service instantiation on first use
Shutdown: Proper cache cleanup and resource disposal

🚦 Usage Examples

IDE Integration (Recommended)

# 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

Direct Pipeline Analysis

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

📊 Output Format

Human-Readable Report

## 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...

Scenario file: features/login.feature:23 Root cause: Updated UI element selector not matching Fix suggestions: Update element selector in 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"] } ] }

🔧 Setup & Installation

Prerequisites

Node.js 18+
pnpm or npm
Access to Woodpecker CI instance

Environment Variables

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

Installation

Option 1: Install from npm (Recommended)

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

Option 2: Local Development

# Clone and install git clone <repository-url> cd mcp-pipeline-server pnpm install # Build pnpm run build # Start pnpm start

MCP Client Integration

Using the published package:

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

Using global installation:

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

Using local build:

{ "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" } } } }

🎯 Key Features

Intelligent Analysis

Final Attempt Focus: Only analyzes the last retry of failed steps
Pattern Recognition: Identifies recurring failure patterns
Context-Aware: Understands git workflow and PR context

IDE Integration

Automatic Repository Resolution: No need to lookup repo IDs manually
Branch-Aware: Finds appropriate pipelines for current branch/PR
Real-time Status: Handles running pipelines gracefully

Developer Experience

File-Specific Suggestions: Pinpoints exact files and line numbers
Interactive Fixes: Prompts before applying any changes
Structured Output: Both human and machine-readable formats

Performance

Smart Caching: Optimized cache strategy for different data types
Lazy Loading: Services instantiated only when needed
Resource Management: Proper cleanup on shutdown

🔍 Troubleshooting

Common Issues

Service not found errors: Ensure ServiceManager is initialized before tool usage
Pipeline not found: Verify repository name spelling and PR number
Token issues: Check WOODPECKER_TOKEN has sufficient permissions

Debug Logging

The server provides detailed logging for service registration and pipeline resolution:

🔧 Service registered: WoodpeckerForgesService Auto-registered services: WoodpeckerForgesService

🤝 Contributing

Follow the NestJS-style dependency injection patterns
Use @Injectable() for services that will be injected
Implement proper caching for external API calls
Add comprehensive error handling
Update this README for new tools/features

📚 API Reference

See individual tool files for detailed parameter schemas:

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