Use the Sentry Link parser for MCP pagination (#1436)

## Summary
- Use the existing @sentry/api Link-header parser for MCP pagination
rather than substring checks that can follow a previous-page cursor.
- Cover a previous link containing an x-rel="next" extension attribute
and align the API-patterns mock with Sentry's results/cursor fields.

## Validation
- Regression failed with the old parser and passed with the SDK parser.
- pnpm install --frozen-lockfile, pnpm run tsc, pnpm run lint,
docs:check, check:generated and Oxfmt check passed.
- Full workspace test run on the initial base passed (CLI 10,529;
MCP-core 1,753; MCP-server 84; MCP test-client 80; MCP Cloudflare 433;
toolkit-core 23). After integrating the latest main, MCP-core passed
1,755 tests, with typecheck and lint passing on the combined tree.

Co-authored-by: GPT-6 Sol <agent@openai.com>

Author: BYK

docs/contributing/api-patterns.md

@@ -26,13 +26,13 @@ pagination behavior, feature-gate handling, and test fixtures.
 ```typescript
 // Standard usage with context helper
 const apiService = apiServiceFromContext(context, {
-  regionUrl: params.regionUrl
+  regionUrl: params.regionUrl,
 });
 
 // Direct instantiation
 const api = new SentryApiService({
   host: "sentry.io",
-  accessToken: token
+  accessToken: token,
 });
 ```
 
@@ -47,19 +47,19 @@ tools.
 const issues = await api.issues.list({
   organizationSlug: "org",
   query: "is:unresolved",
-  sort: "date"
+  sort: "date",
 });
 
 // Get specific resource
 const project = await api.projects.get({
   organizationSlug: "org",
-  projectIdOrSlug: "frontend"
+  projectIdOrSlug: "frontend",
 });
 
 // Create/update
 await api.issues.update({
   issueId: "123",
-  status: "resolved"
+  status: "resolved",
 });
 ```
 
@@ -94,7 +94,7 @@ const orgs = await api.organizations.list();
 
 // Use region URL
 const api = apiServiceFromContext(context, {
-  regionUrl: org.region_url
+  regionUrl: org.region_url,
 });
 ```
 
@@ -105,17 +105,15 @@ const api = apiServiceFromContext(context, {
 ```typescript
 // Support ID variations
 const IssueIdSchema = z.union([
-  z.string(),  // "PROJ-123"
-  z.number()   // 123456789
+  z.string(), // "PROJ-123"
+  z.number(), // 123456789
 ]);
 
 // Partial with passthrough for unknowns
-const FlexibleSchema = BaseSchema
-  .partial()
-  .passthrough();
+const FlexibleSchema = BaseSchema.partial().passthrough();
 
 // Nullable handling
-z.union([DateSchema, z.null()])
+z.union([DateSchema, z.null()]);
 ```
 
 See Zod patterns in [common-patterns.md](common-patterns.md#zod-schema-patterns).
@@ -146,11 +144,11 @@ export const handlers = [
       if (!params.org) {
         return HttpResponse.json("Invalid org", { status: 400 });
       }
-      
+
       // Return fixture
       return HttpResponse.json(issueListFixture);
-    }
-  }
+    },
+  },
 ];
 ```
 
@@ -162,19 +160,17 @@ See: `packages/mcp-server-mocks/src/handlers/`
 fetch: async ({ request }) => {
   const url = new URL(request.url);
   const query = url.searchParams.get("query");
-  
+
   // Validate query parameters
   if (query && !isValidQuery(query)) {
     return HttpResponse.json("Invalid query", { status: 400 });
   }
-  
+
   // Filter based on query
-  const filtered = fixtures.filter(item => 
-    matchesQuery(item, query)
-  );
-  
+  const filtered = fixtures.filter((item) => matchesQuery(item, query));
+
   return HttpResponse.json(filtered);
-}
+};
 ```
 
 ### Dynamic Responses
