@digestseo/mcp-gsc 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -5,6 +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).
 
+## [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 metadata and install guidance now advertise the actual Node.js ranges accepted by bundled runtime dependencies (`^22.18.0 || >=24.11.0`) instead of claiming all Node.js 22+ releases are supported.
+- Indexing API eligibility preflight now recognizes static JSON-LD, Microdata, and RDFa type markup, including schema.org URL type spellings, instead of rejecting otherwise eligible static pages solely because they do not use the narrow JSON-LD form previously detected.
+- URL Inspection now rejects malformed/non-HTTP(S) URLs and URLs outside the supplied Search Console property locally before consuming the server's inspection safety budget or calling Google.
+
 ## [0.4.5] - 2026-09-21
 
 ### Fixed

package/README.md

@@ -78,9 +78,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. |
@@ -89,7 +89,7 @@ Read-write mode requests the Google Search Console read-write and Indexing API s
 
 Large analytics responses are bounded at the MCP boundary instead of being generated and then discarded by clients with structured-content limits. List-style tools expose `start_row` / `next_start_row` where applicable; ranked analytical tools expose `limit`, `start_row`, and `result_page` metadata including `has_more`, `truncated`, and `byte_limit_reached`. Continue paging while `has_more` is true rather than assuming one response is complete.
 
