[mcp-tools] GitHub MCP Remote Server Tools Report - 2025-11-09

[github-actions[bot]]

GitHub MCP Remote Server Tools Report

Generated: 2025-11-09
MCP Mode: Remote
Toolsets: All
Previous Report: None (first run)

Executive Summary

This report provides a comprehensive inventory of all tools available in the GitHub MCP (Model Context Protocol) Remote Server. The GitHub MCP server provides AI agents with programmatic access to GitHub's API through the Model Context Protocol.

Key Findings:

• Total Tools Discovered: 72 tools
• Toolset Categories: 19 toolsets
• JSON Mapping Status: ✅ Accurate and up-to-date
• Recommended Default Toolsets: context, repos, issues, pull_requests, users

Full Report Details

Inconsistency Detection

Toolset Integrity Checks

During the systematic exploration of all 19 toolsets, the following analysis was performed:

✅ Intentional Duplicate Tools (Design Pattern)

The following tools appear in multiple toolsets by design - they exist in both their domain-specific toolset and the consolidated search toolset:

Tool Name	Toolsets	Rationale
search_issues	issues, search	Domain-specific search in issues, plus consolidated search
search_orgs	orgs, search	Domain-specific search in orgs, plus consolidated search
search_pull_requests	pull_requests, search	Domain-specific search in PRs, plus consolidated search
search_repositories	repos, search	Domain-specific search in repos, plus consolidated search
search_users	users, search	Domain-specific search in users, plus consolidated search

This duplication is intentional and supports two usage patterns:

1. Focused workflows: Use domain toolsets (e.g., issues for issue management + issue search)
2. Search-heavy workflows: Use the search toolset for comprehensive search capabilities

✅ No Detected Issues

• ✅ No miscategorized tools
• ✅ No naming inconsistencies
• ✅ No orphaned tools
• ✅ All tools properly categorized by functionality

JSON Mapping Comparison

Discrepancies Between MCP Server and JSON Mapping

Compared the actual MCP server tools with the toolset mapping in pkg/workflow/data/github_toolsets_permissions.json:

Summary:

• Total Discrepancies: 0
• Missing Tools (in JSON but not in MCP): 0
• Extra Tools (in MCP but not in JSON): 0
• Moved Tools (different toolset): 0

✅ JSON mapping is accurate and matches the MCP server perfectly.

No updates to the JSON mapping file were needed.

Changes Since Last Report

This is the first run of the GitHub MCP Tools Report, so there is no previous data to compare against. Future runs will track:

• New tools added
• Removed tools
• Tools moved between toolsets

A cache file has been created at /tmp/gh-aw/cache-memory/github-mcp-tools.json to enable change tracking in future reports.

Tools by Toolset

Context Toolset (6 tools)

Tools for getting user and environment context:

Tool Name	Purpose	Key Parameters
get_copilot_space	Get details of a specific Copilot space	owner, name
get_me	Get details of the authenticated GitHub user	None
get_team_members	Get member usernames of a specific team	org, team_slug
get_teams	Get teams the user is a member of	user (optional)
github_support_docs_search	Search GitHub support documentation	query
list_copilot_spaces	List Copilot Spaces accessible to the user	None

Repos Toolset (10 tools)

Tools for repository operations:

Tool Name	Purpose	Key Parameters
get_commit	Get details for a commit from a repository	owner, repo, sha
get_file_contents	Get contents of a file or directory	owner, repo, path
get_latest_release	Get the latest release in a repository	owner, repo
get_release_by_tag	Get a specific release by tag name	owner, repo, tag
get_tag	Get details about a specific git tag	owner, repo, tag
list_branches	List branches in a repository	owner, repo
list_commits	Get list of commits of a branch	owner, repo, sha
list_releases	List releases in a repository	owner, repo
list_tags	List git tags in a repository	owner, repo
search_repositories	Find repositories by name, description, or metadata	query, sort, order

Issues Toolset (4 tools)

Tools for issue management:

Tool Name	Purpose	Key Parameters
issue_read	Get information about a specific issue (supports multiple methods)	owner, repo, issue_number, method
list_issue_types	List supported issue types for repository owner	owner
list_issues	List issues in a repository	owner, repo, state, labels
search_issues	Search for issues using search syntax	query, sort, order

Note: issue_read supports multiple methods: get, get_comments, get_sub_issues, get_labels

Pull Requests Toolset (3 tools)

Tools for pull request operations:

Tool Name	Purpose	Key Parameters
list_pull_requests	List pull requests in a repository	owner, repo, state, base, head
pull_request_read	Get information on a specific pull request (supports multiple methods)	owner, repo, pullNumber, method
search_pull_requests	Search for pull requests using search syntax	query, sort, order

Note: pull_request_read supports multiple methods: get, get_diff, get_status, get_files, get_review_comments, get_reviews, get_comments

Actions Toolset (9 tools)

