Unit 3 Solution Walkthrough: Building a Pull Request Agent with MCP

Overview

This walkthrough guides you through the complete solution for Unit 3’s Pull Request Agent - an MCP server that helps developers create better pull requests by analyzing code changes, monitoring CI/CD pipelines, and automating team communications. The solution demonstrates all three MCP primitives (Tools, Resources, and Prompts) working together in a real-world workflow.

Architecture Overview

The PR Agent consists of interconnected modules that progressively build a complete automation system:

1. Build MCP Server - Basic server with Tools for PR template suggestions
2. Smart File Analysis - Enhanced analysis using Resources for project context
3. GitHub Actions Integration - CI/CD monitoring with standardized Prompts
4. Hugging Face Hub Integration - Model deployment and dataset PR workflows
5. Slack Notification - Team communication integrating all MCP primitives

Module 1: Build MCP Server

What We’re Building

A minimal MCP server that analyzes file changes and suggests appropriate PR templates using MCP Tools.

Key Components

1. Server Initialization ( server.py )

# The server registers three essential tools:
# - analyze_file_changes: Returns structured data about changed files
# - get_pr_templates: Lists available templates with metadata
# - suggest_template: Provides intelligent template recommendations

The server uses the MCP SDK to expose these tools to Claude Code, allowing it to gather information and make intelligent decisions about which PR template to use.

2. File Analysis Tool

The analyze_file_changes tool examines the git diff to identify:

• File types and extensions
• Number of files changed
• Lines added/removed
• Common patterns (tests, configs, docs)

This structured data enables Claude to understand the nature of the changes without hard-coding decision logic.

3. Template Management

Templates are stored as markdown files in the templates/ directory:

• bug.md - For bug fixes
• feature.md - For new features
• docs.md - For documentation updates
• refactor.md - For code refactoring

Each template includes placeholders that Claude can fill based on the analysis.

How Claude Uses These Tools

1. Claude calls analyze_file_changes to understand what changed
2. Uses get_pr_templates to see available options
3. Calls suggest_template with the analysis data
4. Receives a recommendation with reasoning
5. Can customize the template based on specific changes

Learning Outcomes

• Understanding tool registration and schemas
• Letting Claude make decisions with structured data
• Separation of data gathering from decision logic

Module 2: Smart File Analysis

What We’re Building

Enhanced file analysis using MCP Resources to provide project context and team guidelines.

Key Components

1. Resource Registration

The server exposes four types of resources:

# Resources provide read-only access to:
# - file://templates/ - PR template files
# - file://project-context/ - Coding standards, conventions
# - git://recent-changes/ - Commit history and patterns
# - team://guidelines/ - Review processes and standards

2. Project Context Resources

The project-context/ directory contains:

• coding-standards.md - Language-specific conventions
• review-guidelines.md - What reviewers look for
• architecture.md - System design patterns
• dependencies.md - Third-party library policies

Claude can read these to understand project-specific requirements.

3. Git History Analysis

The git://recent-changes/ resource provides:

• Recent commit messages and patterns
• Common PR titles and descriptions
• Team member contribution patterns
• Historical template usage

This helps Claude suggest templates consistent with team practices.

How Claude Uses Resources

1. Reads team://guidelines/review-process.md to understand PR requirements
2. Accesses file://project-context/coding-standards.md for style guides
3. Analyzes git://recent-changes/ to match team patterns
4. Combines this context with file analysis for better suggestions

Enhanced Decision Making

With resources, Claude can now:

• Suggest templates matching team conventions
• Include project-specific requirements in PRs
• Reference coding standards in descriptions
• Align with historical team practices

Learning Outcomes

• Resource URI design and schemas
• Making project knowledge accessible to AI
• Context-aware decision making
• Balancing automation with team standards

Module 3: GitHub Actions Integration

What We’re Building

Real-time CI/CD monitoring using webhooks and standardized prompts for consistent team communication.

Key Components

1. Webhook Server

Uses Cloudflare Tunnel to receive GitHub Actions events:

# Webhook endpoint handles:
# - workflow_run events
# - check_run events  
# - pull_request status updates
# - deployment notifications

2. Prompt Templates

