Search & Discovery
Relevant source files
The following files were used as context for generating this wiki page:
The Search & Discovery system within the GitHub MCP Server provides a comprehensive set of tools for querying GitHub's vast ecosystem. It enables Model Context Protocol (MCP) clients to programmatically find repositories, code, users, organizations, issues, and discussions. This system acts as the primary interface for "discovery" tasks, allowing agents to locate relevant resources before performing specific operations on them.
The architecture leverages both GitHub's REST API (via go-github) and GraphQL API (via githubv4) to provide flexible search capabilities. Tools are designed to support advanced search syntax, pagination, and configurable output levels (minimal vs. full) to optimize token usage for LLM-based clients.
Sources: pkg/github/search.go:1-25, pkg/github/discussions.go:1-30, cmd/mcpcurl/README.md:1-20
Core Search Capabilities
The system exposes specialized tools for different GitHub entities. Each search tool follows a consistent pattern: taking a query string, optional sorting/ordering parameters, and pagination options.
Repository Discovery
The search_repositories tool allows users to find repositories using metadata such as names, descriptions, README content, and topics. It supports a minimal_output flag which, when enabled, returns a stripped-down MinimalRepository structure to reduce payload size.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Advanced search syntax (e.g., stars:>1000 language:python) |
minimal_output | boolean | No | If true (default), returns reduced metadata |
page | integer | No | Results page number |
perPage | integer | No | Results per page |
Sources: pkg/github/search.go:14-35, pkg/github/search_test.go:48-65
Code and Technical Search
The search_code tool provides access to GitHub's native code search engine. It is optimized for finding specific symbols, functions, classes, or patterns across repositories. Results include file paths, SHAs, and repository context.
Sources: pkg/github/search.go:124-140, pkg/github/search_test.go:195-215
Identity Discovery (Users & Organizations)
Identity search is handled by search_users and search_orgs. Both tools utilize a shared internal handler userOrOrgHandler that automatically applies account-type scoping (e.g., appending type:user or type:org to the query) if not already present in the user's query string.
Sources: pkg/github/search.go:174-210, pkg/github/search_test.go:343-360
Discussion & Category Discovery
Unlike standard entity search, Discussion discovery utilizes GitHub's GraphQL API to provide granular filtering and category-level navigation.
GraphQL Query Architecture
The discovery logic for discussions is implemented using a dynamic query selection mechanism. Based on the presence of a categoryID and whether ordering is requested, the system selects from four predefined GraphQL structures.
The query selection logic ensures that only the necessary GraphQL fragments are requested, optimizing API performance.
Sources: pkg/github/discussions.go:68-85, pkg/github/discussions.go:153-175
Categories and Organization-Level Discovery
The list_discussion_categories tool enables discovery of available discussion types (e.g., Announcements, General, Q&A). If a repository is not specified, the system defaults to querying the .github repository, which effectively discovers discussions and categories at the organization level.
Sources: pkg/github/discussions.go:300-325, pkg/github/discussions.go:338-345
Data Flow and API Integration
The following sequence diagram illustrates how a search request is processed, from parameter validation to data transformation.
This flow highlights the internal transformation logic that converts verbose GitHub API responses into agent-friendly formats.
Sources: pkg/github/search.go:42-105, pkg/github/search_test.go:102-120
Search Logic for Issues and Pull Requests
Search for Issues and Pull Requests often shares the same underlying API endpoint (/search/issues). The MCP server provides distinct tools but uses similar query scoping logic.
| Tool Name | Scoping Applied | Description |
|---|---|---|
search_issues | is:issue | Searches only for issues across repositories |
search_pull_requests | is:pr | Searches only for PRs across repositories |
Tests confirm that the tools correctly handle "query duplication" by ensuring filters like is:pr or repo:owner/repo are not added twice if already present in the user-provided query.
Sources: pkg/github/issues_test.go:275-310, pkg/github/pullrequests_test.go:485-515
Technical Summary
The Search & Discovery system provides a robust discovery layer by:
- Synthesizing APIs: Combining REST and GraphQL for entity-specific optimizations.
- Scoping Safety: Automatically applying
typefilters to prevent mixed-entity results in identity searches. - Efficiency: Offering
minimal_outputmodes to preserve context window space for LLM clients. - Flexibility: Supporting advanced GitHub search syntax natively within the
queryparameters.
Sources: pkg/github/search.go:17-40, pkg/github/discussions.go:110-130