@digestseo/mcp-gsc 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -5,7 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.4.4] - 2026-09-21
+
+### Fixed
+- Search Analytics requests grouped by `hour` now require the documented `hourly_all` data state and reject hourly windows longer than Google's documented 10-day limit before calling the provider.
+- Search Analytics outputs now distinguish local pagination completeness from Google's provider-level limitation that only top rows are guaranteed, preventing agents from treating a fully fetched local window as an exhaustive dataset.
+
+## [0.4.3] - 2026-09-21
+
+### Changed
+- The documented and npm-declared Node.js minimum is now 22+, matching the bundled Wrangler 4 runtime requirement instead of advertising unsupported Node.js 20 installs.
+
+### Fixed
+- URL Inspection guidance now states that Google reports the version currently in its index rather than running a live URL test, and no longer presents the deprecated mobile-usability field as a current primary signal.
 
 ## [0.4.2] - 2026-09-21
 

package/README.md

@@ -73,10 +73,10 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 21 tools. Read-onl
 | **`server.capabilities`** | Read | List every tool this server exposes and report whether your Google connection is currently authenticated (`connected` / `not_connected`). Takes no arguments — a good first call for discovery. |
 | **`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`. |
+| **`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. |
 | **`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. |
-| **`urls.inspect`** | Read | Google's URL Inspection report for a single page. |
-| **`urls.inspect_many`** | Read | Inspect up to 10 URLs sequentially in one call. Each URL still consumes one Google URL Inspection request and one unit of the server's shared inspection safety budget. |
+| **`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 sequentially in one call. 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. |
 | **`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 distinguish likely decay from weak evidence and improving visibility with click volatility. |
 | **`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. `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. |
@@ -97,7 +97,7 @@ Once connected, ask your assistant things like:
 
 - *"What are my top 20 queries by clicks in the last 28 days?"*
 - *"Compare impressions for example.com this month vs last month — which pages dropped?"*
-- *"Is `https://example.com/pricing` indexed? When was it last crawled?"*
+- *"What does Google's indexed version of `https://example.com/pricing` show for index status and last crawl?"*
 - *"Which high-impression query/page rows have an average position between 5 and 15? Show me those optimization opportunities."*
 - *"Give me a weekly digest for `sc-domain:example.com` ending today."*
 - *"Do any of my sitemaps have errors or warnings?"*

package/SETUP.md

