Skip to content

Open source alternative to Semrush and Ahrefs

Let a lost rank-grid or SERP response be recovered without paying again (EVE-386, EVE-385) (#698)

Ben Senescu798b23bd7756
diff --git a/src/server/lib/dataforseo/client.test.ts b/src/server/lib/dataforseo/client.test.ts
index 7149dca3..9e4a1775 100644
--- a/src/server/lib/dataforseo/client.test.ts
+++ b/src/server/lib/dataforseo/client.test.ts
@@ -88,6 +88,7 @@ vi.mock("@/server/lib/dataforseo/serp", () => ({
fetchRankCheckSerp: vi.fn(),
postRankCheckTasks: vi.fn(),
fetchLocalSerp: vi.fn(),
+ postLocalSerpTasks: vi.fn(),
clampSerpDepth: (depth: number) => depth,
SERP_ANALYSIS_DEPTH: 20,
}));
diff --git a/src/server/lib/dataforseo/client.ts b/src/server/lib/dataforseo/client.ts
index 10c90508..f87402e5 100644
--- a/src/server/lib/dataforseo/client.ts
+++ b/src/server/lib/dataforseo/client.ts
@@ -48,6 +48,7 @@ import {
fetchLiveSerp,
fetchLocalSerp,
fetchRankCheckSerp,
+ postLocalSerpTasks,
postRankCheckTasks,
} from "@/server/lib/dataforseo/serp";
import { fetchLighthouseResult } from "@/server/lib/dataforseo/lighthouse";
@@ -228,6 +229,14 @@ export function createDataforseoClient(customer: BillingCustomerContext) {
dataforseoPricing.serp.local,
"local_seo",
),
+ // One queued Maps task per rank grid point; one metered charge covers
+ // them all (DataForSEO bills task_post, collection is free).
+ localTaskPost: meter(
+ customer,
+ postLocalSerpTasks,
+ dataforseoPricing.serp.localTaskPost,
+ "local_seo",
+ ),
},
labs: {
// Callers (e.g. the keyword-metrics MCP tool) can attribute the spend to
diff --git a/src/server/lib/dataforseo/index.ts b/src/server/lib/dataforseo/index.ts
index e9b652c7..22b91549 100644
--- a/src/server/lib/dataforseo/index.ts
+++ b/src/server/lib/dataforseo/index.ts
@@ -26,7 +26,10 @@ export { normalizeBacklinksTarget } from "@/server/lib/dataforseoBacklinksTarget
// at DataForSEO (the task was charged at task_post), so routing these through
// the metering seam would charge the customer twice; business categories are
// free ($0), so a zero-credit org can still list them.
-export { fetchRankCheckTaskResult } from "@/server/lib/dataforseo/serp";
+export {
+ fetchLocalSerpTaskResult,
+ fetchRankCheckTaskResult,
+} from "@/server/lib/dataforseo/serp";
export {
fetchBusinessDataTaskResult,
fetchBusinessListingsCategories,
@@ -43,6 +46,7 @@ export type {
export type { AdsKeywordIdeaItem } from "@/server/lib/dataforseo/google-ads";
export type {
+ LocalSerpTaskOutcome,
SerpLiveItem,
RankCheckResult,
RankCheckTaskInput,
diff --git a/src/server/lib/dataforseo/pricing.test.ts b/src/server/lib/dataforseo/pricing.test.ts
index 52dceeec..fc4bdcb1 100644
--- a/src/server/lib/dataforseo/pricing.test.ts
+++ b/src/server/lib/dataforseo/pricing.test.ts
@@ -118,6 +118,17 @@ describe("dataforseoPricing", () => {
}),
billedUsd: 0.02,
},
+ {
+ name: "Maps tasks queued at high priority",
+ estimateUsd: dataforseoPricing.serp.localTaskPost({
+ keyword: "x",
+ locationCoordinates: ["1,1,13z", "2,2,13z"],
+ languageCode: "en",
+ device: "mobile",
+ depth: 20,
+ }),
+ billedUsd: 0.0024,
+ },
{
name: "Claude response with web search",
estimateUsd: dataforseoPricing.aiSearch.llmResponse({
diff --git a/src/server/lib/dataforseo/pricing.ts b/src/server/lib/dataforseo/pricing.ts
index 3e9cc4d1..05f1b328 100644
--- a/src/server/lib/dataforseo/pricing.ts
+++ b/src/server/lib/dataforseo/pricing.ts
@@ -32,6 +32,7 @@ import {
fetchLiveSerp,
fetchLocalSerp,
fetchRankCheckSerp,
+ postLocalSerpTasks,
postRankCheckTasks,
SERP_ANALYSIS_DEPTH,
} from "@/server/lib/dataforseo/serp";
@@ -131,6 +132,9 @@ const LLM_RESPONSE_USD: Record<
// more. Local Finder bills every page of 10 at the first-page rate ($0.02 at
// depth 100).
const LOCAL_SERP_PAGE_USD = 0.002;
+// SERP Google Maps, queued at high priority. measured: task_post bills $0.0012
+// per task at depth 20.
+const LOCAL_SERP_TASK_USD = 0.0012;
type ProviderUsdEstimator<I> = (input: I) => number;
@@ -253,6 +257,10 @@ export const dataforseoPricing = {
? LOCAL_SERP_PAGE_USD
: Math.ceil(input.depth / 10) * LOCAL_SERP_PAGE_USD,
),
+ localTaskPost: priced(
+ postLocalSerpTasks,
+ (input) => input.locationCoordinates.length * LOCAL_SERP_TASK_USD,
+ ),
},
labs: {
keywordOverview: priced(fetchKeywordOverview, (input) =>
diff --git a/src/server/lib/dataforseo/serp.test.ts b/src/server/lib/dataforseo/serp.test.ts
index 4c43e96b..d839e221 100644
--- a/src/server/lib/dataforseo/serp.test.ts
+++ b/src/server/lib/dataforseo/serp.test.ts
@@ -4,9 +4,12 @@ vi.mock("@/server/lib/runtime-env", () => ({
getRequiredEnvValue: vi.fn(async () => "test-api-key"),
}));
+import { DataforseoChargedTaskError } from "@/server/lib/dataforseo/envelope";
import {
fetchLiveSerp,
+ fetchLocalSerpTaskResult,
fetchRankCheckTaskResult,
+ postLocalSerpTasks,
postRankCheckTasks,
} from "@/server/lib/dataforseo/serp";
@@ -209,3 +212,128 @@ describe("rank check task queue", () => {
});
});
});
+
+describe("Maps task queue", () => {
+ it("posts one task per coordinate, maps ids back by tag, and bills every entry", async () => {
+ const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(
+ Response.json({
+ status_code: 20000,
+ tasks: [
+ {
+ id: "task-c",
+ status_code: 20100,
+ cost: 0.0012,
+ data: { tag: "2" },
+ },
+ {
+ status_code: 40501,
+ status_message: "Invalid Field",
+ cost: 0.0006,
+ data: { tag: "1" },
+ },
+ {
+ id: "task-a",
+ status_code: 20100,
+ cost: 0.0012,
+ data: { tag: "0" },
+ },
+ ],
+ }),
+ );
+ vi.stubGlobal("fetch", fetchMock);
+ vi.spyOn(console, "warn").mockImplementation(() => {});
+
+ const result = await postLocalSerpTasks({
+ keyword: "coffee",
+ locationCoordinates: ["1,1,13z", "2,2,13z", "3,3,13z"],
+ languageCode: "en",
+ device: "mobile",
+ depth: 20,
+ });
+
+ expect(
+ parseDataforseoRequestBody(fetchMock.mock.calls[0]?.[1]),
+ ).toMatchObject([
+ { location_coordinate: "1,1,13z", priority: 2, tag: "0" },
+ { location_coordinate: "2,2,13z", priority: 2, tag: "1" },
+ { location_coordinate: "3,3,13z", priority: 2, tag: "2" },
+ ]);
+ expect(result.data).toEqual(["task-a", null, "task-c"]);
+ // The rejected entry's cost is still metered: a charge is a charge.
+ expect(result.billing.costUsd).toBeCloseTo(0.003, 10);
+ });
+
+ it("keeps DataForSEO's charge when it rejects every entry", async () => {
+ vi.stubGlobal(
+ "fetch",
+ vi.fn<typeof fetch>().mockResolvedValue(
+ Response.json({
+ status_code: 20000,
+ tasks: [
+ {
+ status_code: 40501,
+ status_message: "Invalid Field: 'location_coordinate'.",
+ cost: 0.0012,
+ data: { tag: "0" },
+ },
+ ],
+ }),
+ ),
+ );
+ vi.spyOn(console, "warn").mockImplementation(() => {});
+
+ const posting = postLocalSerpTasks({
+ keyword: "coffee",
+ locationCoordinates: ["1,1,13z"],
+ languageCode: "en",
+ device: "mobile",
+ depth: 20,
+ });
+ // The meter bills a failure only when it is a charged-task error.
+ await expect(posting).rejects.toBeInstanceOf(DataforseoChargedTaskError);
+ await expect(posting).rejects.toMatchObject({
+ billing: { costUsd: 0.0012 },
+ });
+ });
+
+ it("reads a queued Maps task as pending, its items once done, and No Search Results as an empty SERP", async () => {
+ const items = [{ type: "maps_search", rank_absolute: 1, cid: "123" }];
+ vi.stubGlobal(
+ "fetch",
+ vi
+ .fn<typeof fetch>()
+ .mockResolvedValueOnce(
+ Response.json({
+ status_code: 20000,
+ tasks: [{ status_code: 40602 }],
+ }),
+ )
+ .mockResolvedValueOnce(
+ Response.json({
+ status_code: 20000,
+ tasks: [{ status_code: 20000, result: [{ items }] }],
+ }),
+ )
+ .mockResolvedValueOnce(
+ Response.json({
+ status_code: 20000,
+ tasks: [
+ { status_code: 40102, status_message: "No Search Results." },
+ ],
+ }),
+ ),
+ );
+
+ expect(await fetchLocalSerpTaskResult("task-a")).toEqual({
+ status: "pending",
+ });
+ expect(await fetchLocalSerpTaskResult("task-a")).toEqual({
+ status: "completed",
+ items,
+ });
+ expect(await fetchLocalSerpTaskResult("task-b")).toEqual({
+ status: "completed",
+ items: [],
+ });
+ });
+});
diff --git a/src/server/lib/dataforseo/serp.ts b/src/server/lib/dataforseo/serp.ts
index 8ad01c20..93146dc6 100644
--- a/src/server/lib/dataforseo/serp.ts
+++ b/src/server/lib/dataforseo/serp.ts
@@ -1,9 +1,12 @@
+/* eslint-disable max-lines -- one file per DataForSEO section (see index.ts); SERP spans live, rank-check and Maps queue calls */
import { z } from "zod";
import { dataforseoGet, dataforseoPost } from "@/server/lib/dataforseo/core";
import { MAX_TASKS_PER_POST } from "@/server/lib/dataforseo/shared";
import {
assertOk,
buildTaskBilling,
+ DataforseoChargedTaskError,
+ invalidFieldName,
isNoResultsTask,
isTaskInProgress,
parseTaskItems,
@@ -402,3 +405,122 @@ export async function fetchLocalSerp(input: {
billing: buildTaskBilling(task),
};
}
+
+// ---------------------------------------------------------------------------
+// Task-queue Maps searches (local rank grids). One task_post carries every
+// grid point, so DataForSEO runs the searches in parallel instead of a Worker
+// request waiting on them six at a time, and at the queue's lower price.
+// Collection through task_get is free.
+// ---------------------------------------------------------------------------
+
+/** High priority finishes in ~10-40 s; the normal queue takes minutes. */
+const LOCAL_TASK_PRIORITY_HIGH = 2;
+
+/**
+ * Posts one Maps task per coordinate and returns the task ids in input
+ * order, null where DataForSEO rejected an entry. Not retried on a 5xx,
+ * which does not prove the post went unbilled.
+ */
+export async function postLocalSerpTasks(input: {
+ keyword: string;
+ locationCoordinates: string[];
+ languageCode: string;
+ device: "desktop" | "mobile";
+ depth: number;
+}): Promise<DataforseoApiResponse<Array<string | null>>> {
+ const response = await dataforseoPost<
+ DataforseoTaskLike & { id?: string; data?: Record<string, unknown> }
+ >(
+ "/v3/serp/google/maps/task_post",
+ input.locationCoordinates.map((coordinate, index) => ({
+ keyword: input.keyword,
+ location_coordinate: coordinate,
+ language_code: input.languageCode,
+ device: input.device,
+ os: input.device === "desktop" ? "windows" : "android",
+ depth: input.depth,
+ search_places: false,
+ priority: LOCAL_TASK_PRIORITY_HIGH,
+ // Echoed back on each entry, so ids map to points without relying on
+ // response order.
+ tag: String(index),
+ })),
+ { maxServerErrorRetries: 0 },
+ );
+ if (!response || response.status_code !== 20000) {
+ throw new AppError(
+ "INTERNAL_ERROR",
+ response?.status_message || "DataForSEO task_post failed",
+ );
+ }
+
+ // Cost is summed over every entry, accepted or not, so anything DataForSEO
+ // charged is metered.
+ const taskIds: Array<string | null> = input.locationCoordinates.map(
+ () => null,
+ );
+ let costUsd = 0;
+ for (const entry of response.tasks ?? []) {
+ costUsd += entry.cost ?? 0;
+ const index = Number(entry.data?.tag);
+ if (entry.status_code === 20100 && entry.id && taskIds[index] === null) {
+ taskIds[index] = entry.id;
+ } else {
+ console.warn(
+ `dataforseo.task_post.rejected-entry (${entry.status_code}): ${entry.status_message}`,
+ );
+ }
+ }
+ const billing = {
+ path: ["v3", "serp", "google", "maps", "task_post"],
+ costUsd,
+ };
+ if (taskIds.every((id) => id === null)) {
+ // Charged-task error, so the meter still bills whatever DataForSEO
+ // charged, and an uncharged invalid request reads as a validation error.
+ const message =
+ response.tasks?.[0]?.status_message || "DataForSEO created no tasks";
+ throw new DataforseoChargedTaskError(
+ message,
+ billing,
+ invalidFieldName(message) !== null,
+ );
+ }
+ return { data: taskIds, billing };
+}
+
+export type LocalSerpTaskOutcome =
+ | { status: "pending" }
+ | { status: "failed"; message: string }
+ | { status: "completed"; items: Record<string, unknown>[] };
+
+/**
+ * Collects one queued Maps task. Not metered, like fetchRankCheckTaskResult:
+ * the task was charged at task_post.
+ */
+export async function fetchLocalSerpTaskResult(
+ taskId: string,
+): Promise<LocalSerpTaskOutcome> {
+ const response = await dataforseoGet<
+ DataforseoItemsTask<Record<string, unknown>>
+ >(`/v3/serp/google/maps/task_get/advanced/${encodeURIComponent(taskId)}`);
+ const task = response?.tasks?.[0];
+ if (!response || response.status_code !== 20000 || !task) {
+ throw new AppError(
+ "INTERNAL_ERROR",
+ response?.status_message || "DataForSEO task_get failed",
+ );
+ }
+
+ if (isTaskInProgress(task)) return { status: "pending" };
+ if (task.status_code !== 20000) {
+ // "No Search Results" is a billed empty SERP, as on the live path.
+ if (isNoResultsTask(task)) return { status: "completed", items: [] };
+ return {
+ status: "failed",
+ message:
+ task.status_message || `DataForSEO task failed (${task.status_code})`,
+ };
+ }
+ return { status: "completed", items: task.result?.[0]?.items ?? [] };
+}
diff --git a/src/server/mcp/tools/get-serp-results.test.ts b/src/server/mcp/tools/get-serp-results.test.ts
new file mode 100644
index 00000000..cc44f533
--- /dev/null
+++ b/src/server/mcp/tools/get-serp-results.test.ts
@@ -0,0 +1,90 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getSerpResultsTool } from "./get-serp-results";
+import { makeToolContext, textContent } from "./tool-test-support";
+import type * as r2CacheModule from "@/server/lib/r2-cache";
+
+const mocks = vi.hoisted(() => ({
+ createDataforseoClient: vi.fn(),
+ getProjectForOrganization: vi.fn(),
+ cache: new Map<string, unknown>(),
+}));
+
+vi.mock("cloudflare:workers", () => ({
+ env: {},
+ waitUntil: (promise: Promise<unknown>) => promise,
+}));
+vi.mock("@/server/lib/r2-cache", async (importOriginal) => ({
+ ...(await importOriginal<typeof r2CacheModule>()),
+ getCached: async (key: string) => mocks.cache.get(key) ?? null,
+ setCached: async (key: string, value: unknown) => {
+ mocks.cache.set(key, value);
+ },
+}));
+vi.mock("@/server/lib/dataforseo", () => ({
+ createDataforseoClient: mocks.createDataforseoClient,
+ SERP_ANALYSIS_DEPTH: 20,
+}));
+vi.mock("@/server/features/projects/services/ProjectService", () => ({
+ ProjectService: {
+ getProjectForOrganization: mocks.getProjectForOrganization,
+ },
+}));
+
+const toolContext = makeToolContext();
+
+function mockLiveSerp(rows: number) {
+ const live = vi.fn().mockResolvedValue(
+ Array.from({ length: rows }, (_, index) => ({
+ type: "organic",
+ rank_absolute: index + 1,
+ title: `Result ${index + 1}`,
+ url: `https://example.com/${index + 1}`,
+ domain: "example.com",
+ description: "desc",
+ })),
+ );
+ mocks.createDataforseoClient.mockReturnValue({ serp: { live } });
+ return live;
+}
+
+describe("get_serp_results", () => {
+ beforeEach(() => {
+ mocks.cache.clear();
+ mocks.getProjectForOrganization.mockResolvedValue({
+ id: "project_1",
+ locationCode: 2840,
+ languageCode: "en",
+ });
+ });
+
+ it("crawls and returns rows to the requested depth", async () => {
+ const live = mockLiveSerp(40);
+
+ const result = await getSerpResultsTool.handler(
+ {
+ projectId: "project_1",
+ queries: [{ keyword: "seo tools" }],
+ depth: 30,
+ },
+ toolContext,
+ );
+
+ expect(live).toHaveBeenCalledWith(expect.objectContaining({ depth: 30 }));
+ // Rows are trimmed to the depth that was crawled, not the fixed top 20.
+ expect(textContent(result)).toContain('"seo tools" (30 results)');
+ });
+
+ it("answers a repeated query from the saved rows without another paid call", async () => {
+ const live = mockLiveSerp(20);
+ const args = {
+ projectId: "project_1",
+ queries: [{ keyword: "seo tools" }],
+ };
+
+ const first = await getSerpResultsTool.handler(args, toolContext);
+ const repeat = await getSerpResultsTool.handler(args, toolContext);
+
+ expect(live).toHaveBeenCalledTimes(1);
+ expect(repeat.structuredContent).toEqual(first.structuredContent);
+ });
+});
diff --git a/src/server/mcp/tools/get-serp-results.ts b/src/server/mcp/tools/get-serp-results.ts
index b88367d5..7529268b 100644
--- a/src/server/mcp/tools/get-serp-results.ts
+++ b/src/server/mcp/tools/get-serp-results.ts
@@ -1,8 +1,10 @@
+import { waitUntil } from "cloudflare:workers";
import { z } from "zod";
import {
createDataforseoClient,
SERP_ANALYSIS_DEPTH,
} from "@/server/lib/dataforseo";
+import { buildCacheKey, getCached, setCached } from "@/server/lib/r2-cache";
import { mcpResponse } from "@/server/mcp/formatters";
import { buildProjectMeta } from "@/server/mcp/context";
import { optionalMetaOutputSchema } from "@/server/mcp/output-schemas";
@@ -17,14 +19,22 @@ import {
projectIdSchema,
} from "@/server/mcp/schemas";
-type SerpItem = {
- type?: string | null;
- rank: number | null;
- title: string | null;
- url: string | null;
- domain: string | null;
- description: string | null;
-};
+// A repeat within this window is answered from the saved rows, uncharged, so a
+// caller that lost a response can call again instead of paying twice.
+const SERP_RESULTS_CACHE_TTL_SECONDS = 12 * 60 * 60;
+
+const serpItemSchema = z
+ .object({
+ type: z.string().nullable().optional(),
+ rank: z.number().nullable(),
+ title: z.string().nullable(),
+ url: z.string().nullable(),
+ domain: z.string().nullable(),
+ description: z.string().nullable(),
+ })
+ .passthrough();
+
+type SerpItem = z.infer<typeof serpItemSchema>;
const SERP_ITEM_COLUMNS: McpTableColumn<SerpItem>[] = [
{ header: "rank", value: (item) => item.rank },
@@ -74,7 +84,7 @@ export const getSerpResultsTool = {
config: {
title: "Get Google SERP results",
description:
- "Fetch live Google organic search results for 1-10 keywords. Use this to inspect who ranks for a query, verify competitors, compare SERPs across keywords, or gather source URLs before content planning. Returns the top `depth` result rows per keyword (default 20). Charges credits per keyword: ~5 each at the default depth 20, and each additional 10 of depth adds ~2.5. Does not save results to OpenSEO. Per-keyword errors don't fail the batch.",
+ "Fetch live Google organic search results for 1-10 keywords. Use this to inspect who ranks for a query, verify competitors, compare SERPs across keywords, or gather source URLs before content planning. Returns the top `depth` result rows per keyword (default 20). Charges credits per keyword: ~5 each at the default depth 20, and each additional 10 of depth adds ~2.5. A keyword fetched in this project in the last 12 hours with the same market and depth returns those rows again at no charge once the original call has finished, so if a response is lost, wait a minute and repeat the same call. Per-keyword errors don't fail the batch.",
inputSchema,
outputSchema: z.looseObject({
results: z.array(
@@ -83,18 +93,7 @@ export const getSerpResultsTool = {
.object({
keyword: z.string(),
ok: z.literal(true),
- items: z.array(
- z
- .object({
- type: z.string().nullable().optional(),
- rank: z.number().nullable(),
- title: z.string().nullable(),
- url: z.string().nullable(),
- domain: z.string().nullable(),
- description: z.string().nullable(),
- })
- .passthrough(),
- ),
+ items: z.array(serpItemSchema),
})
.passthrough(),
z
@@ -127,6 +126,25 @@ export const getSerpResultsTool = {
q.locationName,
);
}
+ const cacheKey = await buildCacheKey("mcp:serp-results", {
+ organizationId: context.billing.organizationId,
+ projectId: args.projectId,
+ keyword: q.keyword,
+ ...market,
+ locationName: q.locationName,
+ depth,
+ });
+ const cached = z
+ .array(serpItemSchema)
+ .safeParse(await getCached(cacheKey));
+ if (cached.success) {
+ return {
+ keyword: q.keyword,
+ ok: true as const,
+ items: cached.data,
+ };
+ }
+
const items = await client.serp.live({
keyword: q.keyword,
...market,
@@ -142,6 +160,20 @@ export const getSerpResultsTool = {
domain: item.domain ?? null,
description: item.description ?? null,
}));
+ // DataForSEO reports "no results" transiently; don't pin that for
+ // the whole window. waitUntil, not void: workerd cancels
+ // unregistered pending I/O once the response is sent.
+ if (trimmed.length > 0) {
+ waitUntil(
+ setCached(
+ cacheKey,
+ trimmed,
+ SERP_RESULTS_CACHE_TTL_SECONDS,
+ ).catch((error) => {
+ console.error("mcp.serp-results.cache-write failed:", error);
+ }),
+ );
+ }
return { keyword: q.keyword, ok: true as const, items: trimmed };
} catch (error) {
return {
diff --git a/src/server/mcp/tools/local-seo-tools.test.ts b/src/server/mcp/tools/local-seo-tools.test.ts
index d66b4dda..df19ba86 100644
--- a/src/server/mcp/tools/local-seo-tools.test.ts
+++ b/src/server/mcp/tools/local-seo-tools.test.ts
@@ -1,5 +1,4 @@
/* eslint-disable max-lines -- every local-SEO tool is covered in this one spec, matching local-seo-tools.ts */
-import { sort } from "remeda";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { AppError } from "@/server/lib/errors";
import {
@@ -14,7 +13,14 @@ const mocks = vi.hoisted(() => ({
createDataforseoClient: vi.fn(),
fetchBusinessDataTaskResult: vi.fn(),
fetchBusinessListingsCategories: vi.fn(),
+ fetchLocalSerpTaskResult: vi.fn(),
getProjectForOrganization: vi.fn(),
+ localTaskPost:
+ vi.fn<
+ (input: {
+ locationCoordinates: string[];
+ }) => Promise<Array<string | null>>
+ >(),
getCached: vi.fn(),
setCached: vi.fn(),
}));
@@ -25,10 +31,14 @@ vi.mock("@/server/lib/dataforseo", () => ({
createDataforseoClient: mocks.createDataforseoClient,
fetchBusinessDataTaskResult: mocks.fetchBusinessDataTaskResult,
fetchBusinessListingsCategories: mocks.fetchBusinessListingsCategories,
+ fetchLocalSerpTaskResult: mocks.fetchLocalSerpTaskResult,
}));
vi.mock("@/server/lib/r2-cache", () => ({
- buildCacheKey: (prefix: string) => Promise.resolve(`${prefix}:key`),
+ // Distinct params give distinct keys, without the real hash's native async
+ // (which fake timers can't drive).
+ buildCacheKey: async (prefix: string, params: Record<string, unknown>) =>
+ `${prefix}:${JSON.stringify(params)}`,
getCached: mocks.getCached,
setCached: mocks.setCached,
}));
@@ -41,8 +51,6 @@ vi.mock("@/server/features/projects/services/ProjectService", () => ({
const toolContext = makeToolContext();
-const sorted = (values: string[]) => sort(values, (a, b) => a.localeCompare(b));
-
beforeEach(() => {
mocks.getProjectForOrganization.mockResolvedValue({
id: "project_1",
@@ -50,6 +58,7 @@ beforeEach(() => {
languageCode: "en",
});
mocks.getCached.mockResolvedValue(null);
+ mocks.setCached.mockResolvedValue(undefined);
});
describe("get_business_profile", () => {
@@ -228,47 +237,69 @@ describe("get_business_reviews", () => {
});
describe("get_local_rank_grid", () => {
- const gridItems = (items: unknown[]) =>
- vi
- .fn<(input: { locationCoordinate: string }) => Promise<unknown[]>>()
- .mockResolvedValue(items);
- it("searches a 3x3 grid of coordinates around the center", async () => {
- const local = gridItems([]);
- mocks.createDataforseoClient.mockReturnValue({ serp: { local } });
+ const gridArgs = {
+ projectId: "project_1",
+ keyword: "coffee",
+ target: { cid: "123" },
+ center: { latitude: 40, longitude: -74 },
+ };
+ // Receipts persist across calls within a test, as R2 would.
+ const receipts = new Map<string, unknown>();
+
+ beforeEach(() => {
+ receipts.clear();
+ mocks.getCached.mockImplementation(
+ async (key: string) => receipts.get(key) ?? null,
+ );
+ mocks.setCached.mockImplementation(async (key: string, value: unknown) => {
+ receipts.set(key, value);
+ });
+ // One queued task per grid point, named after the point's index.
+ mocks.localTaskPost.mockImplementation(async ({ locationCoordinates }) =>
+ locationCoordinates.map((_, index) => `task-${index}`),
+ );
+ mocks.createDataforseoClient.mockReturnValue({
+ serp: { localTaskPost: mocks.localTaskPost },
+ });
+ completeTasks([]);
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+ function completeTasks(items: unknown[]) {
+ mocks.fetchLocalSerpTaskResult.mockResolvedValue({
+ status: "completed",
+ items,
+ });
+ }
+
+ it("posts one queued search per point of a 3x3 grid, north row first", async () => {
await getLocalRankGridTool.handler(
- {
- projectId: "project_1",
- keyword: "coffee",
- target: { cid: "123" },
- center: { latitude: 40, longitude: -74 },
- spacingKm: 2,
- },
+ { ...gridArgs, spacingKm: 2 },
toolContext,
);
// 2 km spacing at latitude 40: 0.0180874 deg of latitude, 0.0234532 deg of
- // longitude. Row 0 is the northern edge. Every point carries a zoom derived
- // from the spacing (13z here) so each point's viewport spans its neighbours
- // instead of hiding businesses one grid step east or west.
- expect(
- sorted(local.mock.calls.map(([input]) => input.locationCoordinate)),
- ).toEqual(
- sorted([
- "40.0180874,-74.0234532,13z",
- "40.0180874,-74,13z",
- "40.0180874,-73.9765468,13z",
- "40,-74.0234532,13z",
- "40,-74,13z",
- "40,-73.9765468,13z",
- "39.9819126,-74.0234532,13z",
- "39.9819126,-74,13z",
- "39.9819126,-73.9765468,13z",
- ]),
- );
- expect(local).toHaveBeenCalledWith(
+ // longitude. Every point carries a zoom derived from the spacing (13z here)
+ // so each point's viewport spans its neighbours instead of hiding
+ // businesses one grid step east or west. Results map back to points by
+ // position, so the order is part of the contract.
+ expect(mocks.localTaskPost).toHaveBeenCalledTimes(1);
+ expect(mocks.localTaskPost).toHaveBeenCalledWith(
expect.objectContaining({
- searchType: "maps",
+ locationCoordinates: [
+ "40.0180874,-74.0234532,13z",
+ "40.0180874,-74,13z",
+ "40.0180874,-73.9765468,13z",
+ "40,-74.0234532,13z",
+ "40,-74,13z",
+ "40,-73.9765468,13z",
+ "39.9819126,-74.0234532,13z",
+ "39.9819126,-74,13z",
+ "39.9819126,-73.9765468,13z",
+ ],
device: "mobile",
depth: 20,
}),
@@ -276,23 +307,15 @@ describe("get_local_rank_grid", () => {
});
it("ranks by exact cid match and summarizes coverage", async () => {
- const local = gridItems([
+ completeTasks([
{ rank_absolute: 1, title: "Other Cafe", cid: "999" },
{ rank_absolute: 2, title: "Acme Cafe", cid: "123", place_id: "p1" },
]);
- mocks.createDataforseoClient.mockReturnValue({ serp: { local } });
- const result = await getLocalRankGridTool.handler(
- {
- projectId: "project_1",
- keyword: "coffee",
- target: { cid: "123" },
- center: { latitude: 40, longitude: -74 },
- },
- toolContext,
- );
+ const result = await getLocalRankGridTool.handler(gridArgs, toolContext);
expect(result.structuredContent).toMatchObject({
+ status: "completed",
summary: {
pointsSearched: 9,
pointsFound: 9,
@@ -305,114 +328,98 @@ describe("get_local_rank_grid", () => {
});
it("records each point's result count and top business so nulls are interpretable", async () => {
- const local = gridItems([
- { rank_absolute: 1, title: "Other Cafe", cid: "999" },
- ]);
- mocks.createDataforseoClient.mockReturnValue({ serp: { local } });
+ completeTasks([{ rank_absolute: 1, title: "Other Cafe", cid: "999" }]);
- const result = await getLocalRankGridTool.handler(
- {
- projectId: "project_1",
- keyword: "coffee",
- target: { cid: "123" },
- center: { latitude: 40, longitude: -74 },
- },
- toolContext,
- );
+ const result = await getLocalRankGridTool.handler(gridArgs, toolContext);
// The target is absent, but the point still says how contested it was.
- expect(result.structuredContent.grid[0]).toMatchObject({
- rank: null,
- resultsCount: 1,
- topResult: { title: "Other Cafe", cid: "999" },
- });
- });
-
- it("aborts the grid on a credits failure instead of billing every point", async () => {
- const local = vi
- .fn()
- .mockRejectedValue(new AppError("INSUFFICIENT_CREDITS", "No credits"));
- mocks.createDataforseoClient.mockReturnValue({ serp: { local } });
-
- await expect(
- getLocalRankGridTool.handler(
- {
- projectId: "project_1",
- keyword: "coffee",
- target: { cid: "123" },
- center: { latitude: 40, longitude: -74 },
- },
- toolContext,
- ),
- ).rejects.toMatchObject({ code: "INSUFFICIENT_CREDITS" });
- // Only the first batch may have dispatched; later batches must not bill.
- expect(local.mock.calls.length).toBeLessThanOrEqual(3);
+ expect(result.structuredContent).toHaveProperty(
+ "grid.0",
+ expect.objectContaining({
+ rank: null,
+ resultsCount: 1,
+ topResult: { title: "Other Cafe", cid: "999" },
+ }),
+ );
});
it("falls back to a case-insensitive title match", async () => {
- const local = gridItems([
- { rank_absolute: 4, title: "ACME Cafe Downtown" },
- ]);
- mocks.createDataforseoClient.mockReturnValue({ serp: { local } });
+ completeTasks([{ rank_absolute: 4, title: "ACME Cafe Downtown" }]);
const result = await getLocalRankGridTool.handler(
- {
- projectId: "project_1",
- keyword: "coffee",
- target: { name: "acme cafe" },
- center: { latitude: 40, longitude: -74 },
- },
+ { ...gridArgs, target: { name: "acme cafe" } },
toolContext,
);
- expect(result.structuredContent.summary).toMatchObject({
- pointsFound: 9,
- averageRank: 4,
+ expect(result.structuredContent).toMatchObject({
+ summary: { pointsFound: 9, averageRank: 4 },
});
});
- it("keeps the grid when a single point fails", async () => {
- let call = 0;
- const local = vi.fn().mockImplementation(() => {
- call += 1;
- return call === 1
- ? Promise.reject(new Error("upstream blew up"))
- : Promise.resolve([{ rank_absolute: 3, cid: "123" }]);
- });
- mocks.createDataforseoClient.mockReturnValue({ serp: { local } });
-
- const result = await getLocalRankGridTool.handler(
- {
- projectId: "project_1",
- keyword: "coffee",
- target: { cid: "123" },
- center: { latitude: 40, longitude: -74 },
- },
- toolContext,
+ it("keeps the grid when DataForSEO refuses one point's search", async () => {
+ mocks.localTaskPost.mockImplementation(async ({ locationCoordinates }) =>
+ locationCoordinates.map((_, index) =>
+ index === 0 ? null : `task-${index}`,
+ ),
);
+ completeTasks([{ rank_absolute: 3, cid: "123" }]);
+
+ const result = await getLocalRankGridTool.handler(gridArgs, toolContext);
- expect(result.structuredContent.summary).toMatchObject({
- pointsSearched: 9,
- pointsFound: 8,
+ expect(result.structuredContent).toMatchObject({
+ status: "completed",
+ summary: { pointsSearched: 9, pointsFound: 8 },
});
- expect(textContent(result)).toContain("x");
+ expect(result.structuredContent).toHaveProperty("grid.0.error", true);
});
- it("surfaces the upstream error when every point fails", async () => {
- const local = vi.fn().mockRejectedValue(new Error("upstream blew up"));
- mocks.createDataforseoClient.mockReturnValue({ serp: { local } });
+ it("surfaces the upstream error when every search fails, and lets a retry post fresh searches", async () => {
+ mocks.fetchLocalSerpTaskResult.mockResolvedValue({
+ status: "failed",
+ message: "Internal Error.",
+ });
+
+ const failing = getLocalRankGridTool.handler(gridArgs, toolContext);
+ await expect(failing).rejects.toMatchObject({
+ code: "UPSTREAM_UNAVAILABLE",
+ });
+ await expect(failing).rejects.toThrow("Internal Error.");
await expect(
- getLocalRankGridTool.handler(
- {
- projectId: "project_1",
- keyword: "coffee",
- target: { cid: "123" },
- center: { latitude: 40, longitude: -74 },
- },
- toolContext,
- ),
- ).rejects.toThrow("upstream blew up");
+ getLocalRankGridTool.handler(gridArgs, toolContext),
+ ).rejects.toThrow();
+ expect(mocks.localTaskPost).toHaveBeenCalledTimes(2);
+ });
+
+ it("answers processing while the searches run, and collects them on a repeat without buying them again", async () => {
+ mocks.fetchLocalSerpTaskResult.mockResolvedValue({ status: "pending" });
+
+ vi.useFakeTimers();
+ const first = getLocalRankGridTool.handler(gridArgs, toolContext);
+ await vi.runAllTimersAsync();
+ expect((await first).structuredContent).toMatchObject({
+ status: "processing",
+ pointsReady: 0,
+ pointsTotal: 9,
+ });
+
+ completeTasks([{ rank_absolute: 2, cid: "123" }]);
+ const repeat = await getLocalRankGridTool.handler(gridArgs, toolContext);
+ expect(repeat.structuredContent).toMatchObject({
+ status: "completed",
+ summary: { pointsFound: 9 },
+ });
+ expect(mocks.localTaskPost).toHaveBeenCalledTimes(1);
+ });
+
+ it("posts its own searches for a grid with different arguments", async () => {
+ await getLocalRankGridTool.handler(gridArgs, toolContext);
+ await getLocalRankGridTool.handler(
+ { ...gridArgs, keyword: "tea" },
+ toolContext,
+ );
+
+ expect(mocks.localTaskPost).toHaveBeenCalledTimes(2);
});
});
diff --git a/src/server/mcp/tools/local-seo-tools.ts b/src/server/mcp/tools/local-seo-tools.ts
index f1f3bee3..d51a35c5 100644
--- a/src/server/mcp/tools/local-seo-tools.ts
+++ b/src/server/mcp/tools/local-seo-tools.ts
@@ -4,8 +4,10 @@ import {
createDataforseoClient,
fetchBusinessDataTaskResult,
fetchBusinessListingsCategories,
+ fetchLocalSerpTaskResult,
type BusinessTaskEndpoint,
type BusinessTaskOutcome,
+ type LocalSerpTaskOutcome,
} from "@/server/lib/dataforseo";
import { AppError } from "@/server/lib/errors";
import { buildCacheKey, getCached, setCached } from "@/server/lib/r2-cache";
@@ -677,7 +679,16 @@ const KM_PER_DEGREE_LATITUDE = 110.574;
const KM_PER_DEGREE_LONGITUDE = 111.32;
const MIN_LONGITUDE_COSINE = 0.01;
const RANK_GRID_DEPTH = 20;
-const RANK_GRID_CONCURRENCY = 3;
+// The grid's searches run as queued Maps tasks (~5-40 s each, in parallel at
+// DataForSEO). Polling stops 40 s into the call so it answers inside the 60 s
+// many MCP clients wait; tasks still running are collected by the next call.
+const RANK_GRID_COLLECT_MS = 40_000;
+const RANK_GRID_POLL_INTERVAL_MS = 5000;
+// The posted task ids are the grid's receipt: the same grid again within this
+// window collects those searches instead of buying them twice, so a caller
+// that lost the response, or got "processing", can simply call again.
+const RANK_GRID_RECEIPT_TTL_SECONDS = 60 * 60;
+const rankGridReceiptSchema = z.array(z.string().nullable());
// Without an explicit zoom DataForSEO infers one per coordinate, which yields
// "No Search Results" for some points and makes ranks incomparable across the
// grid. A fixed zoom fails the other way: a mobile viewport at zoom 14 spans
@@ -843,13 +854,34 @@ function matchGridItem(
});
}
-// A per-point failure usually means only that point's SERP failed, but these
-// codes mean every remaining call would fail (and possibly bill) the same way —
-// surface them instead of rendering a misleading grid.
-const GRID_ABORT_ERROR_CODES = new Set<string>([
- "INSUFFICIENT_CREDITS",
- "DATAFORSEO_AUTH_FAILED",
-]);
+/** Polls one grid task until it finishes or the deadline passes. */
+async function collectRankGridTask(
+ taskId: string | null,
+ deadline: number,
+): Promise<LocalSerpTaskOutcome> {
+ // A point DataForSEO refused at post time has no task to collect.
+ if (!taskId) {
+ return {
+ status: "failed",
+ message: "DataForSEO did not accept this search.",
+ };
+ }
+ for (;;) {
+ const outcome = await fetchLocalSerpTaskResult(taskId);
+ if (outcome.status === "failed") {
+ console.warn(
+ `[local-rank-grid] task ${taskId} failed: ${outcome.message}`,
+ );
+ }
+ if (
+ outcome.status !== "pending" ||
+ Date.now() + RANK_GRID_POLL_INTERVAL_MS > deadline
+ ) {
+ return outcome;
+ }
+ await wait(RANK_GRID_POLL_INTERVAL_MS);
+ }
+}
function renderGrid(results: GridPointResult[], gridSize: number): string {
const lines: string[] = [];
@@ -870,41 +902,50 @@ export const getLocalRankGridTool = {
config: {
title: "Get local rank grid",
description:
- "Runs one Google Maps search per point of a square grid around a coordinate and reports where the target business ranks at each point — plus each point's result count and #1 business — revealing how far its Maps visibility reaches. Cost scales with the grid: gridSize squared SERP calls (3x3 = 9, the sensible default; 5x5 = 25). Charges credits per grid point.",
+ "Runs one Google Maps search per point of a square grid around a coordinate and reports where the target business ranks at each point — plus each point's result count and #1 business — revealing how far its Maps visibility reaches. Cost scales with the grid: gridSize squared SERP calls (3x3 = 9, the sensible default; 5x5 = 25). Charges credits per grid point. The searches run as one queued batch that usually finishes within this call; if some are still running you get status 'processing'. Calling again with the same arguments within an hour collects the same searches at no extra charge, so repeat the call in about a minute to finish a 'processing' grid or to recover a lost response.",
inputSchema: getLocalRankGridInputSchema,
outputSchema: z.looseObject({
- grid: z.array(
- z.looseObject({
- row: z.number(),
- col: z.number(),
- latitude: z.number(),
- longitude: z.number(),
- rank: z.number().nullable(),
- resultsCount: z.number().optional(),
- topResult: z
- .looseObject({
- title: z.string().nullable(),
- cid: z.string().nullable(),
- })
- .nullable()
- .optional(),
- error: z.boolean().optional(),
- }),
- ),
- summary: z.looseObject({
- pointsSearched: z.number(),
- pointsFound: z.number(),
- averageRank: z.number().nullable(),
- top3Count: z.number(),
- top10Count: z.number(),
- }),
+ status: z.enum(["completed", "processing"]),
+ pointsReady: z.number().optional(),
+ pointsTotal: z.number().optional(),
+ retryAfterSeconds: z.number().optional(),
+ grid: z
+ .array(
+ z.looseObject({
+ row: z.number(),
+ col: z.number(),
+ latitude: z.number(),
+ longitude: z.number(),
+ rank: z.number().nullable(),
+ resultsCount: z.number().optional(),
+ topResult: z
+ .looseObject({
+ title: z.string().nullable(),
+ cid: z.string().nullable(),
+ })
+ .nullable()
+ .optional(),
+ error: z.boolean().optional(),
+ }),
+ )
+ .optional(),
+ summary: z
+ .looseObject({
+ pointsSearched: z.number(),
+ pointsFound: z.number(),
+ averageRank: z.number().nullable(),
+ top3Count: z.number(),
+ top10Count: z.number(),
+ })
+ .optional(),
matchedBusiness: z
.looseObject({
title: z.string().nullable(),
cid: z.string().nullable(),
placeId: z.string().nullable(),
})
- .nullable(),
+ .nullable()
+ .optional(),
...optionalMetaOutputSchema,
}),
annotations: {
@@ -925,73 +966,128 @@ export const getLocalRankGridTool = {
);
}
+ const deadline = Date.now() + RANK_GRID_COLLECT_MS;
const gridSize = args.gridSize ?? 3;
const spacingKm = args.spacingKm ?? 2;
const zoom = args.zoom ?? rankGridZoom(spacingKm, args.center.latitude);
- const points = buildRankGridPoints(args.center, gridSize, spacingKm);
- const client = createDataforseoClient(context.billing);
+ const device = args.device ?? "mobile";
const languageCode = args.languageCode ?? context.project.languageCode;
+ const points = buildRankGridPoints(args.center, gridSize, spacingKm);
+
+ // The target is not part of the key: it only filters the collected rows.
+ const receiptKey = await buildCacheKey("mcp:local-rank-grid", {
+ organizationId: context.billing.organizationId,
+ projectId: args.projectId,
+ keyword: args.keyword,
+ latitude: args.center.latitude,
+ longitude: args.center.longitude,
+ gridSize,
+ spacingKm,
+ zoom,
+ device,
+ languageCode,
+ });
+ const receipt = rankGridReceiptSchema.safeParse(
+ await getCached(receiptKey),
+ );
+ let taskIds: Array<string | null>;
+ if (receipt.success) {
+ taskIds = receipt.data;
+ } else {
+ // Only the post is metered; collection is free.
+ taskIds = await createDataforseoClient(
+ context.billing,
+ ).serp.localTaskPost({
+ keyword: args.keyword,
+ locationCoordinates: points.map((point) =>
+ formatLocalSerpCoordinate({ ...point, zoom }),
+ ),
+ languageCode,
+ device,
+ depth: RANK_GRID_DEPTH,
+ });
+ // The searches are already paid for, so a failed receipt write must not
+ // fail this call; it only means a repeat would buy them again.
+ await setCached(receiptKey, taskIds, RANK_GRID_RECEIPT_TTL_SECONDS).catch(
+ (error) => {
+ console.error("[local-rank-grid] receipt write failed:", error);
+ },
+ );
+ }
+
+ const outcomes = await Promise.all(
+ taskIds.map((taskId) => collectRankGridTask(taskId, deadline)),
+ );
+ const ready = outcomes.filter(
+ (outcome) => outcome.status !== "pending",
+ ).length;
+ if (ready < points.length) {
+ return mcpResponse({
+ text: `Local rank grid for "${args.keyword}": ${ready} of ${points.length} searches are back. Call get_local_rank_grid again with the same arguments in about a minute to collect the rest; that charges no extra credits.`,
+ meta: buildProjectMeta(context, args.projectId, `/p/${args.projectId}`),
+ // Clients that read only structured results still see the progress
+ // and when to call again.
+ structuredContent: {
+ status: "processing",
+ pointsReady: ready,
+ pointsTotal: points.length,
+ retryAfterSeconds: 60,
+ },
+ });
+ }
+
+ // Every search failing means a systemic failure, not a business that
+ // simply doesn't rank — surface it instead of an empty grid.
+ const failures = outcomes.flatMap((outcome) =>
+ outcome.status === "failed" ? [outcome.message] : [],
+ );
+ if (failures.length === points.length) {
+ // Forget the receipt so a retry posts fresh searches instead of
+ // replaying this failure for the next hour.
+ await setCached(receiptKey, null, 0).catch((error) => {
+ console.error("[local-rank-grid] receipt reset failed:", error);
+ });
+ throw new AppError(
+ "UPSTREAM_UNAVAILABLE",
+ `Every grid search failed at DataForSEO: ${failures[0]}`,
+ );
+ }
let matchedBusiness: {
title: string | null;
cid: string | null;
placeId: string | null;
} | null = null;
- let lastError: unknown = null;
-
- const searchPoint = async (point: GridPoint): Promise<GridPointResult> => {
- try {
- const items = await client.serp.local({
- keyword: args.keyword,
- locationCoordinate: formatLocalSerpCoordinate({ ...point, zoom }),
- languageCode,
- searchType: "maps",
- device: args.device ?? "mobile",
- depth: RANK_GRID_DEPTH,
- searchPlaces: false,
- });
- const match = matchGridItem(items, args.target);
- if (match && !matchedBusiness) {
- matchedBusiness = {
- title: readString(match, "title"),
- cid: readString(match, "cid"),
- placeId: readString(match, "place_id"),
- };
- }
- const rank =
- readPath(match, "rank_absolute") ?? readPath(match, "rank_group");
- const first = items[0];
- return {
- ...point,
- rank: typeof rank === "number" ? rank : null,
- resultsCount: items.length,
- topResult:
- first == null
- ? null
- : {
- title: readString(first, "title"),
- cid: readString(first, "cid"),
- },
- };
- } catch (error) {
- if (error instanceof AppError && GRID_ABORT_ERROR_CODES.has(error.code))
- throw error;
- lastError = error;
+ const grid = points.map((point, index): GridPointResult => {
+ const outcome = outcomes[index];
+ if (outcome.status !== "completed") {
return { ...point, rank: null, error: true };
}
- };
-
- // A few points at a time; an abort-worthy failure rejects its batch and
- // stops later batches from dispatching (and billing).
- const grid: GridPointResult[] = [];
- for (let i = 0; i < points.length; i += RANK_GRID_CONCURRENCY) {
- const batch = points.slice(i, i + RANK_GRID_CONCURRENCY);
- grid.push(...(await Promise.all(batch.map(searchPoint))));
- }
-
- // Every point failing means a systemic failure (auth, balance, bad market),
- // not a business that simply doesn't rank — surface it instead of an empty grid.
- if (grid.every((point) => point.error)) throw lastError;
+ const { items } = outcome;
+ const match = matchGridItem(items, args.target);
+ if (match && !matchedBusiness) {
+ matchedBusiness = {
+ title: readString(match, "title"),
+ cid: readString(match, "cid"),
+ placeId: readString(match, "place_id"),
+ };
+ }
+ const rank =
+ readPath(match, "rank_absolute") ?? readPath(match, "rank_group");
+ const first = items[0];
+ return {
+ ...point,
+ rank: typeof rank === "number" ? rank : null,
+ resultsCount: items.length,
+ topResult:
+ first == null
+ ? null
+ : {
+ title: readString(first, "title"),
+ cid: readString(first, "cid"),
+ },
+ };
+ });
const found = grid.filter((point) => point.rank != null);
const ranks = found.map((point) => point.rank ?? 0);
@@ -1021,7 +1117,12 @@ export const getLocalRankGridTool = {
return mcpResponse({
text,
meta: buildProjectMeta(context, args.projectId, `/p/${args.projectId}`),
- structuredContent: { grid, summary, matchedBusiness },
+ structuredContent: {
+ status: "completed",
+ grid,
+ summary,
+ matchedBusiness,
+ },
});
}),
};
diff --git a/src/server/mcp/tools/tool-text-output.test.ts b/src/server/mcp/tools/tool-text-output.test.ts
index 60ffbcf0..5cf56ad9 100644
--- a/src/server/mcp/tools/tool-text-output.test.ts
+++ b/src/server/mcp/tools/tool-text-output.test.ts
@@ -11,7 +11,6 @@ import {
} from "./google-analytics-tools";
import { getRankTrackerTool } from "./get-rank-tracker";
import { getBusinessUpdatesTool } from "./local-seo-tools";
-import { getSerpResultsTool } from "./get-serp-results";
import { makeToolContext, textContent } from "./tool-test-support";
import { makeGa4ReportResult } from "@/server/features/ga4/services/ga4-test-fixtures";
import type * as backlinksTargetModule from "@/server/lib/dataforseoBacklinksTarget";
@@ -45,7 +44,6 @@ vi.mock("@/server/lib/dataforseo", async () => {
createDataforseoClient: mocks.createDataforseoClient,
fetchBusinessDataTaskResult: mocks.fetchBusinessDataTaskResult,
normalizeBacklinksTarget: targets.normalizeBacklinksTarget,
- SERP_ANALYSIS_DEPTH: 20,
};
});
vi.mock("@/server/features/projects/services/ProjectService", () => ({
@@ -273,33 +271,6 @@ describe("MCP tool text output (service-backed tools)", () => {
);
});
- it("get_serp_results crawls and returns rows to the requested depth", async () => {
- const live = vi.fn().mockResolvedValue(
- Array.from({ length: 40 }, (_, index) => ({
- type: "organic",
- rank_absolute: index + 1,
- title: `Result ${index + 1}`,
- url: `https://example.com/${index + 1}`,
- domain: "example.com",
- description: "desc",
- })),
- );
- mocks.createDataforseoClient.mockReturnValue({ serp: { live } });
-
- const result = await getSerpResultsTool.handler(
- {
- projectId: "project_1",
- queries: [{ keyword: "seo tools" }],
- depth: 30,
- },
- toolContext,
- );
-
- expect(live).toHaveBeenCalledWith(expect.objectContaining({ depth: 30 }));
- // Rows are trimmed to the depth that was crawled, not the fixed top 20.
- expect(textContent(result)).toContain('"seo tools" (30 results)');
- });
-
it("get_google_analytics_organic_landing_pages renders every fetched row and points at offset paging", async () => {
const rows = Array.from({ length: 16 }, (_, index) => ({
hostName: "example.com",