Tools for GitHub Actions workflows and CI/CD:

Tool Name	Purpose	Key Parameters
download_workflow_run_artifact	Get download URL for a workflow run artifact	owner, repo, artifact_id
get_job_logs	Download logs for a workflow job or all failed job logs	owner, repo, job_id or run_id with failed_only
get_workflow_run	Get details of a specific workflow run	owner, repo, run_id
get_workflow_run_logs	Download logs for a workflow run (expensive)	owner, repo, run_id
get_workflow_run_usage	Get usage metrics for a workflow run	owner, repo, run_id
list_workflow_jobs	List jobs for a specific workflow run	owner, repo, run_id
list_workflow_run_artifacts	List artifacts for a workflow run	owner, repo, run_id
list_workflow_runs	List workflow runs for a specific workflow	owner, repo, workflow_id
list_workflows	List workflows in a repository	owner, repo

Code Security Toolset (2 tools)

Tools for code scanning alerts:

Tool Name	Purpose	Key Parameters
get_code_scanning_alert	Get details of a specific code scanning alert	owner, repo, alertNumber
list_code_scanning_alerts	List code scanning alerts in a repository	owner, repo, state, severity

Dependabot Toolset (2 tools)

Tools for Dependabot alerts:

Tool Name	Purpose	Key Parameters
get_dependabot_alert	Get details of a specific dependabot alert	owner, repo, alertNumber
list_dependabot_alerts	List dependabot alerts in a repository	owner, repo, state, severity

Discussions Toolset (4 tools)

Tools for GitHub Discussions:

Tool Name	Purpose	Key Parameters
get_discussion	Get a specific discussion by ID	owner, repo, discussionNumber
get_discussion_comments	Get comments from a discussion	owner, repo, discussionNumber
list_discussion_categories	List discussion categories with their id and name	owner, repo (optional)
list_discussions	List discussions for a repository or organisation	owner, repo (optional), category

Experiments Toolset (0 tools)

The experiments toolset is defined but currently contains no tools. This toolset is reserved for experimental/preview features.

Gists Toolset (1 tool)

Tools for gist operations:

Tool Name	Purpose	Key Parameters
list_gists	List gists for a user	username (optional)

Labels Toolset (2 tools)

Tools for label management:

Tool Name	Purpose	Key Parameters
get_label	Get a specific label from a repository	owner, repo, name
list_label	List labels from a repository	owner, repo

Notifications Toolset (2 tools)

Tools for notification management:

Tool Name	Purpose	Key Parameters
get_notification_details	Get detailed information for a specific notification	notificationID
list_notifications	List all GitHub notifications for the authenticated user	filter, owner, repo

Orgs Toolset (2 tools)

Tools for organization operations:

Tool Name	Purpose	Key Parameters
list_org_repository_security_advisories	List repository security advisories for an organization	org, state, sort
search_orgs	Find GitHub organizations by name or metadata	query, sort, order

Projects Toolset (6 tools)

Tools for GitHub Projects:

Tool Name	Purpose	Key Parameters
get_project	Get Project for a user or org	owner, owner_type, project_number
get_project_field	Get Project field for a user or org	owner, owner_type, project_number, field_id
get_project_item	Get a specific Project item	owner, owner_type, project_number, item_id
list_project_fields	List Project fields for a user or org	owner, owner_type, project_number
list_project_items	List Project items for a user or org	owner, owner_type, project_number
list_projects	List Projects for a user or org	owner, owner_type

Secret Protection Toolset (2 tools)

Tools for secret scanning:

Tool Name	Purpose	Key Parameters
get_secret_scanning_alert	Get details of a specific secret scanning alert	owner, repo, alertNumber
list_secret_scanning_alerts	List secret scanning alerts in a repository	owner, repo, state, resolution

Security Advisories Toolset (3 tools)

Tools for security advisories:

Tool Name	Purpose	Key Parameters
get_global_security_advisory	Get a global security advisory	ghsaId
list_global_security_advisories	List global security advisories from GitHub	ecosystem, severity, cveId
list_repository_security_advisories	List repository security advisories	owner, repo, state, sort

Stargazers Toolset (1 tool)

Tools for repository stars:

Tool Name	Purpose	Key Parameters
list_starred_repositories	List starred repositories	username (optional), sort, direction

Users Toolset (1 tool)

Tools for user information:

Tool Name	Purpose	Key Parameters
search_users	Find GitHub users by username or profile information	query, sort, order

Search Toolset (6 tools)

Consolidated search tools across all GitHub resources:

Tool Name	Purpose	Key Parameters
search_code	Fast code search across ALL GitHub repositories	query, sort, order
search_issues	Search for issues using GitHub search syntax	query, sort, order
search_orgs	Find GitHub organizations	query, sort, order
search_pull_requests	Search for pull requests	query, sort, order
search_repositories	Find GitHub repositories	query, sort, order
search_users	Find GitHub users	query, sort, order

