GitHub MCP Server

Instructions

Implementation Reference

• src/mcp/tools.ts:448-484 (handler)

  Core handler implementation: validates parameters, fetches user's pull request review contributions via GitHub GraphQL API, maps to PRReview objects, filters by repository and excludes auto-generated PRs, paginates results, returns structured array of reviews.

  async getPRReviews(
    username: string,
    repos: string[],
    from?: string,
    to?: string
  ): Promise<{ reviews: PRReview[] }> {
    const { normalizedUsername, normalizedRepos, from: validatedFrom, to: validatedTo } =
      this.validateCommonParameters(username, repos, from, to);
  
    const allReviews = await fetchAllPages(
      async (cursor: string | null) => {
        const response = await this.client.query(QUERIES.PRReviews, {
          username: normalizedUsername,
          from: validateTimestamp(validatedFrom),
          to: validateTimestamp(validatedTo),
          after: cursor,
        });
  
        return response.data;
      },
      (data: any) => {
        const contributions = data.user?.contributionsCollection
          ?.pullRequestReviewContributions?.nodes || [];
        // Filter reviews using shared filter method
        return contributions
          .map(mapPRReview)
          .filter((review: PRReview) => this.filterPRReview(review, normalizedRepos)) as PRReview[];
      },
      (data: any) => {
        const pageInfo = data.user?.contributionsCollection
          ?.pullRequestReviewContributions?.pageInfo || {};
        return extractPageInfo(pageInfo);
      }
    );
  
    return { reviews: allReviews as PRReview[] };
  }

• src/mcp/tools.ts:1171-1208 (schema)

  Tool schema definition including name, detailed description, input schema with properties (username, repos, from, to), examples, and required fields.

      {
        name: 'github.getPRReviews',
        description: `Fetch all PR reviews submitted by a user within a time range, filtered by repository. Returns review state (APPROVED, CHANGES_REQUESTED, COMMENTED), PR details, and submission timestamps. Automatically filters out reviews on auto-generated PRs. Use this tool to assess code review participation and review quality.
  
  Example use cases:
  - Measure code review engagement (how many PRs reviewed)
  - Analyze review patterns (approval vs. change requests)
  - Track review activity over time
  - Assess code review contribution for performance evaluations
  
  Returns: Array of review objects with id, state, prId, prNumber, prTitle, prRepo, submittedAt`,
        inputSchema: {
          type: 'object',
          properties: {
            username: {
              type: 'string',
              description: 'GitHub username (case-insensitive, @ prefix optional, required). Examples: "octocat", "@octocat"',
              examples: ['octocat', '@octocat'],
            },
            repos: {
              type: 'array',
              items: { type: 'string' },
              description: 'Array of repositories in owner/repo format (required, at least one). Only reviews for these repositories will be returned. Example: ["owner/repo1", "owner/repo2"]',
              examples: [['owner/repo'], ['owner/repo1', 'owner/repo2']],
            },
            from: {
              type: 'string',
              description: 'Optional: Start timestamp in ISO 8601 format. If omitted, uses last 3 months. Example: "2024-01-01T00:00:00Z"',
              examples: ['2024-01-01T00:00:00Z'],
            },
            to: {
              type: 'string',
              description: 'Optional: End timestamp in ISO 8601 format. If omitted, uses last 3 months. Example: "2024-12-31T23:59:59Z"',
              examples: ['2024-12-31T23:59:59Z'],
            },
          },
          required: ['username', 'repos'],
        },

• src/mcp/server.ts:78-93 (registration)

  Tool dispatch registration in MCP server request handler: calls GitHubTools.getPRReviews with parsed arguments and formats result as MCP text content response.

  case 'github.getPRReviews': {
    const result = await tools.getPRReviews(
      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:278-291 (helper)

  Helper function used by getPRReviews to filter reviews: excludes reviews on auto-created PRs (e.g., backmerges) and ensures repository match.

  private filterPRReview(review: PRReview, normalizedRepos: string[]): boolean {
    // Filter out reviews on auto-created PRs
    if (this.isAutoCreatedPR(review.prTitle)) {
      return false;
    }
  
    // Filter by repository (must match one of the provided repos)
    const reviewRepo = review.prRepo?.toLowerCase();
    if (!reviewRepo || !normalizedRepos.includes(reviewRepo)) {
      return false;
    }
  
    return true;
  }