@@ -189,11 +185,15 @@ const page = fixtures.slice(start, start + limit);
 
 return HttpResponse.json(page, {
   headers: {
-    "Link": `<...?cursor=${start + limit}>; rel="next"`
-  }
+    Link: `<https://sentry.io/api/0/issues/?cursor=${start + limit}>; rel="next"; results="true"; cursor="${start + limit}"`,
+  },
 });
 ```
 
+Use `@sentry/api`'s `parseSentryLinkHeader` to read the next cursor. Sentry's
+`Link` header reports whether the next page has results; a URL query alone does
+not establish that another page exists.
+
 ## Testing with Mocks
 
 ### Setup Pattern
@@ -213,13 +213,12 @@ afterAll(() => server.close());
 ```typescript
 it("handles errors", async () => {
   server.use(
-    http.get("*/issues/", () => 
-      HttpResponse.json({ error: "Server error" }, { status: 500 })
-    )
+    http.get("*/issues/", () =>
+      HttpResponse.json({ error: "Server error" }, { status: 500 }),
+    ),
   );
-  
-  await expect(api.issues.list(params))
-    .rejects.toThrow(ApiError);
+
+  await expect(api.issues.list(params)).rejects.toThrow(ApiError);
 });
 ```
 

packages/mcp-core/package.json

@@ -173,6 +173,7 @@
     "@logtape/sentry": "^1.1.1",
     "@modelcontextprotocol/sdk": "catalog:",
     "@modelcontextprotocol/server": "catalog:",
+    "@sentry/api": "0.337.0",
     "@sentry/core": "catalog:",
     "@sentry/toolkit-core": "workspace:*",
     "ai": "catalog:",

packages/mcp-core/src/api-client/client.test.ts

@@ -44,7 +44,9 @@ describe("API bearer token validation", () => {
       accessToken: "valid\nsecret",
     });
 
-    const error = await api.listOrganizations().catch((cause: unknown) => cause);
+    const error = await api
+      .listOrganizations()
+      .catch((cause: unknown) => cause);
     expect(error).toBeInstanceOf(ConfigurationError);
     expect(String(error)).toContain("Malformed authentication token");
     expect(String(error)).not.toContain("valid\nsecret");
@@ -54,7 +56,9 @@ describe("API bearer token validation", () => {
       host: "sentry.example.com",
       accessToken: "",
     });
-    await expect(emptyTokenApi.listOrganizations()).rejects.toThrow(ConfigurationError);
+    await expect(emptyTokenApi.listOrganizations()).rejects.toThrow(
+      ConfigurationError,
+    );
     expect(requests).toBe(0);
   });
 });
@@ -303,6 +307,29 @@ describe("external issue linking API methods", () => {
     expect(pages).toEqual([null, "next-page"]);
   });
 
+  it("uses the actual next link rather than a previous link's extension attribute", async () => {
+    const pages: (string | null)[] = [];
+    mswServer.use(
+      http.get(
+        "https://us.sentry.io/api/0/organizations/test-org/issues/123/integrations/",
+        ({ request }) => {
+          const cursor = new URL(request.url).searchParams.get("cursor");
+          pages.push(cursor);
+          return HttpResponse.json([], {
+            headers: cursor
+              ? {}
+              : {
+                  Link: '<https://us.sentry.io/>; x-rel="next"; rel="previous"; results="true"; cursor="previous-page", <https://us.sentry.io/>; rel="next"; results="true"; cursor="next-page"',
+                },
+          });
+        },
+      ),
+    );
+
+    await api.listIssueIntegrations({ organizationSlug, issueId });
+    expect(pages).toEqual([null, "next-page"]);
+  });
+
   it("finds App associations beyond the first page", async () => {
     mswServer.use(
       http.get(

packages/mcp-core/src/api-client/client.ts

@@ -1,3 +1,4 @@
+import { parseSentryLinkHeader } from "@sentry/api";
 import { normalizeAuthToken } from "@sentry/toolkit-core/auth-token";
 import { z } from "zod";
 import { DEFAULT_SEARCH_ISSUES_PERIOD } from "../constants";
@@ -260,22 +261,7 @@ function parseStatsPeriod(statsPeriod: string): {
 }
 
 function getNextCursor(linkHeader: string | null): string | null {
-  if (!linkHeader) {
-    return null;
-  }
-
-  for (const link of linkHeader.split(",")) {
-    if (!link.includes('rel="next"') || !link.includes('results="true"')) {
-      continue;
-    }
-
-    const cursorMatch = link.match(/cursor="([^"]+)"/);
-    if (cursorMatch?.[1]) {
-      return cursorMatch[1];
-    }
-  }
-
-  return null;
+  return parseSentryLinkHeader(linkHeader).nextCursor ?? null;
 }
 
 /**
@@ -424,26 +410,22 @@ const EventsValidationIssueSchema = z
     valid: z.boolean(),
     error: ValidationErrorSchema,
   })
-  .transform(
-    ({ valid, error }): EventsValidationIssue => ({
-      valid,
-      ...(error ? { error } : {}),
-    }),
-  );
+  .transform(({ valid, error }): EventsValidationIssue => ({
+    valid,
+    ...(error ? { error } : {}),
+  }));
 
 const EventsNamedValidationIssueSchema = z
   .object({
     name: z.string(),
     valid: z.boolean(),
     error: ValidationErrorSchema,
   })
-  .transform(
-    ({ name, valid, error }): EventsNamedValidationIssue => ({
-      name,
-      valid,
-      ...(error ? { error } : {}),
-    }),
-  );
+  .transform(({ name, valid, error }): EventsNamedValidationIssue => ({
+    name,
+    valid,
+    ...(error ? { error } : {}),
+  }));
 
 const EventsAttributeValidationSchema = z
   .object({
@@ -474,13 +456,11 @@ const EventsQueryValidationSchema = z
     error: ValidationErrorSchema,
     fields: EventsAttributeValidationListSchema,
   })
-  .transform(
-    ({ valid, error, fields }): EventsQueryValidation => ({
-      valid,
-      fields,
-      ...(error ? { error } : {}),
-    }),
-  );
+  .transform(({ valid, error, fields }): EventsQueryValidation => ({
+    valid,
+    fields,
+    ...(error ? { error } : {}),
+  }));
 
 const EventsValidationResponseSchema = z
   .object({
@@ -1331,9 +1311,9 @@ export class SentryApiService {
   private isAggregateExplorerQuery(params: ExplorerAggregateParams): boolean {
     return Boolean(
       params.aggregateFunctions?.length ||
-        params.fields?.some(
-          (field) => field.includes("(") && field.includes(")"),
-        ),
+      params.fields?.some(
+        (field) => field.includes("(") && field.includes(")"),
+      ),
     );
   }