GitHub Repos Manager MCP Server

# 🧪 GitHub Repos Manager MCP Tools - Complete Testing Guide & Reference for MCP Clients <div align="center"> **📋 Comprehensive Testing Manual** **🎯 Tool Validation Procedures** **🔧 Troubleshooting Guide** **📊 Results Analysis Framework** </div> --- ## 📚 Table of Contents 1. [Testing Overview](#testing-overview) 2. [Test Environment Specifications](#test-environment-specifications) 3. [Pre-Test Setup](#pre-test-setup) 4. [Category-by-Category Testing](#category-by-category-testing) 5. [Test Results Analysis](#test-results-analysis) 6. [Common Issues & Troubleshooting](#common-issues--troubleshooting) 7. [Performance Benchmarks](#performance-benchmarks) 8. [Test Evidence Collection](#test-evidence-collection) 9. [Reporting Templates](#reporting-templates) --- ## 🔍 Testing Overview ### 📊 What We Test | Category | Tools Count | Key Functions | Critical Areas | |----------|-------------|---------------|----------------| | **Repository Management** | 5 | List, info, search, contents | Basic connectivity | | **Issue Management** | 12 | CRUD operations, comments | Core functionality | | **Pull Request Management** | 6 | Create, review, manage | Previously problematic | | **Branch & Commit Operations** | 6 | Branch lifecycle, commits | Version control | | **File & Content Management** | 5 | File CRUD operations | Content handling | | **Labels & Milestones** | 8 | Project organization | Metadata management | | **User & Collaboration** | 3 | User info, collaborators | Access control | | **Repository Analytics** | 8 | Stats, metrics, insights | Data accuracy | | **Search & Discovery** | 7 | Advanced search features | Query performance | | **Security & Access** | 7 | Keys, webhooks, secrets | Security features | | **GitHub Actions** | 6 | Workflow management | CI/CD integration | | **Organization Management** | 6 | Org-level operations | Enterprise features | ### 🎯 Testing Objectives - **Functionality Validation**: Ensure all tools work as expected - **Performance Monitoring**: Check response times and reliability - **Error Handling**: Validate graceful failure handling - **Data Accuracy**: Verify responses match GitHub web interface - **Integration Testing**: Confirm end-to-end workflows work - **Regression Testing**: Ensure updates don't break existing features --- ## 🖥️ Test Environment Specifications ### 🤖 Supported MCP Clients and Models #### ** Test Environments** | Client | Model | Status | |--------|-------|--------| | **Claude Desktop** | Claude Sonnet 4, Claude Opus 4 | ✅ **Recommended** - Full feature support | | **Continue (VS Code)** | GPT-4, Claude, Local models | 🧪 **Secondary** - Community testing | | **Cline** | Various providers | 🧪 **Secondary** - Community testing | | **Custom MCP Client** | Any supported model | 🔧 **Advanced** - For debugging specific issues | ### 🎯 Default Test Repository **Unless specified otherwise, all testing should be conducted in:** ``` Repository: kurdin/github-repos-manager-mcp-tests Owner: kurdin Visibility: Private Purpose: Dedicated testing environment URL: https://github.com/kurdin/github-repos-manager-mcp-tests ``` #### **Why This Repository?** - ✅ **Isolated Environment**: No impact on production code - ✅ **Pre-configured**: Contains test data, issues, branches - ✅ **Permission Control**: Private repository for safe testing - ✅ **Test History**: Preserves testing artifacts and evidence - ✅ **Comprehensive Setup**: Labels, milestones, and sample content ready #### **Test Repository Contents** ``` ├── README.md (basic repository info) ├── index.js (sample JavaScript file) ├── test-files/ (directory for file operation tests) ├── npm-update-tests/ (NPM version testing artifacts) ├── retest-validation/ (comprehensive test files) └── Various branches for testing (main, feature branches, etc.) ``` ### 🔧 Client Configuration Requirements #### **Claude Desktop Setup** Ensure your `claude_desktop_config.json` includes: ```json { "mcpServers": { "github-repos-manager": { "command": "npx", "args": ["github-repos-manager-mcp"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_token_here" } } } } ``` #### **Required GitHub Token Permissions** ``` ✅ repo (Full control of private repositories) ✅ read:user (Read user profile data) ✅ read:org (Read organization data) ✅ write:repo_hook (Write repository hooks) ``` ### 🎯 Test Session Initialization **Start every test session with:** ``` 1. Verify MCP client connection 2. Set default repository to kurdin/github-repos-manager-mcp-tests 3. Confirm authentication is working 4. Check repository access permissions ``` **Command Sequence:** ``` local__github-repos-manager__set_default_repo ├── owner: kurdin └── repo: github-repos-manager-mcp-tests local__github-repos-manager__get_user_info (Verify authentication works) local__github-repos-manager__get_repo_info (Confirm repository access) ``` --- ## ⚙️ Pre-Test Setup ### 1. Environment Preparation ```bash # Ensure GitHub MCP is properly installed npm list | grep github-repos-manager-mcp # Verify MCP client configuration includes the GitHub MCP server # Check client-specific configuration files # Confirm you're using a supported test environment: # - Any compatible MCP client # - Any supported LLM model # - Access to kurdin/github-repos-manager-mcp-tests repository ``` ### 2. Test Repository Verification **Standard Test Repository (Default):** ``` Repository: kurdin/github-repos-manager-mcp-tests Owner: kurdin Type: Private Status: ✅ Ready for testing (pre-configured with test data) ``` **Repository Features Available for Testing:** - Multiple issues in various states (open/closed) - Several pull requests for PR testing - Multiple branches for branch operations - Existing labels and milestones - Sample files and directories - Comprehensive test history and artifacts **Alternative Repository Setup (Only if needed):** If you need to test with a different repository, ensure it has: - Read/write access for your GitHub token - At least 2-3 issues with different states - 1-2 branches beyond main - Some existing labels and milestones - Permission to create branches and files ### 3. Authentication Verification ```bash # Verify GitHub token has required permissions: # - repo (full control of private repositories) # - read:user (read user profile data) # - read:org (read organization data) ``` ### 4. Default Repository Setting **Standard Testing Procedure (Always start with this):** ``` local__github-repos-manager__set_default_repo ├── owner: kurdin └── repo: github-repos-manager-mcp-tests ``` **Expected Response:** ``` 📦 Default repository set to: kurdin/github-repos-manager-mcp-tests ``` **Alternative Repository (Only if testing specific scenarios):** ``` local__github-repos-manager__set_default_repo ├── owner: your-username └── repo: your-test-repository ``` **⚠️ Important Note:** Unless specifically testing with a different repository, ALL testing procedures assume you're using `kurdin/github-repos-manager-mcp-tests` as the default repository. --- ## 🧪 Category-by-Category Testing ### 1. 📁 Repository Management Tools #### Test Sequence: ``` 1. set_default_repo → Verify default repo is set 2. list_repos → Check pagination and filtering 3. get_repo_info → Validate complete metadata 4. get_repo_contents → Verify file listing 5. search_repos → Test search functionality ``` #### Expected Results: - **Response Time**: <3 seconds per operation - **Data Accuracy**: Matches GitHub web interface exactly - **Completeness**: All fields populated correctly #### Sample Test Commands: ``` local__github-repos-manager__set_default_repo ├── owner: kurdin └── repo: github-repos-manager-mcp-tests local__github-repos-manager__list_repos ├── per_page: 5 ├── sort: updated └── visibility: all local__github-repos-manager__get_repo_info (no parameters - uses default repo) ``` #### Validation Checklist: - [ ] Default repo setting shows confirmation message - [ ] Repository list includes expected repos with metadata - [ ] Repository info shows correct stats (issues, stars, size) - [ ] File contents list shows all expected files - [ ] Search returns relevant results with proper sorting ### 2. 🎫 Issue Management Tools #### Test Sequence: ``` 1. list_issues → Check existing issues 2. create_issue → Create new test issue 3. get_issue_details → Verify complete issue data 4. edit_issue → Update title/body 5. create_issue_comment → Add comment 6. list_issue_comments → Verify comment listing ``` #### Expected Results: - **Issue Creation**: Properly formatted with labels and assignees - **Comment System**: Full threading and editing support - **Metadata Handling**: Labels, assignees, milestones correctly managed #### Sample Test Commands: ``` local__github-repos-manager__create_issue ├── title: "Test Issue: Validation Run" ├── body: "This issue validates MCP functionality..." ├── labels: ["testing", "validation", "mcp"] └── assignees: ["your-username"] local__github-repos-manager__create_issue_comment ├── issue_number: 1 └── body: "Testing comment functionality" ``` #### Validation Checklist: - [ ] Issue creation returns proper GitHub URL - [ ] All specified labels and assignees are applied - [ ] Issue details match what was created - [ ] Comments appear correctly with timestamps - [ ] Edit operations update issues properly ### 3. 🔀 Pull Request Management Tools #### Test Sequence: ``` 1. list_prs → Check existing PRs 2. create_pull_request → Create new PR 3. get_pr_details → Verify PR metadata 4. list_pr_files → Check changed files 5. create_pr_review → Add review comment 6. list_pr_reviews → Verify review listing ``` #### Expected Results: - **PR Creation**: Successful with proper branch references - **Review System**: Comment reviews work (approval testing limited by GitHub rules) - **File Tracking**: Accurate diff and change information #### Sample Test Commands: ``` local__github-repos-manager__create_pull_request ├── title: "Test PR: Feature Validation" ├── body: "This PR tests the pull request functionality..." ├── head: "feature-branch" └── base: "main" local__github-repos-manager__create_pr_review ├── pull_number: 1 ├── body: "Testing review functionality" └── event: "COMMENT" ``` #### Validation Checklist: - [ ] PR creation succeeds with valid GitHub URL - [ ] PR details show correct branch references - [ ] File lists show accurate diffs and statistics - [ ] Reviews can be created and listed - [ ] All GitHub API responses are complete ### 4. 🌿 Branch & File Management Tools #### Test Sequence: ``` 1. list_branches → Check existing branches 2. create_branch → Create test branch 3. create_file → Add file to new branch 4. update_file → Modify file content 5. list_commits → Check commit history ``` #### Expected Results: - **Branch Operations**: Clean creation and listing - **File Operations**: Proper commit integration - **Version Control**: Accurate commit tracking #### Sample Test Commands: ``` local__github-repos-manager__create_branch ├── branch_name: "test-feature-branch" └── from_branch: "main" local__github-repos-manager__create_file ├── path: "test-files/validation.md" ├── content: "# Test File Content..." ├── message: "Add test validation file" └── branch: "test-feature-branch" ``` #### Validation Checklist: - [ ] Branch creation returns proper SHA reference - [ ] File creation generates commit with correct message - [ ] File updates preserve history - [ ] Commit listings show accurate metadata - [ ] All operations maintain repository integrity ### 5. 🏷️ Labels & Analytics Tools #### Test Sequence: ``` 1. list_repo_labels → Check existing labels 2. create_label → Create test label 3. list_milestones → Check milestones 4. get_repo_languages → Verify language stats 5. list_repo_topics → Check repository topics ``` #### Expected Results: - **Label Management**: Proper color and description handling - **Analytics Accuracy**: Stats match repository reality - **Topic Management**: Current topic list #### Sample Test Commands: ``` local__github-repos-manager__create_label ├── name: "test-validation" ├── color: "00ff00" └── description: "Label for testing validation" local__github-repos-manager__get_repo_languages (no parameters) ``` #### Validation Checklist: - [ ] Label creation shows correct color codes - [ ] Language statistics are accurate - [ ] Topics list is current and complete - [ ] Milestones show proper due dates and progress ### 6. 🔍 Search & User Tools #### Test Sequence: ``` 1. search_issues → Test issue search 2. search_repos → Test repository search 3. get_user_info → Verify user profile 4. list_repo_collaborators → Check access ``` #### Expected Results: - **Search Accuracy**: Relevant results with proper ranking - **User Data**: Complete profile information - **Access Control**: Correct permission levels #### Sample Test Commands: ``` local__github-repos-manager__search_issues ├── query: "repo:your-username/test-repo state:open" └── per_page: 5 local__github-repos-manager__get_user_info (no parameters - gets authenticated user) ``` #### Validation Checklist: - [ ] Search results are relevant and properly formatted - [ ] User profile shows accurate statistics - [ ] Collaborator lists show correct permissions - [ ] All data matches GitHub web interface --- ## 📊 Test Results Analysis ### 🎯 Success Criteria | Metric | Excellent | Good | Needs Attention | |--------|-----------|------|-----------------| | **Functionality** | 100% tools working | 95-99% working | <95% working | | **Response Time** | <2s average | 2-5s average | >5s average | | **Data Accuracy** | 100% match with GitHub | 99% accuracy | <99% accuracy | | **Error Handling** | Graceful failures | Some error messages | Poor error handling | ### 📈 Performance Benchmarks **Expected Response Times:** - **Simple Operations** (get_user_info, set_default_repo): <1 second - **Medium Operations** (list_issues, get_repo_info): 1-2 seconds - **Complex Operations** (search_repos, create_pull_request): 2-3 seconds - **Heavy Operations** (comprehensive searches): 3-5 seconds **Quality Indicators:** - All GitHub URLs should be functional - Timestamps should be in proper ISO 8601 format - Metadata should be complete and accurate - Response formats should be consistent --- ## 🚨 Common Issues & Troubleshooting ### 1. Authentication Problems **Symptoms:** - 401 Unauthorized errors - "Bad credentials" messages - Empty or limited responses **Solutions:** ```bash # Check token permissions # Verify token in GitHub Settings > Personal Access Tokens # Ensure token has required scopes: repo, read:user, read:org # Test token manually: curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user ``` ### 2. Tool Not Found Errors **Symptoms:** - "Tool 'local__github-repos-manager__*' not found" - Tool execution failures **Solutions:** ```bash # Verify MCP server configuration # Check client config file # Restart MCP client application # Verify npm package is latest version ``` ### 3. Rate Limiting Issues **Symptoms:** - 403 Forbidden with rate limit messages - Slow responses or timeouts **Solutions:** - Wait for rate limit reset (usually 1 hour) - Use authenticated requests (higher limits) - Implement delays between test operations ### 4. Permission Errors **Symptoms:** - "Not Found" errors for accessible repositories - Missing data in responses **Solutions:** - Verify repository access permissions - Check if repository is public vs private - Ensure token has appropriate organization access ### 5. Pull Request Creation Failures **Symptoms:** - "Not Found" errors during PR creation - Branch reference issues **Solutions:** - Verify both branches exist - Ensure branches have different commit histories - Check branch names for typos - Verify repository allows pull requests --- ## ⚡ Performance Benchmarks ### 📊 Baseline Metrics (Expected) | Operation Category | Response Time Target | Success Rate Target | |-------------------|---------------------|-------------------| | **Repository Info** | <1.5s | 100% | | **Issue Operations** | <2s | 100% | | **PR Operations** | <3s | 100% | | **Search Operations** | <4s | 100% | | **File Operations** | <3s | 100% | ### 🎯 Quality Metrics | Quality Aspect | Target | Measurement Method | |----------------|--------|-------------------| | **Data Accuracy** | 100% | Compare with GitHub web interface | | **URL Validity** | 100% | All returned URLs should be accessible | | **Response Completeness** | 100% | All expected fields populated | | **Error Handling** | Graceful | Clear, actionable error messages | --- ## 📋 Test Evidence Collection ### 🎯 Required Evidence for Complete Testing #### For Each Test Run, Document: 1. **Environment Information** ``` - Test Date: YYYY-MM-DD - NPM Package Version: X.X.X - Test Repository: username/repo-name - Tester: Name/Role ``` 2. **Created Test Artifacts** ``` - Issues Created: List with URLs - Branches Created: List with commit SHAs - Files Created: List with paths and sizes - Comments Added: List with IDs - Labels/Milestones: List with details ``` 3. **Performance Metrics** ``` - Average Response Times per category - Slowest operations identified - Any timeout or failure incidents - Overall success rate percentage ``` 4. **Functional Validation** ``` - Screenshots of key operations (optional) - Comparison with GitHub web interface - Verification of data accuracy - End-to-end workflow testing ``` ### 📊 Test Evidence Template ```markdown ## Test Evidence Summary **Test Session**: [Date/Time] **Package Version**: [Version Number] **Test Repository**: [Repository URL] ### Artifacts Created - Issue #X: [Title] - [URL] - Branch: [name] - [SHA] - File: [path] - [size] - Labels: [list] ### Performance Results - Repository Operations: [X.Xs average] - Issue Operations: [X.Xs average] - PR Operations: [X.Xs average] - Search Operations: [X.Xs average] ### Quality Assessment - Functionality: [X/Y tools working] ([percentage]%) - Data Accuracy: [assessment] - Error Handling: [assessment] - Overall Rating: [rating/5 stars] ``` --- ## 📝 Reporting Templates ### 🎯 Quick Test Report Template ```markdown # GitHub MCP Quick Test Report **Date**: [Date] **Version**: [Package Version] **Repository**: [Test Repository URL] ## Test Environment **MCP Client**: [Client Name and Version] **LLM Model**: [Model Name and Version] ## Summary - **Tools Tested**: [Number] - **Success Rate**: [Percentage]% - **Average Response**: [Time]s - **Critical Issues**: [Number] ## Category Results - [ ] Repository Management ([X/5] tools) - [ ] Issue Management ([X/12] tools) - [ ] Pull Request Management ([X/6] tools) - [ ] Branch & File Operations ([X/6] tools) - [ ] Labels & Analytics ([X/8] tools) - [ ] Search & User Tools ([X/7] tools) ## Issues Found [List any problems discovered] ## Recommendation [Deploy/Hold/Fix Required] ``` ### 🎯 Comprehensive Test Report Template ```markdown # GitHub MCP Comprehensive Test Report ## Executive Summary [High-level overview of test results] ## Test Environment - **Date**: [Test Date] - **Package Version**: [Version] - **Repository**: [Test Repository] - **Test Duration**: [Duration] - **MCP Client**: [Client Name and Version] - **LLM Model**: [Model Name and Version] ## Detailed Results by Category [Category-by-category breakdown with evidence] ## Performance Analysis [Response times, benchmarks, comparisons] ## Quality Assessment [Data accuracy, error handling, user experience] ## Issues and Recommendations [Detailed findings and suggested actions] ## Test Evidence [Links to created artifacts and documentation] ## Conclusion [Final assessment and deployment recommendation] ``` --- ## 🎯 Best Practices for Testing ### ✅ Do's 1. **Always Use a Dedicated Test Repository** - Prevents pollution of production repositories - Allows for clean, repeatable testing - Provides isolated environment for experiments 2. **Test in Logical Sequence** - Start with basic operations (repository info) - Build up to complex operations (pull requests) - Test dependencies before dependent operations 3. **Document Everything** - Record all created artifacts - Note performance metrics - Screenshot unusual results 4. **Validate Against GitHub Web Interface** - Compare data accuracy - Verify URLs work correctly - Check that operations appear in GitHub UI 5. **Test Error Scenarios** - Try invalid parameters - Test with insufficient permissions - Verify graceful error handling ### ❌ Don'ts 1. **Don't Test on Production Repositories** - Risk of creating unwanted issues/PRs - May trigger notifications to team members - Could interfere with actual work 2. **Don't Skip Authentication Verification** - Always confirm token permissions - Test with both valid and invalid credentials - Verify access to test repositories 3. **Don't Ignore Performance Issues** - Note any operations taking >5 seconds - Investigate timeout or failure patterns - Report significant performance regressions 4. **Don't Test Without Version Information** - Always record package version being tested - Note any recent updates or changes - Track improvements across versions --- ## 🔄 Regular Testing Schedule ### 📅 Recommended Testing Frequency | Trigger | Testing Scope | Purpose | |---------|---------------|---------| | **New NPM Release** | Comprehensive | Validate updates and improvements | | **Weekly** | Core Functions | Monitor production stability | | **Before Production Deploy** | Full Suite | Ensure deployment readiness | | **After GitHub API Changes** | Affected Areas | Verify continued compatibility | | **User-Reported Issues** | Specific Tools | Investigate and validate fixes | ### 🎯 Automated Testing Considerations Consider creating automated tests for: - Basic connectivity and authentication - Core CRUD operations on issues - Repository information retrieval - Search functionality - Performance regression monitoring --- <div align="center"> ## 🎊 Conclusion This comprehensive testing guide provides everything needed to validate GitHub MCP tools effectively. Regular testing using these procedures ensures reliability, performance, and user satisfaction. **Remember**: Good testing practices lead to better software and happier users! 🚀 </div> --- *This testing guide is based on extensive real-world testing of the GitHub MCP tools and represents best practices learned through comprehensive validation efforts.*