@digestseo/mcp-gsc 0.4.35 → 0.4.37

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.37] - 2026-10-24
+
+### Security
+- Refresh the Cloudflare Agents/MCP runtime peer set to patched MCP SDK, client, and server versions, and raise the minimum Zod version for current security advisories.
+
+### Changed
+- Local launcher setup now provides a cross-platform Node.js command for generating `TOKEN_ENCRYPTION_KEY`, and missing/invalid-key errors surface the same recovery command without logging secret values or requiring OpenSSL.
+- `analytics.compare` now accepts one shared Search Analytics `data_state` for both periods while preserving Google's finalized-data default; callers can explicitly request `all` when they want recent preliminary-capable rows.
+
+## [0.4.36] - 2026-09-24
+
+### Changed
+- `analytics.query` now exposes an explicit `multimodal_report_isolatable: false` boundary and matching runtime guidance because Search Console's new web multimodal filter is currently UI-only; the documented Search Analytics API still exposes only web/image/video/news/discover/googleNews search types.
+
+### Fixed
+- User-supplied Search Analytics ranges now reject future end dates against Search Console's Pacific calendar before reserving local safety budget, resolving Google credentials, or calling the provider; the same boundary now applies to explicit indexed-page ranges and weekly-digest input.
+
 ## [0.4.35] - 2026-09-24
 
 ### Fixed

package/README.md

@@ -108,13 +108,13 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 23 tools. Read-onl
 | **`server.capabilities`** | Read | List every tool this server exposes and report local Google credential state. `connected` means a stored refresh credential is present; the response also exposes `auth_status_basis` and `provider_auth_live_verified: false` because this discovery call does not probe Google. A later Google tool call can still require reconnection if the credential expired or was revoked. Takes no arguments. |
 | **`sites.list`** | Read | List the Search Console properties the connected Google account can access (`siteUrl`, `permissionLevel`). |
 | **`sites.get`** | Read | Retrieve one exact Search Console property and the connected account's permission level for it. |
