Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
import type { GscSearchAnalyticsRequest } from "@/server/lib/gscClient";
// Shared option sets — also drive the MCP tool Zod schemas so the two stay in sync.
export const GSC_DIMENSIONS = [
"query",
"page",
"country",
"device",
"date",
"searchAppearance",
] as const;
export const GSC_FILTER_OPERATORS = [
"equals",
"notEquals",
"contains",
"notContains",
] as const;
export const GSC_SEARCH_TYPES = [
"web",
"image",
"video",
"news",
"googleNews",
"discover",
] as const;
export const GSC_DATE_RANGES = [
"last_7_days",
"last_28_days",
"last_3_months",
"last_6_months",
"last_12_months",
"last_16_months",
] as const;
// 250 rows fits comfortably inside one MCP tool result; the agent opts into
// more with `rowLimit` or paginates with `startRow`.
export const GSC_DEFAULT_ROW_LIMIT = 250;
// v1 caps rows-per-call at 1000 to protect the MCP context window. The GSC API
// supports up to 25000, but we keep fetched == returned so counts stay honest;
// the agent paginates with `startRow` for more.
export const GSC_MAX_ROW_LIMIT = 1000;
// GSC data trails by ~2-3 days; default the end of convenience ranges before it.
const GSC_DATA_LAG_DAYS = 3;
export type GscDimension = (typeof GSC_DIMENSIONS)[number];
type GscFilterOperator = (typeof GSC_FILTER_OPERATORS)[number];
export type GscSearchType = (typeof GSC_SEARCH_TYPES)[number];
export type GscDateRange = (typeof GSC_DATE_RANGES)[number];
export type GscPerformanceFilter = {
dimension: GscDimension;
operator: GscFilterOperator;
expression: string;
};
export type GscPerformanceInput = {
projectId: string;
dimensions?: GscDimension[];
dateRange?: GscDateRange;
startDate?: string;
endDate?: string;
filters?: GscPerformanceFilter[];
rowLimit?: number;
startRow?: number;
type?: GscSearchType;
dataState?: "all" | "final";
};
function clamp(value: number, min: number, max: number): number {
return Math.min(Math.max(value, min), max);
}
function formatDate(date: Date): string {
return date.toISOString().slice(0, 10);
}
// Subtract calendar months in UTC, clamping the day to the target month's length.
function subtractUtcMonths(date: Date, months: number): Date {
const day = date.getUTCDate();
const d = new Date(date);
d.setUTCDate(1);
d.setUTCMonth(d.getUTCMonth() - months);
const daysInTargetMonth = new Date(
Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0),
).getUTCDate();
d.setUTCDate(Math.min(day, daysInTargetMonth));
return d;
}
// GSC treats both startDate and endDate as inclusive, so an N-day window starts N-1 days before the end.
function subtractRange(end: Date, range: GscDateRange): Date {
const d = new Date(end);
switch (range) {
case "last_7_days":
d.setUTCDate(d.getUTCDate() - 6);
break;
case "last_28_days":
d.setUTCDate(d.getUTCDate() - 27);
break;
case "last_3_months":
return subtractUtcMonths(d, 3);
case "last_6_months":
return subtractUtcMonths(d, 6);
case "last_12_months":
return subtractUtcMonths(d, 12);
case "last_16_months":
return subtractUtcMonths(d, 16);
}
return d;
}
function sixteenMonthFloor(today: Date): string {
return formatDate(subtractUtcMonths(today, 16));
}
/** Resolve a convenience `dateRange` or explicit start/end into GSC dates.
* `today` is injectable for deterministic tests. */
export function resolveDateRange(
input: Pick<GscPerformanceInput, "dateRange" | "startDate" | "endDate">,
today: Date = new Date(),
): { startDate: string; endDate: string } {
const floor = sixteenMonthFloor(today);
if (input.startDate && input.endDate) {
// Clamp the start to GSC's 16-month lower bound.
const startDate = input.startDate < floor ? floor : input.startDate;
return { startDate, endDate: input.endDate };
}
const end = new Date(today);
end.setUTCDate(end.getUTCDate() - GSC_DATA_LAG_DAYS);
const start = subtractRange(end, input.dateRange ?? "last_28_days");
const startDate = formatDate(start);
return {
startDate: startDate < floor ? floor : startDate,
endDate: formatDate(end),
};
}
/** Build the GSC `searchAnalytics.query` body from validated tool input.
* Critically, flat `filters` are wrapped into `dimensionFilterGroups` — GSC
* silently ignores a top-level `filters` field. */
export function buildSearchAnalyticsRequest(
input: GscPerformanceInput,
today: Date = new Date(),
): GscSearchAnalyticsRequest {
const { startDate, endDate } = resolveDateRange(input, today);
const request: GscSearchAnalyticsRequest = {
startDate,
endDate,
dimensions:
input.dimensions && input.dimensions.length > 0
? input.dimensions
: ["query"],
rowLimit: clamp(
input.rowLimit ?? GSC_DEFAULT_ROW_LIMIT,
1,
GSC_MAX_ROW_LIMIT,
),
type: input.type ?? "web",
dataState: input.dataState ?? "all",
};
if (input.startRow && input.startRow > 0) {
request.startRow = input.startRow;
}
if (input.filters && input.filters.length > 0) {
request.dimensionFilterGroups = [
{ groupType: "and", filters: input.filters },
];
}
return request;
}