@digestseo/mcp-gsc 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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).
 
+## [0.4.8] - 2026-09-21
+
+### Fixed
+- Safe Google read operations now make a tightly bounded retry on transient `408`, `429`, and `5xx` provider failures while leaving Search Console writes and OAuth/token mutation paths single-attempt; long `Retry-After` windows are surfaced immediately instead of stalling an MCP call.
+- The published `npx` launcher now forwards `GSC_ACCESS_MODE`, and MCP Registry package metadata exposes the same setting, so local self-hosters can actually select least-privilege `readonly` mode instead of silently inheriting the template's `readwrite` binding.
+
+## [0.4.7] - 2026-09-21
+
+### Fixed
+- Weekly-digest query movers no longer treat a query missing from one bounded top-query response as zero traffic; comparisons now require the query to be present in both weekly result sets and explain that Search Analytics does not guarantee every data row.
+- Period comparison and content-decay analysis no longer fabricate zero metrics for dimension keys or pages missing from one non-exhaustive Search Analytics response; they now compare only rows returned in both periods and expose that scope explicitly.
+
 ## [0.4.6] - 2026-09-21
 
 ### Fixed

package/README.md

@@ -24,6 +24,8 @@ npx -y @digestseo/mcp-gsc
 
 The npm launcher starts a loopback-only **Streamable HTTP** Worker on `127.0.0.1` (port `8080` by default); it is not a stdio MCP process. Clients that launch the package should connect to `http://127.0.0.1:8080/mcp` after supplying the Google OAuth and token-encryption environment variables described in [SETUP.md](SETUP.md). Before the first OAuth sign-in, authorize the exact callback `http://127.0.0.1:8080/google/callback` in Google Cloud (or use the same custom `PORT` you launch with); the launcher prints both URLs at startup.
 
+The local launcher defaults to `GSC_ACCESS_MODE=readwrite`. For least-privilege analytics/reporting-only use, set `GSC_ACCESS_MODE=readonly` in the environment before running `npx`; the launcher forwards that value into the local Worker so OAuth requests only the read-only Search Console scope and the five mutation tools stay unregistered.
+
 For Google OAuth and Cloudflare deployment configuration, follow [SETUP.md](SETUP.md).
 
 ### Connect in 30 seconds