-| **`analytics.query`** | Read | Impressions, clicks, CTR, and average position over a date range, with dimensions, filters, safe pagination, and selectable search type. Pass `dimensions: []` for true site totals; Google's aggregate row may omit `keys`. Search Analytics does not guarantee every data row and can return only top rows, so exhausting local pagination is not proof that the provider dataset is exhaustive. `data_state: "all"` can include fresh preliminary data, while `final` returns only finalized data; responses echo `data_state` plus `preliminary_data_possible`, and date/hour groupings preserve Google's incomplete-data boundary metadata when returned. Search appearance discovery is a two-step workflow: group by `searchAppearance` alone to discover the exact values Google returns for the property, then filter to one returned value in a separate query when grouping by page/query/country/device/date/hour. For `search_type: "discover"` or `"googleNews"`, `position_supported` is `false`; those reports expose clicks, impressions, and CTR but not average position, so returned rows can omit `position`, and query grouping/filtering is unavailable. Search Console's dedicated Generative AI performance reports are not exposed by the current documented Search Analytics API as a dedicated search type or filter selector; `generative_ai_report_isolatable` is therefore `false`. |
+| **`analytics.query`** | Read | Impressions, clicks, CTR, and average position over a date range, with dimensions, filters, safe pagination, and selectable search type. Pass `dimensions: []` for true site totals; Google's aggregate row may omit `keys`. Search Analytics does not guarantee every data row and can return only top rows, so exhausting local pagination is not proof that the provider dataset is exhaustive. `data_state: "all"` can include fresh preliminary data, while `final` returns only finalized data; responses echo `data_state` plus `preliminary_data_possible`, and date/hour groupings preserve Google's incomplete-data boundary metadata when returned. Search appearance discovery is a two-step workflow: group by `searchAppearance` alone to discover the exact values Google returns for the property, then filter to one returned value in a separate query when grouping by page/query/country/device/date/hour. For `search_type: "discover"` or `"googleNews"`, `position_supported` is `false`; those reports expose clicks, impressions, and CTR but not average position, so returned rows can omit `position`, and query grouping/filtering is unavailable. Search Console's dedicated Generative AI performance reports are not exposed by the current documented Search Analytics API as a dedicated search type or filter selector; `generative_ai_report_isolatable` is therefore `false`. Search Console's new web multimodal UI filter is likewise not exposed as a documented Search Analytics API selector; `multimodal_report_isolatable` is therefore `false`. |
 | **`insights.page_queries`** / **`insights.query_pages`** | Read | Drill from one exact page to its Search Console queries, or from one exact query to the pages Google surfaced for it, with `row_limit` / `start_row` pagination. These query-centric helpers support web, image, video, and the Search results News tab; Discover and the Google News report are excluded because they do not expose query data. |
 | **`urls.inspect`** | Read | Google's URL Inspection report for the version of one page currently known in Google's index. It is not a live URL test; mobile-usability output is deprecated. |
 | **`urls.inspect_many`** | Read | Inspect Google's indexed versions of up to 10 URLs with bounded concurrency of 3 in one call while preserving input-order results. Each URL still consumes one Google URL Inspection request and one unit of the server's shared inspection safety budget; this does not run live URL tests. |
 | **`sitemaps.list`** / **`sitemaps.get`** | Read | List submitted sitemaps or retrieve one sitemap's details. `lastSubmitted` is when the sitemap was submitted to Search Console; `lastDownloaded` is when Google last downloaded the sitemap. Neither value is the sitemap file's modification/deploy time or a page crawl/indexing timestamp. |
 | **`insights.quick_wins`** / **`insights.cannibalization`** / **`insights.content_decay`** | Read | Surface average-position opportunity rows, query/page overlap, and evidence-ranked click declines. Quick-win candidates are observed query/page rows selected by aggregate Search Console average position, not proof of a stable current rank, and CTR is context rather than an eligibility filter. Cannibalization candidate totals/shares are scoped to observed query/page rows rather than true query-level property totals; content-decay results compare only pages returned in both periods and do not turn one-sided row absence into zero traffic. |
-| **`indexing.list_pages`** / **`analytics.compare`** | Read | Analyze pages receiving Search Console impressions and compare two periods, optionally using the same search type and query/page/country/device/search-appearance filters for both periods. `analytics.compare` compares only dimension keys returned in both period responses; a key absent from one non-exhaustive Search Analytics response is not assumed to have zero metrics. Because its comparison contract includes average position, it excludes Discover and Google News. `indexing.list_pages` is performance data, not index coverage: a missing URL may still be indexed; use `urls.inspect` / `urls.inspect_many` for URL-level index status. |
+| **`indexing.list_pages`** / **`analytics.compare`** | Read | Analyze pages receiving Search Console impressions and compare two periods, optionally using the same search type and query/page/country/device/search-appearance filters for both periods. `analytics.compare` compares only dimension keys returned in both period responses; a key absent from one non-exhaustive Search Analytics response is not assumed to have zero metrics. It defaults to finalized Search Analytics rows with `data_state=final`, preserving Google's omitted-`dataState` behavior; pass `all` explicitly when recent preliminary-capable rows are desired. Because its comparison contract includes average position, it excludes Discover and Google News. `indexing.list_pages` is performance data, not index coverage: a missing URL may still be indexed; use `urls.inspect` / `urls.inspect_many` for URL-level index status. |
 | **`reports.weekly_digest`** | Read | Generate a plain-language seven-day performance report with movers, top pages, and one recommended action. Query movers compare only rows returned in both weekly Search Analytics result sets; a query missing from one bounded response is not treated as zero because Google does not guarantee every data row. |
 | **`sites.add`** / **`sites.delete`** | Write | Add or remove a property from the connected account's Search Console site set. `sites.add` returns `ownership_verification_performed: false` because ownership verification is a separate Google Site Verification/Search Console workflow. `sites.delete` removes the property from that account's Search Console site set; it does not delete the website itself. |
 | **`sitemaps.submit`** / **`sitemaps.delete`** | Write | Submit or remove a sitemap. |
