feat: add paginated get_backlinks_profile MCP tool (#38)

* feat: add paginated get_backlinks_profile MCP tool

Exposes detailed per-link backlink rows over MCP, reusing BacklinksService
paginated row fetching. Closes #36.

* fix(test): use type-narrowing text assertion to satisfy oxlint

expect.stringContaining inside toMatchObject tripped
typescript-eslint(no-unsafe-assignment), breaking ci:check. Match the
.toContain() pattern used elsewhere in the MCP tool tests.

* refactor(mcp): simplify get_backlinks_profile handler + fix cost estimate

- Drop the redundant backlinksRowsPageRequestSchema.parse re-validation in
  the handler; the MCP SDK already validates args against inputSchema. Build
  the service request straight from args, removing the duplicated defaults
  that could silently diverge.
- Preserve the target length cap by adding .max(2048) to the input schema
  (previously enforced only via the re-parse).
- Correct the credit estimate in the tool description: measured cost is
  ~30 credits/page, not the ~200-500 copied from get_backlinks_overview.
- Minor: type the statuses accumulator.

* fix(mcp): correct get_backlinks_overview credit estimate

Measured real cost: summary (~26 credits) + history for domain scope
(~29 credits) = ~50 per domain, ~25 for a single page. The previous
~200-500 figure was a ~5-10x overestimate (same one get_backlinks_profile
inherited).

---------

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Ben Senescu <bensenescu@gmail.com>

src/client/features/ai-mcp/AvailableTools.tsx

@@ -74,6 +74,11 @@ const toolCategories: ToolCategory[] = [
         title: "Get backlinks overview",
         description: "Check backlink and referring-domain stats.",
       },
+      {
+        name: "get_backlinks_profile",
+        title: "Get backlinks profile",
+        description: "Fetch paginated link-level backlink rows.",
+      },
     ],
   },
   {

src/server/mcp/output-schemas.ts

@@ -19,6 +19,17 @@ const mcpMetaOutputSchema = z
 // shape, so it validates both plain rows and typed instances.
 export const looseObjectOutputSchema = z.object({}).passthrough();
 
+export const backlinksProfileOutputSchema = z
+  .object({
+    rows: z.array(looseObjectOutputSchema),
+    totalCount: z.number().nullable(),
+    hasMore: z.boolean(),
+    page: z.number(),
+    pageSize: z.number(),
+    fetchedAt: z.string().optional(),
+  })
+  .passthrough();
+
 export const optionalMetaOutputSchema = {
   meta: mcpMetaOutputSchema.optional(),
 } as const;

src/server/mcp/server.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { instrumentMcpToolHandler } from "@/server/mcp/instrumentation";
 import { getBacklinksOverviewTool } from "@/server/mcp/tools/get-backlinks-overview";
+import { getBacklinksProfileTool } from "@/server/mcp/tools/get-backlinks-profile";
 import { getDomainKeywordSuggestionsTool } from "@/server/mcp/tools/get-domain-keyword-suggestions";
 import { getDomainOverviewTool } from "@/server/mcp/tools/get-domain-overview";
 import { getRankTrackerTool } from "@/server/mcp/tools/get-rank-tracker";
@@ -101,6 +102,15 @@ export function registerOpenSeoMcpTools(server: McpServer) {
       getBacklinksOverviewTool.handler,
     ),
   );
