Skip to content

Open source alternative to Semrush and Ahrefs

Gate GA4 MCP tools per-user; fix false ga4_malformed_response on empty comparison periods (#497)

Ben Senescucfa5bc2cf5a4
diff --git a/README.md b/README.md
index 13c54895..9a874a27 100644
--- a/README.md
+++ b/README.md
@@ -47,7 +47,7 @@ OpenSEO supports two self-hosting paths:
- **Simple: Docker (Best for testing it out)** - For personal use on your own machine. See [`docs/SELF_HOSTING_DOCKER.md`](./docs/SELF_HOSTING_DOCKER.md).
- Unless you already are self-hosting other apps and are confident doing so, we recommend self-hosting with Cloudflare as opposed to Railway, Coolify or Dokploy.
- - We plan to make it simpler to host on those platforms in the next few months.
+ - We plan to make it simpler to host on those platforms in the next few months.
- **Recommended: Cloudflare** - For internet-facing self-hosting across multiple devices or with your team (works on the free plan). See [`docs/SELF_HOSTING_CLOUDFLARE.md`](./docs/SELF_HOSTING_CLOUDFLARE.md).
Either way, you need a DataForSEO API key to get SEO data. See [`docs/DATAFORSEO_API_KEY.md`](./docs/DATAFORSEO_API_KEY.md).
diff --git a/src/server/features/ga4/services/Ga4OrganicOverviewService.test.ts b/src/server/features/ga4/services/Ga4OrganicOverviewService.test.ts
index f2cfa764..10bd0f75 100644
--- a/src/server/features/ga4/services/Ga4OrganicOverviewService.test.ts
+++ b/src/server/features/ga4/services/Ga4OrganicOverviewService.test.ts
@@ -123,6 +123,50 @@ describe("Ga4OrganicOverviewService", () => {
expect(mocks.runReport).toHaveBeenCalledTimes(3);
});
+ it("treats a headerless previous-period response as empty instead of malformed", async () => {
+ mocks.runReport
+ .mockResolvedValueOnce({
+ dimensionHeaders: [],
+ metricHeaders,
+ rows: [
+ {
+ dimensionValues: [],
+ metricValues: metricValues([
+ "100",
+ "80",
+ "70",
+ "0.7",
+ "10",
+ "4",
+ "500",
+ ]),
+ },
+ ],
+ rowCount: 1,
+ })
+ // GA4 omits headers and rows entirely when the previous-period window
+ // falls before the property's creation date.
+ .mockResolvedValueOnce({})
+ .mockResolvedValueOnce({
+ dimensionHeaders: [{ name: "date" }],
+ metricHeaders,
+ rows: [],
+ rowCount: 0,
+ });
+ const result = await Ga4OrganicOverviewService.getOrganicOverview(
+ { projectId: "project_1", trend: "daily" },
+ { now: new Date("2026-08-06T15:00:00Z") },
+ );
+ expect(result.previous).toBeNull();
+ expect(result.comparison.sessions).toEqual({
+ current: 100,
+ previous: null,
+ absoluteChange: null,
+ percentChange: null,
+ });
+ expect(result.diagnostics).toEqual([]);
+ });
+
it("flags a material key-event decline with explicit evidence", async () => {
const report = (keyEvents: string) => ({
dimensionHeaders: [],
diff --git a/src/server/features/ga4/services/Ga4ReportNormalization.ts b/src/server/features/ga4/services/Ga4ReportNormalization.ts
index 556c9ff2..2f60c1ef 100644
--- a/src/server/features/ga4/services/Ga4ReportNormalization.ts
+++ b/src/server/features/ga4/services/Ga4ReportNormalization.ts
@@ -50,9 +50,21 @@ export function normalizeGa4Response(
const expectedMetrics = request.metrics.map(({ name }) => name);
const dimensions = (response.dimensionHeaders ?? []).map(({ name }) => name);
const metrics = (response.metricHeaders ?? []).map(({ name }) => name);
+
+ // GA4 omits headers and rows entirely (rather than echoing the requested
+ // headers with zero rows) when the date range has no data on record for
+ // the property at all — e.g. a previous-period comparison window that
+ // falls before the property's creation date. Treat that as a
+ // legitimately empty report instead of a malformed response.
+ const isHeaderlessEmptyResponse =
+ response.dimensionHeaders === undefined &&
+ response.metricHeaders === undefined &&
+ (response.rows?.length ?? 0) === 0;
+
if (
- dimensions.join("\0") !== expectedDimensions.join("\0") ||
- metrics.join("\0") !== expectedMetrics.join("\0")
+ !isHeaderlessEmptyResponse &&
+ (dimensions.join("\0") !== expectedDimensions.join("\0") ||
+ metrics.join("\0") !== expectedMetrics.join("\0"))
) {
throw new Ga4MalformedResponseError();
}
diff --git a/src/server/features/ga4/services/Ga4ReportingService.comparison.test.ts b/src/server/features/ga4/services/Ga4ReportingService.comparison.test.ts
new file mode 100644
index 00000000..3ca9fc89
--- /dev/null
+++ b/src/server/features/ga4/services/Ga4ReportingService.comparison.test.ts
@@ -0,0 +1,87 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type {
+ Ga4RunReportRequest,
+ Ga4RunReportResponse,
+} from "@/server/lib/ga4Client";
+import { makeGa4Connection } from "./ga4-test-fixtures";
+import { Ga4ReportingService } from "./Ga4ReportingService";
+
+const mocks = vi.hoisted(() => ({
+ getByProjectId: vi.fn(),
+ runReport:
+ vi.fn<(request: Ga4RunReportRequest) => Promise<Ga4RunReportResponse>>(),
+}));
+
+vi.mock("@/server/features/ga4/repositories/Ga4ConnectionRepository", () => ({
+ Ga4ConnectionRepository: { getByProjectId: mocks.getByProjectId },
+}));
+
+vi.mock("@/server/lib/ga4Client", () => ({
+ createGa4DataClient: () => ({ runReport: mocks.runReport }),
+}));
+
+const connection = makeGa4Connection();
+
+function noComparison() {
+ return {
+ current: null,
+ previous: null,
+ absoluteChange: null,
+ percentChange: null,
+ };
+}
+
+describe("Ga4ReportingService previous-period comparison", () => {
+ beforeEach(() => {
+ mocks.getByProjectId.mockResolvedValue(connection);
+ });
+
+ it("treats a headerless previous-period response as empty instead of malformed", async () => {
+ mocks.runReport
+ .mockResolvedValueOnce({
+ dimensionHeaders: [{ name: "deviceCategory" }],
+ metricHeaders: [
+ "activeUsers",
+ "sessions",
+ "engagementRate",
+ "keyEvents",
+ ].map((name) => ({ name })),
+ rows: [
+ {
+ dimensionValues: [{ value: "mobile" }],
+ metricValues: ["10", "12", "0.5", "2"].map((value) => ({ value })),
+ },
+ ],
+ rowCount: 1,
+ })
+ // GA4 omits headers and rows entirely when the previous-period window
+ // falls before the property's creation date.
+ .mockResolvedValueOnce({});
+
+ const result = await Ga4ReportingService.runReport(
+ {
+ projectId: "project_1",
+ kind: "audience_breakdown",
+ audienceBreakdown: "device",
+ comparePreviousPeriod: true,
+ },
+ { now: new Date("2026-08-06T15:00:00Z") },
+ );
+
+ expect(result.comparison?.rows).toEqual([
+ {
+ dimensions: { deviceCategory: "mobile" },
+ metrics: {
+ activeUsers: { ...noComparison(), current: 10 },
+ sessions: { ...noComparison(), current: 12 },
+ engagementRate: { ...noComparison(), current: 0.5 },
+ keyEvents: { ...noComparison(), current: 2 },
+ },
+ },
+ ]);
+ expect(result.comparison?.coverage.previous).toEqual({
+ fetchedRowCount: 0,
+ totalRowCount: 0,
+ });
+ });
+});
diff --git a/src/server/mcp/server.ts b/src/server/mcp/server.ts
index 2b61d616..c3ada49a 100644
--- a/src/server/mcp/server.ts
+++ b/src/server/mcp/server.ts
@@ -6,6 +6,7 @@ import {
import type { z } from "zod";
import {
createMcpToolContext,
+ MCP_AUTH_CONTEXT_PROP,
type McpProps,
type ToolContext,
} from "@/server/mcp/context";
@@ -58,7 +59,7 @@ import {
getSearchConsolePerformanceTool,
inspectUrlsTool,
} from "@/server/mcp/tools/search-console-tools";
-import { GA4_OAUTH_APP_PENDING } from "@/shared/ga4";
+import { GA4_OAUTH_APP_PENDING, isGa4ConnectAvailable } from "@/shared/ga4";
import {
getAuditIssuesTool,
getAuditPagesTool,
@@ -179,7 +180,10 @@ export function createOpenSeoMcpServer(authProps: McpProps) {
register(getKeywordMetricsTool);
register(getSearchConsolePerformanceTool);
register(inspectUrlsTool);
- if (!GA4_OAUTH_APP_PENDING) {
+ if (
+ !GA4_OAUTH_APP_PENDING ||
+ isGa4ConnectAvailable(authProps[MCP_AUTH_CONTEXT_PROP].userEmail)
+ ) {
register(getGoogleAnalyticsOrganicLandingPagesTool);
register(getGoogleAnalyticsPagePerformanceTool);
register(getGoogleAnalyticsKeyEventsTool);