Github Pr Automation README

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

server.ts

# 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

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

detect_merge_conflicts - Proactive conflict detection
- Checks for merge conflicts before attempting merge
- Provides file-level conflict details
- Suggests conflict resolution strategies
check_merge_readiness - Comprehensive PR health check
- Validates all merge requirements
- Checks CI status, approvals, branch protection rules
- Reports missing requirements with actionable steps
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
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

bash

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

bash

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

bash

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

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

Uninstall:

bash

# NPM Link
npm unlink github-pr-automation

# Global
npm uninstall -g github-pr-automation

For detailed installation options, see CLI Installation Guide.

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:

server.ts

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:

config.json

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

bash

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

server.ts

# 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

JSON Config

{
  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

JSON Config

{
  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

JSON Config

{
  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

JSON Config

{
  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

bash

# 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 docs/ directory:

Documentation Index - Complete documentation overview
Design Decisions - Rationale for key design choices
Architecture - System architecture and design
API Design - Complete API specifications
Data Models - TypeScript type definitions
Implementation Plan - Development roadmap
GitHub Integration - GitHub API patterns
Testing Strategy - Testing approach
Usage Examples - Real-world workflows

Quick Links

New to the project? Start with the Documentation Index
Want to implement? See Implementation Plan
Need examples? Check Usage Examples
Understanding design? Read Design Decisions

License

MIT

Repository

GitHub: https://github.com/jmalicki/github-pr-automation-mcp
NPM: https://www.npmjs.com/package/github-pr-automation
Issues: https://github.com/jmalicki/github-pr-automation-mcp/issues