GitHub MCP Server

Instructions

Implementation Reference

• src/mcp/tools.ts:312-432 (handler)

  Core handler implementation for the github.getAuthoredPRs tool. Validates inputs, performs GitHub GraphQL search for PR IDs, fetches detailed PR data in batches, applies filters (time range, repository, auto-generated PRs), maps to AuthoredPR format, and returns the results.
  async getAuthoredPRs( username: string, repos: string[], from?: string, to?: string ): Promise<{ prs: AuthoredPR[] }> { // Validate inputs const { normalizedUsername, normalizedRepos, from: validatedFrom, to: validatedTo } = this.validateCommonParameters(username, repos, from, to); // Format dates for GitHub search (YYYY-MM-DD format) const fromDate = new Date(validatedFrom).toISOString().split('T')[0]; const toDate = new Date(validatedTo).toISOString().split('T')[0]; // Build search query // GitHub search syntax: is:pr created:YYYY-MM-DD..YYYY-MM-DD author:username // Note: GitHub search uses inclusive date ranges // GitHub search supports multiple repo: filters const repoFilters = normalizedRepos.map(repo => `repo:${repo}`).join(' '); let searchQuery = `is:pr created:${fromDate}..${toDate} author:${normalizedUsername} ${repoFilters}`; // Two-step approach: get PR IDs from search, then fetch full details by ID // This avoids issues with null nodes in search results for private org repos // Step 1: Collect all PR IDs from search const prIds: string[] = []; await fetchAllPages( async (cursor: string | null) => { const response = await this.client.query(QUERIES.AUTHoredPRsSearch, { searchQuery: searchQuery, after: cursor, }); return response.data; }, (data: any) => { const searchData = data.search || {}; const nodes = searchData.nodes || []; // Extract PR IDs (filter out null nodes) for (const node of nodes) { if (node && node.id && node.__typename === 'PullRequest') { prIds.push(node.id); } } return []; // Return empty array since we're collecting IDs in closure }, (data: any) => { const searchData = data.search || {}; return extractPageInfo(searchData.pageInfo || {}); } ); if (prIds.length === 0) { return { prs: [] }; } // Step 2: Fetch full PR details by ID (batch in groups of 100, GitHub's limit) const batchSize = 100; const allPRs: any[] = []; for (let i = 0; i < prIds.length; i += batchSize) { const batch = prIds.slice(i, i + batchSize); const response = await this.client.query(QUERIES.AUTHoredPRsDetails, { prIds: batch, }); const nodes = response.data.nodes || []; // Filter out null nodes and collect PRs for (const node of nodes) { if (node && node.id) { allPRs.push(node); } } } // Step 3: Filter and map PRs (apply time range filter and repository filter) const fromTime = new Date(validatedFrom).getTime(); const toTime = new Date(validatedTo).getTime(); const validPRs = allPRs .filter((node: any) => { // All nodes from Step 2 should already be PRs with full data // Just apply time range and repository filters if (!node.id || !node.repository) { return false; } // Apply time range filter (createdAt should already be in range from search, but double-check) const createdAt = new Date(node.createdAt).getTime(); if (createdAt < fromTime || createdAt > toTime) { return false; } // Apply repository filter const repoName = node.repository.nameWithOwner.toLowerCase(); if (!normalizedRepos.some(repo => repo === repoName)) { return false; } // Filter out auto-created PRs (e.g., backmerge PRs) if (this.isAutoCreatedPR(node.title)) { return false; } return true; }) .map((node: any) => { try { return mapAuthoredPR(node); } catch (error: any) { console.error(`[Error] Failed to map PR node:`, error.message); return null; } }) .filter((pr: any) => pr !== null) as AuthoredPR[]; return { prs: validPRs }; }
• src/mcp/server.ts:61-76 (registration)

  MCP server request handler registration for github.getAuthoredPRs. Dispatches tool calls to the GitHubTools.getAuthoredPRs method and formats the response as MCP content.
  case 'github.getAuthoredPRs': { const result = await tools.getAuthoredPRs( args.username as string, args.repos as string[], args.from as string | undefined, args.to as string | undefined ); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; }
• src/mcp/tools.ts:1132-1170 (schema)

  Tool schema definition including name, description, inputSchema with properties (username, repos, from, to), required fields, and examples for github.getAuthoredPRs.
  { name: 'github.getAuthoredPRs', description: `Fetch all pull requests authored by a given user within a time range. Returns PRs with metadata including state (OPEN/MERGED/CLOSED), creation/merge dates, code statistics (files changed, additions, deletions), and repository information. Optionally filter by specific repositories. Automatically filters out auto-generated PRs (e.g., backmerge PRs). Use this tool to analyze a user's code contribution activity. Example use cases: - Assess developer productivity by counting PRs authored in a time period - Analyze code contribution trends over time - Get detailed metrics for performance reviews - Track PR merge rates and code change statistics Returns: Array of PR objects with id, repo, title, createdAt, mergedAt, state, filesChanged, additions, deletions`, inputSchema: { type: 'object', properties: { username: { type: 'string', description: 'GitHub username (case-insensitive, @ prefix optional). Examples: "octocat", "@octocat", "JohnDoe"', examples: ['octocat', '@octocat'], }, repos: { type: 'array', items: { type: 'string' }, description: 'Array of repositories in owner/repo format (required, at least one). Example: ["owner/repo1", "owner/repo2"]', examples: [['owner/repo'], ['owner/repo1', 'owner/repo2']], }, from: { type: 'string', description: 'Optional: Start timestamp in ISO 8601 format. Must be before "to" parameter if provided. If omitted, uses last 3 months. Example: "2024-01-01T00:00:00Z"', examples: ['2024-01-01T00:00:00Z', '2024-06-01T00:00:00Z'], }, to: { type: 'string', description: 'Optional: End timestamp in ISO 8601 format. Must be after "from" parameter if provided. If omitted, uses last 3 months. Example: "2024-12-31T23:59:59Z"', examples: ['2024-12-31T23:59:59Z', '2024-06-30T23:59:59Z'], }, }, required: ['username', 'repos'], }, },
• src/mcp/tools.ts:165-181 (helper)

  Shared validation helper used by getAuthoredPRs and other tools for common parameters (username, repos, time range).
  private validateCommonParameters( username: string, repos: string[], from?: string, to?: string ): { normalizedUsername: string; normalizedRepos: string[]; from: string; to: string } { const normalizedUsername = this.validateUsernameParameter(username); const normalizedRepos = this.validateReposParameter(repos); const timeRange = this.validateTimeRangeParameters(from, to); return { normalizedUsername, normalizedRepos, from: timeRange.from, to: timeRange.to }; }
• src/mcp/tools.ts:208-212 (helper)

  Helper function to filter out auto-created PRs (e.g., backmerge PRs) used in getAuthoredPRs filtering logic.
  private isAutoCreatedPR(prTitle: string | null | undefined): boolean { if (!prTitle) return false; const title = prTitle.trim(); return title.toLowerCase().startsWith('backmerge:'); }