GitHub MCP Server

# Agent Guide: GitHub MCP Server This guide is designed for AI agents and agent orchestration systems to efficiently discover and use the GitHub MCP server tools for analyzing developer impact and activity. ## Quick Reference ### Available Tools 1. **`github.getAuthoredPRs`** - Get PRs authored by a user 2. **`github.getPRReviews`** - Get PR reviews submitted by a user 3. **`github.getReviewComments`** - Get review comments with PR grouping 4. **`github.getCommentImpact`** - Analyze if comments led to code changes 5. **`github.getUserComments`** - Get all comments (review + issue) by a user 6. **`github.getUserRepoStats`** - Get comprehensive repository statistics (RECOMMENDED for quick overview) ## Tool Selection Guide ### When to Use Each Tool #### For Quick Overview - **Use `github.getUserRepoStats`** - Single call returns all metrics (PRs, comments, reviews, code changes) #### For Detailed Analysis - **PR Analysis**: Use `github.getAuthoredPRs` for PR details and metadata - **Review Analysis**: Use `github.getPRReviews` for review states, `github.getReviewComments` for comment content - **Impact Analysis**: Use `github.getCommentImpact` to measure review effectiveness - **Comment Analysis**: Use `github.getUserComments` for all comments in a repository ## Common Use Cases ### Use Case 1: Performance Review Data Collection - Complete Activity Overview **Goal**: Get comprehensive metrics for a developer in a repository over a time period. This data can be used for performance reviews and assessments. **Recommended Approach**: ```json { "tool": "github.getUserRepoStats", "arguments": { "username": "developer-name", "repo": "owner/repository", "from": "2024-01-01T00:00:00Z", "to": "2024-12-31T23:59:59Z" } } ``` **Returns**: Complete statistics including: - PRs: count, merged, open, closed - Comments: total, review, issue - Reviews: total, unique PRs reviewed, approved, changes requested, commented - Code changes: files changed, additions, deletions, net change ### Use Case 2: Code Contribution Analysis **Goal**: Analyze code contributions (PRs authored) with detailed metrics. **Step 1**: Get authored PRs ```json { "tool": "github.getAuthoredPRs", "arguments": { "username": "developer-name", "from": "2024-01-01T00:00:00Z", "to": "2024-12-31T23:59:59Z", "repos": ["owner/repository"] // Optional: filter by repos } } ``` ### Use Case 3: Code Review Participation **Goal**: Assess code review engagement and quality. **Step 1**: Get PR reviews ```json { "tool": "github.getPRReviews", "arguments": { "username": "developer-name", "repo": "owner/repository", "from": "2024-01-01T00:00:00Z", "to": "2024-12-31T23:59:59Z" } } ``` **Step 2**: Get review comments ```json { "tool": "github.getReviewComments", "arguments": { "username": "developer-name", "repo": "owner/repository", "from": "2024-01-01T00:00:00Z", "to": "2024-12-31T23:59:59Z" } } ``` **Step 3**: Analyze comment impact (optional) ```json { "tool": "github.getCommentImpact", "arguments": { "username": "developer-name", "repo": "owner/repository", "from": "2024-01-01T00:00:00Z", "to": "2024-12-31T23:59:59Z" } } ``` ### Use Case 4: Comment Analysis **Goal**: Get all comments (review + issue) by a user in a repository. ```json { "tool": "github.getUserComments", "arguments": { "username": "developer-name", "repo": "owner/repository", "from": "2024-01-01T00:00:00Z", "to": "2024-12-31T23:59:59Z" } } ``` **Returns**: Array of all comments with: - Comment body, type (review/issue), creation date - PR context (id, number, title, repo) - File/line context (for review comments) ## Parameter Guidelines ### Username - **Format**: Case-insensitive, `@` prefix optional - **Examples**: `"octocat"`, `"@octocat"`, `"JohnDoe"` all work - **Normalization**: Automatically converted to lowercase ### Repository - **Format**: `"owner/repo"` (required for most tools) - **Examples**: `"owner/repo"`, `"radireddy/AiApps"` - **Case**: Case-insensitive (automatically normalized) ### Time Range - **Format**: ISO 8601 timestamps - **Examples**: - `"2024-01-01T00:00:00Z"` (start of day) - `"2024-12-31T23:59:59Z"` (end of day) - **Validation**: `from` must be before `to` - **Time Zones**: Use UTC (Z suffix) for consistency ### PR IDs - **Format**: GraphQL node IDs (e.g., `"PR_kwDOABC123"`) - **Source**: Get from `github.getAuthoredPRs` results - **Batching**: Automatically batched (max 100 per call) ## Response Formats ### Standard Response Structure All tools return JSON with this structure: ```json { "content": [ { "type": "text", "text": "<JSON string of actual data>" } ] } ``` Parse the `text` field to get the actual data. ### Error Response Structure ```json { "content": [ { "type": "text", "text": "{\"error\": \"Error message\", \"stack\": \"...\"}" } ], "isError": true } ``` ## Best Practices ### 1. Start with Overview Tool For initial analysis, use `github.getUserRepoStats` to get a complete picture quickly. ### 2. Filter by Repository Most tools require a repository parameter. This ensures: - Consistent data across tools - Better performance (focused queries) - Accurate comparisons ### 3. Use Appropriate Time Ranges - **Quarterly reviews**: 3-month ranges - **Annual reviews**: Full year ranges - **Sprint analysis**: 2-week ranges - Avoid very large ranges (>1 year) for detailed analysis ### 4. Use Appropriate Time Ranges When analyzing multiple repositories: 1. Use repository filters to limit scope 2. Use appropriate time ranges (not too large) 3. Consider using `getUserRepoStats` for aggregated data ### 5. Handle Rate Limits - The server automatically handles rate limits - If rate limit errors occur, wait and retry - Consider using shorter time ranges for large datasets ### 6. Combine Tools Strategically - Use `getUserRepoStats` for overview - Use specific tools for detailed analysis - Use `getCommentImpact` to measure review effectiveness ## Data Filtering The server automatically filters: - **Auto-generated PRs**: PRs with titles starting with "Backmerge:" - **Auto-generated comments**: Bot comments and automated messages - **Empty comments**: Comments with no body All filtering is transparent - you receive clean, relevant data. ## Performance Considerations ### Fast Tools (Recommended for Quick Analysis) - `github.getUserRepoStats` - Single call, comprehensive data - `github.getPRReviews` - Efficient contributionsCollection API - `github.getReviewComments` - Efficient contributionsCollection API ### Tools That May Take Longer - `github.getAuthoredPRs` - May paginate through many PRs - `github.getUserComments` - Combines multiple data sources - `github.getCommentImpact` - Fetches PR timelines for each comment ### Optimization Tips 1. Use repository filters to limit scope 2. Use appropriate time ranges (not too large) 3. Use `getUserRepoStats` instead of combining multiple tools when possible 4. Cache results when analyzing the same data multiple times ## Example Agent Workflows ### Workflow 1: Performance Review Data Collection ```javascript // Step 1: Get comprehensive stats (data collection) const stats = await callTool('github.getUserRepoStats', { username: 'developer-name', repo: 'company/main-repo', from: '2024-01-01T00:00:00Z', to: '2024-12-31T23:59:59Z' }); // Step 2: Get top PRs for details const prs = await callTool('github.getAuthoredPRs', { username: 'developer-name', from: '2024-01-01T00:00:00Z', to: '2024-12-31T23:59:59Z', repos: ['company/main-repo'] }); // Step 3: Analyze review impact const impact = await callTool('github.getCommentImpact', { username: 'developer-name', repo: 'company/main-repo', from: '2024-01-01T00:00:00Z', to: '2024-12-31T23:59:59Z' }); // Generate report from combined data (analysis happens outside this MCP) ``` ### Workflow 2: Code Review Quality Assessment ```javascript // Step 1: Get review activity const reviews = await callTool('github.getPRReviews', { username: 'reviewer-name', repo: 'company/main-repo', from: '2024-01-01T00:00:00Z', to: '2024-12-31T23:59:59Z' }); // Step 2: Get review comments const comments = await callTool('github.getReviewComments', { username: 'reviewer-name', repo: 'company/main-repo', from: '2024-01-01T00:00:00Z', to: '2024-12-31T23:59:59Z' }); // Step 3: Measure impact const impact = await callTool('github.getCommentImpact', { username: 'reviewer-name', repo: 'company/main-repo', from: '2024-01-01T00:00:00Z', to: '2024-12-31T23:59:59Z' }); // Calculate metrics: // - Review participation: reviews.length // - Comment quality: comments.totalComments / reviews.length // - Review effectiveness: impact.stats.totalImpacts / impact.stats.totalComments ``` ### Workflow 3: Multi-Repository Analysis ```javascript const repos = ['company/repo1', 'company/repo2', 'company/repo3']; const results = []; for (const repo of repos) { const stats = await callTool('github.getUserRepoStats', { username: 'developer-name', repo: repo, from: '2024-01-01T00:00:00Z', to: '2024-12-31T23:59:59Z' }); results.push({ repo, stats: stats.stats }); } // Compare activity across repositories ``` ## Error Handling ### Common Errors 1. **Missing Repository Parameter** - Error: "Repository parameter is required" - Solution: Always provide `repo` parameter in `owner/repo` format 2. **Invalid Time Range** - Error: "Invalid time range: 'from' must be before 'to'" - Solution: Ensure `from` timestamp is before `to` timestamp 3. **Invalid Timestamp Format** - Error: "Invalid timestamp format" - Solution: Use ISO 8601 format: `"2024-01-01T00:00:00Z"` 4. **Rate Limit Exceeded** - Error: Rate limit information in error message - Solution: Wait for reset time or use shorter time ranges 5. **Authentication Failed** - Error: "GitHub authentication failed" - Solution: Check GITHUB_TOKEN is set and valid ### Error Response Format All errors return structured JSON: ```json { "error": "Error message", "stack": "Stack trace (in development mode only)" } ``` ## Tool Comparison Matrix | Tool | Use Case | Performance | Data Completeness | |------|----------|-------------|-------------------| | `getUserRepoStats` | Quick overview | ⚡ Fast | ✅ Complete | | `getAuthoredPRs` | PR analysis | ⚡ Fast | ✅ Complete | | `getPRReviews` | Review states | ⚡ Fast | ✅ Complete | | `getReviewComments` | Comment content | ⚡ Fast | ✅ Complete | | `getUserComments` | All comments | ⚠️ Medium | ✅ Complete | | `getCommentImpact` | Impact analysis | ⚠️ Slower | ✅ Complete | ## Tips for Agent Orchestration 1. **Parallel Execution**: Tools are independent - run multiple tools in parallel when analyzing different aspects 2. **Caching**: Cache `getUserRepoStats` results for quick lookups 3. **Progressive Enhancement**: Start with overview, then drill down into details 4. **Error Recovery**: Implement retry logic for rate limit errors 5. **Data Validation**: Validate time ranges and repository names before calling tools ## Additional Resources - **README.md**: Detailed tool documentation and architecture - **TESTING.md**: Test examples and validation - **QUICKSTART.md**: Setup and configuration guide ## Support For issues or questions: 1. Check error messages for specific guidance 2. Review tool descriptions for parameter requirements 3. Verify time ranges and repository formats 4. Check GitHub token permissions