Skip to content

EXAMPLES.md

Latest commit

 

History

History
583 lines (482 loc) · 11.4 KB

EXAMPLES.md

File metadata and controls

583 lines (482 loc) · 11.4 KB

Usage Examples

Comprehensive examples for all GitHub MCP Server tools.

Table of Contents

List Pull Requests

List all open PRs

{
  "tool": "list_prs",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "state": "open"
  }
}

List closed PRs

{
  "tool": "list_prs",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "state": "closed",
    "per_page": 50
  }
}

List PRs for specific branch

{
  "tool": "list_prs",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "base": "main",
    "head": "octocat:feature-branch"
  }
}

Response

[
  {
    "number": 123,
    "title": "Add new feature",
    "state": "open",
    "html_url": "https://github.com/octocat/hello-world/pull/123",
    "user": {
      "login": "developer",
      "avatar_url": "https://github.com/avatars/developer"
    },
    "head": {
      "ref": "feature-branch",
      "sha": "abc123"
    },
    "base": {
      "ref": "main",
      "sha": "def456"
    },
    "draft": false,
    "merged": false,
    "mergeable": true
  }
]

Get Pull Request

Get PR details

{
  "tool": "get_pr",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123
  }
}

Response

{
  "number": 123,
  "title": "Add new feature",
  "body": "This PR adds feature X\n\n## Changes\n- Added X\n- Updated Y",
  "state": "open",
  "html_url": "https://github.com/octocat/hello-world/pull/123",
  "user": {
    "login": "developer",
    "avatar_url": "https://github.com/avatars/developer"
  },
  "head": {
    "ref": "feature-branch",
    "sha": "abc123def456"
  },
  "base": {
    "ref": "main",
    "sha": "def456abc789"
  },
  "draft": false,
  "merged": false,
  "mergeable": true,
  "mergeable_state": "clean",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T14:20:00Z"
}

Create Pull Request

Basic PR creation

{
  "tool": "create_pr",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "title": "Add user authentication",
    "body": "Implements JWT-based authentication",
    "head": "feature/auth",
    "base": "main"
  }
}

Create draft PR

{
  "tool": "create_pr",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "title": "WIP: New dashboard design",
    "body": "Work in progress, not ready for review",
    "head": "feature/dashboard",
    "base": "develop",
    "draft": true
  }
}

PR with detailed body (markdown)

{
  "tool": "create_pr",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "title": "Feature: User profiles",
    "body": "# User Profiles Feature\n\n## Description\nAdds user profile pages with customization options.\n\n## Changes\n- Created profile model\n- Added profile routes\n- Implemented profile UI\n\n## Testing\n- [x] Unit tests\n- [x] Integration tests\n- [x] Manual testing\n\n## Screenshots\n![Profile page](url-to-image)\n\nFixes #42",
    "head": "feature/profiles",
    "base": "main"
  }
}

Update Pull Request

Update title and description

{
  "tool": "update_pr",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "title": "Feature: Complete user authentication",
    "body": "Updated implementation with OAuth support"
  }
}

Close a PR

{
  "tool": "update_pr",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "state": "closed"
  }
}

Change base branch

{
  "tool": "update_pr",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "base": "develop"
  }
}

Add Comment

Simple comment

{
  "tool": "add_pr_comment",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "body": "LGTM! Great work on this feature."
  }
}

Detailed review comment

{
  "tool": "add_pr_comment",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "body": "## Code Review\n\n### Strengths\n- Clean implementation\n- Good test coverage\n- Clear documentation\n\n### Suggestions\n- Consider adding error handling in auth.js line 45\n- Could extract helper function for token validation\n\n### Questions\n- Does this handle token expiration?\n- What about refresh tokens?\n\nOverall looks good! Just a few minor points to address."
  }
}

Comment with code suggestion

{
  "tool": "add_pr_comment",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "body": "Consider using async/await instead:\n\n```javascript\nasync function fetchUser(id) {\n  const user = await db.users.findById(id);\n  return user;\n}\n```"
  }
}

Merge Pull Request

Merge with default method

{
  "tool": "merge_pr",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123
  }
}

Squash and merge

{
  "tool": "merge_pr",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "merge_method": "squash",
    "commit_title": "feat: add user authentication",
    "commit_message": "Implements JWT-based authentication with OAuth support\n\nCloses #42"
  }
}

Rebase and merge

{
  "tool": "merge_pr",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "merge_method": "rebase"
  }
}

Request Reviewers

Request individual reviewers

{
  "tool": "request_pr_reviewers",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "reviewers": ["alice", "bob"]
  }
}

Request team reviewers

