@digestseo/mcp-gsc 0.4.23 → 0.4.25

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.25] - 2026-09-23
+
+### Fixed
+- Access-mode onboarding and Official MCP Registry metadata now identify all six read-write mutation tools after `indexing.remove` became part of the public tool surface.
+- `analytics.query` now accepts provider-valid Discover and Google News rows with no `position` field instead of failing MCP structured-output validation; Search Console does not record average position for those surfaces.
+
+## [0.4.24] - 2026-09-23
+
+### Added
+- `indexing.remove` publishes Google's supported `URL_DELETED` notification for previously eligible Indexing API pages after a bounded preflight confirms the URL already returns HTTP 404/410 or exposes a robots `noindex` meta directive. A successful notification is reported only as receipt acknowledgment, never as proof that Google completed removal.
+
+### Changed
+- Search Analytics date inputs now explicitly state Google's Pacific Time calendar (`America/Los_Angeles`, UTC-8/UTC-7 depending on daylight saving time), matching the server's existing Pacific-Time default/date-range calculations and preventing agents from interpreting YYYY-MM-DD inputs in the caller's local timezone or UTC.
+
 ## [0.4.23] - 2026-09-22
 
 ### Fixed

package/README.md

@@ -26,7 +26,7 @@ The npm launcher starts a loopback-only **Streamable HTTP** Worker on `127.0.0.1
 
 Local KV and Durable Object state, including the encrypted Google session, is stored in `~/.mcp-gsc/state` by default instead of inside the versioned npm cache. That keeps the local connection available across package upgrades and ordinary npm cache cleanup. Set `MCP_GSC_STATE_DIR` to use another directory; keep the same `TOKEN_ENCRYPTION_KEY` when reusing existing state because stored refresh tokens are encrypted with that key. The launcher prints the effective state directory at startup. The first release with this stable path may require one Google reconnect because older launcher releases stored local state under the npm package cache.
 
-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.
+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 six mutation tools stay unregistered.
 
 For Google OAuth and Cloudflare deployment configuration, follow [SETUP.md](SETUP.md).
 
@@ -72,14 +72,14 @@ It runs on [Cloudflare Workers](https://workers.cloudflare.com/) and ships with
 
 ## Tools
 
-By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 22 tools. Read-only analytics and reporting tools are marked with MCP's `readOnlyHint`; the write tools below can change Search Console properties, sitemaps, or indexing state. Set `GSC_ACCESS_MODE=readonly` to request only the Search Console read-only scope and expose the 16 tools that do not require either write access or the separate Indexing API scope.
+By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 23 tools. Read-only analytics and reporting tools are marked with MCP's `readOnlyHint`; the write tools below can change Search Console properties, sitemaps, or indexing state. Set `GSC_ACCESS_MODE=readonly` to request only the Search Console read-only scope and expose the 16 tools that do not require either write access or the separate Indexing API scope.
 
 | Tool | Access | What it does |
 |---|---|---|
 | **`server.capabilities`** | Read | List every tool this server exposes and report local Google credential state. `connected` means a stored refresh credential is present; the response also exposes `auth_status_basis` and `provider_auth_live_verified: false` because this discovery call does not probe Google. A later Google tool call can still require reconnection if the credential expired or was revoked. Takes no arguments. |
 | **`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. `data_state: "all"` can include fresh preliminary data, while `final` returns only finalized data; responses echo `data_state` plus `preliminary_data_possible`, and date/hour groupings preserve Google's incomplete-data boundary metadata when returned. 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. Search Console's dedicated Generative AI performance reports are not exposed by the current documented Search Analytics API as a dedicated search type or filter selector; `generative_ai_report_isolatable` is therefore `false`. |
+| **`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. `data_state: "all"` can include fresh preliminary data, while `final` returns only finalized data; responses echo `data_state` plus `preliminary_data_possible`, and date/hour groupings preserve Google's incomplete-data boundary metadata when returned. 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, so returned rows can omit `position`, and query grouping/filtering is unavailable. Search Console's dedicated Generative AI performance reports are not exposed by the current documented Search Analytics API as a dedicated search type or filter selector; `generative_ai_report_isolatable` is therefore `false`. |
 | **`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 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. |