Four standardized prompts ensure consistency:

• “Analyze CI Results” - Process test failures and build errors
• “Generate Status Summary” - Create human-readable status updates
• “Create Follow-up Tasks” - Suggest next steps based on results
• “Draft Team Notification” - Format updates for different audiences

3. Event Processing Pipeline

1. Receive webhook from GitHub
2. Parse event data and extract relevant information
3. Use appropriate prompt based on event type
4. Generate standardized response
5. Store for team notification

How Claude Uses Prompts

Example prompt usage:

# When tests fail, Claude uses the "Analyze CI Results" prompt:
prompt_data = {
    "event_type": "workflow_run",
    "status": "failure",
    "failed_jobs": ["unit-tests", "lint"],
    "error_logs": "...",
    "pr_context": {...}
}

# Claude generates:
# - Root cause analysis
# - Suggested fixes
# - Impact assessment
# - Next steps

Standardized Workflows

Prompts ensure that regardless of who’s working:

• CI failures are analyzed consistently
• Status updates follow team formats
• Follow-up actions align with processes
• Notifications contain required information

Learning Outcomes

• Webhook integration patterns
• Prompt engineering for consistency
• Event-driven architectures
• Standardizing team workflows

Module 4: Hugging Face Hub Integration

What We’re Building

Integration with Hugging Face Hub for LLM and dataset PRs, adding specialized workflows for teams working with language models.

Key Components

1. Hub-Specific Tools

# Tools for Hugging Face workflows:
# - analyze_model_changes: Detect LLM file modifications
# - validate_dataset_format: Check training data compliance
# - generate_model_card: Create/update model documentation
# - suggest_hub_template: PR templates for LLMs/datasets

2. Hub Resources

# Resources for Hub context:
# - hub://model-cards/ - LLM card templates and examples
# - hub://dataset-formats/ - Training data specifications
# - hub://community-standards/ - Hub community guidelines
# - hub://license-info/ - License compatibility checks

3. LLM-Specific Prompts

# Prompts for LLM workflows:
# - "Analyze Model Changes" - Understand LLM updates
# - "Generate Benchmark Summary" - Create evaluation metrics
# - "Check Dataset Quality" - Validate training data
# - "Draft Model Card Update" - Update documentation

Hub-Specific Workflows

When a PR modifies LLM files:

1. Tool: analyze_model_changes detects model architecture changes
2. Resource: Reads hub://model-cards/llm-template.md
3. Prompt: “Generate Benchmark Summary” creates evaluation section
4. Tool: generate_model_card updates documentation
5. Resource: Checks hub://license-info/ for compatibility

Dataset PR Handling

For training data updates:

• Validates format consistency
• Checks data quality metrics
• Updates dataset cards
• Suggests appropriate reviewers

Learning Outcomes

• Hugging Face Hub API integration
• LLM-specific PR workflows
• Model and dataset documentation
• Community standards compliance

Module 5: Slack Notification

What We’re Building

Automated team notifications combining Tools, Resources, and Prompts for complete workflow automation.

Key Components

1. Communication Tools

# Three tools for team updates:
# - send_slack_message: Post to team channels
# - get_team_members: Identify who to notify
# - track_notification_status: Monitor delivery

2. Team Resources

# Resources for team data:
# - team://members/ - Developer profiles and preferences
# - slack://channels/ - Channel configurations
# - notification://templates/ - Message formats

3. Notification Prompts

# Prompts for communication:
# - "Format Team Update" - Style messages appropriately
# - "Choose Communication Channel" - Select right audience
# - "Escalate if Critical" - Handle urgent issues

Integration Example

When CI fails on a critical PR:

1. Tool: get_team_members identifies the PR author and reviewers
2. Resource: team://members/{user}/preferences checks notification settings
3. Prompt: “Format Team Update” creates appropriate message
4. Tool: send_slack_message delivers to right channel
5. Resource: notification://templates/ci-failure ensures consistent format
6. Prompt: “Escalate if Critical” determines if additional alerts needed

Intelligent Routing

The system considers:

• Team member availability (from calendar resources)
• Notification preferences (email vs Slack)
• Message urgency (based on PR labels)
• Time zones and working hours

