Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
feat: add paginated get_backlinks_profile MCP tool (#38)
Matt Van Horn1dabbc88a646
diff --git a/src/client/features/ai-mcp/AvailableTools.tsx b/src/client/features/ai-mcp/AvailableTools.tsxindex df9447a8..f33e0ee7 100644--- a/src/client/features/ai-mcp/AvailableTools.tsx+++ b/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.",+ },],},{diff --git a/src/server/mcp/output-schemas.ts b/src/server/mcp/output-schemas.tsindex 572ad792..acfa165e 100644--- a/src/server/mcp/output-schemas.ts+++ b/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;diff --git a/src/server/mcp/server.ts b/src/server/mcp/server.tsindex eb4911d1..22d224cb 100644--- a/src/server/mcp/server.ts+++ b/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,diff --git a/src/server/mcp/tools/get-backlinks-overview.ts b/src/server/mcp/tools/get-backlinks-overview.tsindex e50cf5c4..535549c7 100644--- a/src/server/mcp/tools/get-backlinks-overview.ts+++ b/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,diff --git a/src/server/mcp/tools/get-backlinks-profile.ts b/src/server/mcp/tools/get-backlinks-profile.tsnew file mode 100644index 00000000..c12faa1c--- /dev/null+++ b/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 },+ });+ }),+};diff --git a/src/server/mcp/tools/output-schema-validation.test.ts b/src/server/mcp/tools/output-schema-validation.test.tsindex e1f6700c..3a185cc3 100644--- a/src/server/mcp/tools/output-schema-validation.test.ts+++ b/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: "[email protected]",+ 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: "[email protected]",+ 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",+ });+ });});diff --git a/src/types/schemas/backlinks.ts b/src/types/schemas/backlinks.tsindex 08be1677..477cc6ef 100644--- a/src/types/schemas/backlinks.ts+++ b/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(),