github-pr-automation-mcp

jmalicki/github-pr-automation-mcp

3.2

If you are the rightful owner of github-pr-automation-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

An MCP server and CLI providing AI-assisted tools for automated GitHub Pull Request management.

Tools
5
Resources
0
Prompts
0

GitHub PR Automation

An MCP (Model Context Protocol) server and CLI that provides AI-assisted tools for automated GitHub Pull Request management, including test failure analysis, comment resolution, stacked PR management, and workflow optimization.

🚀 Quick Start

# Install and use the CLI
git clone https://github.com/jmalicki/github-pr-automation-mcp.git
cd github-pr-automation-mcp
npm install && npm run build
npm run install:cli:npm-link

# Set your GitHub token
export GITHUB_TOKEN="your_token_here"

# Use the CLI
github-pr-automation get-failing-tests --pr "owner/repo#123"

Or use as an MCP server with Claude Desktop for AI-assisted PR management.

Features

Core Tools

  1. get_failing_tests - Analyze PR CI failures and get targeted fix instructions

    • Fetches failing test information from PR checks
    • Options to wait for CI completion or return immediately
    • Can bail on first failure for faster feedback
    • Pagination support for large test suites
    • Returns actionable fix instructions

  2. find_unresolved_comments - Find and manage unresolved PR comments

    • Identifies unresolved review comments and conversations
    • NEW: Parses review bodies to extract actionable suggestions from AI tools (CodeRabbit, etc.)
    • Optional filtering for bot comments (e.g., @coderabbitai)
    • Generates response commands for efficient resolution
    • Summarizes comments requiring human judgment
    • Pagination with configurable page size

  3. manage_stacked_prs - Automated stacked PR management

    • Verifies dependency chains between PRs
    • Detects when base PR changes need to be propagated
    • Generates rebase instructions and automation commands
    • Integrates with get_failing_tests for automated fix loops
    • Batch command generation with pagination

Additional Tools

  1. detect_merge_conflicts - Proactive conflict detection

    • Checks for merge conflicts before attempting merge
    • Provides file-level conflict details
    • Suggests conflict resolution strategies

  2. check_merge_readiness - Comprehensive PR health check

    • Validates all merge requirements
    • Checks CI status, approvals, branch protection rules
    • Reports missing requirements with actionable steps

  3. rebase_after_squash_merge - Clean rebase after upstream squash-merge

    • Handles scenario where upstream PR was squash-merged
    • Uses git rebase --onto to skip upstream commits
    • Only rebases YOUR commits, avoiding conflicts
    • Auto-detects which commits to skip vs. rebase

  4. resolve_review_thread - Resolve specific review threads

    • Resolves individual review threads or comments
    • Supports both thread ID and comment ID targeting
    • Immediate resolution without manual intervention

Requirements

  • Node.js v20 or higher - Minimum version required (v22 LTS recommended)
  • GitHub Token - Set GITHUB_TOKEN environment variable for API access
  • Git - Required for git operations in stacked PR management

Node.js Version Management

This project is configured to use Node.js v22 LTS by default:

  • CI/CD - All GitHub Actions workflows use Node.js v22
  • engines field - NPM will warn about version mismatches (minimum v20)

Installation

Quick Start

# Clone the repository
git clone https://github.com/jmalicki/github-pr-automation-mcp.git
cd github-pr-automation-mcp

# Install dependencies
npm install

# Build the project
npm run build

CLI Installation

Install the CLI for system-wide usage:

# Method 1: NPM Link (Recommended)
npm run install:cli:npm-link

# Method 2: Global Installation
npm run install:cli:global

# Method 3: Interactive Installer
npm run install:cli

Verify Installation:

# Test the CLI
github-pr-automation --help

# Test a specific command
github-pr-automation get-failing-tests --help

Uninstall:

# NPM Link
npm unlink github-pr-automation

# Global
npm uninstall -g github-pr-automation

For detailed installation options, see .

How It Works

This is an MCP (Model Context Protocol) server that runs via stdio (not HTTP):

  • ✅ No HTTP server - communicates via stdin/stdout
  • ✅ No daemon - spawned on-demand by MCP client
  • ✅ No ports - no network exposure
  • ✅ Secure - isolated subprocess