{
  "tool": "request_pr_reviewers",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "team_reviewers": ["frontend-team", "security-team"]
  }
}

Request both individual and team reviewers

{
  "tool": "request_pr_reviewers",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "reviewers": ["alice"],
    "team_reviewers": ["backend-team"]
  }
}

Add Labels

Add single label

{
  "tool": "add_pr_labels",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "labels": ["bug"]
  }
}

Add multiple labels

{
  "tool": "add_pr_labels",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "labels": ["enhancement", "high-priority", "needs-review"]
  }
}

Response

[
  {
    "name": "enhancement",
    "color": "a2eeef",
    "description": "New feature or request"
  },
  {
    "name": "high-priority",
    "color": "d93f0b",
    "description": "High priority issue"
  }
]

Remove Labels

Remove single label

{
  "tool": "remove_pr_labels",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "labels": ["needs-review"]
  }
}

Remove multiple labels

{
  "tool": "remove_pr_labels",
  "arguments": {
    "owner": "octocat",
    "repo": "hello-world",
    "pull_number": 123,
    "labels": ["wip", "needs-changes"]
  }
}

Use Cases

Automated PR Review Flow

  1. List all open PRs
  2. For each PR, get details
  3. If PR is ready (not draft, checks passed):
    • Request reviewers
    • Add "ready-for-review" label

PR Status Dashboard

  1. List all open PRs
  2. For each PR:
    • Get details
    • Check merge status
    • Display: title, author, status, reviewers

Automated Merge

  1. Get PR details
  2. Check if:
    • All checks passed
    • Approved by 2+ reviewers
    • No merge conflicts
  3. If all conditions met:
    • Add "approved" label
    • Merge with squash method
    • Add comment: "Auto-merged by bot"

Release Preparation

  1. List all merged PRs since last release
  2. For each PR:
    • Extract changes from body
    • Group by label (feature, bug, enhancement)
  3. Generate changelog
  4. Create release PR

PR Triage

  1. List all open PRs without labels
  2. For each PR:
    • Analyze title and description
    • Add appropriate labels (bug, feature, docs)
    • Request team reviewers based on files changed

Stale PR Cleanup

  1. List all open PRs
  2. For each PR older than 30 days:
    • Add comment: "This PR is stale, please update or close"
    • Add "stale" label
  3. For PRs older than 60 days:
    • Close with comment
    • Add "auto-closed" label

LLM Prompts

Ask AI to manage PRs

"List all open PRs in myorg/myrepo that haven't been updated in the last week"

"Add reviewers alice and bob to PR #123, and add labels 'ready-for-review' and 'high-priority'"

"Create a PR from feature/new-ui to main with title 'New UI Design' and include a description with changes made"

"Merge PR #45 using squash method with commit message 'feat: add dark mode'"

"Close all draft PRs older than 2 weeks with a comment explaining they're stale"

GitHub Workflow Automation

"For all open PRs in myrepo, check if they have reviewers assigned. If not, request reviews from the core team."

"Find all PRs labeled 'needs-changes', check if they've been updated in the last 3 days, and comment with a reminder if not."

"Create a daily summary of all merged PRs from yesterday, grouped by type (feature, bugfix, docs)."

Error Handling

All tools include proper error handling. Common errors:

Not Found (404)

{
  "error": "GitHub API error (404): Not Found",
  "code": "INTERNAL_ERROR"
}

Validation Error

{
  "error": "Validation error",
  "code": "INVALID_PARAMS",
  "details": [
    {
      "path": ["pull_number"],
      "message": "Pull request number must be positive"
    }
  ]
}

Permission Error

{
  "error": "GitHub API error (403): Resource not accessible by integration",
  "code": "INTERNAL_ERROR"
}

Best Practices

  1. Use specific filters: When listing PRs, use state, base, and head filters to reduce API calls
  2. Handle pagination: For repos with many PRs, use per_page parameter
  3. Check PR state: Before merging, always get PR details to verify it's mergeable
  4. Use draft PRs: Create PRs as drafts when they're not ready for review
  5. Add descriptive comments: Include context and reasoning in PR comments
  6. Label consistently: Use consistent labels across your organization
  7. Request appropriate reviewers: Request reviewers based on code ownership

Rate Limits

GitHub API rate limits (authenticated):

  • 5,000 requests per hour
  • Check remaining: curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/rate_limit

Tips to stay under limits:

  • Cache PR lists when possible
  • Use specific filters to reduce list sizes
  • Batch operations when updating multiple PRs
  • Monitor your rate limit usage

Security

  • Never commit tokens to version control
  • Use environment variables for authentication
  • Rotate tokens regularly
  • Use tokens with minimum required scopes
  • Monitor token usage in GitHub settings