Learning Outcomes

• Primitive integration patterns
• Complex workflow orchestration
• Balancing automation with human needs
• Production-ready error handling

Complete Workflow Example

Here’s how all components work together for a typical PR:

1. Developer creates PR

   • GitHub webhook triggers the server
   • Tool: analyze_file_changes examines the diff
   • Resource: Reads team guidelines and project context
   • Prompt: Suggests optimal PR template

2. CI/CD Pipeline Runs

   • Webhook receives workflow events
   • Prompt: “Analyze CI Results” processes outcomes
   • Resource: Checks team escalation policies
   • Tool: Updates PR status in GitHub

3. Hugging Face Hub Integration

   • Tool: Detects LLM/dataset changes
   • Resource: Reads Hub guidelines
   • Prompt: Generates model card updates
   • Tool: Validates against Hub standards

4. Team Notification

   • Tool: Identifies relevant team members
   • Resource: Reads notification preferences
   • Prompt: Formats appropriate message
   • Tool: Sends via Slack channels

5. Follow-up Actions

   • Prompt: “Create Follow-up Tasks” generates next steps
   • Tool: Creates GitHub issues if needed
   • Resource: Links to documentation
   • All primitives work together seamlessly

Testing Strategy

Unit Tests

Each module includes comprehensive unit tests:

• Tool schema validation
• Resource URI parsing
• Prompt template rendering
• Integration scenarios

Integration Tests

End-to-end tests cover:

• Complete PR workflow
• Error recovery scenarios
• Performance under load
• Security validation

Test Structure

tests/
├── unit/
│   ├── test_tools.py
│   ├── test_resources.py
│   ├── test_prompts.py
│   └── test_integration.py
├── integration/
│   ├── test_workflow.py
│   ├── test_webhooks.py
│   └── test_notifications.py
└── fixtures/
    ├── sample_events.json
    └── mock_responses.json

Running the Solution

Local Development Setup

1. Start the MCP server: python server.py
2. Configure Claude Code: Add server to MCP settings
3. Set up Cloudflare Tunnel: cloudflared tunnel --url http://localhost:3000
4. Configure webhooks: Add tunnel URL to GitHub repository
5. Test the workflow: Create a PR and watch the automation

Configuration

Simple file-based configuration for easy setup:

• GitHub tokens in .env file
• Slack webhooks in config
• Template customization in templates/
• All settings in one place

Common Patterns and Best Practices

Tool Design

• Keep tools focused and single-purpose
• Return structured data for AI interpretation
• Include comprehensive error messages
• Version your tool schemas

Resource Organization

• Use clear URI hierarchies
• Implement resource discovery
• Cache frequently accessed resources
• Version control all resources

Prompt Engineering

• Make prompts specific but flexible
• Include context and examples
• Test with various inputs
• Maintain prompt libraries

Integration Patterns

• Use events for loose coupling
• Implement circuit breakers
• Add retries with backoff
• Monitor all external calls

Troubleshooting Guide

Common Issues

1. Webhook not receiving events

   • Check Cloudflare Tunnel is running
   • Verify GitHub webhook configuration
   • Confirm secret matches

2. Tools not appearing in Claude

   • Validate tool schemas
   • Check server registration
   • Review MCP connection

3. Resources not accessible

   • Verify file permissions
   • Check URI formatting
   • Confirm resource registration

4. Prompts producing inconsistent results

   • Review prompt templates
   • Check context provided
   • Validate input formatting

Next Steps and Extensions

Potential Enhancements

1. Add more code analysis tools (complexity, security)
2. Integrate with more communication platforms
3. Add custom workflow definitions
4. Implement PR auto-merge capabilities

Learning Path

• Next: Unit 4 - Deploy this server remotely
• Advanced: Custom MCP protocol extensions
• Expert: Multi-server orchestration

Conclusion

This PR Agent demonstrates the power of MCP’s three primitives working together. Tools provide capabilities, Resources offer context, and Prompts ensure consistency. Combined, they create an intelligent automation system that enhances developer productivity while maintaining team standards.

The modular architecture ensures each component can be understood, tested, and extended independently, while the integration showcases real-world patterns you’ll use in production MCP servers.