@digestseo/mcp-gsc 0.4.10 → 0.4.11

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.11] - 2026-09-22
+
+### Fixed
+- Sitemap read tools now explain Google's `lastSubmitted` and `lastDownloaded` timestamp semantics so agents do not mistake Search Console submission/download times for sitemap-file modification, page-crawl, or indexing timestamps.
+- Google News Search Analytics now rejects unsupported query grouping/filtering, marks average position unavailable, and removes Google News from query-centric and average-position comparison helpers while preserving supported page/country/date/device/appearance and News Showcase reporting.
+
 ## [0.4.10] - 2026-09-21
 
 ### Fixed

package/README.md

@@ -75,13 +75,13 @@ 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`. 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. For `search_type: "discover"`, `position_supported` is `false` because Google Discover does not support average position. |
-| **`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. |
+| **`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. For `search_type: "discover"` or `"googleNews"`, `position_supported` is `false`; those reports expose clicks, impressions, and CTR but not average position, and query grouping/filtering is unavailable. |
+| **`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 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. |
+| **`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. `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. 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 Search Console property. |
 | **`sitemaps.submit`** / **`sitemaps.delete`** | Write | Submit or remove a sitemap. |

package/package.json

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

package/src/google.ts

@@ -343,9 +343,10 @@ export function assertSearchAnalyticsQueryCompatible(body: SearchAnalyticsQuery)
     }
   }
 