@@ -91,14 +91,17 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 22 tools. Read-onl
 | **`sitemaps.submit`** / **`sitemaps.delete`** | Write | Submit or remove a sitemap. |
 | **`indexing.status`** | Read | Read Google's latest successful Indexing API `URL_UPDATED` / `URL_DELETED` notification receipts for a previously submitted URL. This is notification metadata only, not index coverage, crawl status, indexing completion, or removal completion. It requires `GSC_ACCESS_MODE=readwrite` because Google's metadata endpoint uses the Indexing API OAuth scope. |
 | **`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. Google's default 200 publish requests/day/project is onboarding/testing capacity rather than ongoing-use approval; additional approval is required for usage/resource provisioning, and submissions are spam-screened. |
+| **`indexing.remove`** | Write | Request a `URL_DELETED` notification for a previously eligible Indexing API page. Before removal, the URL must already return HTTP 404/410 or expose a robots `noindex` meta directive. Google's receipt does not prove removal completed; use URL Inspection for indexed-state evidence. |
+
+Search Analytics calendar dates (`start_date`, `end_date`, and comparison-period dates) use Google's Pacific Time calendar (`America/Los_Angeles`, UTC-8/UTC-7 depending on daylight saving time), not the caller's local timezone or UTC. This also governs the server's generated/default Search Analytics date ranges.
 
 > **Platform properties.** Search Console now supports platform properties for social/video accounts such as Instagram, TikTok, X, and YouTube in its UI. Google's current Search Console API documentation still defines `siteUrl` using URL-prefix and `sc-domain:` website-property forms and does not publish a platform-property API identifier contract. `sites.list` therefore preserves every identifier Google returns and marks whether it matches the documented API grammar; the other tools deliberately reject undocumented forms instead of inventing an identifier. Use the Search Console UI/export for a platform property until Google documents API support.
 
-Read-write mode requests the Google Search Console read-write and Indexing API scopes. Read-only mode requests only `https://www.googleapis.com/auth/webmasters.readonly` (plus `openid` and `email`) and does not register the five write tools or the read-only `indexing.status` lookup, because that lookup still requires Google's separate Indexing API scope. Read-write remains the default so existing deployments retain their current behavior; see [SETUP.md](SETUP.md) to select a mode before connecting users.
+Read-write mode requests the Google Search Console read-write and Indexing API scopes. Read-only mode requests only `https://www.googleapis.com/auth/webmasters.readonly` (plus `openid` and `email`) and does not register the six write tools or the read-only `indexing.status` lookup, because that lookup still requires Google's separate Indexing API scope. Read-write remains the default so existing deployments retain their current behavior; see [SETUP.md](SETUP.md) to select a mode before connecting users.
 
 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 and provider approval.** 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. Google's default 200 publish requests/day/project is for onboarding and submission testing; using the API beyond that onboarding/testing context requires Google's usage/resource-provisioning approval. Google also subjects every submission to spam detection and warns that abuse or attempts to exceed quotas through multiple accounts or other means can revoke access. A successful submission is only an acknowledgment that Google received the notification — it does not guarantee the URL will be indexed.
+> **Indexing API eligibility and provider approval.** 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 `indexing.request`, 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. Before `indexing.remove`, the server instead confirms Google's removal precondition: the URL must already return HTTP 404/410 or expose a robots `noindex` meta directive. Update and removal notifications share the same publish quota. Google's default 200 publish requests/day/project is for onboarding and submission testing; using the API beyond that onboarding/testing context requires Google's usage/resource-provisioning approval. Google also subjects every submission to spam detection and warns that abuse or attempts to exceed quotas through multiple accounts or other means can revoke access. A successful notification is only an acknowledgment that Google received it — it does not guarantee indexing or removal completed.
 
 ## What you can ask
 

package/SECURITY.md

@@ -32,9 +32,10 @@ Notes:
 - With `GSC_ACCESS_MODE=readonly`, the server requests only `openid`, `email`,
   and `https://www.googleapis.com/auth/webmasters.readonly`. It does not
   register `sites.add`, `sites.delete`, `sitemaps.submit`, `sitemaps.delete`,
-  or `indexing.request`; the remaining tool suite uses APIs that accept the
+  `indexing.request`, or `indexing.remove`; the remaining tool suite uses APIs that accept the
   read-only Search Console scope.
-- The Indexing API is requested only in read-write mode for `indexing.request`.
+- The Indexing API is requested only in read-write mode for `indexing.request`,
+  `indexing.remove`, and the otherwise read-only `indexing.status` lookup.
   Google restricts that API to `JobPosting` pages or livestream pages with a
   `BroadcastEvent` inside a `VideoObject`; it is not a general page-submission
   API.
@@ -60,7 +61,7 @@ delay and does not disclose another user's usage.
 | 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 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 |
+| Indexing publish | `indexing.request`, `indexing.remove` | 2 per user / 24 hours; 200 per deployment / 24 hours |
 | Indexing metadata | `indexing.status` | 30 per user / minute; 180 per deployment / minute |
 | Weekly digest | `reports.weekly_digest` | 6 per user / hour |
 

package/SETUP.md

@@ -61,7 +61,7 @@ npx wrangler login
 
    `readwrite` preserves the full tool surface: it grants Search Console read-write access and the Indexing API scope required to manage sites, sitemaps, and request URL crawling. `readonly` requests only the Search Console read-only scope and omits the mutation tools.
 
