refactor: share cursor pagination metadata

RossTarrant · RossTarrant · commit de042c018479 · 2026-06-10T14:25:12.000+01:00
diff --git a/README.md b/README.md
@@ -717,7 +717,7 @@ The following sets of tools are available:
 - **list_dependabot_alerts** - List dependabot alerts
   - **Required OAuth Scopes**: `security_events`
   - **Accepted OAuth Scopes**: `repo`, `security_events`
-  - `after`: Omit for the first page. For subsequent pages, use pageInfo.nextCursor from the previous response. (string, optional)
+  - `after`: Cursor for pagination. Use the cursor from the previous response. (string, optional)
   - `owner`: The owner of the repository. (string, required)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: The name of the repository. (string, required)
@@ -755,7 +755,7 @@ The following sets of tools are available:
 
 - **get_discussion_comments** - Get discussion comments
   - **Required OAuth Scopes**: `repo`
-  - `after`: Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs. (string, optional)
+  - `after`: Cursor for pagination. Use the cursor from the previous response. (string, optional)
   - `discussionNumber`: Discussion Number (number, required)
   - `includeReplies`: When true, each top-level comment will include its replies nested within it (up to 100 replies per comment, which is the GitHub API maximum). Defaults to false. (boolean, optional)
   - `owner`: Repository owner (string, required)
@@ -769,7 +769,7 @@ The following sets of tools are available:
 
 - **list_discussions** - List discussions
   - **Required OAuth Scopes**: `repo`
-  - `after`: Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs. (string, optional)
+  - `after`: Cursor for pagination. Use the cursor from the previous response. (string, optional)
   - `category`: Optional filter by discussion category ID. If provided, only discussions with this category are listed. (string, optional)
   - `direction`: Order direction. (string, optional)
   - `orderBy`: Order discussions by field. If provided, the 'direction' also needs to be provided. (string, optional)
@@ -881,7 +881,7 @@ The following sets of tools are available:
 
 - **list_issues** - List issues
   - **Required OAuth Scopes**: `repo`
-  - `after`: Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs. (string, optional)
+  - `after`: Cursor for pagination. Use the cursor from the previous response. (string, optional)
   - `direction`: Order direction. If provided, the 'orderBy' also needs to be provided. (string, optional)
   - `labels`: Filter by labels (string[], optional)
   - `orderBy`: Order issues by field. If provided, the 'direction' also needs to be provided. (string, optional)
diff --git a/docs/feature-flags.md b/docs/feature-flags.md
@@ -102,7 +102,7 @@ runtime behavior (such as output formatting) won't appear here.
 
 - **list_issues** - List issues
   - **Required OAuth Scopes**: `repo`
-  - `after`: Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs. (string, optional)
+  - `after`: Cursor for pagination. Use the cursor from the previous response. (string, optional)
   - `direction`: Order direction. If provided, the 'orderBy' also needs to be provided. (string, optional)
   - `field_filters`: Filter by custom issue field values. Each entry takes a field_name and a value; the server looks up the field and coerces the value to its type (single-select option name, text, number, or YYYY-MM-DD date). (object[], optional)
   - `labels`: Filter by labels (string[], optional)
diff --git a/docs/insiders-features.md b/docs/insiders-features.md
@@ -96,7 +96,7 @@ The list below is generated from the Go source. It covers tool **inventory and s
 
 - **list_issues** - List issues
   - **Required OAuth Scopes**: `repo`
-  - `after`: Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs. (string, optional)
+  - `after`: Cursor for pagination. Use the cursor from the previous response. (string, optional)
   - `direction`: Order direction. If provided, the 'orderBy' also needs to be provided. (string, optional)
   - `field_filters`: Filter by custom issue field values. Each entry takes a field_name and a value; the server looks up the field and coerces the value to its type (single-select option name, text, number, or YYYY-MM-DD date). (object[], optional)
   - `labels`: Filter by labels (string[], optional)
