search
Read-only
Find beginner-friendly open-source issues on GitHub matching your programming languages and interests to start contributing.
Instructions
Search GitHub for beginner-friendly open-source issues to contribute to. Returns issues matching configured languages and interests.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of issues to return (default: 5) |
Implementation Reference
- The core handler logic for the 'search' tool. It initializes IssueDiscovery with a GitHub token and fetches search results based on the provided options.
export async function runSearch(options: SearchOptions): Promise<SearchOutput> { const token = requireGitHubToken(); const discovery = new IssueDiscovery(token); const candidates = await discovery.searchIssues({ maxResults: options.maxResults }); const stateManager = getStateManager(); const { config } = stateManager.getState(); const excludedRepos = config.excludeRepos || []; const aiPolicyBlocklist = config.aiPolicyBlocklist ?? DEFAULT_CONFIG.aiPolicyBlocklist ?? []; const searchOutput: SearchOutput = { candidates: candidates.map((c) => { const repoScoreRecord = stateManager.getRepoScore(c.issue.repo); return { issue: { repo: c.issue.repo, repoUrl: `https://github.com/${c.issue.repo}`, number: c.issue.number, title: c.issue.title, url: c.issue.url, labels: c.issue.labels, }, recommendation: c.recommendation, reasonsToApprove: c.reasonsToApprove, reasonsToSkip: c.reasonsToSkip, searchPriority: c.searchPriority, viabilityScore: c.viabilityScore, repoScore: repoScoreRecord ? { score: repoScoreRecord.score, mergedPRCount: repoScoreRecord.mergedPRCount, closedWithoutMergeCount: repoScoreRecord.closedWithoutMergeCount, isResponsive: repoScoreRecord.signals?.isResponsive ?? false, lastMergedAt: repoScoreRecord.lastMergedAt, } : undefined, }; }), excludedRepos, aiPolicyBlocklist, }; if (discovery.rateLimitWarning) { searchOutput.rateLimitWarning = discovery.rateLimitWarning; } return searchOutput; } - packages/mcp-server/src/tools.ts:92-114 (registration)The MCP tool registration for the 'search' command, which includes input validation for maxResults and wraps the call to the search handler.
// 3. search — Search for contributable issues server.registerTool( 'search', { description: 'Search GitHub for beginner-friendly open-source issues to contribute to. Returns issues matching configured languages and interests.', inputSchema: { maxResults: z.number().optional().describe('Maximum number of issues to return (default: 5)'), }, annotations: { readOnlyHint: true }, }, wrapTool((args: { maxResults?: number }) => { const MAX_SEARCH_RESULTS = 100; let maxResults = args.maxResults ?? 5; if (!Number.isInteger(maxResults) || maxResults < 1) { throw new Error(`Invalid maxResults: ${maxResults}. Must be a positive integer.`); } if (maxResults > MAX_SEARCH_RESULTS) { maxResults = MAX_SEARCH_RESULTS; } return runSearch({ maxResults }); }), );