Woodpecker MCP Server

MCP管道服务器

一种用于自动化CI/CD管道故障分析的模型上下文协议（MCP）服务器，专为具有IDE支持的Woodpecker CI集成而设计。

🚀 概述

MCP Pipeline Server通过两种灵活的方法提供智能CI管道故障分析：

• 直接管道分析：使用存储库ID和管道编号分析特定管道
• Git上下文分析：使用IDE中的存储库名称、PR编号或分支信息自动解析和分析管道

🛠️ 可用工具

1.啄木鸟流水线报告生成器工具

目的：使用特定标识符进行直接管道分析 输入:

• repoId：啄木鸟CI存储库ID（例如“1”）
• pipelineNumber：具体管道编号（例如“100577”）

用法:

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

2.GitBasedPipeline分析器工具

目的：使用IDE中的git上下文进行智能管道分析 输入:

• repoName：存储库名称（例如“我的项目”）
• pullRequestNumber：PR编号（例如“123”）
• branchName：Git分支名称（可选）

特性:

• 从名称自动解析存储库ID
• 查找指定PR的最新管道
• 优雅地处理正在运行的管道
• 与IDE git上下文集成

📋 可用提示

1.分析管道

目的：具有特定回购/管道编号的传统管道分析 最适合：当您有啄木鸟CI URL时进行直接分析

2.分析公关失败

目的：使用git上下文的IDE集成分析 最适合：直接从开发环境中分析公关失败

🔄 分析流程

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]

🏗️ 建筑

依赖注入系统

服务器使用NestJS风格的依赖注入模式：

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

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

缓存策略

• 存储库解析：回购名称的24小时缓存→ 回购ID映射
• 管道分析：2小时缓存完整的管道分析结果
• 无管道分辨率缓存：始终获取最新的管道以避免过时的数据

服务生命周期

1. 初创公司：ServiceManager初始化并发现@Injectable服务
2. 运行时：首次使用时延迟服务实例化
3. 关机：正确的缓存清理和资源处置

🚦 使用示例

IDE集成（推荐）

# 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

直接管道分析

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

📊 输出格式

人类可读报告

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

Key failure indicators...

*场景文件*：功能/登录。功能：23
*根本原因*：更新的UI元素选择器不匹配
*修复建议*：更新auth.js中的元素选择器

Machine-Readable 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"]
    }
  ]
}

🔧 设置和安装

先决条件

• Node.js 18+
• pnpm或npm
• 访问啄木鸟CI实例

环境变量

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

安装

选项1：从npm安装（推荐）

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

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

方案2：地方发展

# Clone and install
git clone 
cd mcp-pipeline-server
pnpm install

# Build
pnpm run build

# Start
pnpm start

MCP客户端集成

使用已发布的软件包：

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

使用全局安装：

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

使用本地构建：

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

🎯 主要特点

智能分析

• 最终尝试焦点：仅分析失败步骤的最后一次重试
• 模式识别：识别重复出现的故障模式
• 上下文感知：了解git工作流程和公关背景

IDE集成

• 自动存储库解析：无需手动查找仓库ID
• 分行意识：为当前分支/PR找到合适的管道
• 实时状态：优雅地处理正在运行的管道

开发者体验

• 文件具体建议：精确定位文件和行号
• 交互式修复：应用任何更改前的提示
• 结构化输出：人类和机器可读格式

演出

• 智能缓存：针对不同数据类型优化缓存策略
• 延迟加载：仅在需要时实例化服务
• 资源管理：停机时进行适当的清理

🔍 故障排除

常见问题

1. 服务未找到错误：确保ServiceManager在使用工具之前已初始化
2. 未找到管道：验证存储库名称拼写和PR编号
3. 代币问题：检查WOODPECKER_TOKEN是否有足够的权限

调试日志记录

服务器为服务注册和管道解析提供详细的日志记录：

🔧 Service registered: WoodpeckerForgesService
Auto-registered services: WoodpeckerForgesService

🤝 贡献

1. 遵循NestJS风格的依赖注入模式
2. 使用 @Injectable() 对于即将注入的服务
3. 为外部API调用实现适当的缓存
4. 添加全面的错误处理
5. 更新此README以获取新工具/功能

📚 api参考

有关详细的参数模式，请参阅各个工具文件：

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