@digestseo/mcp-gsc 0.4.34 → 0.4.36

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Search Analytics pagination now treats provider responses shorter than the requested page size as terminal, matching Google's documented contract and avoiding false continuations or unnecessary follow-up requests across direct and higher-level workflows.
+- `insights.page_queries` now rejects exact page URLs outside the supplied Search Console property before reserving local Search Analytics safety budget, resolving Google credentials, or calling the provider, preventing misleading empty cross-property drilldowns.
+
 ## [0.4.34] - 2026-09-24
 
 ### Fixed

package/README.md

@@ -66,6 +66,8 @@ Codex CLI and the Codex IDE extension share MCP configuration, so registering th
 
 When this repository is installed as a Cursor plugin, Cursor also auto-discovers three bundled Agent Skills that compose the MCP tools into evidence-safe workflows: `gsc-weekly-review`, `gsc-indexing-triage`, and `gsc-search-opportunities`. The **Add to Cursor** button above installs the MCP connection only; the bundled skills are part of the repository's Cursor plugin package.
 
+The button and plugin MCP configuration above are for Cursor running on the same machine as the npm launcher. **Cursor Cloud Agents run in isolated cloud VMs, so they cannot reach `127.0.0.1` on your computer.** For Cloud Agents, deploy your own externally reachable HTTPS Worker and add its `/mcp` URL from the MCP controls at [cursor.com/agents](https://cursor.com/agents); Cursor supports HTTP MCP servers and OAuth there. Do not reuse the loopback URL for a Cloud Agent.
+
 **GitHub Copilot CLI**
 
 ```bash
@@ -89,7 +91,9 @@ The Gemini CLI extension bundles the verified local loopback MCP configuration p
 
 Start the npm launcher before using either install button or the Copilot plugin. Complete its Google OAuth flow on first use.
 
-**ChatGPT** — ChatGPT cannot connect directly to this loopback `127.0.0.1` endpoint. Use OpenAI's **Secure MCP Tunnel** for the local launcher, or deploy your own remote Cloudflare Worker and add that `/mcp` URL as a custom MCP app in Developer mode; see [Connect in your AI client](#connect-in-your-ai-client) below.
+**ChatGPT** — ChatGPT cannot connect directly to this loopback `127.0.0.1` endpoint. For private/local use, create an OpenAI **Secure MCP Tunnel**, then run `tunnel-client` on the same machine as the launcher so it can reach `http://127.0.0.1:8080/mcp`; when creating the ChatGPT app, choose the **Tunnel** connection and select that tunnel. The tunnel setup requires an OpenAI `tunnel_id` and runtime API key; see OpenAI's [Secure MCP Tunnel guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels). The tunnel keeps the MCP server private and is intended for private/developer-mode connectivity, not public plugin distribution.
+
+Alternatively, deploy your own remote Cloudflare Worker and add its HTTPS `/mcp` URL as a custom MCP app in Developer mode; see [Connect in your AI client](#connect-in-your-ai-client) below.
 
 A self-hostable [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **Google Search Console**. Connect it to Claude.ai, Cursor, ChatGPT, or any MCP-compatible client and ask your AI assistant about your site's organic search performance — impressions, clicks, top queries, index status, and sitemap health — straight from your own Google account.
 
@@ -104,7 +108,7 @@ 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. |
@@ -145,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digestseo/mcp-gsc",
-  "version": "0.4.34",
+  "version": "0.4.36",
   "private": false,
   "main": "scripts/glama-start.mjs",
   "bin": {

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/google.ts

@@ -785,10 +785,9 @@ export async function querySearchAnalytics(
 
 /**
  * Fetches Search Analytics rows in 25,000-row pages for higher-level tools.
- * Google's documented pagination contract uses an explicit empty response as
- * the terminal page, so a short non-empty page is not treated as exhaustion.
- * A full final page conservatively reports localLimitReached because the API
- * can have more rows even when Search Console's own internal limits apply.
+ * Google's documented pagination contract treats a response shorter than the
+ * requested rowLimit as exhausted. An exactly full final page still requires
+ * a following empty-page probe unless the local safety ceiling is reached.
  */
 export async function querySearchAnalyticsPaginated(
   accessToken: string,
@@ -820,7 +819,7 @@ export async function querySearchAnalyticsPaginated(
 
     const acceptedRows = page.rows.slice(0, requestedRows);
     rows.push(...acceptedRows);
-    if (page.rows.length === 0) {
+    if (page.rows.length < requestedRows) {
       return { rows, pagesFetched, localLimitReached: false };
     }
     if (rows.length >= maximumRows || page.rows.length > requestedRows) {

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(),
@@ -698,6 +702,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,
@@ -1279,6 +1286,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 +1372,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 +1402,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,
@@ -1408,11 +1427,10 @@ class GscMcpRuntime {
         if (rateLimitError) return rateLimitError;
         const accessToken = await this.getAccessToken(googleId);
         const response = await querySearchAnalytics(accessToken, site_url, query);
-        // Search Analytics pagination is complete only after Google returns an
-        // explicit empty page. A short non-empty page can still be followed by
-        // later rows, so preserve a continuation for dimensioned queries.
+        // Google documents a short page as terminal. An exactly full page can
+        // still have a following page, so expose continuation only then.
         const sourceMayHaveMore =
-          dimensions.length > 0 && response.rows.length > 0;
+          dimensions.length > 0 && response.rows.length === sourceRowLimit;
         const bounded = windowSourceRows(
           response.rows,
           start_row,
@@ -1440,6 +1458,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,
@@ -1463,10 +1483,10 @@ class GscMcpRuntime {
       'insights.page_queries',
       {
         title: 'Find queries for a page',
-        description: 'For one exact page URL, return the Search Console queries that produced impressions for it over a date range. This wraps an exact page dimension filter so agents do not need to construct analytics.query filter groups manually. Exact page matching is case-sensitive in Search Console. Use row_limit and start_row to page through bounded results; Search Console can still omit anonymized queries. Google Discover and Google News are intentionally unavailable because those reports do not expose query data.',
+        description: 'For one exact page URL within the supplied Search Console property, return the queries that produced impressions for it over a date range. This wraps an exact page dimension filter so agents do not need to construct analytics.query filter groups manually. Exact page matching is case-sensitive in Search Console. Use row_limit and start_row to page through bounded results; Search Console can still omit anonymized queries. Google Discover and Google News are intentionally unavailable because those reports do not expose query data.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
-          page_url: z.string().url().describe('Exact fully-qualified page URL to filter on, e.g. https://example.com/guides/seo/. Search Console exact page filters are case-sensitive.'),
+          page_url: z.string().url().describe('Exact fully-qualified page URL to filter on, e.g. https://example.com/guides/seo/. The URL must belong to site_url; Search Console exact page filters are case-sensitive.'),
           start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe(
             searchConsoleDateDescription('Start date (inclusive) in YYYY-MM-DD format.'),
           ),
@@ -1498,6 +1518,12 @@ 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');
         if (rateLimitError) return rateLimitError;
@@ -1582,6 +1608,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 +1807,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 +1859,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;
@@ -2124,7 +2165,7 @@ class GscMcpRuntime {
           pages,
           start_row,
           row_limit,
-          response.rows.length > 0,
+          response.rows.length === sourceRowLimit,
           start_row + sourceRowLimit,
         );
 
@@ -2187,6 +2228,9 @@ class GscMcpRuntime {
       }) => {
         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;
@@ -2248,12 +2292,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 };
 }