-   Note that the Indexing API itself is narrow: Google currently restricts it to pages containing `JobPosting` structured data or livestream pages containing `BroadcastEvent` inside `VideoObject`. It is not available for general webpage submission — the `indexing.request` tool checks a page's structured data before submitting and returns an error for ineligible URLs. Google's default **200 publish requests/day/project** is explicitly for onboarding and submission testing; ongoing usage/resource provisioning requires additional Google approval. All submissions are subject to spam detection, and Google warns that abuse or attempts to exceed quotas through multiple accounts or other means can result in revoked access. The server's own lower safety limits do not constitute Google approval or increase provider quota.
+   Note that the Indexing API itself is narrow: Google currently restricts it to pages containing `JobPosting` structured data or livestream pages containing `BroadcastEvent` inside `VideoObject`. It is not available for general webpage submission - the `indexing.request` tool checks a page's structured data before submitting and returns an error for ineligible URLs. `indexing.remove` is for previously eligible pages and requires the URL to already return HTTP 404/410 or expose a robots `noindex` meta directive before it sends Google's `URL_DELETED` notification. Google's default **200 publish requests/day/project** is shared by update and removal notifications and is explicitly for onboarding and submission testing; ongoing usage/resource provisioning requires additional Google approval. All submissions are subject to spam detection, and Google warns that abuse or attempts to exceed quotas through multiple accounts or other means can result in revoked access. The server's own lower safety limits do not constitute Google approval or increase provider quota.
 5. Save the Data Access changes. In **Google Auth platform → Audience**, leave **Publishing status** as **Testing** for now — see [Step 7](#step-7--important-google-verification).
 
 ---
@@ -154,7 +154,7 @@ The template also sets `GSC_ACCESS_MODE` to `readwrite`, preserving the historic
 }
 ```
 
-Read-only deployments request `webmasters.readonly`, omit the Indexing API scope, and do not register `sites.add`, `sites.delete`, `sitemaps.submit`, `sitemaps.delete`, `indexing.request`, or the otherwise read-only `indexing.status` lookup. Changing modes affects OAuth grants for future connections; reconnect users after changing the mode so Google grants the matching scope set.
+Read-only deployments request `webmasters.readonly`, omit the Indexing API scope, and do not register `sites.add`, `sites.delete`, `sitemaps.submit`, `sitemaps.delete`, `indexing.request`, `indexing.remove`, or the otherwise read-only `indexing.status` lookup. Changing modes affects OAuth grants for future connections; reconnect users after changing the mode so Google grants the matching scope set.
 
 `wrangler.jsonc` is gitignored because it contains your account's namespace ids. The `wrangler.example.jsonc` template stays in git.
 

package/package.json

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

package/src/access-mode.ts

@@ -23,6 +23,7 @@ export const WRITE_TOOL_NAMES = [
   'sitemaps.submit',
   'sitemaps.delete',
   'indexing.request',
+  'indexing.remove',
 ] as const;
 
 const INDEXING_SCOPE_READ_TOOL_NAMES = ['indexing.status'] as const;

package/src/date-validation.ts

@@ -1,7 +1,13 @@
 import { z } from 'zod';
 
 const YYYY_MM_DD = /^(\d{4})-(\d{2})-(\d{2})$/;
-const SEARCH_CONSOLE_TIME_ZONE = 'America/Los_Angeles';
+export const SEARCH_CONSOLE_TIME_ZONE = 'America/Los_Angeles';
+export const SEARCH_CONSOLE_DATE_TIME_ZONE_NOTE =
+  'Google Search Console interprets this calendar date in Pacific Time (America/Los_Angeles; UTC-8/UTC-7 depending on daylight saving time).';
+
+export function searchConsoleDateDescription(base: string): string {
+  return `${base} ${SEARCH_CONSOLE_DATE_TIME_ZONE_NOTE}`;
+}
 
 export function getSearchConsoleCalendarDate(now: Date = new Date()): string {
   const parts = new Intl.DateTimeFormat('en-US', {

package/src/digest.ts

@@ -1,4 +1,8 @@
-import { querySearchAnalytics, type SearchAnalyticsRow } from './google';
+import {
+  hasRecordedPosition,
+  querySearchAnalytics,
+  type SearchAnalyticsRow,
+} from './google';
 import type { GoogleAccessTokenProvider } from './access-token-lifecycle';
 import { getSearchConsoleCalendarDate } from './date-validation';
 
@@ -180,13 +184,15 @@ function totalsFromRow(row: SearchAnalyticsRow | undefined): SiteTotals {
 }
 
 function rowsToQueries(rows: SearchAnalyticsRow[]): QueryRow[] {
-  return rows.map((r) => ({
-    query: r.keys?.[0] ?? '',
-    clicks: r.clicks,
-    impressions: r.impressions,
-    ctr: r.ctr,
-    position: r.position,
-  }));
+  return rows
+    .filter(hasRecordedPosition)
+    .map((r) => ({
+      query: r.keys?.[0] ?? '',
+      clicks: r.clicks,
+      impressions: r.impressions,
+      ctr: r.ctr,
+      position: r.position,
+    }));
 }
 
 function rowsToPages(rows: SearchAnalyticsRow[]): PageRow[] {

package/src/google.ts

@@ -399,7 +399,20 @@ export interface SearchAnalyticsRow {
   clicks: number;
   impressions: number;
   ctr: number;
-  position: number;
+  /**
+   * Average position when Google records it. Search Console does not record
+   * position for Discover or the Google News app/news.google.com, so those
+   * Search Analytics rows can legitimately omit this field.
+   */
+  position?: number;
+}
+
+export type PositionedSearchAnalyticsRow = SearchAnalyticsRow & { position: number };
+
+export function hasRecordedPosition(
+  row: SearchAnalyticsRow,
+): row is PositionedSearchAnalyticsRow {
+  return row.position !== undefined;
 }
 
 export interface SearchAnalyticsResponseMetadata {
@@ -812,6 +825,7 @@ export function processQuickWins(
   maxPosition: number,
 ): QuickWinResult[] {
   return rows
+    .filter(hasRecordedPosition)
     .filter(
       (row) =>
         (row.keys?.length ?? 0) >= 2 &&
@@ -860,7 +874,7 @@ export function processCannibalization(
 ): CannibalizationResult[] {
   const queryGroups = new Map<string, Array<{ page: string; clicks: number; impressions: number; ctr: number; position: number }>>();
   for (const row of rows) {
-    if ((row.keys?.length ?? 0) < 2) continue;
+    if ((row.keys?.length ?? 0) < 2 || row.position === undefined) continue;
     const query = row.keys![0];
     const page = row.keys![1];
     if (!queryGroups.has(query)) {
@@ -1010,7 +1024,7 @@ export function processContentDecay(
 ): DecayPageResult[] {
   const recentMap = new Map<string, { clicks: number; impressions: number; ctr: number; position: number }>();
   for (const row of recentRows) {
-    if ((row.keys?.length ?? 0) < 1) continue;
+    if ((row.keys?.length ?? 0) < 1 || row.position === undefined) continue;
     recentMap.set(row.keys![0], {
       clicks: row.clicks,
       impressions: row.impressions,
@@ -1022,7 +1036,7 @@ export function processContentDecay(
   const decayCandidates: DecayPageResult[] = [];
 
   for (const row of previousRows) {
-    if ((row.keys?.length ?? 0) < 1) continue;
+    if ((row.keys?.length ?? 0) < 1 || row.position === undefined) continue;
     const page = row.keys![0];
     const prevClicks = row.clicks;
     const prevImps = row.impressions;
@@ -1458,15 +1472,124 @@ export async function checkIndexingEligibility(
   };
 }
 
-export async function requestIndexing(
-  accessToken: string,
+function hasRobotsNoindexMeta(html: string): boolean {
+  // HTML permits an omitted </head>, so stop at </head>, <body>, or EOF.
+  const head = /<head\b[^>]*>([\s\S]*?)(?:<\/head\s*>|<body\b|$)/i.exec(html)?.[1];
+  if (!head) return false;
+
+  const metaPattern = /<meta\b([^>]*)>/gi;
+  let match: RegExpExecArray | null;
+  while ((match = metaPattern.exec(head)) !== null) {
+    const name = htmlAttribute(match[1], 'name')?.trim().toLowerCase();
+    if (name !== 'robots') continue;
+    const content = htmlAttribute(match[1], 'content')?.trim().toLowerCase();
+    if (!content) continue;
+    const directives = content.split(/[\s,]+/).filter(Boolean);
+    if (directives.includes('noindex')) return true;
+  }
+
+  return false;
+}
+
+const INDEXING_REMOVAL_REQUIREMENT_MESSAGE =
+  'Before requesting removal, Google requires the URL to return HTTP 404 or 410, or the page to contain a robots noindex meta directive.';
+
+/**
+ * Verifies Google's documented precondition for an Indexing API URL_DELETED
+ * notification without requiring the page to keep its former structured data.
+ */
+export async function checkIndexingRemovalEligibility(
   url: string,
-): Promise<unknown> {
-  const eligibility = await checkIndexingEligibility(url);
-  if (!eligibility.eligible) {
-    throw new Error(eligibility.reason);
+  { timeoutMs = INDEXING_ELIGIBILITY_TIMEOUT_MS }: IndexingEligibilityOptions = {},
+): Promise<IndexingEligibility> {
+  if (!isHttpUrl(url)) {
+    return {
+      eligible: false,
+      reason: `${url} must be a valid HTTP or HTTPS URL. ${INDEXING_REMOVAL_REQUIREMENT_MESSAGE}`,
+    };
   }
 
+  const controller = new AbortController();
+  let timedOut = false;
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+
+  try {
+    const resp = await fetch(url, {
+      signal: controller.signal,
+      redirect: 'manual',
+      headers: {
+        'user-agent':
+          'Mozilla/5.0 (compatible; DigestSEO-GSC-MCP/1.0; +https://github.com/AKzar1el/mcp-gsc)',
+      },
+    });
+
+    if (resp.status === 404 || resp.status === 410) {
+      await cancelResponseBody(resp);
+      return { eligible: true };
+    }
+
+    if (!resp.ok) {
+      await cancelResponseBody(resp);
+      return {
+        eligible: false,
+        reason: `Could not confirm indexing-removal eligibility for ${url} (HTTP ${resp.status}). ${INDEXING_REMOVAL_REQUIREMENT_MESSAGE}`,
+      };
+    }
+
+    const contentType = resp.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase();
+    if (
+      contentType &&
+      contentType !== 'text/html' &&
+      contentType !== 'application/xhtml+xml'
+    ) {
+      await cancelResponseBody(resp);
+      return {
+        eligible: false,
+        reason: `Could not confirm indexing-removal eligibility for ${url} (expected HTML, received ${contentType}). ${INDEXING_REMOVAL_REQUIREMENT_MESSAGE}`,
+      };
+    }
+
+    const contentLength = Number(resp.headers.get('content-length'));
+    if (
+      Number.isFinite(contentLength) &&
+      contentLength > INDEXING_ELIGIBILITY_MAX_RESPONSE_BYTES
+    ) {
+      await cancelResponseBody(resp);
+      return {
+        eligible: false,
+        reason: `Could not confirm indexing-removal eligibility for ${url} (response exceeds the ${INDEXING_ELIGIBILITY_MAX_RESPONSE_BYTES}-byte limit). ${INDEXING_REMOVAL_REQUIREMENT_MESSAGE}`,
+      };
+    }
+
+    const html = await readBoundedResponseText(resp);
+    if (hasRobotsNoindexMeta(html)) return { eligible: true };
+
+    return {
+      eligible: false,
+      reason: `${url} does not currently return HTTP 404/410 and does not expose a robots noindex meta directive. ${INDEXING_REMOVAL_REQUIREMENT_MESSAGE}`,
+    };
+  } catch (err) {
+    const detail = timedOut
+      ? `timed out after ${timeoutMs}ms`
+      : (err as Error).message;
+    return {
+      eligible: false,
+      reason: `Could not confirm indexing-removal eligibility for ${url} (${detail}). ${INDEXING_REMOVAL_REQUIREMENT_MESSAGE}`,
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function publishIndexingNotification(
+  accessToken: string,
+  url: string,
+  type: 'URL_UPDATED' | 'URL_DELETED',
+  actionLabel: string,
+): Promise<unknown> {
   const resp = await fetch(
     'https://indexing.googleapis.com/v3/urlNotifications:publish',
     {
@@ -1475,10 +1598,7 @@ export async function requestIndexing(
         authorization: `Bearer ${accessToken}`,
         'content-type': 'application/json',
       },
-      body: JSON.stringify({
-        url,
-        type: 'URL_UPDATED',
-      }),
+      body: JSON.stringify({ url, type }),
     },
   );
   if (resp.status === 401) {
@@ -1486,11 +1606,38 @@ export async function requestIndexing(
   }
   if (!resp.ok) {
     const text = await resp.text();
-    throw new Error(`Request indexing failed: ${resp.status} ${text}`);
+    throw new Error(`${actionLabel} failed: ${resp.status} ${text}`);
   }
   return await resp.json();
 }
 
+export async function requestIndexing(
+  accessToken: string,
+  url: string,
+): Promise<unknown> {
+  const eligibility = await checkIndexingEligibility(url);
+  if (!eligibility.eligible) {
+    throw new Error(eligibility.reason);
+  }
+  return publishIndexingNotification(accessToken, url, 'URL_UPDATED', 'Request indexing');
+}
+
+export async function requestIndexingRemoval(
+  accessToken: string,
+  url: string,
+): Promise<unknown> {
+  const eligibility = await checkIndexingRemovalEligibility(url);
+  if (!eligibility.eligible) {
+    throw new Error(eligibility.reason);
+  }
+  return publishIndexingNotification(
+    accessToken,
+    url,
+    'URL_DELETED',
+    'Request indexing removal',
+  );
+}
+
 export interface IndexingNotification {
   url?: string;
   type?: 'URL_UPDATED' | 'URL_DELETED' | string;
@@ -1555,7 +1702,7 @@ export function processPerformanceComparison(
 ): PerformanceComparisonRow[] {
   const mapB = new Map<string, { clicks: number; impressions: number; ctr: number; position: number }>();
   for (const row of rowsB) {
-    if ((row.keys?.length ?? 0) < 1) continue;
+    if ((row.keys?.length ?? 0) < 1 || row.position === undefined) continue;
     mapB.set(row.keys![0], {
       clicks: row.clicks,
       impressions: row.impressions,
@@ -1567,7 +1714,7 @@ export function processPerformanceComparison(
   const comparison: PerformanceComparisonRow[] = [];
 
   for (const row of rowsA) {
-    if ((row.keys?.length ?? 0) < 1) continue;
+    if ((row.keys?.length ?? 0) < 1 || row.position === undefined) continue;
     const key = row.keys![0];
     const clicksA = row.clicks;
     const impsA = row.impressions;

package/src/index.ts

@@ -24,10 +24,12 @@ import {
   submitSitemap,
   deleteSitemap,
   getSitemap,
+  hasRecordedPosition,
   processQuickWins,
   processCannibalization,
   processContentDecay,
   requestIndexing,
+  requestIndexingRemoval,
   getIndexingNotificationMetadata,
   processPerformanceComparison,
   type PaginatedSearchAnalyticsResult,
@@ -58,6 +60,7 @@ import {
   assertDateRange,
   getSearchConsoleCalendarDate,
   SEARCH_CONSOLE_DATE_SCHEMA,
+  searchConsoleDateDescription,
 } from './date-validation';
 import { CONTENT_DECAY_COMPARE_DAYS_SCHEMA } from './content-decay-schema';
 import { resolveIndexedPagesDateRange } from './indexed-pages-range';
@@ -132,7 +135,15 @@ const SEARCH_ROW_OUTPUT_SCHEMA = {
     .describe(
       'Dimension values returned by Google. Aggregate queries with dimensions: [] may legitimately omit this field.',
     ),
-  ...METRIC_OUTPUT_SCHEMA,
+  clicks: z.number(),
+  impressions: z.number(),
+  ctr: z.number(),
+  position: z
+    .number()
+    .optional()
+    .describe(
+      'Average position when Google records it. Omitted for Discover and Google News, where Search Console does not record position.',
+    ),
 };
 
 const SITE_OUTPUT_SCHEMA = {
@@ -473,6 +484,11 @@ const INDEXING_OUTPUT_SCHEMA = {
   provider_usage_note: z.string(),
 };
 
+const INDEXING_REMOVE_OUTPUT_SCHEMA = {
+  ...INDEXING_OUTPUT_SCHEMA,
+  removal_completion_proven: z.literal(false),
+};
+
 const INDEXING_NOTIFICATION_SCHEMA = z.object({
   url: z.string().optional(),
   type: z.string().optional(),
@@ -709,6 +725,11 @@ const TOOL_CATALOG = [
     description:
       'Request an eligible JobPosting or livestream URL update through Google\'s restricted Indexing API; this is not a general webpage submission tool. Google treats the default publish quota as onboarding/testing capacity, requires approval for ongoing usage/resource provisioning, and spam-screens submissions.',
   },
+  {
+    name: 'indexing.remove',
+    description:
+      "Request a URL_DELETED notification for a previously eligible JobPosting or livestream URL through Google's restricted Indexing API. The URL must already return HTTP 404/410 or expose a robots noindex meta directive; notification receipt does not prove removal completed.",
+  },
   {
     name: 'indexing.status',
     description:
@@ -1125,9 +1146,13 @@ class GscMcpRuntime {
         ].join('\n'),
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
-          start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date (inclusive) in YYYY-MM-DD format.'),
+          start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe(
+            searchConsoleDateDescription('Start date (inclusive) in YYYY-MM-DD format.'),
+          ),
           end_date: SEARCH_CONSOLE_DATE_SCHEMA.describe(
-            'End date (inclusive) in YYYY-MM-DD format. Recent dates are allowed: data_state all/hourly_all can include preliminary data, while final returns only finalized data.',
+            searchConsoleDateDescription(
+              'End date (inclusive) in YYYY-MM-DD format. Recent dates are allowed: data_state all/hourly_all can include preliminary data, while final returns only finalized data.',
+            ),
           ),
           dimensions: z
             .array(
@@ -1296,8 +1321,14 @@ class GscMcpRuntime {
         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.'),
+          start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe(
+            searchConsoleDateDescription('Start date (inclusive) in YYYY-MM-DD format.'),
+          ),
+          end_date: SEARCH_CONSOLE_DATE_SCHEMA.describe(
+            searchConsoleDateDescription(
+              'End date (inclusive) in YYYY-MM-DD format. Note the 2-3 day GSC data lag.',
+            ),
+          ),
           search_type: z
             .enum(['web', 'image', 'video', 'news'])
             .default('web')
@@ -1342,7 +1373,7 @@ class GscMcpRuntime {
           ],
         }, { maxRows: sourceRowLimit });
         const rows = source.rows
-          .filter((row) => (row.keys?.length ?? 0) > 0)
+          .filter((row) => (row.keys?.length ?? 0) > 0 && hasRecordedPosition(row))
           .map((row) => ({
             query: row.keys![0],
             clicks: row.clicks,
@@ -1374,8 +1405,14 @@ class GscMcpRuntime {
         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.'),
+          start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe(
+            searchConsoleDateDescription('Start date (inclusive) in YYYY-MM-DD format.'),
+          ),
+          end_date: SEARCH_CONSOLE_DATE_SCHEMA.describe(
+            searchConsoleDateDescription(
+              'End date (inclusive) in YYYY-MM-DD format. Note the 2-3 day GSC data lag.',
+            ),
+          ),
           search_type: z
             .enum(['web', 'image', 'video', 'news'])
             .default('web')
@@ -1420,7 +1457,7 @@ class GscMcpRuntime {
           ],
         }, { maxRows: sourceRowLimit });
         const rows = source.rows
-          .filter((row) => (row.keys?.length ?? 0) > 0)
+          .filter((row) => (row.keys?.length ?? 0) > 0 && hasRecordedPosition(row))
           .map((row) => ({
             page: row.keys![0],
             clicks: row.clicks,
@@ -1608,8 +1645,14 @@ class GscMcpRuntime {
         description: 'Analyze query/page Search Analytics to find queries split across multiple pages. Candidates are ranked deterministically by the observed query/page impression sum, each candidate bounds its page list, and limit/start_row plus result_page provide safe pagination. total_clicks, total_impressions, and impression_share are calculated from observed query/page rows and are not true query-level property aggregates; multiple pages can make that row sum exceed the query-level Search Console total. Multiple ranking URLs can also reflect legitimate locale or intent differences, so treat candidates as evidence to investigate rather than proof of harmful cannibalization.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
-          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.'),
+          start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe(
+            searchConsoleDateDescription('Start date (inclusive) in YYYY-MM-DD format.'),
+          ),
+          end_date: SEARCH_CONSOLE_DATE_SCHEMA.describe(
+            searchConsoleDateDescription(
+              'End date (inclusive) in YYYY-MM-DD format. Note the 2-3 day GSC data lag.',
+            ),
+          ),
           min_impressions: CANNIBALIZATION_MIN_IMPRESSIONS_SCHEMA,
           min_page_percentage: CANNIBALIZATION_MIN_PAGE_PERCENTAGE_SCHEMA,
           limit: ANALYSIS_RESULT_LIMIT_SCHEMA,
@@ -1818,6 +1861,48 @@ class GscMcpRuntime {
         return toolResponse(JSON.stringify(payload, null, 2), payload);
       },
       );
+
+      this.server.registerTool(
+      'indexing.remove',
+      {
+        title: 'Request Indexing API removal',
+        description: "Requests a URL_DELETED notification through Google's Indexing API for a URL within an owner-level Search Console property accessible to the connected Google account. Use only for pages that were eligible for the restricted Indexing API (JobPosting or livestream BroadcastEvent in VideoObject). Before removal Google requires the URL to return HTTP 404/410 or contain a robots noindex meta directive. A successful notification is only receipt acknowledgment and does not prove Google removed the URL from its index.",
+        inputSchema: {
+          site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA.describe(`${SEARCH_CONSOLE_PROPERTY_DESCRIPTION} The connected Google account must be an owner of this property.`),
+          url: z.string().superRefine((value, ctx) => {
+            try {
+              assertIndexingRequestUrl(value);
+            } catch (error) {
+              ctx.addIssue({
+                code: 'custom',
+                message: (error as Error).message,
+              });
+            }
+          }).describe('The fully qualified HTTP/HTTPS URL to request removal for. It must fall within site_url, must have been eligible for the restricted Indexing API, and must currently return HTTP 404/410 or contain a robots noindex meta directive.'),
+        },
+        outputSchema: INDEXING_REMOVE_OUTPUT_SCHEMA,
+        annotations: WRITE_TOOL_ANNOTATIONS['indexing.remove'],
+      },
+      async ({ site_url, url }) => {
+        const googleId = this.requireGoogleId();
+        const rateLimitError = await this.rateLimitError(googleId, 'indexing.remove');
+        if (rateLimitError) return rateLimitError;
+        const accessToken = await this.getAccessToken(googleId);
+        const sites = await listSites(accessToken);
+        assertIndexingUrlAuthorized(url, site_url, sites);
+        const result = await requestIndexingRemoval(accessToken, url);
+        const payload = {
+          result,
+          note: "Google accepting this URL_DELETED notification only confirms receipt. It does not prove the URL was removed from Google's index; use URL Inspection for indexed-state evidence.",
+          provider_default_quota_for_testing_only: true as const,
+          provider_usage_approval_required: true as const,
+          provider_spam_detection_applies: true as const,
+          provider_usage_note: INDEXING_PROVIDER_USAGE_NOTE,
+          removal_completion_proven: false as const,
+        };
+        return toolResponse(JSON.stringify(payload, null, 2), payload);
+      },
+      );
     }
 
     this.server.registerTool(
@@ -1827,8 +1912,16 @@ class GscMcpRuntime {
         description: `${SEARCH_VISIBLE_PAGES_DESCRIPTION} When one date boundary is omitted, the server derives the other to target an inclusive 30-day range; generated end dates are capped at the latest complete date. Responses are bounded and pageable with row_limit/start_row.`,
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
-          start_date: SEARCH_CONSOLE_DATE_SCHEMA.optional().describe('Start date (inclusive) in YYYY-MM-DD format. If end_date is omitted, the generated end date is 29 days later, capped at the latest complete date.'),
-          end_date: SEARCH_CONSOLE_DATE_SCHEMA.optional().describe('End date (inclusive) in YYYY-MM-DD format. If start_date is omitted, the generated start date is 29 days earlier. Defaults to 3 days ago. Note the 2-3 day data lag.'),
+          start_date: SEARCH_CONSOLE_DATE_SCHEMA.optional().describe(
+            searchConsoleDateDescription(
+              'Start date (inclusive) in YYYY-MM-DD format. If end_date is omitted, the generated end date is 29 days later, capped at the latest complete date.',
+            ),
+          ),
+          end_date: SEARCH_CONSOLE_DATE_SCHEMA.optional().describe(
+            searchConsoleDateDescription(
+              'End date (inclusive) in YYYY-MM-DD format. If start_date is omitted, the generated start date is 29 days earlier. Defaults to 3 days ago. Note the 2-3 day data lag.',
+            ),
+          ),
           row_limit: z.number().int().min(1).max(25000).default(1000).describe(`Maximum pages requested for this logical response (1-25000). Output is safely bounded; continue with result_page.next_start_row while result_page.has_more is true.`),
           start_row: z.number().int().min(0).default(0).describe('Zero-based page-row offset for pagination.'),
         },
@@ -1856,7 +1949,7 @@ class GscMcpRuntime {
         });
 
         const pages = response.rows
-          .filter((row) => (row.keys?.length ?? 0) > 0)
+          .filter((row) => (row.keys?.length ?? 0) > 0 && hasRecordedPosition(row))
           .map((row) => ({
             page: row.keys![0],
             clicks: row.clicks,
@@ -1887,10 +1980,18 @@ class GscMcpRuntime {
         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)'),
-          end_date_a: SEARCH_CONSOLE_DATE_SCHEMA.describe('End date of Period A (recent, YYYY-MM-DD)'),
-          start_date_b: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date of Period B (previous, YYYY-MM-DD)'),
-          end_date_b: SEARCH_CONSOLE_DATE_SCHEMA.describe('End date of Period B (previous, YYYY-MM-DD)'),
+          start_date_a: SEARCH_CONSOLE_DATE_SCHEMA.describe(
+            searchConsoleDateDescription('Start date of Period A (recent, YYYY-MM-DD).'),
+          ),
+          end_date_a: SEARCH_CONSOLE_DATE_SCHEMA.describe(
+            searchConsoleDateDescription('End date of Period A (recent, YYYY-MM-DD).'),
+          ),
+          start_date_b: SEARCH_CONSOLE_DATE_SCHEMA.describe(
+            searchConsoleDateDescription('Start date of Period B (previous, YYYY-MM-DD).'),
+          ),
+          end_date_b: SEARCH_CONSOLE_DATE_SCHEMA.describe(
+            searchConsoleDateDescription('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'])
@@ -1997,7 +2098,11 @@ class GscMcpRuntime {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           end_date: SEARCH_CONSOLE_DATE_SCHEMA
             .optional()
-            .describe('End date (inclusive) in YYYY-MM-DD format. Defaults to 3 days ago, which is usually the latest complete Search Console date. Pass a more recent date explicitly to include preliminary data.'),
+            .describe(
+              searchConsoleDateDescription(
+                'End date (inclusive) in YYYY-MM-DD format. Defaults to 3 days ago, which is usually the latest complete Search Console date. Pass a more recent date explicitly to include preliminary data.',
+              ),
+            ),
         },
         outputSchema: WEEKLY_DIGEST_OUTPUT_SCHEMA,
         annotations: READ_ONLY_ANNOTATIONS,

package/src/quick-wins-schema.ts

@@ -1,5 +1,8 @@
 import { z } from 'zod';
-import { SEARCH_CONSOLE_DATE_SCHEMA } from './date-validation';
+import {
+  SEARCH_CONSOLE_DATE_SCHEMA,
+  searchConsoleDateDescription,
+} from './date-validation';
 import { SEARCH_CONSOLE_PROPERTY_SCHEMA } from './search-console-property-schema';
 import {
   DEFAULT_ANALYSIS_RESULT_LIMIT,
@@ -21,8 +24,14 @@ export function createQuickWinsInputSchema() {
   return z
     .object({
       site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
-      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.'),
+      start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe(
+        searchConsoleDateDescription('Start date (inclusive) in YYYY-MM-DD format.'),
+      ),
+      end_date: SEARCH_CONSOLE_DATE_SCHEMA.describe(
+        searchConsoleDateDescription(
+          'End date (inclusive) in YYYY-MM-DD format. Note the 2-3 day GSC data lag.',
+        ),
+      ),
       ...QUICK_WINS_THRESHOLDS_SHAPE,
       limit: z
         .number()

package/src/tool-rate-limit.ts

@@ -59,7 +59,7 @@ export const TOOL_RATE_LIMIT_POLICIES = {
   },
   indexing_request: {
     category: 'indexing-request',
-    tools: ['indexing.request'],
+    tools: ['indexing.request', 'indexing.remove'],
     // Google's 200 publish/day default is onboarding/testing quota and does
     // not itself authorize ongoing use. Mirror that number only as a local
     // safety ceiling; two per user reserves it for up to 100 users.

package/src/write-tool-annotations.ts

@@ -4,10 +4,10 @@
  * MCP defines destructiveHint=false for non-read-only tools that perform only
  * additive updates. Search Console's site addition and sitemap submission are
  * additive PUT operations; the corresponding DELETE operations remain
- * destructive. Indexing publishes a URL_UPDATED notification with POST; each
- * call can consume quota and change Google's indexing state, so it remains
- * conservative (destructive + non-idempotent). Tool annotations are client
- * hints, not an enforcement or confirmation mechanism.
+ * destructive. Indexing update/removal notifications use POST; each call can
+ * consume quota and change Google's indexing state, so both remain conservative
+ * (destructive + non-idempotent). Tool annotations are client hints, not an
+ * enforcement or confirmation mechanism.
  */
 export const WRITE_TOOL_ANNOTATIONS = {
   'sites.add': {
@@ -35,7 +35,12 @@ export const WRITE_TOOL_ANNOTATIONS = {
     openWorldHint: true,
   },
   'indexing.request': {
-    // The implementation only publishes URL_UPDATED, never URL_DELETED.
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  'indexing.remove': {
     readOnlyHint: false,
     destructiveHint: true,
     idempotentHint: false,