@@ -78,9 +80,9 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 21 tools. Read-onl
 | **`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. |
-| **`reports.weekly_digest`** | Read | Generate a plain-language seven-day performance report with movers, top pages, and one recommended action. |
+| **`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. |
+| **`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. |
 | **`indexing.request`** | Write | Requests indexing through Google's Indexing API. Google currently restricts this API to pages containing `JobPosting` structured data or livestream pages containing `BroadcastEvent` inside `VideoObject`. It is not available for general webpage submission. |

package/package.json

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

package/scripts/glama-start.mjs

@@ -9,6 +9,7 @@ const forwardedVariables = [
   'GOOGLE_CLIENT_ID',
   'GOOGLE_CLIENT_SECRET',
   'TOKEN_ENCRYPTION_KEY',
+  'GSC_ACCESS_MODE',
   'GLAMA_INSPECTION_MODE',
 ];
 const args = [

package/src/digest.ts

@@ -199,25 +199,22 @@ function rowsToPages(rows: SearchAnalyticsRow[]): PageRow[] {
 
 function computeMovers(current: QueryRow[], prev: QueryRow[]): Movers {
   const prevByQuery = new Map(prev.map((q) => [q.query, q]));
-  const currentByQuery = new Map(current.map((q) => [q.query, q]));
-  const allQueries = new Set<string>([
-    ...current.map((q) => q.query),
-    ...prev.map((q) => q.query),
-  ]);
 
   const rising: Mover[] = [];
   const falling: Mover[] = [];
   const newImpressions: Mover[] = [];
 
-  for (const query of allQueries) {
-    const c = currentByQuery.get(query);
+  for (const c of current) {
+    const query = c.query;
     const p = prevByQuery.get(query);
-    const cClicks = c?.clicks ?? 0;
-    const pClicks = p?.clicks ?? 0;
-    const cImpr = c?.impressions ?? 0;
-    const pImpr = p?.impressions ?? 0;
-    const cPos = c?.position ?? 0;
-    const pPos = p?.position ?? 0;
+    if (!p) continue;
+
+    const cClicks = c.clicks;
+    const pClicks = p.clicks;
+    const cImpr = c.impressions;
+    const pImpr = p.impressions;
+    const cPos = c.position;
+    const pPos = p.position;
 
     if (cClicks - pClicks >= 5 && cClicks >= 2 * Math.max(pClicks, 1)) {
       rising.push({
@@ -403,6 +400,10 @@ function renderMarkdown(data: {
 
   lines.push('## What changed this week');
   lines.push('');
+  lines.push(
+    '> Query movers compare only query rows returned in both weekly Search Console result sets. A query missing from one bounded response is not treated as zero because Search Analytics returns top rows and does not guarantee every data row.',
+  );
+  lines.push('');
 
   const hasAnyMovers =
     movers.rising.length > 0 ||

package/src/google.ts

@@ -51,6 +51,63 @@ export class GoogleRefreshTokenRevokedError extends Error {
   }
 }
 
+const GOOGLE_READ_RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+const GOOGLE_READ_MAX_ATTEMPTS = 3;
+const GOOGLE_READ_BASE_DELAY_MS = 1_000;
+const GOOGLE_READ_MAX_DELAY_MS = 5_000;
+
+function googleReadRetryDelayMs(response: Response, retryNumber: number): number | null {
+  const retryAfter = response.headers.get('retry-after')?.trim();
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    const requestedDelay = Number.isFinite(seconds)
+      ? Math.max(0, seconds * 1_000)
+      : Math.max(0, Date.parse(retryAfter) - Date.now());
+    if (Number.isFinite(requestedDelay)) {
+      return requestedDelay <= GOOGLE_READ_MAX_DELAY_MS ? requestedDelay : null;
+    }
+  }
+
+  const exponentialDelay = GOOGLE_READ_BASE_DELAY_MS * 2 ** (retryNumber - 1);
+  const jitterMs = Math.floor(Math.random() * 250);
+  return Math.min(exponentialDelay + jitterMs, GOOGLE_READ_MAX_DELAY_MS);
+}
+
+async function fetchGoogleRead(url: string, init?: RequestInit): Promise<Response> {
+  let lastNetworkError: unknown;
+
+  for (let attempt = 1; attempt <= GOOGLE_READ_MAX_ATTEMPTS; attempt += 1) {
+    try {
+      const response = await fetch(url, init);
+      if (
+        !GOOGLE_READ_RETRYABLE_STATUSES.has(response.status) ||
+        attempt === GOOGLE_READ_MAX_ATTEMPTS
+      ) {
+        return response;
+      }
+
+      const delayMs = googleReadRetryDelayMs(response, attempt);
+      if (delayMs === null) return response;
+      try {
+        await response.body?.cancel();
+      } catch {
+        // Best-effort cleanup before retrying a transient provider response.
+      }
+      if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+    } catch (error) {
+      lastNetworkError = error;
+      if (attempt === GOOGLE_READ_MAX_ATTEMPTS) throw error;
+      const delayMs = Math.min(
+        GOOGLE_READ_BASE_DELAY_MS * 2 ** (attempt - 1) + Math.floor(Math.random() * 250),
+        GOOGLE_READ_MAX_DELAY_MS,
+      );
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
+  throw lastNetworkError;
+}
+
 export async function exchangeCodeForTokens(
   code: string,
   clientId: string,
@@ -89,7 +146,7 @@ export interface GoogleUserInfo {
 export async function fetchGoogleUserInfo(
   accessToken: string,
 ): Promise<GoogleUserInfo> {
-  const resp = await fetch(GOOGLE_USERINFO_URL, {
+  const resp = await fetchGoogleRead(GOOGLE_USERINFO_URL, {
     headers: { authorization: `Bearer ${accessToken}` },
   });
   if (!resp.ok) {
@@ -141,7 +198,7 @@ export interface SiteEntry {
 }
 
 export async function listSites(accessToken: string): Promise<SiteEntry[]> {
-  const resp = await fetch('https://www.googleapis.com/webmasters/v3/sites', {
+  const resp = await fetchGoogleRead('https://www.googleapis.com/webmasters/v3/sites', {
     headers: { authorization: `Bearer ${accessToken}` },
   });
   if (resp.status === 401) {
@@ -160,7 +217,7 @@ export async function getSite(
   siteUrl: string,
 ): Promise<SiteEntry> {
   const encoded = encodeURIComponent(siteUrl);
-  const resp = await fetch(
+  const resp = await fetchGoogleRead(
     `https://www.googleapis.com/webmasters/v3/sites/${encoded}`,
     {
       headers: { authorization: `Bearer ${accessToken}` },
@@ -381,7 +438,7 @@ export async function inspectUrl(
     siteUrl,
   };
   if (languageCode) body.languageCode = languageCode;
-  const resp = await fetch(
+  const resp = await fetchGoogleRead(
     'https://searchconsole.googleapis.com/v1/urlInspection/index:inspect',
     {
       method: 'POST',
@@ -477,7 +534,7 @@ export async function listSitemaps(
   const query = sitemapIndex
     ? `?sitemapIndex=${encodeURIComponent(sitemapIndex)}`
     : '';
-  const resp = await fetch(
+  const resp = await fetchGoogleRead(
     `https://www.googleapis.com/webmasters/v3/sites/${encoded}/sitemaps${query}`,
     {
       headers: { authorization: `Bearer ${accessToken}` },
@@ -501,7 +558,7 @@ export async function querySearchAnalytics(
 ): Promise<SearchAnalyticsResponse> {
   assertSearchAnalyticsQueryCompatible(body);
   const encoded = encodeURIComponent(siteUrl);
-  const resp = await fetch(
+  const resp = await fetchGoogleRead(
     `https://www.googleapis.com/webmasters/v3/sites/${encoded}/searchAnalytics/query`,
     {
       method: 'POST',
@@ -676,7 +733,7 @@ export async function getSitemap(
 ): Promise<SitemapEntry> {
   const encodedSite = encodeURIComponent(siteUrl);
   const encodedFeed = encodeURIComponent(feedpath);
-  const resp = await fetch(
+  const resp = await fetchGoogleRead(
     `https://www.googleapis.com/webmasters/v3/sites/${encodedSite}/sitemaps/${encodedFeed}`,
     {
       headers: { authorization: `Bearer ${accessToken}` },
@@ -925,9 +982,10 @@ export function processContentDecay(
     const prevPos = row.position;
 
     const recent = recentMap.get(page);
-    const recClicks = recent ? recent.clicks : 0;
-    const recImps = recent ? recent.impressions : 0;
-    const recPos = recent ? recent.position : 0;
+    if (!recent) continue;
+    const recClicks = recent.clicks;
+    const recImps = recent.impressions;
+    const recPos = recent.position;
 
     const clickDiff = recClicks - prevClicks;
     const impDiff = recImps - prevImps;
@@ -1433,7 +1491,8 @@ export function processPerformanceComparison(
     const ctrA = row.ctr;
     const posA = row.position;
 
-    const b = mapB.get(key) || { clicks: 0, impressions: 0, ctr: 0, position: 0 };
+    const b = mapB.get(key);
+    if (!b) continue;
     const clicksB = b.clicks;
     const impsB = b.impressions;
     const ctrB = b.ctr;
@@ -1457,36 +1516,6 @@ export function processPerformanceComparison(
     });
   }
 
-  const mapAKeys = new Set(
-    rowsA
-      .map((r) => r.keys?.[0])
-      .filter((key): key is string => key !== undefined),
-  );
-  for (const row of rowsB) {
-    if ((row.keys?.length ?? 0) < 1) continue;
-    const key = row.keys![0];
-    if (mapAKeys.has(key)) continue;
-
-    const clicksB = row.clicks;
-    const impsB = row.impressions;
-    const ctrB = row.ctr;
-    const posB = row.position;
-
-    comparison.push({
-      key,
-      period_a: { clicks: 0, impressions: 0, ctr: 0, position: 0 },
-      period_b: { clicks: clicksB, impressions: impsB, ctr: ctrB, position: posB },
-      diff: {
-        clicks: -clicksB,
-        clicks_percentage: calculatePercentageChange(0, clicksB),
-        impressions: -impsB,
-        impressions_percentage: calculatePercentageChange(0, impsB),
-        ctr: -ctrB,
-        position: -posB,
-      },
-    });
-  }
-
   return comparison.sort(
     (a, b) =>
       Math.abs(b.diff.clicks) - Math.abs(a.diff.clicks) ||

package/src/index.ts

@@ -345,6 +345,8 @@ const CONTENT_DECAY_OUTPUT_SCHEMA = {
     recent: z.object({ start: z.string(), end: z.string() }),
     previous: z.object({ start: z.string(), end: z.string() }),
   }),
+  comparison_scope: z.literal('common_returned_rows_only'),
+  comparison_note: z.string(),
   decay_count: z.number().int().nonnegative(),
   assessment_count: z.number().int().nonnegative(),
   decay_results: z.array(
@@ -393,7 +395,12 @@ const SEARCH_VISIBLE_PAGES_DESCRIPTION =
 const SEARCH_VISIBLE_PAGES_NOTE =
   'These are Search Analytics performance rows for pages with recorded impressions in the requested period, not a complete list of indexed URLs. Absence does not mean a URL is unindexed. Use urls.inspect or urls.inspect_many for URL-level index status.';
 
+const COMMON_RETURNED_ROWS_COMPARISON_NOTE =
+  'Comparisons use only dimension keys returned in both period responses. A key missing from one Search Analytics response is not treated as zero because Google does not guarantee every data row.';
+
 const PERFORMANCE_COMPARISON_OUTPUT_SCHEMA = {
+  comparison_scope: z.literal('common_returned_rows_only'),
+  comparison_note: z.string(),
   comparisons: z.array(
     z.object({
       key: z.string(),
@@ -584,7 +591,7 @@ const TOOL_CATALOG = [
   {
     name: 'insights.content_decay',
     description:
-      'Assess page-level click declines across two contiguous periods and distinguish likely decay from weak evidence or improving visibility with click volatility.',
+      'Assess page-level click declines across two contiguous periods for pages returned in both Search Analytics responses, without treating one-sided row absence as zero traffic.',
   },
   {
     name: 'indexing.request',
@@ -598,7 +605,7 @@ const TOOL_CATALOG = [
   {
     name: 'analytics.compare',
     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.',
+      'Compare Search Console performance metrics between two date ranges for dimension keys returned in both Search Analytics responses; one-sided row absence is not treated as zero.',
   },
   {
     name: 'reports.weekly_digest',
@@ -1456,7 +1463,7 @@ class GscMcpRuntime {
       'insights.content_decay',
       {
         title: 'Detect Content Decay',
-        description: 'Assess page-level click declines across two contiguous periods without treating every small click change as content decay. Each result is classified as likely_decay, weak_insufficient_evidence, or improving_visibility_with_click_volatility using deterministic click-volume, impression, and average-position signals. This is a heuristic assessment, not statistical proof. Results are bounded with limit/start_row; source pagination is reported separately.',
+        description: 'Assess page-level click declines across two contiguous periods without treating every small click change as content decay. Only pages returned in both Search Analytics period responses are compared; a page missing from one response is not treated as zero because Google does not guarantee every data row. Each result is classified as likely_decay, weak_insufficient_evidence, or improving_visibility_with_click_volatility using deterministic click-volume, impression, and average-position signals. This is a heuristic assessment, not statistical proof. Results are bounded with limit/start_row; source pagination is reported separately.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           compare_days: CONTENT_DECAY_COMPARE_DAYS_SCHEMA,
@@ -1510,6 +1517,8 @@ class GscMcpRuntime {
             recent: { start: recentStart, end: recentEnd },
             previous: { start: previousStart, end: previousEnd },
           },
+          comparison_scope: 'common_returned_rows_only' as const,
+          comparison_note: COMMON_RETURNED_ROWS_COMPARISON_NOTE,
           decay_count: decayResults.filter(
             (result) => result.classification === 'likely_decay',
           ).length,
@@ -1628,7 +1637,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). 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 the baseline is 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 is intentionally unavailable because this comparison contract includes average position, which the Discover report does 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)'),
@@ -1718,6 +1727,8 @@ class GscMcpRuntime {
         const comparison = processPerformanceComparison(sourceA.rows, sourceB.rows);
         const bounded = windowKnownResults(comparison, start_row, limit);
         const payload = {
+          comparison_scope: 'common_returned_rows_only' as const,
+          comparison_note: COMMON_RETURNED_ROWS_COMPARISON_NOTE,
           comparisons: bounded.items,
           pagination: {
             period_a: paginationMetadata(sourceA),