Github Workflow Debugger

🚀 GitHub Workflow Debugger MCP

A Multiple Choice Prompt (MCP) utility for diagnosing and fixing GitHub Actions workflow failures using the GitHub API.

🚀 Quick Start

The GitHub Workflow Debugger MCP is a tool designed to diagnose and fix GitHub Actions workflow failures. It uses the GitHub API to obtain workflow run information, analyzes failure situations, and provides actionable solutions.

✨ Features

• Retrieve recent failed workflow runs in the repository.
• Analyze jobs and steps of workflow runs.
• Identify common failure patterns.
• Suggest specific fixes for common issues.
• View and update workflow files.

📦 Installation

Install via Smithery

Automatically install githubworkflowmcp for Claude Desktop through Smithery:

npx -y @smithery/cli install @Maxteabag/githubworkflowmcp --client claude

Manual Installation

# Clone the repository
git clone https://github.com/yourusername/github-workflow-debugger-mcp.git
cd github-workflow-debugger-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Link for local use
npm link

💻 Usage Examples

Prerequisite Permissions

When using this tool, you need a GitHub Personal Access Token (PAT) with the following permissions:

• repo - Full control of private repositories.
• workflow - Update GitHub Action workflows. This token must be set as the environment variable GITHUB_PERSONAL_ACCESS_TOKEN.

Configuration

When used with an MCP-compatible client, it can be configured as follows:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Replace <YOUR_TOKEN> with your own GitHub Personal Access Token.

Available Tools

1. get-failed-workflow-runs - Retrieve recent failed workflow runs in the repository.
2. get-workflow-run-jobs - Get the jobs of a specific workflow run.
3. get-workflow-file - Retrieve the content of the workflow file.
4. update-workflow-file - Update the workflow file with fixes.
5. analyze-workflow-failure - Analyze a failed workflow run and suggest fixes.

Example Usage

Here are examples of using the GitHub Workflow Debugger MCP with an AI assistant:

Basic Usage

1. First, get recent failed workflow runs:

I need to check recent failed workflow runs in the repository "username/repo".

Advanced Usage

2. Analyze a specific failed run:

Can you analyze workflow run #123456 and suggest fixes?

3. View the workflow file:

Show the content of the workflow file in .github/workflows/main.yml.

4. Update the workflow file with suggested fixes:

Update the workflow file with the suggested fixes.

🔧 Technical Details

Prerequisites

• Node.js 16 or higher.
• npm or yarn.

Setup

# Install dependencies
npm install

# Build the project
npm run build

Project Structure

• src/index.ts - The main entry point of the MCP server.
• build/ - Compiled JavaScript files.