Contributing Guide

​

Ways to Contribute

• Report bugs: Help us identify and fix issues
• Request features: Suggest new functionality
• Improve documentation: Fix typos, clarify instructions, add examples
• Write code: Implement new features or fix bugs
• Share feedback: Let us know how the server works for you

​

Reporting Bugs

​

Security Vulnerabilities

• Provide detailed description of the vulnerability
• Include steps to reproduce
• Suggest potential fixes if possible
• Allow time for the team to address before public disclosure

​

Regular Bugs

1. Search existing issues: Check if the bug is already reported at github.com/pagerduty/pagerduty-mcp-server/issues
2. Verify it’s a bug: Ensure it’s not a configuration issue (see Troubleshooting Guide)
3. Gather information:
   • Steps to reproduce
   • Expected behavior
   • Actual behavior
   • Version information (uvx pagerduty-mcp --version)
   • Environment (OS, Python version, client application)
   • Error messages and logs
4. Create a bug report: Use the bug report template

​

Requesting Features

1. Check existing requests: Look for similar feature requests in GitHub issues
2. Discuss in the community: Consider posting in the PagerDuty Community Forum to gauge interest and gather feedback
3. Create a feature request: Use the feature request template

• Clear description of the proposed feature
• Use cases and benefits
• Potential implementation approach
• Examples of how it would be used
• Alternatives you’ve considered

​

Development Setup

​

Prerequisites

• asdf-vm: Version management tool (asdf-vm.com)
• uv: Python package installer (github.com/astral-sh/uv)
• PagerDuty User API Token: See Installation Guide for instructions

​

Initial Setup

git clone https://github.com/pagerduty/pagerduty-mcp-server.git
cd pagerduty-mcp-server

asdf plugin add python
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
asdf plugin add uv

asdf install

uv sync

cp .env.example .env

PAGERDUTY_USER_API_KEY=your-token-here
PAGERDUTY_API_HOST=https://api.pagerduty.com

​

Running Locally

uv run python -m pagerduty_mcp --enable-write-tools

​

Configuring Your MCP Client

{
  "pagerduty-mcp": { 
    "type": "stdio",
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/absolute/path/to/pagerduty-mcp-server",
      "python",
      "-m",
      "pagerduty_mcp",
      "--enable-write-tools"
    ],
    "env": {
      "PAGERDUTY_USER_API_KEY": "${input:pagerduty-api-key}"
    }
  }
}

​

Development Workflow

​

Step 1: Find Something to Work On

• Look for issues labeled good first issue
• Check for issues labeled help wanted
• Review the backlog

• Check high priority issues for impactful work
• Review enhancement issues for new features
• Look at active pull requests to avoid duplicate work

• Comment on the issue to let others know you’re working on it
• Ask clarifying questions if needed
• Ensure no one else is already working on it

​

Step 2: Design and Discussion

1. Propose your approach: Comment on the issue with your implementation plan
2. Gather feedback: Discuss with maintainers and community
3. Iterate on design: Refine based on feedback
4. Get approval: Wait for maintainer acknowledgment before starting

​

Step 3: Code Your Changes

# Create a new branch from next
git checkout next
git pull origin next
git checkout -b feature/your-feature-name

• One feature per PR: Keep pull requests focused on a single feature or bugfix
• Write tests: Add unit tests for new features and bug fixes
• Follow code style: Use the project’s linting and formatting rules
• Document your code: Add docstrings and comments where appropriate
• Keep changes minimal: Avoid unnecessary refactoring or housekeeping changes

​

Step 4: Testing

​

Run Unit Tests

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_incidents.py

# Run with coverage
uv run coverage run -m pytest
uv run coverage report

​

Run Evals

uv run python tests/evals/run_tests.py

​

Lint and Format Code

# Run linter
uv run ruff check .

# Auto-fix issues
uv run ruff check --fix .

# Format code
uv run ruff format .

# Type checking
uv run pyright

​

Step 5: Commit Your Changes

<type>: <description>

[optional body]

[optional footer]

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring
• test: Test changes
• chore: Maintenance tasks

git commit -m "feat: add support for incident workflows"
git commit -m "fix: handle missing service_id in create_incident"
git commit -m "docs: update installation instructions for Windows"

​

Step 6: Create a Pull Request

git push origin feature/your-feature-name

• Title must follow conventional commits format
• Title should be lowercase
• No period at the end of the title
• Description must explain motivation and approach
• All CI checks must pass
• At least one approving review required

• feat: add create_status_page_post tool
• fix: handle null values in schedule overrides
• docs: clarify regional endpoint configuration

​

Step 7: Review and Iteration

1. Respond to feedback: Address reviewer comments promptly
2. Push new commits: Add commits to the same branch
3. Request re-review: After addressing feedback
4. Be patient: Maintainers are volunteers and may take time to review

​

Step 8: Merge

1. A maintainer will squash-merge your PR to next
2. Your changes will be included in the next pre-release
3. After testing, changes will be merged to main
4. Your name will be added to the release notes

​

Code Style and Standards

​

Python Style

• PEP 8: Follow Python style guidelines
• Type hints: Use type annotations for all functions
• Docstrings: Use Google-style docstrings
• Line length: Maximum 120 characters

def create_incident(create_model: IncidentCreateRequest) -> Incident:
    """Create a new incident.
    
    Args:
        create_model: The incident creation parameters
    
    Returns:
        The created incident object
    
    Raises:
        ValidationError: If required fields are missing
    """
    response = get_client().rpost("/incidents", json=create_model.model_dump())
    return Incident.model_validate(response)

​

Tool Design Guidelines

1. Clear descriptions: Write tool descriptions for AI assistants, not humans
2. Intuitive parameters: Use parameter names that match PagerDuty terminology
3. Error handling: Provide helpful error messages
4. Documentation: Update tool reference docs
5. Examples: Include usage examples in docstrings

​

Testing Standards

• Unit tests required: All new functionality must have tests
• Test file naming: test_<module>.py
• Test function naming: test_<function>_<scenario>
• Use fixtures: Leverage pytest fixtures for common setup
• Mock external calls: Don’t make real API calls in tests

def test_create_incident_success(mock_client):
    """Test successful incident creation."""
    create_request = IncidentCreateRequest(
        title="Test incident",
        service_id="SVC123"
    )
    
    result = create_incident(create_request)
    
    assert result.title == "Test incident"
    assert result.service.id == "SVC123"

​

Project Structure

pagerduty-mcp-server/
├── pagerduty_mcp/          # Main package
│   ├── __init__.py
│   ├── __main__.py         # Entry point
│   ├── server.py           # MCP server implementation
│   ├── client.py           # PagerDuty API client
│   ├── context/            # Context and authentication
│   ├── models/             # Pydantic models
│   └── tools/              # Tool implementations
│       ├── incidents.py
│       ├── schedules.py
│       └── ...
├── tests/                  # Test suite
│   ├── test_incidents.py
│   ├── test_schedules.py
│   └── evals/              # LLM evaluation tests
├── docs/                   # Documentation (separate repo)
├── pyproject.toml          # Project metadata and dependencies
├── uv.lock                 # Locked dependencies
└── README.md               # Project overview

​

Community and Support

​

Communication Channels

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: General questions and discussions
• PagerDuty Community Forum: Community support and best practices
• Pull Request Comments: Technical discussions about specific changes

​

Code of Conduct

​

Recognition

• Release notes
• GitHub contributors page
• Project documentation (for significant contributions)

​

Additional Resources

• PagerDuty API Documentation
• Model Context Protocol Specification
• MCP Python SDK
• Project License

​

Thank You!