The MCP client (like Claude Desktop) spawns this as a subprocess and communicates via JSON-RPC over stdio.

Configuration

Set the following environment variable:

export GITHUB_TOKEN="your_github_personal_access_token"

The token needs the following scopes:

  • repo (full control of private repositories)
  • read:org (read organization membership)

Usage

MCP Mode (Primary)

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "github-pr-automation": {
      "command": "node",
      "args": ["/path/to/github-pr-automation/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_github_token"
      }
    }
  }
}

CLI Mode (Direct Usage)

Use the tools directly from the command line:

# Get failing tests for a PR
github-pr-automation get-failing-tests --pr "owner/repo#123" --wait --bail-on-first

# Find unresolved comments
github-pr-automation find-unresolved-comments --pr "owner/repo#456" --include-bots

# Manage stacked PRs
github-pr-automation manage-stacked-prs --base-pr "owner/repo#100" --dependent-pr "owner/repo#101"

# Resolve review thread
github-pr-automation resolve-review-thread --pr "owner/repo#123" --thread-id "thread_id"

# Output as JSON for scripting
github-pr-automation get-failing-tests --pr "owner/repo#123" --json

CLI Use Cases:

  • 🚀 Quick PR checks - Get immediate feedback on PR status
  • 🤖 Automation scripts - Integrate into CI/CD pipelines
  • 🔧 Development workflow - Test tools during development
  • 📊 Data extraction - Get structured JSON output for analysis

Environment Setup:

# Set your GitHub token
export GITHUB_TOKEN="your_github_personal_access_token"

# Or use a .env file
echo "GITHUB_TOKEN=your_token_here" > .env

Tool Reference

get_failing_tests

{
  pr: "owner/repo#123",           // PR identifier
  wait: false,                     // Wait for CI completion (default: false)
  bail_on_first: true,            // 💾 Stop at first failure (default: true)
  page: 1,                         // Page number (default: 1)
  page_size: 10                    // 💾 Results per page (default: 10)
}

// 💾 = User preference hint - AI agents may learn and remember your preference

find_unresolved_comments

{
  pr: "owner/repo#123",           // PR identifier
  include_bots: true,             // 💾 Include bot comments (default: true)
  page: 1,                         // Page number (default: 1)
  page_size: 20,                   // 💾 Results per page (default: 20)
  sort: "chronological"            // 💾 Sort order (default: chronological)
}

manage_stacked_prs

{
  base_pr: "owner/repo#123",      // Earlier PR in stack
  dependent_pr: "owner/repo#124", // Later PR in stack
  auto_fix: true,                  // Auto-fix test failures (default: true)
  use_onto: true,                  // Use --onto rebase strategy (optional)
  max_iterations: 3                // Max fix iterations (default: 3)
}

resolve_review_thread

{
  pr: "owner/repo#123",           // PR identifier
  thread_id: "thread_id",         // Review thread GraphQL node ID (optional)
  comment_id: "comment_id",       // Comment GraphQL node ID (optional)
  prefer: "thread"                // Prefer "thread" or "comment" when both provided
}

Development

# Watch mode for development
npm run watch

# Build for production
npm run build

# Test MCP server (stdio mode)
npm run dev

# Test CLI mode
npm run cli -- get-failing-tests --pr "owner/repo#123"

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

Architecture

The server is built using:

  • @modelcontextprotocol/sdk - MCP protocol implementation
  • @octokit/rest - GitHub API client
  • @octokit/auth-app - GitHub App authentication
  • Zod - Runtime type validation for tool inputs
  • Commander - CLI framework
  • Vitest - Testing framework
  • TypeScript - Type safety and development experience

Documentation

Comprehensive documentation is available in the directory:

  • - Complete documentation overview
  • - Rationale for key design choices
  • - System architecture and design
  • - Complete API specifications
  • - TypeScript type definitions
  • - Development roadmap
  • - GitHub API patterns
  • - Testing approach
  • - Real-world workflows

Quick Links

  • New to the project? Start with the
  • Want to implement? See
  • Need examples? Check
  • Understanding design? Read

License

MIT

Repository