Note: Search tools also appear in their respective domain toolsets. This is intentional to support both focused workflows (using domain toolsets) and search-heavy workflows (using the search toolset).

Recommended Default Toolsets

Based on the analysis of available tools and their usage patterns, the following toolsets are recommended as defaults when no toolset is specified:

Recommended Defaults: context, repos, issues, pull_requests, users

Rationale:

1. context - Essential for understanding the GitHub environment

   • Provides user identity, team memberships, and environment context
   • Required for permission-aware operations
   • Minimal security exposure (read-only user context)

2. repos - Fundamental repository operations

   • Core functionality for reading files, commits, releases
   • Most workflows involve repository interactions
   • Covers the majority of read-only repository needs

3. issues - Critical for issue tracking

   • Issue management is central to most GitHub workflows
   • Includes issue search for cross-repository queries
   • Frequently used alongside pull requests

4. pull_requests - Essential for code review workflows

   • PR operations are fundamental to collaborative development
   • Includes PR diff, reviews, and comments
   • Pairs naturally with issues and repos toolsets

5. users - Useful for finding contributors

   • User search is commonly needed across workflows
   • Helps identify team members and contributors
   • Lightweight with minimal security implications

Specialized Toolsets (enable explicitly when needed):

• actions - For CI/CD workflow analysis and debugging
• discussions - For GitHub Discussions workflows
• projects - For GitHub Projects management
• labels - For label management (commonly used with issues/PRs)
• notifications - For notification workflows
• Security toolsets - For security-focused workflows
• search - For search-heavy workflows (domain searches already in defaults)

Toolset Configuration Reference

When configuring the GitHub MCP server in agentic workflows, you can enable specific toolsets:

tools:
  github:
    mode: "remote"  # or "local"
    toolsets: [default]  # or specific toolsets like [repos, issues, pull_requests]

Available toolset options:

• context - GitHub Actions context and environment
• repos - Repository operations
• issues - Issue management
• pull_requests - Pull request operations
• actions - GitHub Actions workflows
• code_security - Code scanning alerts
• dependabot - Dependabot alerts
• discussions - GitHub Discussions
• experiments - Experimental features
• gists - Gist operations
• labels - Label management
• notifications - Notification management
• orgs - Organization operations
• projects - GitHub Projects
• secret_protection - Secret scanning
• security_advisories - Security advisories
• stargazers - Repository stars
• users - User information
• search - Advanced search
• default - Enable recommended default toolsets
• all - Enable all toolsets

Notes and Observations

Tool Design Patterns

1. Multi-method Tools: Some tools like issue_read and pull_request_read support multiple methods, providing a single entry point for various operations (e.g., getting issue details, comments, labels).

2. Search Tool Duplication: Search tools intentionally appear in both domain toolsets and the consolidated search toolset to support different workflow patterns.

3. Empty Experiments Toolset: The experiments toolset exists but contains no tools, suggesting it's reserved for future experimental features.

Tool Count Distribution

• High concentration: repos (10 tools), actions (9 tools) - reflects complexity of these domains
• Medium concentration: context (6 tools), projects (6 tools), discussions (4 tools), issues (4 tools)
• Low concentration: Most security and utility toolsets (1-3 tools each)
• Search consolidation: 6 tools in the search toolset consolidate all search capabilities

Authentication and Permissions

Different toolsets require different GitHub token permissions:

• Core toolsets (repos, issues, pull_requests) require basic repository permissions
• Security toolsets require security-events scope
• Actions toolset requires actions scope
• Projects toolset requires repository-projects scope

Methodology

• Discovery Method: Self-inspection of available tools in the GitHub MCP remote server
• MCP Configuration: Remote mode with all toolsets enabled
• Categorization: Based on GitHub API domains and functionality
• Documentation: Derived from tool names, descriptions, and parameter schemas
• Validation: Cross-referenced with pkg/workflow/data/github_toolsets_permissions.json

Next Steps

Future reports will include:

1. Change Tracking: Comparison with previous runs to identify new/removed/moved tools
2. Usage Analytics: If available, statistics on which tools are most frequently used
3. Deprecation Notices: Alerts for tools scheduled for removal
4. New Feature Highlights: Emphasis on newly added capabilities

---

Documentation Updated:

• ✅ Created comprehensive documentation at .github/instructions/github-mcp-server.instructions.md
• ✅ Documented all 72 tools across 19 toolsets with parameters and usage examples
• ✅ Confirmed recommended default toolsets: context, repos, issues, pull_requests, users
• ✅ Included best practices for toolset selection and token permissions

Cache Created:

• ✅ Saved current tool inventory to /tmp/gh-aw/cache-memory/github-mcp-tools.json for future change tracking

AI generated by GitHub MCP Remote Server Tools Report Generator

[github-actions[bot]]

This discussion was automatically closed because it was created by an agentic workflow more than 1 week ago.