@digestseo/mcp-gsc 0.4.31 → 0.4.33

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.33] - 2026-09-24
+
+### Changed
+- `analytics.query` responses now echo the ordered requested `dimensions` and `search_type`, so `rows[].keys` remain self-describing when responses are saved, forwarded, or consumed outside the original request context.
+
+### Fixed
+- `analytics.query` now rejects duplicate grouping dimensions and mixed `searchAppearance` grouping at MCP input validation, before local rate-limit, Google credential, or provider work.
+
+## [0.4.32] - 2026-09-24
+
+### Added
+- `urls.inspect` and successful `urls.inspect_many` items now include a conservative, schema-discoverable `index_status_summary` derived from Google's documented index-status verdict and key crawl/indexing fields while preserving the complete raw provider response.
+
+### Changed
+- Successful `sitemaps.submit` and `sitemaps.delete` results now expose explicit Search Console effect boundaries so agents do not mistake submission for completed processing/indexing or Search Console removal for deletion of the hosted sitemap file/deindexing.
+
 ## [0.4.31] - 2026-09-24
 
 ### Added

package/README.md

@@ -78,7 +78,7 @@ The marketplace path makes the plugin discoverable and updateable through Copilo
 **Gemini CLI**
 
 ```bash
-gemini extensions install https://github.com/AKzar1el/mcp-gsc --ref main
+gemini extensions install https://github.com/AKzar1el/mcp-gsc
 ```
 
 The Gemini CLI extension bundles the verified local loopback MCP configuration plus the same three Agent Skills: `gsc-weekly-review`, `gsc-indexing-triage`, and `gsc-search-opportunities`. Start the npm launcher before using the extension; the extension does not start or deploy mcp-gsc for you.

package/package.json

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

package/src/google.ts

@@ -548,6 +548,70 @@ export async function inspectUrl(
   return data.inspectionResult ?? null;
 }
 
