@digestseo/mcp-gsc 0.4.11 → 0.4.12

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.12] - 2026-09-22
+
+### Fixed
+- `urls.inspect_many` now runs URL Inspection requests with bounded concurrency of three instead of strictly sequentially, reducing batch latency while preserving per-URL safety-budget accounting, input-order results, per-URL failures, and batch-fatal Google-access revocation.
+- Search Analytics now rejects `searchAppearance` combined with another grouping dimension and documents Google's required two-step appearance discovery/filter workflow instead of sending invalid grouped requests to the provider.
+- Brand/non-brand Search Analytics guidance now distinguishes caller-supplied regex segmentation from Search Console's AI-assisted native Branded/Non-branded filter, which the Search Analytics API does not expose.
+
 ## [0.4.11] - 2026-09-22
 
 ### Fixed

package/README.md

@@ -75,10 +75,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`. 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. |
+| **`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. 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, 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. |
+| **`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. |
@@ -105,9 +105,11 @@ Once connected, ask your assistant things like:
 - *"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?"*
-- *"Split my clicks into brand vs non-brand using a regex on the query."*
+- *"Using this brand regex I provide, approximate my clicks as brand vs non-brand."*
 - *"How is my site doing in Google Discover vs regular web search?"*
 
+Query regexes are a manual approximation only. Search Console's native Branded/Non-branded filter uses Google's own AI-assisted classification (including language variants, typos, and associated products/services), and that native classifier is not exposed as a Search Analytics API filter.
+
 ## 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/SECURITY.md

@@ -58,7 +58,7 @@ delay and does not disclose another user's usage.
 | Category | Tools | Limit |
 |---|---|---|
 | Search Analytics | `analytics.query`, `insights.quick_wins`, `insights.cannibalization`, `insights.content_decay`, `indexing.list_pages`, `analytics.compare` | 30 per user / 10 minutes |
-| URL inspection | `urls.inspect`, `urls.inspect_many` | 20 inspected URLs per user / 24 hours; batch requests reserve one unit per URL |
+| URL inspection | `urls.inspect`, `urls.inspect_many` | 20 inspected URLs per user / 24 hours; batch requests reserve one unit per URL and run at most 3 inspections concurrently |
 | Search Console writes | `sites.add`, `sites.delete`, `sitemaps.submit`, `sitemaps.delete` | 10 per user / hour |
 | Indexing publish | `indexing.request` | 2 per user / 24 hours; 200 per deployment / 24 hours |
 | Weekly digest | `reports.weekly_digest` | 6 per user / hour |

package/package.json

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

package/src/google.ts

@@ -309,6 +309,12 @@ export function assertSearchAnalyticsQueryCompatible(body: SearchAnalyticsQuery)
     throw new Error('Search Analytics dimensions must not contain duplicates.');
   }
 
+  if (body.dimensions.includes('searchAppearance') && body.dimensions.length > 1) {
+    throw new Error(
+      'Search Analytics searchAppearance must be the only grouping dimension. Discover an appearance value with dimensions ["searchAppearance"], then filter by that value in a separate query when grouping by page, query, country, device, date, or hour.',
+    );
+  }
+
   const hasHourDimension = body.dimensions.includes('hour');
   const usesHourlyData = body.dataState === 'hourly_all';
   if (hasHourDimension && !usesHourlyData) {
@@ -467,7 +473,9 @@ export interface UrlInspectionBatchResult {
   error?: string;
 }
 
-export async function inspectUrlsSequentially(
+export const URL_INSPECTION_BATCH_CONCURRENCY = 3;
+
+export async function inspectUrlsBoundedConcurrently(
   accessToken: string,
   siteUrl: string,
   inspectionUrls: readonly string[],
@@ -475,31 +483,53 @@ export async function inspectUrlsSequentially(
 ): Promise<UrlInspectionBatchResult[]> {
   const results: UrlInspectionBatchResult[] = [];
 
-  for (const inspectionUrl of inspectionUrls) {
-    try {
-      results.push({
-        inspectionUrl,
-        inspectionResult: await inspectUrl(
-          accessToken,
-          siteUrl,
-          inspectionUrl,
-          languageCode,
-        ),
-      });
-    } catch (error) {
-      if (error instanceof Error && error.message === GSC_ACCESS_REVOKED_MESSAGE) {
-        throw error;
-      }
-      results.push({
-        inspectionUrl,
-        error: error instanceof Error ? error.message : 'URL inspection failed.',
-      });
+  for (
+    let offset = 0;
+    offset < inspectionUrls.length;
+    offset += URL_INSPECTION_BATCH_CONCURRENCY
+  ) {
+    const chunk = inspectionUrls.slice(offset, offset + URL_INSPECTION_BATCH_CONCURRENCY);
+    const chunkResults = await Promise.all(
+      chunk.map(async (inspectionUrl): Promise<UrlInspectionBatchResult | Error> => {
+        try {
+          return {
+            inspectionUrl,
+            inspectionResult: await inspectUrl(
+              accessToken,
+              siteUrl,
+              inspectionUrl,
+              languageCode,
+            ),
+          };
+        } catch (error) {
+          if (error instanceof Error && error.message === GSC_ACCESS_REVOKED_MESSAGE) {
+            return error;
+          }
+          return {
+            inspectionUrl,
+            error: error instanceof Error ? error.message : 'URL inspection failed.',
+          };
+        }
+      }),
+    );
+
+    const accessRevoked = chunkResults.find((result): result is Error => result instanceof Error);
+    if (accessRevoked) {
+      throw accessRevoked;
     }
+    results.push(
+      ...chunkResults.filter(
+        (result): result is UrlInspectionBatchResult => !(result instanceof Error),
+      ),
+    );
   }
 
   return results;
 }
 
+// Kept for compatibility with callers that imported the original helper directly.
+export const inspectUrlsSequentially = inspectUrlsBoundedConcurrently;
+
 export interface SitemapEntry {
   path: string;
   lastSubmitted?: string | null;

package/src/index.ts

@@ -12,7 +12,8 @@ import {
   GSC_ACCESS_REVOKED_MESSAGE,
   MCP_RECONNECT_INSTRUCTION,
   inspectUrl,
-  inspectUrlsSequentially,
+  inspectUrlsBoundedConcurrently,
+  URL_INSPECTION_BATCH_CONCURRENCY,
   listSitemaps,
   listSites,
   getSite,
@@ -589,7 +590,7 @@ const TOOL_CATALOG = [
   {
     name: 'urls.inspect_many',
     description:
-      "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.",
+      `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.`,
   },
   {
     name: 'sitemaps.list',
@@ -836,7 +837,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 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.`,
+        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.`,
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           inspection_urls: z
@@ -873,7 +874,7 @@ class GscMcpRuntime {
         if (rateLimitError) return rateLimitError;
 
         const accessToken = await this.getAccessToken(googleId);
-        const batchResults = await inspectUrlsSequentially(
+        const batchResults = await inspectUrlsBoundedConcurrently(
           accessToken,
           site_url,
           inspection_urls,
@@ -985,10 +986,22 @@ class GscMcpRuntime {
           '  data_state to "hourly_all". The hourly date range can span at',
           '  most 10 inclusive days, and hourly data',
           '  is preliminary.',
+          '- SEARCH APPEARANCE uses a two-step workflow. To discover the',
+          '  property-specific appearance values Google currently exposes,',
+          '  call with dimensions: ["searchAppearance"] and no other grouping',
+          '  dimension. Then filter to one exact returned searchAppearance',
+          '  value in a separate query and group by page/query/country/device/',
+          '  date/hour as needed. Do not guess new appearance identifiers;',
+          '  discover the values Google returns for the property first.',
           '- 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,',
-          "  pass a single regex filter on the 'query' dimension.",
+          '  excludingRegex use RE2 syntax. A query regex can provide a manual',
+          '  brand/non-brand approximation when the caller supplies the brand',
+          "  pattern. It is not equivalent to Search Console's native Branded/",
+          '  Non-branded filter: Google describes that classification as',
+          '  AI-assisted (including language variants, typos, and associated',
+          '  products/services), and the Search Analytics API does not expose',
+          '  that native classifier as a filter.',
           "- data_state defaults to 'all' which matches the GSC dashboard.",
           "  Pass 'final' only when the user explicitly asks for stable,",
           '  non-preliminary data.',
@@ -1013,7 +1026,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 and Google News do not support the query dimension.",
+              "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.",
             ),
           row_limit: z
             .number()
@@ -1732,7 +1745,7 @@ class GscMcpRuntime {
             )
             .optional()
             .describe(
-              "Optional Search Console filters applied identically to both periods. Use query regex filters for brand/non-brand comparisons; countries use ISO 3166-1 alpha-3 codes.",
+              "Optional Search Console filters applied identically to both periods. A caller-supplied query regex can approximate a manual brand/non-brand split, but it is not equivalent to Search Console's AI-assisted native Branded/Non-branded filter, which the Search Analytics API does not expose. Countries use ISO 3166-1 alpha-3 codes.",
             ),
           limit: ANALYSIS_RESULT_LIMIT_SCHEMA,
           start_row: RESULT_START_ROW_SCHEMA,