-> **`indexing.request` eligibility.** Google's Indexing API is not a general-purpose page submission tool — as of this writing, Google's own documentation limits it to two content types: pages with `JobPosting` structured data, and livestream pages with `BroadcastEvent` structured data nested inside `VideoObject`. Before submitting, the server fetches the target URL and checks its JSON-LD for one of those two types; if neither is present (or the page can't be fetched), it returns an error explaining why the URL is ineligible instead of calling the Indexing API. A successful submission is only an acknowledgment that Google received the notification — it does not guarantee the URL will be indexed.
+> **`indexing.request` eligibility.** Google's Indexing API is not a general-purpose page submission tool — as of this writing, Google's own documentation limits it to two content types: pages with `JobPosting` structured data, and livestream pages with `BroadcastEvent` structured data nested inside `VideoObject`. Before submitting, the server fetches the target URL and checks static JSON-LD, Microdata, and RDFa markup for one of those two types; if neither is present (or the page can't be fetched), it returns an error explaining why the URL is ineligible instead of calling the Indexing API. Structured data injected only after client-side JavaScript runs cannot be confirmed by this bounded preflight and therefore fails closed. A successful submission is only an acknowledgment that Google received the notification — it does not guarantee the URL will be indexed.
 
 ## What you can ask
 

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 22+ and npm. The bundled Wrangler 4 runtime requires Node 22 or newer.
+- Node.js 22.18+ within the 22.x line, or Node.js 24.11+ with npm. The bundled runtime dependency graph includes Babel 8 packages with this stricter Node support range.
 - 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.5",
+  "version": "0.4.7",
   "private": false,
   "main": "scripts/glama-start.mjs",
   "bin": {
@@ -87,6 +87,6 @@
     "vitest": "^4.1.11"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": "^22.18.0 || >=24.11.0"
   }
 }

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

@@ -925,9 +925,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;
@@ -985,6 +986,15 @@ const INDEXING_SCOPE_MESSAGE =
   'and livestream pages (BroadcastEvent structured data inside VideoObject). ' +
   'It is not available for general webpage submission.';
 
+function normalizeSchemaType(value: string): string {
+  const trimmed = value.trim().replace(/[\/#]+$/, '');
+  const schemaUrl = trimmed.match(
+    /^https?:\/\/(?:www\.)?schema\.org\/([^/?#\s]+)$/i,
+  );
+  if (schemaUrl) return schemaUrl[1];
+  return trimmed;
+}
+
 function collectSchemaTypes(node: unknown, types: Set<string>): void {
   if (Array.isArray(node)) {
     for (const item of node) collectSchemaTypes(item, types);
@@ -993,9 +1003,11 @@ function collectSchemaTypes(node: unknown, types: Set<string>): void {
   if (!node || typeof node !== 'object') return;
   const obj = node as Record<string, unknown>;
   const type = obj['@type'];
-  if (typeof type === 'string') types.add(type);
+  if (typeof type === 'string') types.add(normalizeSchemaType(type));
   else if (Array.isArray(type)) {
-    for (const t of type) if (typeof t === 'string') types.add(t);
+    for (const t of type) {
+      if (typeof t === 'string') types.add(normalizeSchemaType(t));
+    }
   }
   for (const [key, value] of Object.entries(obj)) {
     if (key === '@type') continue;
@@ -1010,9 +1022,11 @@ function containsBroadcastEvent(node: unknown): boolean {
   const obj = node as Record<string, unknown>;
   const types = new Set<string>();
   const type = obj['@type'];
-  if (typeof type === 'string') types.add(type);
+  if (typeof type === 'string') types.add(normalizeSchemaType(type));
   else if (Array.isArray(type)) {
-    for (const t of type) if (typeof t === 'string') types.add(t);
+    for (const t of type) {
+      if (typeof t === 'string') types.add(normalizeSchemaType(t));
+    }
   }
   if (types.has('BroadcastEvent')) return true;
   return Object.values(obj).some(containsBroadcastEvent);
@@ -1025,14 +1039,134 @@ function hasEligibleVideoBroadcast(node: unknown): boolean {
   const obj = node as Record<string, unknown>;
   const types = new Set<string>();
   const type = obj['@type'];
-  if (typeof type === 'string') types.add(type);
+  if (typeof type === 'string') types.add(normalizeSchemaType(type));
   else if (Array.isArray(type)) {
-    for (const t of type) if (typeof t === 'string') types.add(t);
+    for (const t of type) {
+      if (typeof t === 'string') types.add(normalizeSchemaType(t));
+    }
   }
   if (types.has('VideoObject') && containsBroadcastEvent(obj)) return true;
   return Object.values(obj).some(hasEligibleVideoBroadcast);
 }
 
+const VOID_HTML_TAGS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+]);
+
+function htmlAttribute(attributes: string, name: string): string | undefined {
+  const pattern = new RegExp(
+    `\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'=<>]+))`,
+    'i',
+  );
+  const match = pattern.exec(attributes);
+  return match?.[1] ?? match?.[2] ?? match?.[3];
+}
+
+function isSchemaVocabulary(value: string | undefined): boolean {
+  return Boolean(value && /^https?:\/\/(?:www\.)?schema\.org\/?$/i.test(value.trim()));
+}
+
+function explicitSchemaType(value: string): string | undefined {
+  const trimmed = value.trim();
+  if (/^https?:\/\/(?:www\.)?schema\.org\//i.test(trimmed)) {
+    return normalizeSchemaType(trimmed);
+  }
+  return undefined;
+}
+
+function htmlStructuredTypes(
+  attributes: string,
+  schemaVocabularyInScope: boolean,
+): Set<string> {
+  const types = new Set<string>();
+
+  const itemType = htmlAttribute(attributes, 'itemtype');
+  if (itemType) {
+    for (const token of itemType.split(/\s+/)) {
+      const normalized = explicitSchemaType(token);
+      if (normalized) types.add(normalized);
+    }
+  }
+
+  const rdfaType = htmlAttribute(attributes, 'typeof');
+  if (rdfaType) {
+    for (const token of rdfaType.split(/\s+/)) {
+      const explicit = explicitSchemaType(token);
+      if (explicit) types.add(explicit);
+      else if (schemaVocabularyInScope && token.trim()) {
+        types.add(normalizeSchemaType(token));
+      }
+    }
+  }
+
+  return types;
+}
+
+/**
+ * Recognize static Microdata/RDFa eligibility without turning this preflight
+ * into a general-purpose HTML validator. The stack is only used to enforce
+ * Google's VideoObject -> BroadcastEvent nesting requirement.
+ */
+function hasEligibleHtmlStructuredData(html: string): boolean {
+  const staticMarkup = html
+    .replace(/<!--(?:[\s\S]*?)-->/g, '')
+    .replace(/<(script|style|template)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, '');
+  const stack: Array<{
+    tag: string;
+    schemaVocabulary: boolean;
+    videoObjectInScope: boolean;
+  }> = [];
+  const tagPattern = /<\s*(\/?)\s*([a-zA-Z][\w:-]*)([^>]*)>/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = tagPattern.exec(staticMarkup)) !== null) {
+    const closing = match[1] === '/';
+    const tag = match[2].toLowerCase();
+    const attributes = match[3];
+
+    if (closing) {
+      for (let index = stack.length - 1; index >= 0; index -= 1) {
+        if (stack[index].tag === tag) {
+          stack.length = index;
+          break;
+        }
+      }
+      continue;
+    }
+
+    const parent = stack.at(-1);
+    const schemaVocabulary =
+      isSchemaVocabulary(htmlAttribute(attributes, 'vocab')) ||
+      parent?.schemaVocabulary === true;
+    const types = htmlStructuredTypes(attributes, schemaVocabulary);
+    if (types.has('JobPosting')) return true;
+
+    const videoObjectInScope =
+      types.has('VideoObject') || parent?.videoObjectInScope === true;
+    if (types.has('BroadcastEvent') && videoObjectInScope) return true;
+
+    const selfClosing = /\/\s*$/.test(attributes);
+    if (!selfClosing && !VOID_HTML_TAGS.has(tag)) {
+      stack.push({ tag, schemaVocabulary, videoObjectInScope });
+    }
+  }
+
+  return false;
+}
+
 export interface IndexingEligibility {
   eligible: boolean;
   reason?: string;
@@ -1112,9 +1246,9 @@ async function readBoundedResponseText(response: Response): Promise<string> {
 /**
  * Checks whether `url` carries the structured data Google's Indexing API
  * currently supports (JobPosting, or BroadcastEvent nested in VideoObject),
- * by inspecting its JSON-LD. Best-effort: if the page can't be fetched or
- * parsed, eligibility can't be confirmed and the URL is treated as
- * ineligible rather than silently submitted.
+ * by inspecting static JSON-LD, Microdata, and RDFa markup. Best-effort: if
+ * the page can't be fetched or parsed, eligibility can't be confirmed and the
+ * URL is treated as ineligible rather than silently submitted.
  */
 export async function checkIndexingEligibility(
   url: string,
@@ -1193,7 +1327,8 @@ export async function checkIndexingEligibility(
 
   const types = new Set<string>();
   let hasVideoBroadcast = false;
-  const scriptPattern = /<script[^>]+type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+  const scriptPattern =
+    /<script\b[^>]*\btype\s*=\s*(?:"application\/ld\+json"|'application\/ld\+json'|application\/ld\+json)[^>]*>([\s\S]*?)<\/script>/gi;
   let match: RegExpExecArray | null;
   while ((match = scriptPattern.exec(html)) !== null) {
     try {
@@ -1205,7 +1340,11 @@ export async function checkIndexingEligibility(
     }
   }
 
-  if (types.has('JobPosting') || hasVideoBroadcast) {
+  if (
+    types.has('JobPosting') ||
+    hasVideoBroadcast ||
+    hasEligibleHtmlStructuredData(html)
+  ) {
     return { eligible: true };
   }
 
@@ -1295,7 +1434,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;
@@ -1319,36 +1459,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

@@ -70,6 +70,7 @@ import {
 import {
   assertIndexingRequestUrl,
   assertIndexingUrlAuthorized,
+  assertUrlWithinSearchConsoleProperty,
 } from './indexing-property-authorization';
 import {
   DEFAULT_ANALYSIS_RESULT_LIMIT,
@@ -344,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(
@@ -392,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(),
@@ -583,12 +591,12 @@ 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',
     description:
-      'Request Google to index or update a URL using the Google Indexing API.',
+      'Request an eligible JobPosting or livestream URL update through Google\'s restricted Indexing API; this is not a general webpage submission tool.',
   },
   {
     name: 'indexing.list_pages',
@@ -597,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',
@@ -759,6 +767,11 @@ class GscMcpRuntime {
       },
       async ({ site_url, inspection_url, language_code }) => {
         const googleId = this.requireGoogleId();
+        assertUrlWithinSearchConsoleProperty(
+          inspection_url,
+          site_url,
+          'inspection_url',
+        );
         const rateLimitError = await this.rateLimitError(googleId, 'urls.inspect');
         if (rateLimitError) return rateLimitError;
         const accessToken = await this.getAccessToken(googleId);
@@ -801,6 +814,13 @@ class GscMcpRuntime {
       },
       async ({ site_url, inspection_urls, language_code }) => {
         const googleId = this.requireGoogleId();
+        for (const inspectionUrl of inspection_urls) {
+          assertUrlWithinSearchConsoleProperty(
+            inspectionUrl,
+            site_url,
+            'inspection_url',
+          );
+        }
         const rateLimitError = await this.rateLimitError(
           googleId,
           'urls.inspect_many',
@@ -1443,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,
@@ -1497,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,
@@ -1615,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)'),
@@ -1705,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),

package/src/indexing-property-authorization.ts

@@ -76,6 +76,32 @@ function isWithinDomainProperty(target: URL, domain: string): boolean {
   return target.hostname === domain || target.hostname.endsWith(`.${domain}`);
 }
 
+/**
+ * Confirms that a fully-qualified HTTP(S) URL belongs to the supplied Search
+ * Console property. This is shared by URL Inspection and Indexing API guards
+ * so both paths use identical URL-prefix and Domain-property semantics.
+ */
+export function assertUrlWithinSearchConsoleProperty(
+  url: string,
+  siteUrl: string,
+  fieldName = 'url',
+): void {
+  const target = parseHttpUrl(url, fieldName);
+  const normalizedSiteUrl = normalizeSiteUrl(siteUrl);
+
+  if (normalizedSiteUrl.startsWith(DOMAIN_PROPERTY_PREFIX)) {
+    if (isWithinDomainProperty(target, parseDomainProperty(normalizedSiteUrl))) {
+      return;
+    }
+  } else if (isWithinUrlPrefix(target, new URL(normalizedSiteUrl))) {
+    return;
+  }
+
+  throw new Error(
+    `${fieldName} must belong to the site_url Search Console property.`,
+  );
+}
+
 /**
  * Confirms that an Indexing API URL is contained by an owner-level Search
  * Console property available to the authenticated account. URL parsing avoids
@@ -86,7 +112,6 @@ export function assertIndexingUrlAuthorized(
   siteUrl: string,
   sites: SearchConsoleSite[],
 ): void {
-  const target = parseHttpUrl(url, 'url');
   const normalizedSiteUrl = normalizeSiteUrl(siteUrl);
   const authorizedSite = sites.find((site) => {
     if (site.permissionLevel !== SITE_OWNER_PERMISSION) return false;
@@ -103,15 +128,7 @@ export function assertIndexingUrlAuthorized(
     );
   }
 
-  if (normalizedSiteUrl.startsWith(DOMAIN_PROPERTY_PREFIX)) {
-    if (isWithinDomainProperty(target, parseDomainProperty(normalizedSiteUrl))) {
-      return;
-    }
-  } else if (isWithinUrlPrefix(target, new URL(normalizedSiteUrl))) {
-    return;
-  }
-
-  throw new Error('url must belong to the authorized site_url Search Console property.');
+  assertUrlWithinSearchConsoleProperty(url, normalizedSiteUrl);
 }
 
 export function assertIndexingRequestUrl(url: string): void {