@@ -149,6 +149,8 @@ Query regexes are a manual approximation only. Search Console's native Branded/N
 
 Search Console also has dedicated Generative AI performance reports for Search and Discover. The current documented Search Analytics API does not expose a dedicated Generative AI search type or filter selector, so this MCP does not guess one. AI Overviews and AI Mode remain included in overall web Search performance data; use the Search Console UI for the dedicated Generative AI report until Google documents API access.
 
+As of September 24, 2026, Search Console also has a web multimodal performance filter in the UI for searches such as Lens, Circle to Search, image uploads, and Chrome image search. The current Search Analytics API and Discovery document still expose only `web`, `image`, `video`, `news`, `discover`, and `googleNews` search types, so this MCP does not invent `search_type: "multimodal"` or guess a `searchAppearance` value. Use the Search Console UI for isolated multimodal reporting until Google documents API access.
+
 ## Connect in your AI client
 
 Once you've deployed the server (see **[SETUP.md](SETUP.md)**), connect it by pasting your Worker's `/mcp` URL into your client:

package/SETUP.md

@@ -103,15 +103,17 @@ npx wrangler secret put TOKEN_ENCRYPTION_KEY
 # paste the key generated below
 ```
 
-`TOKEN_ENCRYPTION_KEY` is the **AES-256 key** used by `src/crypto.ts` to encrypt each user's Google refresh token before it's stored in KV. Generate a fresh 32-byte key, base64-encoded:
+`TOKEN_ENCRYPTION_KEY` is the **AES-256 key** used by `src/crypto.ts` to encrypt each user's Google refresh token before it's stored in KV. Generate a fresh 32-byte key, base64-encoded. Node.js is already required by this project, so this command works on Windows, macOS, and Linux without an extra OpenSSL install:
 
 ```bash
-openssl rand -base64 32
+node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"
 ```
 
+If OpenSSL is already installed, `openssl rand -base64 32` is equivalent.
+
 Paste that value when prompted. Keep it safe — if you lose it, the refresh tokens already in KV become undecryptable and every user has to reconnect.
 
-The published `npx` launcher validates this exact key format before starting Wrangler. A malformed base64 value or a value that does not decode to exactly 32 bytes is rejected without printing the secret value.
+The published `npx` launcher validates this exact key format before starting Wrangler. A missing or malformed key is rejected without printing the secret value, and the error repeats the cross-platform Node.js generation command so local setup can recover without another tool dependency.
 
 For **local development**, put the same three values in `.dev.vars` instead — copy `.dev.vars.example` to `.dev.vars` (it's gitignored). The published npm launcher can also read them from the process environment; its bundled Wrangler config declares `GOOGLE_CLIENT_SECRET` and `TOKEN_ENCRYPTION_KEY` as required local secrets so those sensitive values do not need to be serialized into `--var` command-line arguments:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digestseo/mcp-gsc",
-  "version": "0.4.35",
+  "version": "0.4.37",
   "private": false,
   "main": "scripts/glama-start.mjs",
   "bin": {
@@ -75,10 +75,10 @@
   "mcpName": "io.github.AKzar1el/mcp-gsc",
   "dependencies": {
     "@cloudflare/workers-oauth-provider": "^0.10.3",
-    "@modelcontextprotocol/server": "2.0.0",
-    "agents": "^0.24.0",
+    "@modelcontextprotocol/server": "2.3.1",
+    "agents": "0.29.0",
     "wrangler": "^4.136.3",
-    "zod": "^4.4.3"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@cloudflare/vitest-plugin": "^1.2.3",

package/scripts/glama-start.mjs

@@ -4,6 +4,8 @@ import { constants, homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+const tokenEncryptionKeyGenerationCommand =
+  `node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"`;
 const requiredEnvironmentVariables = [
   'GOOGLE_CLIENT_ID',
   'GOOGLE_CLIENT_SECRET',
@@ -13,8 +15,13 @@ const missingRequiredEnvironmentVariables = requiredEnvironmentVariables.filter(
   (name) => !process.env[name]?.trim(),
 );
 if (missingRequiredEnvironmentVariables.length > 0) {
+  const tokenEncryptionKeyHint = missingRequiredEnvironmentVariables.includes(
+    'TOKEN_ENCRYPTION_KEY',
+  )
+    ? ` Generate one with: ${tokenEncryptionKeyGenerationCommand}`
+    : '';
   console.error(
-    `[mcp-gsc] Missing required environment variables: ${missingRequiredEnvironmentVariables.join(', ')}. See SETUP.md for local launcher configuration.`,
+    `[mcp-gsc] Missing required environment variables: ${missingRequiredEnvironmentVariables.join(', ')}. See SETUP.md for local launcher configuration.${tokenEncryptionKeyHint}`,
   );
   process.exit(1);
 }
@@ -27,7 +34,7 @@ if (
   || Buffer.from(tokenEncryptionKey, 'base64').byteLength !== 32
 ) {
   console.error(
-    '[mcp-gsc] Invalid TOKEN_ENCRYPTION_KEY: expected a valid base64-encoded 32-byte (256-bit) AES key. See SETUP.md for local launcher configuration.',
+    `[mcp-gsc] Invalid TOKEN_ENCRYPTION_KEY: expected a valid base64-encoded 32-byte (256-bit) AES key. See SETUP.md for local launcher configuration. Generate one with: ${tokenEncryptionKeyGenerationCommand}`,
   );
   process.exit(1);
 }

package/src/date-validation.ts

@@ -81,10 +81,14 @@ export function assertDateRange(
   }
 }
 
