GitHub MCP Server

# Testing Guide This guide shows you how to test the GitHub MCP server with real data. For agent orchestration examples and workflows, see [AGENT_GUIDE.md](./AGENT_GUIDE.md) and [agent-examples.json](./agent-examples.json). ## Prerequisites 1. **Set your GitHub token:** ```bash export GITHUB_TOKEN=ghp_your_token_here ``` 2. **Build the project:** ```bash npm run build ``` ## Testing Methods ### Method 1: Automated Test Suite (Easiest) Run the comprehensive test suite: ```bash npm run test ``` This will: - ✅ List all available tools - ✅ Test `github.getAuthoredPRs` with sample data - ✅ Test `github.getPRReviews` - ✅ Test `github.getReviewComments` - ✅ Test `github.getUserComments` for a repository - ✅ Display formatted results #### Running Specific Tests You can run only specific tests by passing test names as arguments: ```bash # Run a single test npm run test -- github.getReviewComments # Run multiple tests (comma-separated or space-separated) npm run test -- github.getReviewComments github.getPRReviews # Or with comma separation npm run test -- github.getReviewComments,github.getPRReviews # List available tools only npm run test -- listTools ``` **Available test names:** - `listTools` - List all available tools - `github.getAuthoredPRs` - Test getting authored PRs - `github.getPRReviews` - Test getting PR reviews - `github.getReviewComments` - Test getting review comments - `github.getCommentImpact` - Test getting comment impact - `github.getUserComments` - Test getting all user comments for a repository - `github.getUserRepoStats` - Test getting comprehensive repository statistics **Example Output:** ``` 🧪 Testing MCP Server ============================================================ 📋 Test 1: List available tools ------------------------------------------------------------ ✅ Found 5 tools: - github.getAuthoredPRs: Fetch all pull requests... - github.getPRReviews: Fetch all PR reviews... ... 📋 Test 2: Get Authored PRs ------------------------------------------------------------ ✅ Response received: Found 3 PRs First PR: { "id": "PR_kwDO...", "repo": "owner/repo", "title": "Fix bug", ... } ``` ### Method 2: Quick Manual Test Use the shell script for quick testing: ```bash ./test-manual.sh ``` ### Method 3: Test Individual Tools Test specific tools with custom data: #### List Available Tools ```bash echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/mcp/server.js ``` #### Get Authored PRs ```bash echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"github.getAuthoredPRs","arguments":{"username":"YOUR_USERNAME","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js ``` #### Get PR Reviews ```bash echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"github.getPRReviews","arguments":{"username":"YOUR_USERNAME","repo":"owner/repo","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js ``` #### Get Review Comments ```bash echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"github.getReviewComments","arguments":{"username":"YOUR_USERNAME","repo":"owner/repo","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js ``` #### Get Comment Impact ```bash echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"github.getCommentImpact","arguments":{"username":"YOUR_USERNAME","repo":"owner/repo","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js ``` #### Get User Comments ```bash echo '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"github.getUserComments","arguments":{"username":"YOUR_USERNAME","repo":"owner/repo","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js ``` #### Get User Repository Statistics ```bash echo '{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"github.getUserRepoStats","arguments":{"username":"YOUR_USERNAME","repo":"owner/repo","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js ``` ### Method 4: Pretty Print with jq For better readability, pipe output through `jq`: ```bash # Install jq if needed brew install jq # macOS # or sudo apt-get install jq # Linux # Test with pretty output echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \ node dist/mcp/server.js | \ grep -v "^Content-Length:" | \ tail -n +2 | \ jq '.' ``` ## Test Data Examples ### Using Real GitHub Users Replace `YOUR_USERNAME` with actual GitHub usernames: ```bash # Test with a known user (e.g., GitHub's octocat) USERNAME="octocat" FROM="2024-01-01T00:00:00Z" TO="2024-12-31T23:59:59Z" echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"github.getAuthoredPRs\",\"arguments\":{\"username\":\"$USERNAME\",\"from\":\"$FROM\",\"to\":\"$TO\"}}}" | \ node dist/mcp/server.js ``` ### Filtering by Repository Test repository filtering: ```bash echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"github.getAuthoredPRs","arguments":{"username":"octocat","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z","repos":["github/docs"]}}}' | \ node dist/mcp/server.js ``` ### Getting User Comments for a Repository Test fetching all comments by a user for a specific repository: ```bash echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"github.getUserComments","arguments":{"username":"octocat","repo":"github/docs","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | \ node dist/mcp/server.js ``` ## Understanding Responses ### Successful Response Format ```json { "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": "{\"prs\":[...]}" } ] } } ``` ### Error Response Format ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32603, "message": "Internal error", "data": "..." } } ``` ## Common Issues ### "GITHUB_TOKEN environment variable is required" - Make sure you've exported the token: `export GITHUB_TOKEN=your_token` - Verify: `echo $GITHUB_TOKEN` ### "GitHub authentication failed" - Check your token is valid - Ensure token has required scopes: `repo`, `read:org`, `read:user` - Regenerate token if needed ### "Rate limit exceeded" - Wait for the reset time shown in the error - The server automatically handles rate limits, but you may need to wait ### No output / Empty response - Check server logs on stderr - Verify the request format is correct JSON - Make sure the username exists and has activity in the time range ## Testing Workflow 1. **Start with listing tools** to verify server is working 2. **Test with a known user** (like `octocat`) to verify API access 3. **Test with your own username** to see your data 4. **Test time ranges** to verify filtering works 5. **Test repository filtering** if applicable 6. **Test error cases** (invalid usernames, invalid dates, etc.) ## Example Test Session ```bash # 1. Set token export GITHUB_TOKEN=ghp_your_token_here # 2. Build npm run build # 3. List tools echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/mcp/server.js | jq '.result.tools[].name' # 4. Get PRs for a user echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"github.getAuthoredPRs","arguments":{"username":"octocat","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | \ node dist/mcp/server.js | \ jq -r '.result.content[0].text' | \ jq '.prs | length' # 5. Get reviews echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"github.getPRReviews","arguments":{"username":"octocat","repo":"owner/repo","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | \ node dist/mcp/server.js | \ jq -r '.result.content[0].text' | \ jq '.reviews[0]' ``` ## Agent Usage Scenarios ### Scenario 1: Performance Review Data Collection Workflow **Objective**: Collect comprehensive data for generating a performance review report for a developer. **Steps**: 1. Get comprehensive stats using `github.getUserRepoStats` (data collection) 2. Get detailed PR information using `github.getAuthoredPRs` (data collection) 3. Get review impact using `github.getCommentImpact` (data collection) **Test Commands**: ```bash # Step 1: Get comprehensive stats echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"github.getUserRepoStats","arguments":{"username":"developer-name","repo":"owner/repo","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js # Step 2: Get authored PRs echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"github.getAuthoredPRs","arguments":{"username":"developer-name","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z","repos":["owner/repo"]}}}' | node dist/mcp/server.js # Step 3: Get review impact echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"github.getCommentImpact","arguments":{"username":"developer-name","repo":"owner/repo","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js ``` ### Scenario 2: Code Review Quality Assessment **Objective**: Assess the quality and effectiveness of code reviews. **Steps**: 1. Get PR reviews using `github.getPRReviews` 2. Get review comments using `github.getReviewComments` 3. Analyze comment impact using `github.getCommentImpact` **Test Commands**: ```bash # Step 1: Get PR reviews echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"github.getPRReviews","arguments":{"username":"reviewer-name","repo":"owner/repo","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js # Step 2: Get review comments echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"github.getReviewComments","arguments":{"username":"reviewer-name","repo":"owner/repo","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js # Step 3: Get comment impact echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"github.getCommentImpact","arguments":{"username":"reviewer-name","repo":"owner/repo","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js ``` ### Scenario 3: Multi-Repository Analysis **Objective**: Compare activity across multiple repositories. **Test Commands**: ```bash # Get stats for repo 1 echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"github.getUserRepoStats","arguments":{"username":"developer-name","repo":"owner/repo1","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js # Get stats for repo 2 echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"github.getUserRepoStats","arguments":{"username":"developer-name","repo":"owner/repo2","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js ``` **Note**: These calls can be made in parallel for better performance in agent orchestration systems. ### Scenario 4: Complete Developer Activity Analysis **Objective**: Get a complete picture of developer activity in a repository. **Recommended Approach**: Use `github.getUserRepoStats` for a single comprehensive call. **Test Command**: ```bash echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"github.getUserRepoStats","arguments":{"username":"developer-name","repo":"owner/repo","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js ``` **Expected Response**: 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 ## Agent Testing Best Practices 1. **Start with Overview**: Use `github.getUserRepoStats` for initial analysis 2. **Use Repository Filters**: Always specify repo parameter for consistent data 3. **Appropriate Time Ranges**: Use 3-month ranges for quarterly analysis, full year for annual 4. **Handle Errors Gracefully**: Check error responses and retry with adjusted parameters 5. **Parallel Execution**: Run independent tool calls in parallel when possible ## Next Steps - See `test-examples.json` for more example requests - See `agent-examples.json` for agent orchestration workflows - Check `README.md` for detailed tool documentation - Review `AGENT_GUIDE.md` for comprehensive agent documentation - Review `QUICKSTART.md` for setup instructions