@@ -10,7 +10,7 @@ By the end you'll have a Worker at `https://<your-worker>.workers.dev/mcp` that
 
 - A [Cloudflare account](https://dash.cloudflare.com/sign-up) (the free Workers plan is enough to start).
 - A [Google account](https://accounts.google.com/) with access to the Search Console properties you want to query.
-- Node.js 20+ and npm.
+- Node.js 22+ and npm. The bundled Wrangler 4 runtime requires Node 22 or newer.
 - The Wrangler CLI — installed for you by `npm install`; invoke it with `npx wrangler …`.
 
 Clone and install:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digestseo/mcp-gsc",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "private": false,
   "main": "scripts/glama-start.mjs",
   "bin": {
@@ -87,6 +87,6 @@
     "vitest": "^4.1.11"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   }
 }

package/src/google.ts

@@ -239,11 +239,28 @@ export interface SearchAnalyticsQuery {
   dimensionFilterGroups?: DimensionFilterGroup[];
 }
 
+function inclusiveCalendarDayCount(startDate: string, endDate: string): number {
+  const [startYear, startMonth, startDay] = startDate.split('-').map(Number);
+  const [endYear, endMonth, endDay] = endDate.split('-').map(Number);
+  const startUtc = Date.UTC(startYear, startMonth - 1, startDay);
+  const endUtc = Date.UTC(endYear, endMonth - 1, endDay);
+  return Math.floor((endUtc - startUtc) / 86_400_000) + 1;
+}
+
 export function assertSearchAnalyticsQueryCompatible(body: SearchAnalyticsQuery): void {
   if (new Set(body.dimensions).size !== body.dimensions.length) {
     throw new Error('Search Analytics dimensions must not contain duplicates.');
   }
 
+  const hasHourDimension = body.dimensions.includes('hour');
+  const usesHourlyData = body.dataState === 'hourly_all';
+  if (hasHourDimension && !usesHourlyData) {
+    throw new Error('Search Analytics hour dimension requires dataState hourly_all.');
+  }
+  if (hasHourDimension && inclusiveCalendarDayCount(body.startDate, body.endDate) > 10) {
+    throw new Error('Search Analytics hourly queries support at most 10 inclusive calendar days.');
+  }
+
   const filters = body.dimensionFilterGroups?.flatMap((group) => group.filters) ?? [];
   const hasPageGroupingOrFilter =
     body.dimensions.includes('page') || filters.some((filter) => filter.dimension === 'page');

package/src/index.ts

@@ -172,14 +172,19 @@ const SITE_DETAIL_OUTPUT_SCHEMA = {
   site: z.object(SITE_OUTPUT_SCHEMA),
 };
 
+const URL_INSPECTION_SCOPE_NOTE =
+  "Google's URL Inspection API reports the version currently known in Google's index; it does not run a live URL test or prove current live-page indexability. The mobileUsabilityResult field is deprecated and may be absent.";
+
 const INSPECTION_OUTPUT_SCHEMA = {
   inspection_result: z.unknown(),
+  note: z.string(),
 };
 
 const INSPECTION_BATCH_OUTPUT_SCHEMA = {
   requested_count: z.number().int().positive(),
   succeeded_count: z.number().int().nonnegative(),
   failed_count: z.number().int().nonnegative(),
+  note: z.string(),
   results: z.array(
     z.object({
       inspection_url: z.string(),
@@ -197,6 +202,10 @@ const SEARCH_ANALYTICS_OUTPUT_SCHEMA = {
   row_count: z.number().int().nonnegative(),
   start_row: z.number().int().nonnegative(),
   rows: z.array(z.object(SEARCH_ROW_OUTPUT_SCHEMA)),
+  provider_exhaustiveness_guaranteed: z.literal(false).describe(
+    'False because the Search Analytics API does not guarantee every data row; Google can return only top rows even after local pagination is exhausted.',
+  ),
+  provider_note: z.string(),
   next_start_row: z.number().int().nonnegative().optional(),
   has_more: z.boolean(),
   truncated: z.boolean(),
@@ -227,6 +236,10 @@ const SEARCH_ANALYTICS_PAGINATION_OUTPUT_SCHEMA = z.object({
   rows_fetched: z.number().int().nonnegative(),
   pages_fetched: z.number().int().positive(),
   local_limit_reached: z.boolean(),
+  provider_exhaustiveness_guaranteed: z.literal(false).describe(
+    'False because Google does not guarantee that Search Analytics exposes every data row.',
+  ),
+  provider_note: z.string(),
 });
 
 const RESULT_PAGE_OUTPUT_SCHEMA = z.object({
@@ -420,11 +433,16 @@ function toolResponse<T extends Record<string, unknown>>(
   };
 }
 
+const SEARCH_ANALYTICS_PROVIDER_NOTE =
+  'Google Search Analytics does not guarantee all data rows and can return only top rows. Local pagination fields describe what this server fetched or bounded; they do not prove provider-level exhaustiveness.';
+
 function paginationMetadata(result: PaginatedSearchAnalyticsResult) {
   return {
     rows_fetched: result.rows.length,
     pages_fetched: result.pagesFetched,
     local_limit_reached: result.localLimitReached,
+    provider_exhaustiveness_guaranteed: false as const,
+    provider_note: SEARCH_ANALYTICS_PROVIDER_NOTE,
   };
 }
 
@@ -508,7 +526,7 @@ const TOOL_CATALOG = [
   {
     name: 'analytics.query',
     description:
-      'Query Search Console search analytics (impressions, clicks, CTR, average position) over a date range, broken down by query, page, country, device, date, or search appearance. Supports filters and pagination.',
+      'Query Search Console search analytics (impressions, clicks, CTR, average position) over a date range, broken down by query, page, country, device, date, or search appearance. Supports filters and pagination. Google does not guarantee every data row and can return only top rows.',
   },
   {
     name: 'insights.page_queries',
@@ -523,12 +541,12 @@ const TOOL_CATALOG = [
   {
     name: 'urls.inspect',
     description:
-      "Inspect a single URL's index status in Google: indexed state, last crawl, mobile usability, and rich-results eligibility. Use urls.inspect_many for 2-10 URLs.",
+      "Inspect Google's indexed version of a single URL: index status, last crawl, page-fetch/indexing state, canonicals, and rich-results/AMP analysis where available. This is not a live URL test; mobile usability is a deprecated response field. Use urls.inspect_many for 2-10 URLs.",
   },
   {
     name: 'urls.inspect_many',
     description:
-      'Inspect up to 10 URLs sequentially in one MCP call while charging the same URL Inspection safety budget per URL.',
+      "Inspect Google's indexed versions of up to 10 URLs sequentially in one MCP call while charging the same URL Inspection safety budget per URL. This does not run live URL tests.",
   },
   {
     name: 'sitemaps.list',
@@ -719,7 +737,7 @@ class GscMcpRuntime {
       'urls.inspect',
       {
         title: 'Inspect URL index status',
-        description: `Inspect a single URL's index status in Google. Returns: whether the URL is indexed, last crawl date, indexing state, mobile usability, rich-results eligibility, and any AMP results. Use this when the user asks 'is X indexed?', 'why isn't X showing in Google?', or wants a deep look at one specific page. For a bounded group of 2-10 URLs, prefer urls.inspect_many; Google still processes one URL Inspection request per URL and applies the same quota semantics.`,
+        description: `Inspect the version of a single URL currently known in Google's index. Returns Google's index-status analysis, last crawl, page-fetch/indexing state, canonicals, and rich-results/AMP analysis where available. This API does not test the live URL or prove current live-page indexability, and its mobile-usability result is deprecated. Use this when the user asks 'is X indexed?' or wants Google's indexed-state evidence for one page. For a bounded group of 2-10 URLs, prefer urls.inspect_many; Google still processes one URL Inspection request per URL and applies the same quota semantics.`,
         inputSchema: {
           site_url: z.string().describe(SITE_URL_DESCRIPTION),
           inspection_url: z
@@ -748,8 +766,9 @@ class GscMcpRuntime {
           inspection_url,
           language_code,
         );
-        return toolResponse(JSON.stringify(result, null, 2), {
+        return toolResponse(JSON.stringify({ note: URL_INSPECTION_SCOPE_NOTE, inspection_result: result }, null, 2), {
           inspection_result: result,
+          note: URL_INSPECTION_SCOPE_NOTE,
         });
       },
     );
@@ -758,7 +777,7 @@ class GscMcpRuntime {
       'urls.inspect_many',
       {
         title: 'Inspect multiple URLs',
-        description: `Inspect up to 10 URLs from one Search Console property in a single MCP call. Google still processes one URL Inspection request per URL, so every requested URL consumes one quota unit and one unit of this server's shared URL-inspection safety budget. Requests are sent sequentially to avoid unnecessary bursts. Use this for a small group of important, recently changed, or debugging-target URLs; do not use it to crawl an entire site.`,
+        description: `Inspect the versions of up to 10 URLs currently known in Google's index from one Search Console property. This API does not run live URL tests. Google still processes one URL Inspection request per URL, so every requested URL consumes one quota unit and one unit of this server's shared URL-inspection safety budget. Requests are sent sequentially to avoid unnecessary bursts. Use this for a small group of important or debugging-target URLs; do not use it to crawl an entire site.`,
         inputSchema: {
           site_url: z.string().describe(SITE_URL_DESCRIPTION),
           inspection_urls: z
@@ -809,6 +828,7 @@ class GscMcpRuntime {
           requested_count: inspection_urls.length,
           succeeded_count: succeededCount,
           failed_count: results.length - succeededCount,
+          note: URL_INSPECTION_SCOPE_NOTE,
           results,
         };
         return toolResponse(JSON.stringify(payload, null, 2), payload);
@@ -848,13 +868,18 @@ class GscMcpRuntime {
         title: 'Query search analytics',
         description: [
           'Query Google Search Console search analytics data. Returns',
-          '{ row_count, start_row, rows, has_more, truncated, byte_limit_reached }',
+          '{ row_count, start_row, rows, provider_exhaustiveness_guaranteed,',
+          '  provider_note, has_more, truncated, byte_limit_reached }',
           'where dimensioned rows have keys plus clicks, impressions, ctr, and',
           'position. Aggregate rows from dimensions: [] may omit keys because',
           'Google itself omits that field. When has_more is true, the response',
           'includes next_start_row — pass it back as start_row to fetch the next',
           'safe page. Large requested row_limit values are automatically split',
           'into bounded MCP responses rather than failing structured output.',
+          'Google does not guarantee that Search Analytics exposes every data',
+          'row; it can return only top rows. Local has_more/pagination fields',
+          'therefore describe this server\'s fetch window, not provider-level',
+          'exhaustiveness.',
           'When Google provides',
           'them, response_aggregation_type and metadata are also included;',
           'metadata may identify the first incomplete date or hour.',
@@ -891,7 +916,9 @@ class GscMcpRuntime {
           '  "NEWS_SHOWCASE" filter. Do not group/filter by page or add',
           '  another searchAppearance filter for that aggregation mode.',
           '- For hourly breakdowns, include "hour" in dimensions and set',
-          '  data_state to "hourly_all". Hourly data is preliminary.',
+          '  data_state to "hourly_all". The hourly date range can span at',
+          '  most 10 inclusive days, and hourly data',
+          '  is preliminary.',
           '- Use dimension_filter_groups to filter by country, device, query',
           '  content, page URL, or search feature. includingRegex and',
           '  excludingRegex use RE2 syntax. For brand vs non-brand splits,',
@@ -920,7 +947,7 @@ class GscMcpRuntime {
             )
             .default(['query'])
             .describe(
-              'Dimensions to group rows by. Pass [] (empty array) to get a single row of true site-level totals. Google Discover does not support the query dimension.',
+              "Dimensions to group rows by. Pass [] (empty array) to get a single row of true site-level totals. The 'hour' dimension requires data_state 'hourly_all' and an inclusive date range of at most 10 days. Google Discover does not support the query dimension.",
             ),
           row_limit: z
             .number()
@@ -943,7 +970,7 @@ class GscMcpRuntime {
             .enum(['all', 'final', 'hourly_all'])
             .default('all')
             .describe(
-              "'all' includes fresh (preliminary) data and matches the GSC dashboard; 'final' returns only finalized data; 'hourly_all' returns hourly preliminary data and should be paired with the 'hour' dimension.",
+              "'all' includes fresh (preliminary) data and matches the GSC dashboard; 'final' returns only finalized data; 'hourly_all' includes hourly preliminary data and must be used when grouping by the 'hour' dimension. Hour-grouped requests can span at most 10 inclusive days.",
             ),
           search_type: z
             .enum(['web', 'image', 'video', 'news', 'discover', 'googleNews'])
@@ -1032,6 +1059,8 @@ class GscMcpRuntime {
           row_count: bounded.items.length,
           start_row,
           rows: bounded.items,
+          provider_exhaustiveness_guaranteed: false,
+          provider_note: SEARCH_ANALYTICS_PROVIDER_NOTE,
           has_more: bounded.resultPage.has_more,
           truncated: bounded.resultPage.truncated,
           byte_limit_reached: bounded.resultPage.byte_limit_reached,