+export type UrlInspectionIndexedState = 'indexed' | 'not_indexed' | 'unknown';
+
+export interface UrlInspectionIndexStatusSummary {
+  indexed_state: UrlInspectionIndexedState;
+  verdict?: string;
+  coverage_state?: string;
+  robots_txt_state?: string;
+  indexing_state?: string;
+  last_crawl_time?: string;
+  page_fetch_state?: string;
+  google_canonical?: string;
+  user_canonical?: string;
+  crawled_as?: string;
+}
+
+function asUnknownRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function optionalStringField(
+  record: Record<string, unknown> | undefined,
+  key: string,
+): string | undefined {
+  const value = record?.[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+export function summarizeUrlInspectionIndexStatus(
+  inspectionResult: unknown,
+): UrlInspectionIndexStatusSummary {
+  const result = asUnknownRecord(inspectionResult);
+  const indexStatus = asUnknownRecord(result?.indexStatusResult);
+  const verdict = optionalStringField(indexStatus, 'verdict');
+  const coverageState = optionalStringField(indexStatus, 'coverageState');
+  const robotsTxtState = optionalStringField(indexStatus, 'robotsTxtState');
+  const indexingState = optionalStringField(indexStatus, 'indexingState');
+  const lastCrawlTime = optionalStringField(indexStatus, 'lastCrawlTime');
+  const pageFetchState = optionalStringField(indexStatus, 'pageFetchState');
+  const googleCanonical = optionalStringField(indexStatus, 'googleCanonical');
+  const userCanonical = optionalStringField(indexStatus, 'userCanonical');
+  const crawledAs = optionalStringField(indexStatus, 'crawledAs');
+  const indexedState: UrlInspectionIndexedState =
+    verdict === 'PASS'
+      ? 'indexed'
+      : verdict === 'FAIL' || verdict === 'NEUTRAL'
+        ? 'not_indexed'
+        : 'unknown';
+
+  return {
+    indexed_state: indexedState,
+    ...(verdict !== undefined ? { verdict } : {}),
+    ...(coverageState !== undefined ? { coverage_state: coverageState } : {}),
+    ...(robotsTxtState !== undefined ? { robots_txt_state: robotsTxtState } : {}),
+    ...(indexingState !== undefined ? { indexing_state: indexingState } : {}),
+    ...(lastCrawlTime !== undefined ? { last_crawl_time: lastCrawlTime } : {}),
+    ...(pageFetchState !== undefined ? { page_fetch_state: pageFetchState } : {}),
+    ...(googleCanonical !== undefined ? { google_canonical: googleCanonical } : {}),
+    ...(userCanonical !== undefined ? { user_canonical: userCanonical } : {}),
+    ...(crawledAs !== undefined ? { crawled_as: crawledAs } : {}),
+  };
+}
+
 export interface UrlInspectionBatchResult {
   inspectionUrl: string;
   inspectionResult?: unknown;

package/src/index.ts

@@ -13,6 +13,7 @@ import {
   MCP_RECONNECT_INSTRUCTION,
   inspectUrl,
   inspectUrlsBoundedConcurrently,
+  summarizeUrlInspectionIndexStatus,
   URL_INSPECTION_BATCH_CONCURRENCY,
   listSitemaps,
   listSites,
@@ -319,8 +320,24 @@ const INDEXING_PROVIDER_USAGE_NOTE =
 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 URL_INSPECTION_INDEX_STATUS_SUMMARY_SCHEMA = z.object({
+  indexed_state: z.enum(['indexed', 'not_indexed', 'unknown']).describe(
+    "Conservative state derived only from Google's indexStatusResult.verdict: PASS => indexed, FAIL/NEUTRAL => not_indexed, and missing/unknown/reserved verdicts => unknown.",
+  ),
+  verdict: z.string().optional(),
+  coverage_state: z.string().optional(),
+  robots_txt_state: z.string().optional(),
+  indexing_state: z.string().optional(),
+  last_crawl_time: z.string().optional(),
+  page_fetch_state: z.string().optional(),
+  google_canonical: z.string().optional(),
+  user_canonical: z.string().optional(),
+  crawled_as: z.string().optional(),
+});
+
 const INSPECTION_OUTPUT_SCHEMA = {
   inspection_result: z.unknown(),
+  index_status_summary: URL_INSPECTION_INDEX_STATUS_SUMMARY_SCHEMA,
   note: z.string(),
 };
 
@@ -333,6 +350,7 @@ const INSPECTION_BATCH_OUTPUT_SCHEMA = {
     z.object({
       inspection_url: z.string(),
       inspection_result: z.unknown().optional(),
+      index_status_summary: URL_INSPECTION_INDEX_STATUS_SUMMARY_SCHEMA.optional(),
       error: z.string().optional(),
     }),
   ),
@@ -347,6 +365,24 @@ 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)),
+  dimensions: z
+    .array(
+      z.enum([
+        'query',
+        'page',
+        'country',
+        'device',
+        'date',
+        'hour',
+        'searchAppearance',
+      ]),
+    )
+    .describe(
+      'Ordered labels for rows[].keys. Each key position corresponds to the dimension at the same index. Empty for aggregate dimensions: [] queries.',
+    ),
+  search_type: z
+    .enum(['web', 'image', 'video', 'news', 'discover', 'googleNews'])
+    .describe('The Search Analytics search type requested for this response.'),
   data_state: z.enum(['all', 'final', 'hourly_all']).describe(
     'The Search Analytics dataState requested from Google for this response.',
   ),
@@ -404,6 +440,22 @@ const SITE_DELETE_OUTPUT_SCHEMA = {
   provider_scope_note: z.string(),
 };
 
+const SITEMAP_SUBMIT_OUTPUT_SCHEMA = {
+  message: z.string(),
+  submitted_to_search_console: z.literal(true),
+  sitemap_processing_completion_proven: z.literal(false),
+  page_indexing_proven: z.literal(false),
+  provider_scope_note: z.string(),
+};
+
+const SITEMAP_DELETE_OUTPUT_SCHEMA = {
+  message: z.string(),
+  removed_from_search_console: z.literal(true),
+  sitemap_file_deleted: z.literal(false),
+  page_deindexing_proven: z.literal(false),
+  provider_scope_note: z.string(),
+};
+
 const SEARCH_ANALYTICS_PAGINATION_OUTPUT_SCHEMA = z.object({
   rows_fetched: z.number().int().nonnegative(),
   pages_fetched: z.number().int().positive(),
@@ -758,12 +810,12 @@ const TOOL_CATALOG = [
   {
     name: 'urls.inspect',
     description:
-      "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.",
+      "Inspect Google's indexed version of a single URL: a conservative normalized index-status summary plus Google's raw 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 Google's indexed versions of up to 10 URLs with bounded concurrency of ${URL_INSPECTION_BATCH_CONCURRENCY} in one MCP call while charging the same URL Inspection safety budget per URL. This does not run live URL tests.`,
+      `Inspect Google's indexed versions of up to 10 URLs with a conservative normalized index-status summary per successful item and bounded concurrency of ${URL_INSPECTION_BATCH_CONCURRENCY} in one MCP call while charging the same URL Inspection safety budget per URL. This does not run live URL tests.`,
   },
   {
     name: 'sitemaps.list',
@@ -773,12 +825,12 @@ const TOOL_CATALOG = [
   {
     name: 'sitemaps.submit',
     description:
-      'Submit a new sitemap to your Google Search Console account.',
+      'Submit a sitemap URL to a Search Console property. A successful API response proves the Search Console submission request succeeded; it does not prove sitemap processing completed or that any page was indexed.',
   },
   {
     name: 'sitemaps.delete',
     description:
-      'Remove/delete a submitted sitemap from your Google Search Console account.',
+      'Remove a submitted sitemap from a Search Console property. This removes the Search Console sitemap entry; it does not delete the remotely hosted sitemap file or prove that any page was deindexed.',
   },
   {
     name: 'sitemaps.get',
@@ -1012,7 +1064,7 @@ class GscMcpRuntime {
       'urls.inspect',
       {
         title: 'Inspect URL index status',
-        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.`,
+        description: `Inspect the version of a single URL currently known in Google's index. Returns a conservative normalized index-status summary alongside Google's raw 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: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           inspection_url: z
@@ -1041,8 +1093,10 @@ class GscMcpRuntime {
           inspection_url,
           language_code,
         );
-        return toolResponse(JSON.stringify({ note: URL_INSPECTION_SCOPE_NOTE, inspection_result: result }, null, 2), {
+        const indexStatusSummary = summarizeUrlInspectionIndexStatus(result);
+        return toolResponse(JSON.stringify({ note: URL_INSPECTION_SCOPE_NOTE, index_status_summary: indexStatusSummary, inspection_result: result }, null, 2), {
           inspection_result: result,
+          index_status_summary: indexStatusSummary,
           note: URL_INSPECTION_SCOPE_NOTE,
         });
       },
@@ -1052,7 +1106,7 @@ class GscMcpRuntime {
       'urls.inspect_many',
       {
         title: 'Inspect multiple URLs',
-        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 use bounded concurrency of ${URL_INSPECTION_BATCH_CONCURRENCY}; results preserve input order, and a Google-access revocation stops later chunks from starting. Use this for a small group of important 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. Each successful item includes a conservative normalized index-status summary alongside Google's raw response. 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 use bounded concurrency of ${URL_INSPECTION_BATCH_CONCURRENCY}; results preserve input order, and a Google-access revocation stops later chunks from starting. Use this for a small group of important or debugging-target URLs; do not use it to crawl an entire site.`,
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           inspection_urls: z
@@ -1096,7 +1150,12 @@ class GscMcpRuntime {
         const results = batchResults.map((result) => ({
           inspection_url: result.inspectionUrl,
           ...(result.inspectionResult !== undefined
-            ? { inspection_result: result.inspectionResult }
+            ? {
+                inspection_result: result.inspectionResult,
+                index_status_summary: summarizeUrlInspectionIndexStatus(
+                  result.inspectionResult,
+                ),
+              }
             : {}),
           ...(result.error !== undefined ? { error: result.error } : {}),
         }));
@@ -1147,10 +1206,13 @@ class GscMcpRuntime {
         title: 'Query search analytics',
         description: [
           'Query Google Search Console search analytics data. Returns',
-          '{ row_count, start_row, rows, provider_exhaustiveness_guaranteed,',
-          '  provider_note, has_more, truncated, byte_limit_reached }',
+          '{ row_count, start_row, rows, dimensions, search_type,',
+          '  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',
+          'position. The echoed dimensions array labels rows[].keys in order,',
+          'so saved or forwarded responses remain self-describing. 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',
@@ -1251,6 +1313,20 @@ class GscMcpRuntime {
                 'searchAppearance',
               ]),
             )
+            .superRefine((dimensions, ctx) => {
+              if (new Set(dimensions).size !== dimensions.length) {
+                ctx.addIssue({
+                  code: 'custom',
+                  message: 'Search Analytics dimensions must not contain duplicates.',
+                });
+              }
+              if (dimensions.includes('searchAppearance') && dimensions.length > 1) {
+                ctx.addIssue({
+                  code: 'custom',
+                  message: 'Search Analytics searchAppearance must be the only grouping dimension.',
+                });
+              }
+            })
             .default(['query'])
             .describe(
               "Dimensions to group rows by. Pass [] (empty array) to get a single row of true site-level totals. searchAppearance must be the only grouping dimension; discover an appearance value with ['searchAppearance'], then filter to that value in a separate query when grouping by another dimension. 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.",
@@ -1345,6 +1421,8 @@ class GscMcpRuntime {
           row_count: bounded.items.length,
           start_row,
           rows: bounded.items,
+          dimensions,
+          search_type,
           data_state,
           preliminary_data_possible: data_state !== 'final',
           position_supported:
@@ -1606,12 +1684,12 @@ class GscMcpRuntime {
       'sitemaps.submit',
       {
         title: 'Submit sitemap',
-        description: 'Submit a new sitemap to your Google Search Console account.',
+        description: 'Submit a sitemap URL to a Search Console property. A successful API response means the Search Console submission request succeeded; it does not prove sitemap processing completed or that any page was indexed.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           feedpath: SITEMAP_URL_SCHEMA.describe('The full HTTP/HTTPS URL of the sitemap file to submit, e.g. https://example.com/sitemap.xml'),
         },
-        outputSchema: MESSAGE_OUTPUT_SCHEMA,
+        outputSchema: SITEMAP_SUBMIT_OUTPUT_SCHEMA,
         annotations: WRITE_TOOL_ANNOTATIONS['sitemaps.submit'],
       },
       async ({ site_url, feedpath }) => {
@@ -1620,8 +1698,15 @@ class GscMcpRuntime {
         if (rateLimitError) return rateLimitError;
         const accessToken = await this.getAccessToken(googleId);
         await submitSitemap(accessToken, site_url, feedpath);
-        const message = `Successfully submitted sitemap: ${feedpath} for site: ${site_url}`;
-        return toolResponse(message, { message });
+        const message = `Successfully submitted sitemap to Search Console: ${feedpath} for site: ${site_url}`;
+        const payload = {
+          message,
+          submitted_to_search_console: true as const,
+          sitemap_processing_completion_proven: false as const,
+          page_indexing_proven: false as const,
+          provider_scope_note: "Google's Sitemaps.submit method returns an empty body on success. That success confirms the Search Console submission operation, not completed sitemap processing or page indexing.",
+        };
+        return toolResponse(`${message}\n\n${payload.provider_scope_note}`, payload);
       },
     );
 
@@ -1629,12 +1714,12 @@ class GscMcpRuntime {
       'sitemaps.delete',
       {
         title: 'Delete sitemap',
-        description: 'Remove/delete a submitted sitemap from your Google Search Console account.',
+        description: 'Remove a submitted sitemap from a Search Console property. This removes the Search Console sitemap entry; it does not delete the remotely hosted sitemap file or prove that any page was deindexed.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           feedpath: SITEMAP_URL_SCHEMA.describe('The full HTTP/HTTPS URL of the sitemap file to delete, e.g. https://example.com/sitemap.xml'),
         },
-        outputSchema: MESSAGE_OUTPUT_SCHEMA,
+        outputSchema: SITEMAP_DELETE_OUTPUT_SCHEMA,
         annotations: WRITE_TOOL_ANNOTATIONS['sitemaps.delete'],
       },
       async ({ site_url, feedpath }) => {
@@ -1643,8 +1728,15 @@ class GscMcpRuntime {
         if (rateLimitError) return rateLimitError;
         const accessToken = await this.getAccessToken(googleId);
         await deleteSitemap(accessToken, site_url, feedpath);
-        const message = `Successfully deleted sitemap: ${feedpath} for site: ${site_url}`;
-        return toolResponse(message, { message });
+        const message = `Successfully removed sitemap from Search Console: ${feedpath} for site: ${site_url}`;
+        const payload = {
+          message,
+          removed_from_search_console: true as const,
+          sitemap_file_deleted: false as const,
+          page_deindexing_proven: false as const,
+          provider_scope_note: "Google's Sitemaps.delete method removes the submitted sitemap from the Search Console property. It does not delete the remotely hosted sitemap file or prove that any page was deindexed.",
+        };
+        return toolResponse(`${message}\n\n${payload.provider_scope_note}`, payload);
       },
       );
     }