Github Workflow Debugger

🚀 GitHub Workflow Debugger MCP

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

🚀 Quick Start

This tool helps users diagnose and fix GitHub Actions workflow failures through a structured decision tree. It uses the GitHub API to obtain workflow run information, analyze failure scenarios, and provide actionable solutions.

✨ Features

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

📦 Installation

Install via Smithery

To automatically install githubworkflowmcp for Claude Desktop via 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

Basic Usage

The GitHub Workflow Debugger MCP is designed for AI assistants supporting the Model Context Protocol (MCP). It provides multiple tools for diagnosing and fixing GitHub Actions workflow failures.

Required Permissions

Using this tool requires 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 - supported 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 GitHub Personal Access Token.

Available Tools

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

Example Usage

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

1. First, retrieve the most recent failed workflow runs:

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

2. Analyze a specific failed run:

Can you analyze workflow run #123456 and suggest fixes?

3. View the content of a workflow file:

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

4. Update a workflow file with suggested fixes:

Update the workflow file with the suggested fixes.

🔧 Technical Details

Prerequisites

• Node.js 16 or higher
• npm or yarn

Project Setup

# Run the following commands in the terminal to set up the project and start the development server
npm install
npm run dev

Contribution Guidelines

Please refer to the Contribution Guidelines to learn how to contribute to this project.

📄 License

ISC License

Documentation

• Installation: Installation Instructions
• Usage: Usage Guide
• Development: Development Documentation