Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
fix(ga4): honor full date ranges instead of clamping to 90 days (#563)
Ben Senescuad2d28ea6fdd
diff --git a/specs/0007-google-analytics-mcp-integration.md b/specs/0007-google-analytics-mcp-integration.mdindex e70522d4..7e520996 100644--- a/specs/0007-google-analytics-mcp-integration.md+++ b/specs/0007-google-analytics-mcp-integration.md@@ -127,12 +127,14 @@ common input:| `offset` | Non-negative integer; default 0 |With no explicit dates, the range is the last 28 complete days in the GA4-property time zone. Explicit ranges are inclusive. The report builder caps the-end at the last complete property day and moves the start forward when the-range exceeds 90 days. The response returns requested and resolved dates plus-`end_date_clamped` or `start_date_clamped` warnings. Invalid date formats,-reversed dates, and a single date without its pair return `validation_error`-before an API call.+property time zone. Explicit ranges are inclusive and honored in full; there is+no maximum range. The report builder caps the end at the last complete property+day. The response returns requested and resolved dates plus an+`end_date_clamped` warning, which the text output also states. The organic+overview trend is capped at 1,000 rows and reports `trend_truncated` (also+stated in the text) when a range exceeds that. Invalid date+formats, reversed dates, and a single date without its pair return+`validation_error` before an API call.Only these tool-specific inputs are accepted:diff --git a/src/server/features/ga4/services/Ga4OrganicOverviewService.test.ts b/src/server/features/ga4/services/Ga4OrganicOverviewService.test.tsindex 10bd0f75..25959f5d 100644--- a/src/server/features/ga4/services/Ga4OrganicOverviewService.test.ts+++ b/src/server/features/ga4/services/Ga4OrganicOverviewService.test.ts@@ -36,7 +36,7 @@ describe("Ga4OrganicOverviewService", () => {mocks.getByProjectId.mockResolvedValue(connection);});- it("returns an equal-length comparison and weekly trend", async () => {+ it("returns an equal-length comparison and flags a truncated trend", async () => {mocks.runReport.mockResolvedValueOnce({dimensionHeaders: [],@@ -93,7 +93,7 @@ describe("Ga4OrganicOverviewService", () => {]),},],- rowCount: 1,+ rowCount: 1200,});const result = await Ga4OrganicOverviewService.getOrganicOverview({@@ -120,6 +120,7 @@ describe("Ga4OrganicOverviewService", () => {sessions: 100,});expect(result.diagnostics).toEqual([]);+ expect(result.warnings).toEqual(["trend_truncated"]);expect(mocks.runReport).toHaveBeenCalledTimes(3);});diff --git a/src/server/features/ga4/services/Ga4OrganicOverviewService.ts b/src/server/features/ga4/services/Ga4OrganicOverviewService.tsindex 058cdbf6..04505217 100644--- a/src/server/features/ga4/services/Ga4OrganicOverviewService.ts+++ b/src/server/features/ga4/services/Ga4OrganicOverviewService.ts@@ -142,7 +142,12 @@ async function getOrganicOverview(reports: reports.map((report) => report.reportMetadata),},quota: trendReport.quota ?? current.quota,- warnings: dateRange.warnings,+ warnings: [+ ...dateRange.warnings,+ ...(trendReport.totalRowCount > trendReport.rows.length+ ? ["trend_truncated"]+ : []),+ ],};} catch (error) {mapGa4ReportError(error);diff --git a/src/server/features/ga4/services/Ga4ReportingService.test.ts b/src/server/features/ga4/services/Ga4ReportingService.test.tsindex 1ab8dfb9..b7455fe7 100644--- a/src/server/features/ga4/services/Ga4ReportingService.test.ts+++ b/src/server/features/ga4/services/Ga4ReportingService.test.ts@@ -134,7 +134,7 @@ describe("Ga4ReportingService", () => {});});- it("clamps explicit dates and nulls restricted metrics", async () => {+ it("clamps a future endDate, keeps a long startDate, and nulls restricted metrics", async () => {mocks.runReport.mockResolvedValue({...landingHeaders,rows: [@@ -168,10 +168,10 @@ describe("Ga4ReportingService", () => {);expect(result.request.resolvedDateRange).toEqual({- startDate: "2026-05-08",+ startDate: "2025-01-01",endDate: "2026-08-05",});- expect(result.warnings).toEqual(["end_date_clamped", "start_date_clamped"]);+ expect(result.warnings).toEqual(["end_date_clamped"]);expect(result.rows[0]?.purchaseRevenue).toBeNull();});diff --git a/src/server/features/ga4/services/Ga4ReportingService.ts b/src/server/features/ga4/services/Ga4ReportingService.tsindex 9b3eb776..d62b0b4c 100644--- a/src/server/features/ga4/services/Ga4ReportingService.ts+++ b/src/server/features/ga4/services/Ga4ReportingService.ts@@ -87,17 +87,12 @@ export function resolveGa4DateRange(-1,);let endDate = requestedDateRange?.endDate ?? lastCompleteDay;- let startDate = requestedDateRange?.startDate ?? shiftGa4Date(endDate, -27);+ const startDate = requestedDateRange?.startDate ?? shiftGa4Date(endDate, -27);const warnings: string[] = [];if (endDate > lastCompleteDay) {endDate = lastCompleteDay;warnings.push("end_date_clamped");}- const ninetyDayFloor = shiftGa4Date(endDate, -89);- if (startDate < ninetyDayFloor) {- startDate = ninetyDayFloor;- warnings.push("start_date_clamped");- }if (startDate > endDate) {throw new Ga4ReportError("validation_error",diff --git a/src/server/mcp/tools/google-analytics-tools.test.ts b/src/server/mcp/tools/google-analytics-tools.test.tsindex 912e5f4f..b94c225f 100644--- a/src/server/mcp/tools/google-analytics-tools.test.ts+++ b/src/server/mcp/tools/google-analytics-tools.test.ts@@ -253,6 +253,7 @@ describe("Google Analytics MCP tools", () => {},comparison: {},trend: [],+ warnings: [],});mocks.getMeasurementHealth.mockResolvedValue({status: "ok",diff --git a/src/server/mcp/tools/google-analytics-tools.ts b/src/server/mcp/tools/google-analytics-tools.tsindex fda37e8f..a5899f37 100644--- a/src/server/mcp/tools/google-analytics-tools.ts+++ b/src/server/mcp/tools/google-analytics-tools.ts@@ -257,6 +257,15 @@ function emptyOrganicHint(result: Ga4ReportResult): string {: " This report is limited to Organic Search.";}+function endDateClampNote(result: {+ warnings: string[];+ request: { resolvedDateRange: { endDate: string } };+}) {+ return result.warnings.includes("end_date_clamped")+ ? ` The requested endDate was moved back to ${result.request.resolvedDateRange.endDate}, the last complete Analytics day.`+ : "";+}+function reportText(label: string, result: Ga4ReportResult) {const range = result.request.resolvedDateRange;const comparison = result.comparison@@ -272,7 +281,7 @@ function reportText(label: string, result: Ga4ReportResult) {const paginate = result.pageInfo.hasMore? " More rows are available; call again with offset to page through them.": "";- const summary = `${label}: ${result.rowCount} of ${result.totalRowCount} rows for ${range.startDate} through ${range.endDate}.${comparison}${diagnostics}${limited}${emptyOrganicHint(result)}${paginate}`;+ const summary = `${label}: ${result.rowCount} of ${result.totalRowCount} rows for ${range.startDate} through ${range.endDate}.${endDateClampNote(result)}${comparison}${diagnostics}${limited}${emptyOrganicHint(result)}${paginate}`;if (result.rows.length === 0) return summary;return `${summary}\n${formatMcpTable(result.rows, reportTableColumns(result))}`;}@@ -280,7 +289,10 @@ function reportText(label: string, result: Ga4ReportResult) {function overviewText(result: Ga4OverviewResult) {const range = result.request.resolvedDateRange;const previousRange = result.request.previousDateRange;- const summary = `Organic overview for ${range.startDate} through ${range.endDate}, compared with ${previousRange.startDate} through ${previousRange.endDate}.`;+ const trendTruncated = result.warnings.includes("trend_truncated")+ ? ` The trend was cut at ${result.trend.length} rows; use trend=weekly or a shorter date range for the full series.`+ : "";+ const summary = `Organic overview for ${range.startDate} through ${range.endDate}, compared with ${previousRange.startDate} through ${previousRange.endDate}.${endDateClampNote(result)}${trendTruncated}`;if (!result.current) {return `${summary} No Organic Search rows for this date range.`;}diff --git a/src/server/mcp/tools/tool-text-output.test.ts b/src/server/mcp/tools/tool-text-output.test.tsindex 6c1a7a5f..791b9ebd 100644--- a/src/server/mcp/tools/tool-text-output.test.ts+++ b/src/server/mcp/tools/tool-text-output.test.ts@@ -552,6 +552,21 @@ describe("MCP tool text output (service-backed tools)", () => {);});+ it("get_google_analytics_organic_landing_pages states an end-date clamp", async () => {+ mocks.runGa4Report.mockResolvedValue(+ makeGa4ReportResult({ warnings: ["end_date_clamped"] }),+ );++ const result = await getGoogleAnalyticsOrganicLandingPagesTool.handler(+ { projectId: "project_1", limit: 100, offset: 0 },+ toolContext,+ );++ expect(textContent(result)).toEqual(+ "Organic landing pages: 0 of 0 rows for 2026-07-09 through 2026-08-05. The requested endDate was moved back to 2026-08-05, the last complete Analytics day. This report is limited to Organic Search.",+ );+ });+it("get_google_analytics_traffic_acquisition does not mention Organic Search when empty", async () => {mocks.runGa4Report.mockResolvedValue(makeGa4ReportResult({@@ -587,6 +602,7 @@ describe("MCP tool text output (service-backed tools)", () => {resolvedDateRange: { startDate: "2026-07-09", endDate: "2026-08-05" },previousDateRange: { startDate: "2026-06-11", endDate: "2026-07-08" },},+ warnings: [],current: {sessions: 120,activeUsers: 80,@@ -629,13 +645,14 @@ describe("MCP tool text output (service-backed tools)", () => {);});- it("get_google_analytics_organic_overview names Organic Search when there is no current row", async () => {+ it("get_google_analytics_organic_overview states a truncated trend and names Organic Search when there is no current row", async () => {mocks.getOrganicOverview.mockResolvedValue({status: "ok",request: {resolvedDateRange: { startDate: "2026-07-09", endDate: "2026-08-05" },previousDateRange: { startDate: "2026-06-11", endDate: "2026-07-08" },},+ warnings: ["trend_truncated"],current: null,previous: null,comparison: {},@@ -648,7 +665,7 @@ describe("MCP tool text output (service-backed tools)", () => {);expect(textContent(result)).toEqual(- "Organic overview for 2026-07-09 through 2026-08-05, compared with 2026-06-11 through 2026-07-08. No Organic Search rows for this date range.",+ "Organic overview for 2026-07-09 through 2026-08-05, compared with 2026-06-11 through 2026-07-08. The trend was cut at 0 rows; use trend=weekly or a shorter date range for the full series. No Organic Search rows for this date range.",);});});