feat: implement cursor-based pagination for get_file_blame tool

Author: MayorFaj

README.md

@@ -1225,9 +1225,9 @@ The following sets of tools are available:
 
 - **get_file_blame** - Get file blame information
   - **Required OAuth Scopes**: `repo`
+  - `after`: Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs. (string, optional)
   - `end_line`: Optional 1-based ending line of the window of interest. Must be >= start_line when both are provided. (number, optional)
   - `owner`: Repository owner (username or organization) (string, required)
-  - `page`: Page number for pagination (min 1) (number, optional)
   - `path`: Path to the file in the repository, relative to the repository root (string, required)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `ref`: Git reference (branch, tag, or commit SHA). Defaults to the repository's default branch (HEAD). (string, optional)

pkg/github/__toolsnaps__/get_file_blame.snap

@@ -3,9 +3,13 @@
     "readOnlyHint": true,
     "title": "Get file blame information"
   },
-  "description": "Get git blame information for a file, showing the commit that last modified each line. Ranges share commit metadata via the top-level 'commits' map keyed by SHA. Use 'start_line'/'end_line' to restrict the result to a window of the file, and 'page'/'perPage' to page through returned ranges. Matching ranges are capped at 1000; when the cap is hit 'truncated' is set to true and 'total_ranges' reports the pre-cap match count.",
+  "description": "Get git blame information for a file, showing the commit that last modified each line. Ranges share commit metadata via the top-level 'commits' map keyed by SHA. Use 'start_line'/'end_line' to restrict the result to a window of the file, and 'perPage'/'after' to cursor-page through returned ranges. Matching ranges are capped at 1000; when the cap is hit 'truncated' is set to true and 'total_ranges' reports the pre-cap match count.",
   "inputSchema": {
     "properties": {
+      "after": {
+        "description": "Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs.",
+        "type": "string"
+      },
       "end_line": {
         "description": "Optional 1-based ending line of the window of interest. Must be \u003e= start_line when both are provided.",
         "minimum": 1,
@@ -15,11 +19,6 @@
         "description": "Repository owner (username or organization)",
         "type": "string"
       },
-      "page": {
-        "description": "Page number for pagination (min 1)",
-        "minimum": 1,
-        "type": "number"
-      },
       "path": {
         "description": "Path to the file in the repository, relative to the repository root",
         "type": "string"

pkg/github/repositories.go

@@ -8,6 +8,7 @@ import (
 	"io"
 	"net/http"
 	"slices"
+	"strconv"
 	"strings"
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
@@ -2208,6 +2209,35 @@ func UnstarRepository(t translations.TranslationHelperFunc) inventory.ServerTool
 // maxBlameRanges caps the number of matching blame ranges considered for one response.
 const maxBlameRanges = 1000
 
+const blameCursorPrefix = "blame-range:"
+
+func encodeBlameCursor(offset int) string {
+	return base64.RawURLEncoding.EncodeToString(fmt.Appendf(nil, "%s%d", blameCursorPrefix, offset))
+}
+
+func decodeBlameCursor(cursor string) (int, error) {
+	if cursor == "" {
+		return 0, nil
+	}
+
+	decoded, err := base64.RawURLEncoding.DecodeString(cursor)
+	if err != nil {
+		return 0, fmt.Errorf("after cursor is invalid")
+	}
+
+	value := string(decoded)
+	if !strings.HasPrefix(value, blameCursorPrefix) {
+		return 0, fmt.Errorf("after cursor is invalid")
+	}
+
+	offset, err := strconv.Atoi(strings.TrimPrefix(value, blameCursorPrefix))
+	if err != nil || offset < 0 {
+		return 0, fmt.Errorf("after cursor is invalid")
+	}
+
+	return offset, nil
+}
+
 // BlameAuthor describes the author of a commit referenced by a BlameRange.
 type BlameAuthor struct {
 	Name  string  `json:"name"`
@@ -2238,14 +2268,15 @@ type BlameRange struct {
 
 // BlameResult is the response payload returned by the get_file_blame tool.
 //
-// Commits is keyed by SHA. TotalRanges counts matching ranges before
+// Commits is keyed by SHA. TotalRanges counts matching ranges before cursor
 // pagination or truncation. Truncated reports whether maxBlameRanges was hit.
 type BlameResult struct {
 	Repository  string                 `json:"repository"`
 	Path        string                 `json:"path"`
 	Ref         string                 `json:"ref"`
 	Ranges      []BlameRange           `json:"ranges"`
 	Commits     map[string]BlameCommit `json:"commits"`
+	PageInfo    MinimalPageInfo        `json:"pageInfo"`
 	TotalRanges int                    `json:"total_ranges"`
 	Truncated   bool                   `json:"truncated,omitempty"`
 }
@@ -2279,14 +2310,14 @@ func GetFileBlame(t translations.TranslationHelperFunc) inventory.ServerTool {
 				"Get git blame information for a file, showing the commit that last modified each line. "+
 					"Ranges share commit metadata via the top-level 'commits' map keyed by SHA. "+
 					"Use 'start_line'/'end_line' to restrict the result to a window of the file, and "+
-					"'page'/'perPage' to page through returned ranges. Matching ranges are capped at "+
+					"'perPage'/'after' to cursor-page through returned ranges. Matching ranges are capped at "+
 					"1000; when the cap is hit 'truncated' is set to true and 'total_ranges' reports the pre-cap match count.",
 			),
 			Annotations: &mcp.ToolAnnotations{
 				Title:        t("TOOL_GET_FILE_BLAME_USER_TITLE", "Get file blame information"),
 				ReadOnlyHint: true,
 			},
-			InputSchema: WithPagination(&jsonschema.Schema{
+			InputSchema: WithCursorPagination(&jsonschema.Schema{
 				Type: "object",
 				Properties: map[string]*jsonschema.Schema{
 					"owner": {
@@ -2359,25 +2390,26 @@ func GetFileBlame(t translations.TranslationHelperFunc) inventory.ServerTool {
 			if hasStartLine && hasEndLine && endLine < startLine {
 				return utils.NewToolResultError("end_line must be >= start_line when both are provided"), nil, nil
 			}
-			page := 1
 			if _, hasPage := args["page"]; hasPage {
-				page, err = OptionalIntParam(args, "page")
-				if err != nil {
-					return utils.NewToolResultError(err.Error()), nil, nil
-				}
-				if page < 1 {
-					return utils.NewToolResultError("page must be >= 1 when provided"), nil, nil
-				}
+				return utils.NewToolResultError("This tool uses cursor-based pagination. Use the 'after' parameter with the 'endCursor' value from the previous response instead of 'page'."), nil, nil
+			}
+			pagination, err := OptionalCursorPaginationParams(args)
+			if err != nil {
+				return utils.NewToolResultError(err.Error()), nil, nil
 			}
-			perPage := 30
 			if _, hasPerPage := args["perPage"]; hasPerPage {
-				perPage, err = OptionalIntParam(args, "perPage")
+				perPage, err := OptionalIntParam(args, "perPage")
 				if err != nil {
 					return utils.NewToolResultError(err.Error()), nil, nil
 				}
 				if perPage < 1 || perPage > 100 {
 					return utils.NewToolResultError("perPage must be between 1 and 100 when provided"), nil, nil
 				}
+				pagination.PerPage = perPage
+			}
+			afterOffset, err := decodeBlameCursor(pagination.After)
+			if err != nil {
+				return utils.NewToolResultError(err.Error()), nil, nil
 			}
 
 			client, err := deps.GetGQLClient(ctx)
@@ -2465,9 +2497,11 @@ func GetFileBlame(t translations.TranslationHelperFunc) inventory.ServerTool {
 			}
 
 			rawRanges := blameQuery.Repository.Object.Commit.Blame.Ranges
+			pageRanges := make([]BlameRange, 0, pagination.PerPage)
+			commits := make(map[string]BlameCommit)
+			totalRanges := 0
+			truncated := false
 
-			// Filter / clamp to the requested line window.
-			windowed := make([]BlameRange, 0, len(rawRanges))
 			for _, r := range rawRanges {
 				start := int(r.StartingLine)
 				end := int(r.EndingLine)
@@ -2483,40 +2517,26 @@ func GetFileBlame(t translations.TranslationHelperFunc) inventory.ServerTool {
 				if endLine > 0 && end > endLine {
 					end = endLine
 				}
-				windowed = append(windowed, BlameRange{
+
+				matchIndex := totalRanges
+				totalRanges++
+				if matchIndex >= maxBlameRanges {
+					truncated = true
+					continue
+				}
+				if matchIndex < afterOffset || len(pageRanges) >= pagination.PerPage {
+					continue
+				}
+
+				blameRange := BlameRange{
 					StartingLine: start,
 					EndingLine:   end,
 					Age:          int(r.Age),
 					CommitSHA:    string(r.Commit.OID),
-				})
-			}
-
-			totalRanges := len(windowed)
-
-			// Cap before pagination so truncation is reported consistently.
-			truncated := false
-			if len(windowed) > maxBlameRanges {
-				truncated = true
-				windowed = windowed[:maxBlameRanges]
-			}
-
-			// Apply page/perPage pagination over the (filtered, capped) set.
-			cappedRanges := len(windowed)
-			offset := min((page-1)*perPage, cappedRanges)
-			end := min(offset+perPage, cappedRanges)
-			pageRanges := windowed[offset:end]
+				}
+				pageRanges = append(pageRanges, blameRange)
 
-			// Collect commit metadata only for SHAs referenced by this page.
-			needed := make(map[string]struct{}, len(pageRanges))
-			for _, br := range pageRanges {
-				needed[br.CommitSHA] = struct{}{}
-			}
-			commits := make(map[string]BlameCommit, len(needed))
-			for _, r := range rawRanges {
 				sha := string(r.Commit.OID)
-				if _, want := needed[sha]; !want {
-					continue
-				}
 				if _, seen := commits[sha]; seen {
 					continue
 				}
@@ -2543,12 +2563,24 @@ func GetFileBlame(t translations.TranslationHelperFunc) inventory.ServerTool {
 				commits[sha] = bc
 			}
 
+			cappedRanges := min(totalRanges, maxBlameRanges)
+			consumedRanges := min(afterOffset+len(pageRanges), cappedRanges)
+			pageInfo := MinimalPageInfo{
+				HasNextPage:     consumedRanges < cappedRanges,
+				HasPreviousPage: afterOffset > 0,
+			}
+			if len(pageRanges) > 0 {
+				pageInfo.StartCursor = encodeBlameCursor(afterOffset)
+				pageInfo.EndCursor = encodeBlameCursor(consumedRanges)
+			}
+
 			result := BlameResult{
 				Repository:  fmt.Sprintf("%s/%s", owner, repo),
 				Path:        path,
 				Ref:         responseRef,
 				Ranges:      pageRanges,
 				Commits:     commits,
+				PageInfo:    pageInfo,
 				TotalRanges: totalRanges,
 				Truncated:   truncated,
 			}

pkg/github/repositories_test.go

@@ -4380,9 +4380,10 @@ func Test_GetFileBlame(t *testing.T) {
 	require.True(t, ok, "InputSchema should be *jsonschema.Schema")
 	assert.Equal(t, "get_file_blame", tool.Name)
 	assert.NotEmpty(t, tool.Description)
-	for _, key := range []string{"owner", "repo", "path", "ref", "start_line", "end_line", "page", "perPage"} {
+	for _, key := range []string{"owner", "repo", "path", "ref", "start_line", "end_line", "perPage", "after"} {
 		assert.Contains(t, schema.Properties, key, "schema missing property %q", key)
 	}
+	assert.NotContains(t, schema.Properties, "page")
 	assert.ElementsMatch(t, schema.Required, []string{"owner", "repo", "path"})
 	require.NotNil(t, tool.Annotations)
 	assert.True(t, tool.Annotations.ReadOnlyHint, "blame is read-only")
@@ -4510,6 +4511,10 @@ func Test_GetFileBlame(t *testing.T) {
 				assert.Equal(t, "main", br.Ref, "ref should resolve to default branch name")
 				assert.False(t, br.Truncated)
 				assert.Equal(t, 3, br.TotalRanges)
+				assert.False(t, br.PageInfo.HasNextPage)
+				assert.False(t, br.PageInfo.HasPreviousPage)
+				assert.NotEmpty(t, br.PageInfo.StartCursor)
+				assert.NotEmpty(t, br.PageInfo.EndCursor)
 				require.Len(t, br.Ranges, 3)
 				// Commits map is deduplicated.
 				require.Len(t, br.Commits, 2)
@@ -4598,6 +4603,8 @@ func Test_GetFileBlame(t *testing.T) {
 				assert.Equal(t, 0, br.TotalRanges)
 				assert.Empty(t, br.Ranges)
 				assert.Empty(t, br.Commits)
+				assert.False(t, br.PageInfo.HasNextPage)
+				assert.False(t, br.PageInfo.HasPreviousPage)
 				assert.False(t, br.Truncated)
 				// Ranges should marshal as an empty array, not null.
 				assert.Contains(t, result, `"ranges":[]`)
@@ -4715,6 +4722,68 @@ func Test_GetFileBlame(t *testing.T) {
 				assert.NotContains(t, br.Commits, "sha-A", "filtered-out commit must not appear")
 			},
 		},
+		{
+			name: "cursor pagination returns requested page",
+			mockedClient: githubv4mock.NewMockedHTTPClient(
+				githubv4mock.NewQueryMatcher(
+					blameQueryShape{},
+					makeBlameVars("testowner", "testrepo", "HEAD", "src/paged.go"),
+					githubv4mock.DataResponse(map[string]any{
+						"repository": map[string]any{
+							"defaultBranchRef": map[string]any{"name": "main"},
+							"object": map[string]any{
+								"__typename": "Commit",
+								"blame": map[string]any{
+									"ranges": []map[string]any{
+										{
+											"startingLine": 1, "endingLine": 1, "age": 1,
+											"commit": map[string]any{
+												"oid": "sha-A", "message": "A", "committedDate": "2024-01-01T00:00:00Z",
+												"author": map[string]any{"name": "a", "email": "a@x", "user": nil},
+											},
+										},
+										{
+											"startingLine": 2, "endingLine": 2, "age": 1,
+											"commit": map[string]any{
+												"oid": "sha-B", "message": "B", "committedDate": "2024-01-01T00:00:00Z",
+												"author": map[string]any{"name": "b", "email": "b@x", "user": nil},
+											},
+										},
+										{
+											"startingLine": 3, "endingLine": 3, "age": 1,
+											"commit": map[string]any{
+												"oid": "sha-C", "message": "C", "committedDate": "2024-01-01T00:00:00Z",
+												"author": map[string]any{"name": "c", "email": "c@x", "user": nil},
+											},
+										},
+									},
+								},
+							},
+						},
+					}),
+				),
+			),
+			requestArgs: map[string]any{
+				"owner":   "testowner",
+				"repo":    "testrepo",
+				"path":    "src/paged.go",
+				"perPage": float64(1),
+				"after":   encodeBlameCursor(1),
+			},
+			validateResponse: func(t *testing.T, result string) {
+				var br BlameResult
+				require.NoError(t, json.Unmarshal([]byte(result), &br))
+				assert.Equal(t, 3, br.TotalRanges)
+				require.Len(t, br.Ranges, 1)
+				assert.Equal(t, "sha-B", br.Ranges[0].CommitSHA)
+				require.Len(t, br.Commits, 1)
+				require.Contains(t, br.Commits, "sha-B")
+				assert.True(t, br.PageInfo.HasNextPage)
+				assert.True(t, br.PageInfo.HasPreviousPage)
+				assert.Equal(t, encodeBlameCursor(1), br.PageInfo.StartCursor)
+				assert.Equal(t, encodeBlameCursor(2), br.PageInfo.EndCursor)
+			},
+		},
 		{
 			name: "GraphQL error is surfaced",
 			mockedClient: githubv4mock.NewMockedHTTPClient(
@@ -4791,7 +4860,7 @@ func Test_GetFileBlame(t *testing.T) {
 		}
 	})
 
-	// Line-window and pagination validation also short-circuits.
+	// Line-window and cursor pagination validation also short-circuits.
 	t.Run("line-range argument validation", func(t *testing.T) {
 		client := githubv4.NewClient(githubv4mock.NewMockedHTTPClient())
 		deps := BaseDeps{GQLClient: client}
@@ -4818,14 +4887,14 @@ func Test_GetFileBlame(t *testing.T) {
 				"end_line must be omitted or >= 1",
 			},
 			{
-				"invalid page",
-				map[string]any{"owner": "o", "repo": "r", "path": "f.go", "page": float64(-1)},
-				"page must be >= 1 when provided",
+				"page not supported",
+				map[string]any{"owner": "o", "repo": "r", "path": "f.go", "page": float64(1)},
+				"cursor-based pagination",
 			},
 			{
-				"page zero",
-				map[string]any{"owner": "o", "repo": "r", "path": "f.go", "page": float64(0)},
-				"page must be >= 1 when provided",
+				"invalid after cursor",
+				map[string]any{"owner": "o", "repo": "r", "path": "f.go", "after": "not-a-cursor"},
+				"after cursor is invalid",
 			},
 			{
 				"perPage too large",
@@ -4896,6 +4965,8 @@ func Test_GetFileBlame(t *testing.T) {
 		assert.True(t, br.Truncated, "truncation flag must be set")
 		assert.Equal(t, maxBlameRanges+5, br.TotalRanges)
 		assert.Len(t, br.Ranges, 100, "perPage limits the page size")
+		assert.True(t, br.PageInfo.HasNextPage)
+		assert.NotEmpty(t, br.PageInfo.EndCursor)
 	})
 }