-export function assertDateNotInFuture(date: string, today: string): void {
+export function assertDateNotInFuture(
+  date: string,
+  today: string,
+  dateName = 'End date',
+): void {
   if (date > today) {
     throw new Error(
-      'End date must be today or earlier. Google Search Console has no data for dates that have not happened yet.',
+      `${dateName} must be today or earlier (current Search Console Pacific date: ${today}). Google Search Console has no data for dates that have not happened yet.`,
     );
   }
 }

package/src/index.ts

@@ -402,6 +402,10 @@ const SEARCH_ANALYTICS_OUTPUT_SCHEMA = {
     'False because the current documented Search Analytics API exposes no dedicated Generative AI report search type or filter selector.',
   ),
   generative_ai_note: z.string(),
+  multimodal_report_isolatable: z.literal(false).describe(
+    'False because the current documented Search Analytics API exposes no dedicated web multimodal search type or filter selector.',
+  ),
+  multimodal_note: z.string(),
   next_start_row: z.number().int().nonnegative().optional(),
   has_more: z.boolean(),
   truncated: z.boolean(),
@@ -650,6 +654,12 @@ const COMMON_RETURNED_ROWS_COMPARISON_NOTE =
 const PERFORMANCE_COMPARISON_OUTPUT_SCHEMA = {
   comparison_scope: z.literal('common_returned_rows_only'),
   comparison_note: z.string(),
+  data_state: z.enum(['all', 'final']).describe(
+    'The Search Analytics dataState applied identically to both comparison periods.',
+  ),
+  preliminary_data_possible: z.boolean().describe(
+    'True when data_state=all, because recent Search Analytics rows can still be incomplete and subject to change.',
+  ),
   comparisons: z.array(
     z.object({
       key: z.string(),
@@ -698,6 +708,9 @@ const SEARCH_ANALYTICS_PROVIDER_NOTE =
 const GENERATIVE_AI_REPORT_API_NOTE =
   "Search Console's dedicated Generative AI performance reports are not exposed by the current documented Search Analytics API as a dedicated search type or filter selector. AI Overviews and AI Mode remain included in overall web Search performance data. Do not infer isolated Generative AI metrics from analytics.query or guess a searchAppearance identifier.";
 
+const MULTIMODAL_REPORT_API_NOTE =
+  "Search Console's web multimodal performance filter is currently available in the Search Console UI, but the documented Search Analytics API does not expose a multimodal search type or filter selector. Current API search types remain web, image, video, news, discover, and googleNews. Do not pass search_type='multimodal' or guess a searchAppearance identifier to isolate Lens, Circle to Search, image-upload, or Chrome image-search traffic.";
+
 function paginationMetadata(result: PaginatedSearchAnalyticsResult) {
   return {
     rows_fetched: result.rows.length,
@@ -875,7 +888,7 @@ const TOOL_CATALOG = [
   {
     name: 'analytics.compare',
     description:
-      'Compare Search Console performance metrics between two date ranges for dimension keys returned in both Search Analytics responses; one-sided row absence is not treated as zero.',
+      'Compare Search Console performance metrics between two date ranges for dimension keys returned in both Search Analytics responses; one-sided row absence is not treated as zero. The same search type, optional finalized/all data state, and filters are applied to both periods.',
   },
   {
     name: 'reports.weekly_digest',
@@ -1279,6 +1292,13 @@ class GscMcpRuntime {
           '  included in overall web Search performance data. Do not guess a',
           '  searchAppearance identifier or claim analytics.query isolates the',
           '  dedicated Generative AI report.',
+          '- WEB MULTIMODAL REPORT: Search Console now has a web multimodal',
+          '  performance filter in its UI for searches such as Lens, Circle to',
+          '  Search, image uploads, and Chrome image search. The current',
+          '  documented Search Analytics API still exposes only web, image,',
+          '  video, news, discover, and googleNews search types, with no',
+          '  multimodal selector. Do not pass search_type="multimodal" or guess',
+          '  a searchAppearance identifier to isolate this UI report.',
           '- Use dimension_filter_groups to filter by country, device, query',
           '  content, page URL, or search feature. includingRegex and',
           '  excludingRegex use RE2 syntax. A query regex can provide a manual',
@@ -1358,7 +1378,7 @@ class GscMcpRuntime {
           search_type: z
             .enum(['web', 'image', 'video', 'news', 'discover', 'googleNews'])
             .default('web')
-            .describe('Which documented Search Analytics search index to query. Defaults to web. Google Discover and Google News do not support query grouping/filtering or average position. The current API does not expose a dedicated Generative AI performance-report search type.'),
+            .describe('Which documented Search Analytics search index to query. Defaults to web. Google Discover and Google News do not support query grouping/filtering or average position. The current API does not expose a dedicated Generative AI performance-report search type or the Search Console UI web multimodal filter as a search type.'),
           aggregation_type: z
             .enum(['auto', 'byNewsShowcasePanel', 'byPage', 'byProperty'])
             .default('auto')
@@ -1388,6 +1408,11 @@ class GscMcpRuntime {
         dimension_filter_groups,
       }) => {
         assertDateRange(start_date, end_date);
+        assertDateNotInFuture(
+          end_date,
+          getSearchConsoleCalendarDate(),
+          'end_date',
+        );
         const sourceRowLimit = Math.min(row_limit, MAX_DIRECT_SOURCE_ROWS);
         const query = {
           startDate: start_date,
@@ -1439,6 +1464,8 @@ class GscMcpRuntime {
           provider_note: SEARCH_ANALYTICS_PROVIDER_NOTE,
           generative_ai_report_isolatable: false,
           generative_ai_note: GENERATIVE_AI_REPORT_API_NOTE,
+          multimodal_report_isolatable: false,
+          multimodal_note: MULTIMODAL_REPORT_API_NOTE,
           has_more: bounded.resultPage.has_more,
           truncated: bounded.resultPage.truncated,
           byte_limit_reached: bounded.resultPage.byte_limit_reached,
@@ -1497,6 +1524,11 @@ class GscMcpRuntime {
       },
       async ({ site_url, page_url, start_date, end_date, search_type, row_limit = 100, start_row = 0 }) => {
         assertDateRange(start_date, end_date);
+        assertDateNotInFuture(
+          end_date,
+          getSearchConsoleCalendarDate(),
+          'end_date',
+        );
         assertUrlWithinSearchConsoleProperty(page_url, site_url, 'page_url');
         const googleId = this.requireGoogleId();
         const rateLimitError = await this.rateLimitError(googleId, 'insights.page_queries');
@@ -1582,6 +1614,11 @@ class GscMcpRuntime {
       },
       async ({ site_url, query, start_date, end_date, search_type, row_limit = 100, start_row = 0 }) => {
         assertDateRange(start_date, end_date);
+        assertDateNotInFuture(
+          end_date,
+          getSearchConsoleCalendarDate(),
+          'end_date',
+        );
         const googleId = this.requireGoogleId();
         const rateLimitError = await this.rateLimitError(googleId, 'insights.query_pages');
         if (rateLimitError) return rateLimitError;
@@ -1776,6 +1813,11 @@ class GscMcpRuntime {
       },
       async ({ site_url, start_date, end_date, min_impressions, min_position, max_position, limit = DEFAULT_ANALYSIS_RESULT_LIMIT, start_row = 0 }) => {
         assertDateRange(start_date, end_date);
+        assertDateNotInFuture(
+          end_date,
+          getSearchConsoleCalendarDate(),
+          'end_date',
+        );
         const googleId = this.requireGoogleId();
         const rateLimitError = await this.rateLimitError(googleId, 'insights.quick_wins');
         if (rateLimitError) return rateLimitError;
@@ -1823,6 +1865,11 @@ class GscMcpRuntime {
       },
       async ({ site_url, start_date, end_date, min_impressions, min_page_percentage, limit = DEFAULT_ANALYSIS_RESULT_LIMIT, start_row = 0 }) => {
         assertDateRange(start_date, end_date);
+        assertDateNotInFuture(
+          end_date,
+          getSearchConsoleCalendarDate(),
+          'end_date',
+        );
         const googleId = this.requireGoogleId();
         const rateLimitError = await this.rateLimitError(googleId, 'insights.cannibalization');
         if (rateLimitError) return rateLimitError;
@@ -2141,7 +2188,7 @@ class GscMcpRuntime {
       'analytics.compare',
       {
         title: 'Compare Performance Between Periods',
-        description: 'Compare Search Console performance metrics (clicks, impressions, CTR, average position) between two distinct date ranges (Period A vs Period B) for a selected dimension (query, page, country, device). Only dimension keys returned in both Search Analytics period responses are compared; a key missing from one response is not treated as zero because Google does not guarantee every data row. Apply the same search type and optional dimension filters to both periods. Results are ranked by largest absolute click change, then impression change, and safely paged with limit/start_row. Percentage change is null when an explicitly returned baseline row has zero and the comparison value differs. Discover and Google News are intentionally unavailable because this comparison contract includes average position, which those reports do not support.',
+        description: 'Compare Search Console performance metrics (clicks, impressions, CTR, average position) between two distinct date ranges (Period A vs Period B) for a selected dimension (query, page, country, device). Only dimension keys returned in both Search Analytics period responses are compared; a key missing from one response is not treated as zero because Google does not guarantee every data row. Apply the same search type, data state, and optional dimension filters to both periods. data_state defaults to final, preserving Google\'s finalized-only behavior when dataState is omitted; use all explicitly when recent preliminary-capable rows are desired. Results are ranked by largest absolute click change, then impression change, and safely paged with limit/start_row. Percentage change is null when an explicitly returned baseline row has zero and the comparison value differs. Discover and Google News are intentionally unavailable because this comparison contract includes average position, which those reports do not support.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           start_date_a: SEARCH_CONSOLE_DATE_SCHEMA.describe(
@@ -2161,6 +2208,12 @@ class GscMcpRuntime {
             .enum(['web', 'image', 'video', 'news'])
             .default('web')
             .describe('Which Search Console search index to compare. The same search type is used for both periods. Discover and Google News are excluded because this tool returns average-position comparisons.'),
+          data_state: z
+            .enum(['all', 'final'])
+            .default('final')
+            .describe(
+              "'final' requests finalized data only and preserves Google's behavior when dataState is omitted; 'all' can include fresh preliminary Search Analytics data. The same state is applied to both comparison periods.",
+            ),
           dimension_filter_groups: z
             .array(SEARCH_ANALYTICS_FILTER_GROUP_SCHEMA)
             .optional()
@@ -2181,12 +2234,16 @@ class GscMcpRuntime {
         end_date_b,
         dimension,
         search_type,
+        data_state,
         dimension_filter_groups,
         limit = DEFAULT_ANALYSIS_RESULT_LIMIT,
         start_row = 0,
       }) => {
         assertDateRange(start_date_a, end_date_a, 'start_date_a', 'end_date_a');
         assertDateRange(start_date_b, end_date_b, 'start_date_b', 'end_date_b');
+        const today = getSearchConsoleCalendarDate();
+        assertDateNotInFuture(end_date_a, today, 'end_date_a');
+        assertDateNotInFuture(end_date_b, today, 'end_date_b');
         const googleId = this.requireGoogleId();
         const rateLimitError = await this.rateLimitError(googleId, 'analytics.compare');
         if (rateLimitError) return rateLimitError;
@@ -2197,6 +2254,7 @@ class GscMcpRuntime {
           endDate: end_date_a,
           dimensions: [dimension],
           type: search_type,
+          dataState: data_state,
           ...(dimension_filter_groups !== undefined
             ? { dimensionFilterGroups: dimension_filter_groups }
             : {}),
@@ -2207,6 +2265,7 @@ class GscMcpRuntime {
           endDate: end_date_b,
           dimensions: [dimension],
           type: search_type,
+          dataState: data_state,
           ...(dimension_filter_groups !== undefined
             ? { dimensionFilterGroups: dimension_filter_groups }
             : {}),
@@ -2217,6 +2276,8 @@ class GscMcpRuntime {
         const payload = {
           comparison_scope: 'common_returned_rows_only' as const,
           comparison_note: COMMON_RETURNED_ROWS_COMPARISON_NOTE,
+          data_state,
+          preliminary_data_possible: data_state !== 'final',
           comparisons: bounded.items,
           pagination: {
             period_a: paginationMetadata(sourceA),
@@ -2248,12 +2309,12 @@ class GscMcpRuntime {
         annotations: READ_ONLY_ANNOTATIONS,
       },
       async ({ site_url, end_date }) => {
+        const today = getSearchConsoleCalendarDate();
+        const resolvedEndDate = resolveWeeklyDigestEndDate(end_date, today);
+        assertDateNotInFuture(resolvedEndDate, today, 'end_date');
         const googleId = this.requireGoogleId();
         const rateLimitError = await this.rateLimitError(googleId, 'reports.weekly_digest');
         if (rateLimitError) return rateLimitError;
-        const today = getSearchConsoleCalendarDate();
-        const resolvedEndDate = resolveWeeklyDigestEndDate(end_date, today);
-        assertDateNotInFuture(resolvedEndDate, today);
 
         try {
           const markdown = await generateWeeklyDigest(

package/src/indexed-pages-range.ts

@@ -1,4 +1,4 @@
-import { assertDateRange } from './date-validation';
+import { assertDateNotInFuture, assertDateRange } from './date-validation';
 
 export interface IndexedPagesDateRange {
   startDate: string;
@@ -26,6 +26,7 @@ export function resolveIndexedPagesDateRange(
   }
 
   if (!startDate) {
+    assertDateNotInFuture(endDate!, today, 'end_date');
     return {
       startDate: addUtcDays(endDate!, -29),
       endDate: endDate!,
@@ -50,5 +51,6 @@ export function resolveIndexedPagesDateRange(
   }
 
   assertDateRange(startDate, endDate);
+  assertDateNotInFuture(endDate, today, 'end_date');
   return { startDate, endDate };
 }