+  server.registerTool(
+    getBacklinksProfileTool.name,
+    getBacklinksProfileTool.config,
+    instrumentMcpToolHandler(
+      getBacklinksProfileTool.name,
+      getBacklinksProfileTool.config.outputSchema,
+      getBacklinksProfileTool.handler,
+    ),
+  );
   server.registerTool(
     getSerpResultsTool.name,
     getSerpResultsTool.config,

src/server/mcp/tools/get-backlinks-overview.ts

@@ -40,7 +40,7 @@ export const getBacklinksOverviewTool = {
   config: {
     title: "Get backlinks overview",
     description:
-      "Returns a backlinks profile summary (total backlinks, referring domains, top referring domains). Charges credits (~200-500 typical). Self-hosted deployments need the Backlinks API enabled on their DataForSEO account.",
+      "Returns a backlinks profile summary (total backlinks, referring domains, top referring domains). Charges credits (~50 typical for a domain, ~25 for a single page). Self-hosted deployments need the Backlinks API enabled on their DataForSEO account.",
     inputSchema,
     outputSchema: {
       overview: looseObjectOutputSchema,

src/server/mcp/tools/get-backlinks-profile.ts

@@ -0,0 +1,170 @@
+import { z } from "zod";
+import { BacklinksService } from "@/server/features/backlinks/services/BacklinksService";
+import { buildProjectMeta } from "@/server/mcp/context";
+import { mcpResponse } from "@/server/mcp/formatters";
+import {
+  backlinksProfileOutputSchema,
+  optionalMetaOutputSchema,
+} from "@/server/mcp/output-schemas";
+import { withMcpProjectAuth } from "@/server/mcp/project-auth";
+import { projectIdSchema } from "@/server/mcp/schemas";
+import {
+  BACKLINKS_DEFAULT_SORT,
+  BACKLINKS_PAGE_SIZES,
+  DEFAULT_BACKLINKS_PAGE_SIZE,
+  backlinksRowsFiltersSchema,
+  backlinksRowsModeSchema,
+  backlinksRowsSortFieldSchema,
+  backlinksSortOrderSchema,
+  backlinksTargetScopeSchema,
+} from "@/types/schemas/backlinks";
+
+const inputSchema = {
+  projectId: projectIdSchema,
+  target: z
+    .string()
+    .min(1)
+    .max(2048)
+    .describe(
+      "Domain or URL to analyze (e.g. 'example.com' or 'https://example.com/blog').",
+    ),
+  scope: backlinksTargetScopeSchema
+    .optional()
+    .describe(
+      "'domain' analyzes the whole domain; 'page' analyzes a specific URL. Defaults to 'domain'.",
+    ),
+  page: z
+    .number()
+    .int()
+    .positive()
+    .default(1)
+    .describe("1-indexed results page. Defaults to 1."),
+  pageSize: z
+    .number()
+    .int()
+    .refine((value) =>
+      (BACKLINKS_PAGE_SIZES as readonly number[]).includes(value),
+    )
+    .default(DEFAULT_BACKLINKS_PAGE_SIZE)
+    .describe("Rows per page. Allowed values: 50, 100, or 200."),
+  sortField: backlinksRowsSortFieldSchema
+    .default(BACKLINKS_DEFAULT_SORT.backlinks.field)
+    .describe("Backlink row sort field."),
+  sortOrder: backlinksSortOrderSchema
+    .default(BACKLINKS_DEFAULT_SORT.backlinks.order)
+    .describe("Sort direction."),
+  filters: backlinksRowsFiltersSchema
+    .default({})
+    .describe(
+      "Backlink row filters: include/exclude source URL terms, authority/spam ranges, dofollow/nofollow, lost/broken visibility, or exact domainFrom.",
+    ),
+  mode: backlinksRowsModeSchema
+    .default("one_per_domain")
+    .describe(
+      "DataForSEO backlink grouping: one_per_domain returns each referring domain's strongest link; as_is returns individual backlink rows.",
+    ),
+  hideSpam: z
+    .boolean()
+    .optional()
+    .describe("Filter out spammy backlinks. Defaults to true."),
+} as const;
+
+type Args = z.infer<z.ZodObject<typeof inputSchema>>;
+
+function formatMetric(value: unknown) {
+  return typeof value === "number" || typeof value === "string" ? value : "?";
+}
+
+function formatLinkType(value: boolean | null | undefined) {
+  if (value === true) return "dofollow";
+  if (value === false) return "nofollow";
+  return "unknown";
+}
+
+function formatStatus(row: {
+  isLost?: boolean | null;
+  isBroken?: boolean | null;
+}) {
+  const statuses: string[] = [];
+  if (row.isLost) statuses.push("lost");
+  if (row.isBroken) statuses.push("broken");
+  return statuses.length > 0 ? statuses.join(", ") : "live";
+}
+
+function formatBacklinkRow(row: {
+  domainFrom?: string | null;
+  urlFrom?: string | null;
+  urlTo?: string | null;
+  anchor?: string | null;
+  isDofollow?: boolean | null;
+  rank?: number | null;
+  domainFromRank?: number | null;
+  spamScore?: number | null;
+  isLost?: boolean | null;
+  isBroken?: boolean | null;
+}) {
+  const source = row.urlFrom ?? row.domainFrom ?? "?";
+  return `- ${source} -> ${row.urlTo ?? "?"} anchor:"${row.anchor ?? ""}" ${formatLinkType(row.isDofollow)} rank:${formatMetric(row.rank)} domainRank:${formatMetric(row.domainFromRank)} spam:${formatMetric(row.spamScore)} status:${formatStatus(row)}`;
+}
+
+export const getBacklinksProfileTool = {
+  name: "get_backlinks_profile",
+  config: {
+    title: "Get backlinks profile",
+    description:
+      "Returns one bounded page of detailed backlink rows for a domain or page: linking URLs, target URLs, anchors, dofollow/nofollow, authority/spam signals, and lost/broken status. Supports filters, sorting, one_per_domain/as_is mode, and pagination. Charges credits (~30 per page typical). Self-hosted deployments need the Backlinks API enabled on their DataForSEO account.",
+    inputSchema,
+    outputSchema: {
+      backlinks: backlinksProfileOutputSchema,
+      ...optionalMetaOutputSchema,
+    },
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+      destructiveHint: false,
+    },
+  },
+  handler: withMcpProjectAuth(async (args: Args, context) => {
+    // The MCP SDK already validated args against inputSchema (which mirrors
+    // backlinksRowsPageRequestSchema), so pass them straight through.
+    const request = {
+      target: args.target,
+      scope: args.scope,
+      page: args.page,
+      pageSize: args.pageSize,
+      sortField: args.sortField,
+      sortOrder: args.sortOrder,
+      filters: args.filters,
+      mode: args.mode,
+    };
+
+    const backlinks = await BacklinksService.profileBacklinksPage(
+      request,
+      context.billing,
+      { hideSpam: args.hideSpam ?? true },
+    );
+    const shownRows = backlinks.rows.slice(0, 10);
+    const text = [
+      `Backlinks profile for ${request.target} (${request.scope ?? "domain"}):`,
+      `- page: ${backlinks.page}`,
+      `- page size: ${backlinks.pageSize}`,
+      `- rows returned: ${backlinks.rows.length}`,
+      `- total backlinks: ${formatMetric(backlinks.totalCount)}`,
+      `- has more: ${backlinks.hasMore ? "yes" : "no"}`,
+      "",
+      `Backlink rows (${shownRows.length} shown in text, ${backlinks.rows.length} in structured content):`,
+      ...shownRows.map(formatBacklinkRow),
+    ].join("\n");
+
+    return mcpResponse({
+      text,
+      meta: buildProjectMeta(
+        context,
+        args.projectId,
+        `/p/${args.projectId}/backlinks`,
+        { target: request.target, scope: request.scope },
+      ),
+      structuredContent: { backlinks },
+    });
+  }),
+};

src/server/mcp/tools/output-schema-validation.test.ts

@@ -2,12 +2,32 @@ import {
   normalizeObjectSchema,
   safeParseAsync,
 } from "@modelcontextprotocol/sdk/server/zod-compat.js";
-import { describe, expect, it, vi } from "vitest";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import type { ToolExtra } from "@/server/mcp/context";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { MCP_AUTH_CONTEXT_PROP } from "@/server/mcp/context";
+
+const mocks = vi.hoisted(() => ({
+  getProjectForOrganization: vi.fn(),
+  profileBacklinksPage: vi.fn(),
+}));
 
 vi.mock("cloudflare:workers", () => ({
   env: {},
 }));
 
+vi.mock("@/server/features/projects/services/ProjectService", () => ({
+  ProjectService: {
+    getProjectForOrganization: mocks.getProjectForOrganization,
+  },
+}));
+
+vi.mock("@/server/features/backlinks/services/BacklinksService", () => ({
+  BacklinksService: {
+    profileBacklinksPage: mocks.profileBacklinksPage,
+  },
+}));
+
 // A class instance reproduces what the DataForSEO SDK hands the tools: an
 // object whose prototype is not Object.prototype (e.g.
 // DataforseoLabsSerpCompetitorsLiveItem). Zod 4's z.record() rejects those
@@ -21,6 +41,67 @@ class ProviderRow {
   ) {}
 }
 
+const authContext = {
+  userId: "user_123",
+  userEmail: "team@example.com",
+  organizationId: "org_123",
+  clientId: "client_123",
+  scopes: ["mcp"],
+  audience: "open-seo",
+  subject: "user_123",
+  baseUrl: "https://app.example.com",
+};
+
+const authExtra: ToolExtra = {
+  signal: new AbortController().signal,
+  requestId: 1,
+  sendNotification: vi.fn(),
+  sendRequest: vi.fn(),
+  authInfo: {
+    token: "token",
+    clientId: "client_123",
+    scopes: ["mcp"],
+    resource: new URL("https://app.example.com/mcp"),
+    extra: {
+      [MCP_AUTH_CONTEXT_PROP]: authContext,
+    },
+  } satisfies AuthInfo,
+};
+
+const backlinkPage = {
+  rows: [
+    {
+      domainFrom: "source.example",
+      urlFrom: "https://source.example/post",
+      urlTo: "https://example.com/",
+      anchor: "Example",
+      itemType: "content",
+      isDofollow: true,
+      relAttributes: ["noopener"],
+      rank: 77,
+      domainFromRank: 65,
+      pageFromRank: 54,
+      spamScore: 3,
+      firstSeen: "2026-01-01",
+      lastSeen: "2026-03-01",
+      isLost: false,
+      isBroken: false,
+      linksCount: 1,
+    },
+  ],
+  totalCount: 450,
+  hasMore: true,
+  page: 2,
+  pageSize: 50,
+  fetchedAt: "2026-06-25T00:00:00.000Z",
+};
+
+beforeEach(() => {
+  mocks.getProjectForOrganization.mockReset();
+  mocks.profileBacklinksPage.mockReset();
+  mocks.getProjectForOrganization.mockResolvedValue({ id: "project_123" });
+});
+
 describe("DataForSEO research tool output schemas", () => {
   // Every tool that streams provider rows straight to structuredContent.
   it.each([
@@ -50,4 +131,143 @@ describe("DataForSEO research tool output schemas", () => {
       expect(result.success).toBe(true);
     },
   );
+
+  it("get_backlinks_profile accepts a paginated backlinks profile payload", async () => {
+    const { getBacklinksProfileTool } = await import("./get-backlinks-profile");
+    const schema = normalizeObjectSchema(
+      getBacklinksProfileTool.config.outputSchema,
+    );
+    if (!schema) throw new Error("output schema did not normalize");
+
+    const result = await safeParseAsync(schema, {
+      backlinks: backlinkPage,
+      meta: {
+        organizationId: "org_123",
+        projectId: "project_123",
+        url: "https://app.example.com/p/project_123/backlinks",
+      },
+    });
+
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("get_backlinks_profile MCP tool", () => {
+  it("returns paginated backlink rows and honors filters, sorting, and mode", async () => {
+    mocks.profileBacklinksPage.mockResolvedValue(backlinkPage);
+    const { getBacklinksProfileTool } = await import("./get-backlinks-profile");
+
+    const result = await getBacklinksProfileTool.handler(
+      {
+        projectId: "project_123",
+        target: "example.com",
+        scope: "domain",
+        page: 2,
+        pageSize: 50,
+        sortField: "spamScore",
+        sortOrder: "asc",
+        filters: {
+          include: "blog",
+          linkType: "nofollow",
+          hideLost: true,
+        },
+        mode: "as_is",
+        hideSpam: false,
+      },
+      authExtra,
+    );
+
+    expect(mocks.profileBacklinksPage).toHaveBeenCalledWith(
+      {
+        target: "example.com",
+        scope: "domain",
+        page: 2,
+        pageSize: 50,
+        sortField: "spamScore",
+        sortOrder: "asc",
+        filters: {
+          include: "blog",
+          linkType: "nofollow",
+          hideLost: true,
+        },
+        mode: "as_is",
+      },
+      {
+        userId: "user_123",
+        userEmail: "team@example.com",
+        organizationId: "org_123",
+        projectId: "project_123",
+      },
+      { hideSpam: false },
+    );
+    expect(result.structuredContent?.backlinks).toEqual(backlinkPage);
+    const first = result.content[0];
+    expect(first.type === "text" && first.text).toContain("- has more: yes");
+  });
+
+  it("passes through final-page pagination state", async () => {
+    const finalPage = {
+      ...backlinkPage,
+      totalCount: 51,
+      hasMore: false,
+      page: 2,
+    };
+    mocks.profileBacklinksPage.mockResolvedValue(finalPage);
+    const { getBacklinksProfileTool } = await import("./get-backlinks-profile");
+
+    const result = await getBacklinksProfileTool.handler(
+      {
+        projectId: "project_123",
+        target: "example.com",
+        scope: "domain",
+        page: 2,
+        pageSize: 50,
+        sortField: "rank",
+        sortOrder: "desc",
+        filters: {},
+        mode: "one_per_domain",
+        hideSpam: true,
+      },
+      authExtra,
+    );
+
+    expect(result.structuredContent?.backlinks).toMatchObject({
+      totalCount: 51,
+      hasMore: false,
+      page: 2,
+      pageSize: 50,
+    });
+  });
+
+  it("preserves Backlinks API access and credit errors", async () => {
+    const { AppError } = await import("@/server/lib/errors");
+    const error = new AppError(
+      "BACKLINKS_BILLING_ISSUE",
+      "The connected DataForSEO account has a billing or balance issue",
+    );
+    mocks.profileBacklinksPage.mockRejectedValue(error);
+    const { getBacklinksProfileTool } = await import("./get-backlinks-profile");
+
+    await expect(
+      getBacklinksProfileTool.handler(
+        {
+          projectId: "project_123",
+          target: "example.com",
+          scope: "domain",
+          page: 1,
+          pageSize: 100,
+          sortField: "rank",
+          sortOrder: "desc",
+          filters: {},
+          mode: "one_per_domain",
+          hideSpam: true,
+        },
+        authExtra,
+      ),
+    ).rejects.toMatchObject({
+      code: "BACKLINKS_BILLING_ISSUE",
+      message:
+        "The connected DataForSEO account has a billing or balance issue",
+    });
+  });
 });

src/types/schemas/backlinks.ts

@@ -88,7 +88,7 @@ export const backlinksRowsFiltersSchema = z.object({
  * each referring domain's strongest link (the default, denoised view);
  * `as_is` returns every individual backlink.
  */
-const backlinksRowsModeSchema = z.enum(["one_per_domain", "as_is"]);
+export const backlinksRowsModeSchema = z.enum(["one_per_domain", "as_is"]);
 
 export const referringDomainsFiltersSchema = z.object({
   include: z.string().optional(),