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

1. Startup: ServiceManager initializes and discovers @Injectable services
2. Runtime: Lazy service instantiation on first use
3. 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

1. Service not found errors: Ensure ServiceManager is initialized before tool usage
2. Pipeline not found: Verify repository name spelling and PR number
3. 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

1. Follow the NestJS-style dependency injection patterns
2. Use @Injectable() for services that will be injected
3. Implement proper caching for external API calls
4. Add comprehensive error handling
5. 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