github-repos-manager-mcp/TEST-CLIENT-GUIDE.md

Model Context Protocol (MCP) server that enables your MCP client (e.g., Claude Desktop, Cline, Roo Code, Cursor, Windsurf, etc.) to interact with GitHub repositories using your GitHub personal access token.

# 🧪 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.*