diff --git a/pkg/github/__toolsnaps__/get_discussion_comments.snap b/pkg/github/__toolsnaps__/get_discussion_comments.snap
@@ -7,7 +7,7 @@
   "inputSchema": {
     "properties": {
       "after": {
-        "description": "Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs.",
+        "description": "Cursor for pagination. Use the cursor from the previous response.",
         "type": "string"
       },
       "discussionNumber": {
diff --git a/pkg/github/__toolsnaps__/list_dependabot_alerts.snap b/pkg/github/__toolsnaps__/list_dependabot_alerts.snap
@@ -7,7 +7,7 @@
   "inputSchema": {
     "properties": {
       "after": {
-        "description": "Omit for the first page. For subsequent pages, use pageInfo.nextCursor from the previous response.",
+        "description": "Cursor for pagination. Use the cursor from the previous response.",
         "type": "string"
       },
       "owner": {
diff --git a/pkg/github/__toolsnaps__/list_discussions.snap b/pkg/github/__toolsnaps__/list_discussions.snap
@@ -7,7 +7,7 @@
   "inputSchema": {
     "properties": {
       "after": {
-        "description": "Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs.",
+        "description": "Cursor for pagination. Use the cursor from the previous response.",
         "type": "string"
       },
       "category": {
diff --git a/pkg/github/__toolsnaps__/list_issues.snap b/pkg/github/__toolsnaps__/list_issues.snap
@@ -7,7 +7,7 @@
   "inputSchema": {
     "properties": {
       "after": {
-        "description": "Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs.",
+        "description": "Cursor for pagination. Use the cursor from the previous response.",
         "type": "string"
       },
       "direction": {
diff --git a/pkg/github/__toolsnaps__/list_issues_ff_remote_mcp_issue_fields.snap b/pkg/github/__toolsnaps__/list_issues_ff_remote_mcp_issue_fields.snap
@@ -7,7 +7,7 @@
   "inputSchema": {
     "properties": {
       "after": {
-        "description": "Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs.",
+        "description": "Cursor for pagination. Use the cursor from the previous response.",
         "type": "string"
       },
       "direction": {
diff --git a/pkg/github/dependabot.go b/pkg/github/dependabot.go
@@ -121,10 +121,6 @@ func ListDependabotAlerts(t translations.TranslationHelperFunc) inventory.Server
 		Required: []string{"owner", "repo"},
 	}
 	WithCursorPagination(schema)
-	// The Dependabot alerts REST endpoint uses cursor pagination via the response's
-	// Link header (surfaced as pageInfo.nextCursor), not GraphQL. Override the shared
-	// cursor description, which otherwise refers to a GraphQL PageInfo.
-	schema.Properties["after"].Description = "Omit for the first page. For subsequent pages, use pageInfo.nextCursor from the previous response."
 
 	return NewTool(
 		ToolsetMetadataDependabot,
diff --git a/pkg/github/params.go b/pkg/github/params.go
@@ -376,7 +376,7 @@ func WithCursorPagination(schema *jsonschema.Schema) *jsonschema.Schema {
 
 	schema.Properties["after"] = &jsonschema.Schema{
 		Type:        "string",
-		Description: "Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs.",
+		Description: "Cursor for pagination. Use the cursor from the previous response.",
 	}
 
 	return schema
@@ -435,6 +435,22 @@ type CursorPaginationParams struct {
 	After   string
 }
 
+type pageInfo struct {
+	HasNextPage     bool   `json:"hasNextPage"`
+	HasPreviousPage bool   `json:"hasPreviousPage"`
+	NextCursor      string `json:"nextCursor,omitempty"`
+	PrevCursor      string `json:"prevCursor,omitempty"`
+}
+
+func buildPageInfo(resp *github.Response) pageInfo {
+	return pageInfo{
+		HasNextPage:     resp.After != "",
+		HasPreviousPage: resp.Before != "",
+		NextCursor:      resp.After,
+		PrevCursor:      resp.Before,
+	}
+}
+
 // ToGraphQLParams converts cursor pagination parameters to GraphQL-specific parameters.
 func (p CursorPaginationParams) ToGraphQLParams() (*GraphQLPaginationParams, error) {
 	if p.PerPage > 100 {
diff --git a/pkg/github/projects.go b/pkg/github/projects.go
@@ -1350,13 +1350,6 @@ func getProjectStatusUpdate(ctx context.Context, gqlClient *githubv4.Client, sta
 	return utils.NewToolResultText(string(r)), nil, nil
 }
 
-type pageInfo struct {
-	HasNextPage     bool   `json:"hasNextPage"`
-	HasPreviousPage bool   `json:"hasPreviousPage"`
-	NextCursor      string `json:"nextCursor,omitempty"`
-	PrevCursor      string `json:"prevCursor,omitempty"`
-}
-
 // validateAndConvertToInt64 ensures the value is a number and converts it to int64.
 func validateAndConvertToInt64(value any) (int64, error) {
 	switch v := value.(type) {
@@ -1407,15 +1400,6 @@ func buildUpdateProjectItem(input map[string]any) (*github.UpdateProjectItemOpti
 	return payload, nil
 }
 
-func buildPageInfo(resp *github.Response) pageInfo {
-	return pageInfo{
-		HasNextPage:     resp.After != "",
-		HasPreviousPage: resp.Before != "",
-		NextCursor:      resp.After,
-		PrevCursor:      resp.Before,
-	}
-}
-
 func extractPaginationOptionsFromArgs(args map[string]any) (github.ListProjectsPaginationOptions, error) {
 	perPage, err := OptionalIntParamWithDefault(args, "per_page", MaxProjectsPerPage)
 	if err != nil {
