Sumanshu Arora

# GitHub MCP Server Documentation ## Overview The GitHub MCP Server template provides seamless integration with GitHub's comprehensive API through the Model Context Protocol (MCP). This template extends the official GitHub MCP server to provide enhanced capabilities, streamlined deployment, and robust tooling for GitHub operations. Our platform extends the official GitHub MCP server by providing: - **🚀 One-Command Deployment**: Deploy and manage GitHub MCP servers with a single command - **🔧 Dynamic Tool Discovery**: Automatically discover and catalog all 77+ available GitHub tools - **📊 Comprehensive Monitoring**: Built-in logging, status monitoring, and error tracking - **🔄 Auto-Scaling**: Docker-based deployment with automatic container management - **⚙️ Configuration Management**: Simplified environment variable and secret management - **🛡️ Security**: Secure token handling and access control - **📈 Performance Optimization**: Efficient caching and connection pooling ## Available Tools (77 Total) The GitHub MCP server provides comprehensive GitHub API access through 77 specialized tools organized by functionality: ### Repository Management - **`create_repository`**: Create new GitHub repositories - **`fork_repository`**: Fork repositories to your account or organization - **`search_repositories`**: Search for GitHub repositories - **`get_file_contents`**: Read file contents from repositories - **`create_or_update_file`**: Create or update files in repositories - **`delete_file`**: Delete files from repositories - **`push_files`**: Push multiple files in a single commit ### Branch & Tag Management - **`create_branch`**: Create new branches - **`list_branches`**: List all repository branches - **`get_tag`**: Get git tag details - **`list_tags`**: List all repository tags - **`get_commit`**: Get commit details - **`list_commits`**: List repository commits ### Issue Management - **`create_issue`**: Create new issues - **`get_issue`**: Get issue details - **`update_issue`**: Update existing issues - **`list_issues`**: List repository issues - **`search_issues`**: Search issues across repositories - **`add_issue_comment`**: Add comments to issues - **`get_issue_comments`**: Get issue comments - **`add_sub_issue`**: Add sub-issues to parent issues - **`list_sub_issues`**: List sub-issues for an issue - **`remove_sub_issue`**: Remove sub-issues - **`reprioritize_sub_issue`**: Reorder sub-issues ### Pull Request Management - **`create_pull_request`**: Create new pull requests - **`get_pull_request`**: Get pull request details - **`update_pull_request`**: Update existing pull requests - **`list_pull_requests`**: List repository pull requests - **`search_pull_requests`**: Search pull requests - **`merge_pull_request`**: Merge pull requests - **`get_pull_request_comments`**: Get PR comments - **`get_pull_request_diff`**: Get PR diff - **`get_pull_request_files`**: Get changed files in PR - **`get_pull_request_reviews`**: Get PR reviews - **`get_pull_request_status`**: Get PR status - **`update_pull_request_branch`**: Update PR branch ### Code Review & Comments - **`create_pending_pull_request_review`**: Create pending reviews - **`add_comment_to_pending_pull_request_review`**: Add review comments - **`submit_pending_pull_request_review`**: Submit reviews - **`delete_pending_pull_request_review`**: Delete pending reviews - **`create_and_submit_pull_request_review`**: Create and submit reviews - **`request_copilot_review`**: Request GitHub Copilot reviews - **`assign_copilot_to_issue`**: Assign Copilot to issues ### GitHub Actions & Workflows - **`list_workflows`**: List repository workflows - **`run_workflow`**: Trigger workflow runs - **`get_workflow_run`**: Get workflow run details - **`list_workflow_runs`**: List workflow runs - **`cancel_workflow_run`**: Cancel running workflows - **`rerun_workflow_run`**: Re-run entire workflows - **`rerun_failed_jobs`**: Re-run only failed jobs - **`list_workflow_jobs`**: List workflow jobs - **`get_job_logs`**: Get job logs - **`get_workflow_run_logs`**: Get complete workflow logs - **`get_workflow_run_usage`**: Get workflow usage metrics - **`list_workflow_run_artifacts`**: List workflow artifacts - **`download_workflow_run_artifact`**: Download artifacts - **`delete_workflow_run_logs`**: Delete workflow logs ### Security & Scanning - **`list_code_scanning_alerts`**: List code scanning alerts - **`get_code_scanning_alert`**: Get specific code scanning alerts - **`list_dependabot_alerts`**: List Dependabot alerts - **`get_dependabot_alert`**: Get specific Dependabot alerts - **`list_secret_scanning_alerts`**: List secret scanning alerts - **`get_secret_scanning_alert`**: Get specific secret scanning alerts ### Discussions - **`list_discussions`**: List repository discussions - **`get_discussion`**: Get discussion details - **`get_discussion_comments`**: Get discussion comments - **`list_discussion_categories`**: List discussion categories ### Notifications & Activity - **`list_notifications`**: List GitHub notifications - **`get_notification_details`**: Get notification details - **`dismiss_notification`**: Mark notifications as read - **`mark_all_notifications_read`**: Mark all notifications read - **`manage_notification_subscription`**: Manage notification settings - **`manage_repository_notifications`**: Manage repository notifications ### Search & Discovery - **`search_code`**: Search code across repositories - **`search_users`**: Search GitHub users - **`search_orgs`**: Search GitHub organizations ### User & Profile - **`get_me`**: Get authenticated user details ## Quick Start ### Installation Deploy the GitHub MCP server using our platform: ```bash # Deploy with automatic configuration mcpt deploy github # Deploy with custom configuration mcpt deploy github --config GITHUB_PERSONAL_ACCESS_TOKEN="your_token" # Check deployment status mcpt status github # View real-time logs mcpt logs github ``` ### Configuration The template requires a GitHub Personal Access Token for authentication: | Variable | Description | Required | Default | |----------|-------------|----------|---------| | `GITHUB_PERSONAL_ACCESS_TOKEN` | GitHub Personal Access Token with appropriate scopes | Yes | - | | `LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | No | INFO | #### Creating a GitHub Token 1. Go to GitHub Settings → Developer settings → Personal access tokens 2. Generate a new token with required scopes: - `repo` - Full repository access - `workflow` - GitHub Actions access - `notifications` - Notification access - `security_events` - Security alert access ### Usage Examples #### Repository Operations ```bash # List repository files mcp-client call get_file_contents --owner "octocat" --repo "Hello-World" --path "README.md" # Create a new file mcp-client call create_or_update_file --owner "user" --repo "repo" --path "new_file.py" --content "print('Hello')" --message "Add new file" # Create a new repository mcp-client call create_repository --name "my-new-repo" --description "A new repository" ``` #### Issue Management ```bash # Create an issue mcp-client call create_issue --owner "user" --repo "repo" --title "Bug Report" --body "Found a bug" # Add a comment to an issue mcp-client call add_issue_comment --owner "user" --repo "repo" --issue_number 1 --body "Working on this" # Search for issues mcp-client call search_issues --query "is:open label:bug" ``` #### Pull Request Workflow ```bash # Create a pull request mcp-client call create_pull_request --owner "user" --repo "repo" --title "Feature" --head "feature-branch" --base "main" # Review a pull request mcp-client call create_pending_pull_request_review --owner "user" --repo "repo" --pull_number 1 mcp-client call add_comment_to_pending_pull_request_review --body "Looks good!" mcp-client call submit_pending_pull_request_review --event "APPROVE" ``` #### GitHub Actions ```bash # List workflows mcp-client call list_workflows --owner "user" --repo "repo" # Trigger a workflow mcp-client call run_workflow --owner "user" --repo "repo" --workflow_id "deploy.yml" # Get workflow run logs mcp-client call get_job_logs --owner "user" --repo "repo" --run_id 123456 --failed_only true ``` ## Tool Discovery Our platform provides dynamic tool discovery to automatically catalog all available GitHub tools: ```bash # Discover all available tools mcpt> tools github --config GITHUB_PERSONAL_ACCESS_TOKEN="your_token" # Refresh tool cache mcpt> tools github --refresh # Get detailed tool information mcpt> tools github --verbose ``` ## Platform Benefits ### Enhanced Deployment - **Docker Integration**: Seamless container-based deployment - **Environment Management**: Secure handling of GitHub tokens - **Health Monitoring**: Automatic health checks and restart policies - **Port Management**: Automatic port allocation and management ### Advanced Tooling - **Real-time Discovery**: Dynamic discovery of all 77 GitHub tools - **Intelligent Caching**: Tool information caching for improved performance - **Error Handling**: Robust error handling and retry mechanisms - **Logging**: Comprehensive request/response logging ### Developer Experience - **One-Command Setup**: Deploy GitHub integration in seconds - **Interactive CLI**: Rich terminal interface with progress indicators - **Comprehensive Documentation**: Auto-generated tool documentation - **Testing Integration**: Built-in testing framework for GitHub operations ## Development ### Local Development ```bash # Clone and set up local development git clone <repository-url> cd github-template # Install dependencies pip install -r requirements.txt # Set environment variables export GITHUB_PERSONAL_ACCESS_TOKEN="your_token" export LOG_LEVEL="DEBUG" # Run the server locally python -m server ``` ### Testing ```bash # Run all tests pytest tests/ -v # Run integration tests pytest tests/test_github_integration.py # Test with real GitHub API (requires token) pytest tests/ --github-token="your_token" ``` ### Docker Development ```bash # Build local image docker build -t github-mcp-local . # Run with environment variables docker run -e GITHUB_PERSONAL_ACCESS_TOKEN="your_token" github-mcp-local # Run with our platform mcpt deploy github --local ``` ## Monitoring & Troubleshooting ### Health Checks ```bash # Check service status mcpt status github # Get detailed health information mcpt status github --detailed # View real-time logs mcpt logs github --follow ``` ### Common Issues 1. **Authentication Errors** - Verify GitHub token has correct scopes - Check token expiration date - Ensure token is properly set in environment 2. **Rate Limiting** - GitHub API has rate limits (5000 requests/hour for authenticated users) - Use conditional requests when possible - Consider GitHub Apps for higher limits 3. **Permission Errors** - Verify repository access permissions - Check organization policies - Ensure token has required scopes 4. **Network Issues** - Check GitHub API status at https://www.githubstatus.com/ - Verify network connectivity - Check firewall settings ### Debug Mode Enable comprehensive debugging: ```bash # Deploy with debug logging mcpt deploy github --config LOG_LEVEL="DEBUG" # View debug logs mcpt logs github --level debug # Enable trace logging for API calls mcpt logs github --trace ``` ## Security ### Token Management - **Secure Storage**: Tokens are stored securely and never logged - **Scope Validation**: Automatic validation of token scopes - **Rotation Support**: Easy token rotation without service interruption ### Access Control - **Principle of Least Privilege**: Request only necessary GitHub scopes - **Audit Logging**: All API calls are logged for audit purposes - **Error Sanitization**: Sensitive information is never exposed in error messages ## Performance Optimization ### Caching Strategy - **Tool Discovery Cache**: Cache discovered tools for improved performance - **Response Caching**: Cache frequently accessed GitHub data - **Connection Pooling**: Efficient HTTP connection management ### Rate Limit Management - **Intelligent Throttling**: Automatic rate limit respect - **Request Batching**: Batch compatible requests - **Priority Queuing**: Prioritize critical operations ## API Reference All 77 GitHub tools are available through the MCP interface. Each tool includes: - **Input Schema**: Detailed parameter specifications - **Output Schema**: Response format documentation - **Error Handling**: Comprehensive error response patterns - **Examples**: Real-world usage examples For detailed API documentation of each tool, use: ```bash mcpt> tools github --tool-name <tool_name> --detailed ``` ## Contributing We welcome contributions to improve the GitHub MCP server template: 1. **Bug Reports**: Submit issues with detailed reproduction steps 2. **Feature Requests**: Propose new GitHub integrations 3. **Pull Requests**: Contribute code improvements 4. **Documentation**: Help improve this documentation See the main repository's contributing guidelines for detailed information. ## License This template extends the official GitHub MCP server and is part of the MCP Server Templates project. See LICENSE for details. ## Support For support, please open an issue in the main repository or contact the maintainers.