-  if (body.type === 'discover' && hasQueryGroupingOrFilter) {
+  if ((body.type === 'discover' || body.type === 'googleNews') && hasQueryGroupingOrFilter) {
+    const surfaceName = body.type === 'discover' ? 'Google Discover' : 'Google News';
     throw new Error(
-      'Google Discover does not support the query dimension or query filters in Search Analytics.',
+      `${surfaceName} does not support the query dimension or query filters in Search Analytics.`,
     );
   }
 

package/src/index.ts

@@ -143,21 +143,38 @@ const LISTED_SITE_OUTPUT_SCHEMA = {
 const PLATFORM_PROPERTY_API_NOTE =
   "Google Search Console now has platform properties for social/video accounts in its UI, but the current Search Console API documentation still defines siteUrl using URL-prefix and sc-domain website-property forms. mcp-gsc preserves any other identifier returned by sites.list but will not pass an undocumented property identifier to API tools until Google publishes that contract.";
 
+const SITEMAP_PROVIDER_NOTE =
+  "Google's lastSubmitted is the time the sitemap was submitted to Search Console; it is not the sitemap file's generation, deployment, or last-modified time. lastDownloaded is the time Google last downloaded the sitemap; it is not a page crawl or indexing timestamp.";
+
 const SITEMAP_OUTPUT_SCHEMA = z
   .object({
     path: z.string(),
-    lastSubmitted: z.string().nullable().optional(),
+    lastSubmitted: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(
+        'Provider-reported time the sitemap was submitted to Search Console; not the sitemap file generation, deployment, or modification time.',
+      ),
     isPending: z.boolean().nullable().optional(),
     isSitemapsIndex: z.boolean().nullable().optional(),
     type: z.string().nullable().optional(),
-    lastDownloaded: z.string().nullable().optional(),
+    lastDownloaded: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(
+        'Provider-reported time Google last downloaded the sitemap; not a page crawl or page indexing timestamp.',
+      ),
     warnings: z.string().nullable().optional(),
     errors: z.string().nullable().optional(),
     contents: z
       .array(
         z.object({
           type: z.string(),
-          submitted: z.string(),
+          submitted: z
+            .string()
+            .describe('Provider-reported submitted URL count for this sitemap content type.'),
         }),
       )
       .nullable()
@@ -210,6 +227,7 @@ const INSPECTION_BATCH_OUTPUT_SCHEMA = {
 
 const SITEMAPS_OUTPUT_SCHEMA = {
   sitemaps: z.array(SITEMAP_OUTPUT_SCHEMA),
+  provider_note: z.string(),
 };
 
 const SEARCH_ANALYTICS_OUTPUT_SCHEMA = {
@@ -217,7 +235,7 @@ const SEARCH_ANALYTICS_OUTPUT_SCHEMA = {
   start_row: z.number().int().nonnegative(),
   rows: z.array(z.object(SEARCH_ROW_OUTPUT_SCHEMA)),
   position_supported: z.boolean().describe(
-    'Whether average position is supported for the selected Search Analytics search type. False for Google Discover.',
+    'Whether average position is supported for the selected Search Analytics search type. False for Google Discover and Google News.',
   ),
   position_note: z.string().optional(),
   provider_exhaustiveness_guaranteed: z.literal(false).describe(
@@ -888,7 +906,7 @@ class GscMcpRuntime {
       {
         title: 'List submitted sitemaps',
         description:
-          'List sitemaps submitted for a Search Console property. Optionally filter to entries included by one sitemap index. Returns sitemap URLs, last submitted/downloaded dates, submitted URL counts, warning and error counts, and sitemap status. Google\'s deprecated sitemap indexed count is intentionally omitted. Use this when the user asks about sitemap health, submission status, wants to audit which sitemaps are working, or needs the child sitemaps belonging to a specific sitemap index.',
+          'List sitemaps submitted for a Search Console property. Optionally filter to entries included by one sitemap index. Returns sitemap URLs, provider-reported submission/download timestamps, submitted URL counts, warning and error counts, and sitemap status. lastSubmitted is when the sitemap was submitted to Search Console; lastDownloaded is when Google last downloaded the sitemap. Neither timestamp is a sitemap-file modification time or a page crawl/indexing time. Google\'s deprecated sitemap indexed count is intentionally omitted. Use this when the user asks about sitemap health, submission status, wants to audit which sitemaps are working, or needs the child sitemaps belonging to a specific sitemap index.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           sitemap_index: SITEMAP_URL_SCHEMA
@@ -904,7 +922,8 @@ class GscMcpRuntime {
         const googleId = this.requireGoogleId();
         const accessToken = await this.getAccessToken(googleId);
         const sitemaps = await listSitemaps(accessToken, site_url, sitemap_index);
-        return toolResponse(JSON.stringify(sitemaps, null, 2), { sitemaps });
+        const payload = { sitemaps, provider_note: SITEMAP_PROVIDER_NOTE };
+        return toolResponse(JSON.stringify(payload, null, 2), payload);
       },
     );
 
@@ -952,10 +971,11 @@ class GscMcpRuntime {
           '- CTR in the response is a 0–1 fraction. Multiply by 100 for percent.',
           '- Use search_type to query image/video/news/discover indexes',
           '  separately from web.',
-          '- Google Discover does not support query grouping/filtering or',
-          '  average position. For Discover, use page/country/device/date/',
-          '  searchAppearance dimensions and interpret clicks, impressions,',
-          '  and CTR; query dimensions/filters are rejected before the API call.',
+          '- Google Discover and Google News do not support query grouping/',
+          '  filtering or average position. For those surfaces, use page/',
+          '  country/device/date/searchAppearance dimensions and interpret',
+          '  clicks, impressions, and CTR; query dimensions/filters are',
+          '  rejected before the API call.',
           '- News Showcase panel reporting: set aggregation_type to',
           '  "byNewsShowcasePanel", use search_type "discover" or',
           '  "googleNews", and include a searchAppearance equals',
@@ -993,7 +1013,7 @@ class GscMcpRuntime {
             )
             .default(['query'])
             .describe(
-              "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.",
+              "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 and Google News do not support the query dimension.",
             ),
           row_limit: z
             .number()
@@ -1021,7 +1041,7 @@ class GscMcpRuntime {
           search_type: z
             .enum(['web', 'image', 'video', 'news', 'discover', 'googleNews'])
             .default('web')
-            .describe('Which search index to query. Defaults to web. Google Discover does not support query grouping/filtering or average position.'),
+            .describe('Which search index to query. Defaults to web. Google Discover and Google News do not support query grouping/filtering or average position.'),
           aggregation_type: z
             .enum(['auto', 'byNewsShowcasePanel', 'byPage', 'byProperty'])
             .default('auto')
@@ -1056,7 +1076,7 @@ class GscMcpRuntime {
             )
             .optional()
             .describe(
-              "Optional filters ANDed together, e.g. [{ groupType: 'and', filters: [{ dimension: 'country', operator: 'equals', expression: 'usa' }] }]. Countries use ISO 3166-1 alpha-3 codes. Query filters are not supported when search_type is discover.",
+              "Optional filters ANDed together, e.g. [{ groupType: 'and', filters: [{ dimension: 'country', operator: 'equals', expression: 'usa' }] }]. Countries use ISO 3166-1 alpha-3 codes. Query filters are not supported when search_type is discover or googleNews.",
             ),
         },
         outputSchema: SEARCH_ANALYTICS_OUTPUT_SCHEMA,
@@ -1105,11 +1125,12 @@ class GscMcpRuntime {
           row_count: bounded.items.length,
           start_row,
           rows: bounded.items,
-          position_supported: search_type !== 'discover',
-          ...(search_type === 'discover'
+          position_supported:
+            search_type !== 'discover' && search_type !== 'googleNews',
+          ...(search_type === 'discover' || search_type === 'googleNews'
             ? {
                 position_note:
-                  "Google Discover does not support average position. Do not interpret rows[].position for search_type='discover'.",
+                  `${search_type === 'discover' ? 'Google Discover' : 'Google News'} does not support average position. Do not interpret rows[].position for search_type='${search_type}'.`,
               }
             : {}),
           provider_exhaustiveness_guaranteed: false,
@@ -1137,16 +1158,16 @@ 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 is intentionally unavailable because Discover does not expose query data.',
+        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.',
         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.'),
           start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date (inclusive) in YYYY-MM-DD format.'),
           end_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('End date (inclusive) in YYYY-MM-DD format. Note the 2-3 day GSC data lag.'),
           search_type: z
-            .enum(['web', 'image', 'video', 'news', 'googleNews'])
+            .enum(['web', 'image', 'video', 'news'])
             .default('web')
-            .describe('Which search index to query. Defaults to web. Discover is not supported because this tool groups by query.'),
+            .describe('Which search index to query. Defaults to web. Discover and Google News are not supported because this tool groups by query.'),
           row_limit: z
             .number()
             .int()
@@ -1215,16 +1236,16 @@ class GscMcpRuntime {
       'insights.query_pages',
       {
         title: 'Find pages for a query',
-        description: 'For one exact search query, return the site pages that received impressions for it over a date range. This wraps an exact query dimension filter so agents do not need to construct analytics.query filter groups manually. Exact query matching is case-sensitive in Search Console. Use row_limit and start_row to page through bounded results and verify which URL Google is surfacing before diagnosing cannibalization or content targeting. Google Discover is intentionally unavailable because Discover does not expose query data.',
+        description: 'For one exact search query, return the site pages that received impressions for it over a date range. This wraps an exact query dimension filter so agents do not need to construct analytics.query filter groups manually. Exact query matching is case-sensitive in Search Console. Use row_limit and start_row to page through bounded results and verify which URL Google is surfacing before diagnosing cannibalization or content targeting. Google Discover and Google News are intentionally unavailable because those reports do not expose query data.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           query: z.string().min(1).describe('Exact Search Console query text to filter on. Exact query filters are case-sensitive.'),
           start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date (inclusive) in YYYY-MM-DD format.'),
           end_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('End date (inclusive) in YYYY-MM-DD format. Note the 2-3 day GSC data lag.'),
           search_type: z
-            .enum(['web', 'image', 'video', 'news', 'googleNews'])
+            .enum(['web', 'image', 'video', 'news'])
             .default('web')
-            .describe('Which search index to query. Defaults to web. Discover is not supported because this tool filters by query.'),
+            .describe('Which search index to query. Defaults to web. Discover and Google News are not supported because this tool filters by query.'),
           row_limit: z
             .number()
             .int()
@@ -1385,19 +1406,20 @@ class GscMcpRuntime {
       'sitemaps.get',
       {
         title: 'Get sitemap details',
-        description: 'Get status and details of a single sitemap submitted to Google Search Console.',
+        description: 'Get status and details of a single sitemap submitted to Google Search Console. lastSubmitted is when the sitemap was submitted to Search Console; lastDownloaded is when Google last downloaded the sitemap. Neither timestamp is a sitemap-file modification time or a page crawl/indexing time.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           feedpath: SITEMAP_URL_SCHEMA.describe('The full HTTP/HTTPS URL of the sitemap file, e.g. https://example.com/sitemap.xml'),
         },
-        outputSchema: { sitemap: SITEMAP_OUTPUT_SCHEMA },
+        outputSchema: { sitemap: SITEMAP_OUTPUT_SCHEMA, provider_note: z.string() },
         annotations: READ_ONLY_ANNOTATIONS,
       },
       async ({ site_url, feedpath }) => {
         const googleId = this.requireGoogleId();
         const accessToken = await this.getAccessToken(googleId);
         const details = await getSitemap(accessToken, site_url, feedpath);
-        return toolResponse(JSON.stringify(details, null, 2), { sitemap: details });
+        const payload = { sitemap: details, provider_note: SITEMAP_PROVIDER_NOTE };
+        return toolResponse(JSON.stringify(payload, null, 2), payload);
       },
     );
 
@@ -1670,7 +1692,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 is intentionally unavailable because this comparison contract includes average position, which the Discover report does 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 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.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           start_date_a: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date of Period A (recent, YYYY-MM-DD)'),
@@ -1679,9 +1701,9 @@ class GscMcpRuntime {
           end_date_b: SEARCH_CONSOLE_DATE_SCHEMA.describe('End date of Period B (previous, YYYY-MM-DD)'),
           dimension: z.enum(['query', 'page', 'country', 'device']).default('query').describe('The dimension to compare performance for. Defaults to query.'),
           search_type: z
-            .enum(['web', 'image', 'video', 'news', 'googleNews'])
+            .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 is excluded because this tool returns average-position comparisons.'),
+            .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.'),
           dimension_filter_groups: z
             .array(
               z.object({