@digestseo/mcp-gsc 0.4.16 → 0.4.17

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.17] - 2026-09-22
+
+### Added
+- `indexing.status` reads Google's latest successful Indexing API update/remove notification receipts for a previously submitted URL while explicitly distinguishing notification receipt from crawl, index coverage, indexing completion, or removal completion.
+
+### Fixed
+- `sites.delete` now describes and reports Google's actual account-scoped effect: it removes the property from the connected user's Search Console site set rather than implying that the website itself or a global Search Console property is deleted.
+
 ## [0.4.16] - 2026-09-22
 
 ### Fixed

package/README.md

@@ -72,7 +72,7 @@ It runs on [Cloudflare Workers](https://workers.cloudflare.com/) and ships with
 
 ## Tools
 
-By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 21 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 read-only 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.
 
 | Tool | Access | What it does |
 |---|---|---|
@@ -87,13 +87,14 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 21 tools. Read-onl
 | **`insights.quick_wins`** / **`insights.cannibalization`** / **`insights.content_decay`** | Read | Surface average-position opportunity rows, query/page overlap, and evidence-ranked click declines. Quick-win candidates are observed query/page rows selected by aggregate Search Console average position, not proof of a stable current rank, and CTR is context rather than an eligibility filter. Cannibalization candidate totals/shares are scoped to observed query/page rows rather than true query-level property totals; content-decay results compare only pages returned in both periods and do not turn one-sided row absence into zero traffic. |
 | **`indexing.list_pages`** / **`analytics.compare`** | Read | Analyze pages receiving Search Console impressions and compare two periods, optionally using the same search type and query/page/country/device/search-appearance filters for both periods. `analytics.compare` compares only dimension keys returned in both period responses; a key absent from one non-exhaustive Search Analytics response is not assumed to have zero metrics. Because its comparison contract includes average position, it excludes Discover and Google News. `indexing.list_pages` is performance data, not index coverage: a missing URL may still be indexed; use `urls.inspect` / `urls.inspect_many` for URL-level index status. |
 | **`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. `sites.add` only adds the property to the connected account's Search Console site set; it returns `ownership_verification_performed: false` because ownership verification is a separate Google Site Verification/Search Console workflow. |
+| **`sites.add`** / **`sites.delete`** | Write | Add or remove a property from the connected account's Search Console site set. `sites.add` returns `ownership_verification_performed: false` because ownership verification is a separate Google Site Verification/Search Console workflow. `sites.delete` removes the property from that account's Search Console site set; it does not delete the website itself. |
 | **`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. |
 
 > **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. 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 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.
 
 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.
 

package/SECURITY.md

@@ -51,8 +51,8 @@ Notes:
 ## Tool rate limits
 
 The server enforces the following fixed-window limits before making upstream
-requests. They are per authenticated user and tool category; `indexing.request`
-also has a deployment-wide project guard. A rejected invocation returns a retry
+requests. They are per authenticated user and tool category; the Indexing API
+publish and metadata-read categories also have deployment-wide project guards. A rejected invocation returns a retry
 delay and does not disclose another user's usage.
 
 | Category | Tools | Limit |
@@ -61,9 +61,11 @@ delay and does not disclose another user's usage.
 | 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 metadata | `indexing.status` | 30 per user / minute; 180 per deployment / minute |
 | Weekly digest | `reports.weekly_digest` | 6 per user / hour |
 
-The Indexing API's default publish quota is 200 requests per project per day.
+The Indexing API's default publish quota is 200 requests per project per day,
+and its default metadata-read quota is 180 requests per project per minute.
 Search Analytics and URL Inspection have separate load and per-site quotas, so
 these limits are intentionally conservative rather than a replacement for
 monitoring the Google Cloud project quota.

package/SETUP.md

@@ -155,7 +155,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`, or `indexing.request`. 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`, 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.16",
+  "version": "0.4.17",
   "private": false,
   "main": "scripts/glama-start.mjs",
   "bin": {

package/src/access-mode.ts

@@ -25,6 +25,13 @@ export const WRITE_TOOL_NAMES = [
   'indexing.request',
 ] as const;
 
+const INDEXING_SCOPE_READ_TOOL_NAMES = ['indexing.status'] as const;
+
+const READWRITE_ONLY_TOOL_NAMES = [
+  ...WRITE_TOOL_NAMES,
+  ...INDEXING_SCOPE_READ_TOOL_NAMES,
+] as const;
+
 export function resolveGscAccessMode(value: string | undefined): GscAccessMode {
   if (value === undefined || value === '') {
     return DEFAULT_GSC_ACCESS_MODE;
@@ -54,6 +61,6 @@ export function getToolCatalogForAccessMode<T extends { name: string }>(
   }
 
   return tools.filter(
-    (tool) => !(WRITE_TOOL_NAMES as readonly string[]).includes(tool.name),
+    (tool) => !(READWRITE_ONLY_TOOL_NAMES as readonly string[]).includes(tool.name),
   );
 }

package/src/google.ts

@@ -1475,6 +1475,42 @@ export async function requestIndexing(
   return await resp.json();
 }
 
+export interface IndexingNotification {
+  url?: string;
+  type?: 'URL_UPDATED' | 'URL_DELETED' | string;
+  notifyTime?: string;
+}
+
+export interface IndexingNotificationMetadata {
+  url?: string;
+  latestUpdate?: IndexingNotification;
+  latestRemove?: IndexingNotification;
+}
+
+export async function getIndexingNotificationMetadata(
+  accessToken: string,
+  url: string,
+): Promise<IndexingNotificationMetadata> {
+  const endpoint = new URL(
+    'https://indexing.googleapis.com/v3/urlNotifications/metadata',
+  );
+  endpoint.searchParams.set('url', url);
+
+  const resp = await fetchGoogleRead(endpoint.toString(), {
+    headers: { authorization: `Bearer ${accessToken}` },
+  });
+  if (resp.status === 401) {
+    throw new Error(GSC_ACCESS_REVOKED_MESSAGE);
+  }
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(
+      `Get indexing notification status failed: ${resp.status} ${text}`,
+    );
+  }
+  return (await resp.json()) as IndexingNotificationMetadata;
+}
+
 export interface PerformanceComparisonRow {
   key: string;
   period_a: { clicks: number; impressions: number; ctr: number; position: number };

package/src/index.ts

@@ -28,6 +28,7 @@ import {
   processCannibalization,
   processContentDecay,
   requestIndexing,
+  getIndexingNotificationMetadata,
   processPerformanceComparison,
   type PaginatedSearchAnalyticsResult,
 } from './google';
@@ -301,6 +302,13 @@ const SITE_ADD_OUTPUT_SCHEMA = {
   ownership_verification_note: z.string(),
 };
 
+const SITE_DELETE_OUTPUT_SCHEMA = {
+  message: z.string(),
+  removed_from_connected_account_site_set: z.literal(true),
+  website_content_deleted: z.literal(false),
+  provider_scope_note: z.string(),
+};
+
 const SEARCH_ANALYTICS_PAGINATION_OUTPUT_SCHEMA = z.object({
   rows_fetched: z.number().int().nonnegative(),
   pages_fetched: z.number().int().positive(),
@@ -453,6 +461,24 @@ const INDEXING_OUTPUT_SCHEMA = {
   provider_usage_note: z.string(),
 };
 
+const INDEXING_NOTIFICATION_SCHEMA = z.object({
+  url: z.string().optional(),
+  type: z.string().optional(),
+  notifyTime: z.string().optional(),
+});
+
+const INDEXING_STATUS_OUTPUT_SCHEMA = {
+  notification_metadata: z.object({
+    url: z.string().optional(),
+    latestUpdate: INDEXING_NOTIFICATION_SCHEMA.optional(),
+    latestRemove: INDEXING_NOTIFICATION_SCHEMA.optional(),
+  }),
+  notification_receipt_only: z.literal(true),
+  index_coverage_report: z.literal(false),
+  indexing_or_removal_completion_proven: z.literal(false),
+  note: z.string(),
+};
+
 const INDEXED_PAGES_OUTPUT_SCHEMA = {
   pages: z.array(z.object({ page: z.string(), ...METRIC_OUTPUT_SCHEMA })),
   note: z.string(),
@@ -604,7 +630,7 @@ const TOOL_CATALOG = [
   {
     name: 'sites.delete',
     description:
-      'Remove an existing website property from your Google Search Console account.',
+      "Remove an existing website property from the connected Google account's Search Console site set. This changes that account's Search Console membership for the property; it does not delete the website itself.",
   },
   {
     name: 'analytics.query',
@@ -671,6 +697,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.status',
+    description:
+      'Read the latest successful Indexing API update/remove notifications Google received for a previously submitted URL. This reports notification receipt only, not crawl, index coverage, indexing completion, or removal completion.',
+  },
   {
     name: 'indexing.list_pages',
     description: SEARCH_VISIBLE_PAGES_DESCRIPTION,
@@ -1413,12 +1444,12 @@ class GscMcpRuntime {
       this.server.registerTool(
       'sites.delete',
       {
-        title: 'Delete Search Console property',
-        description: 'Remove an existing website property from your Google Search Console account.',
+        title: 'Remove Search Console property from account',
+        description: "Remove an existing website property from the connected Google account's Search Console site set. Google documents this operation as removing the site from the user's Search Console sites; it does not delete website content.",
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
         },
-        outputSchema: MESSAGE_OUTPUT_SCHEMA,
+        outputSchema: SITE_DELETE_OUTPUT_SCHEMA,
         annotations: WRITE_TOOL_ANNOTATIONS['sites.delete'],
       },
       async ({ site_url }) => {
@@ -1427,8 +1458,14 @@ class GscMcpRuntime {
         if (rateLimitError) return rateLimitError;
         const accessToken = await this.getAccessToken(googleId);
         await deleteSite(accessToken, site_url);
-        const message = `Successfully deleted site property: ${site_url}`;
-        return toolResponse(message, { message });
+        const message = `Successfully removed site property from the connected account's Search Console site set: ${site_url}`;
+        const payload = {
+          message,
+          removed_from_connected_account_site_set: true as const,
+          website_content_deleted: false as const,
+          provider_scope_note: "Google's Sites.delete method removes the property from the connected user's Search Console site set. It does not delete the website itself.",
+        };
+        return toolResponse(`${message}\n\n${payload.provider_scope_note}`, payload);
       },
     );
 
@@ -1667,6 +1704,49 @@ class GscMcpRuntime {
     );
 
     if (accessMode === 'readwrite') {
+      this.server.registerTool(
+      'indexing.status',
+      {
+        title: 'Get Indexing API notification status',
+        description: "Read the latest successful Indexing API URL_UPDATED and URL_DELETED notifications Google received for a previously submitted URL within an owner-level Search Console property accessible to the connected Google account. This is a read-only notification-receipt lookup, not an index-coverage report and not proof that Google crawled, indexed, or removed the URL. It is available only in readwrite access mode because Google's metadata endpoint requires the Indexing API OAuth scope.",
+        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('A fully qualified HTTP/HTTPS URL previously submitted successfully through the Google Indexing API. It must fall within site_url.'),
+        },
+        outputSchema: INDEXING_STATUS_OUTPUT_SCHEMA,
+        annotations: READ_ONLY_ANNOTATIONS,
+      },
+      async ({ site_url, url }) => {
+        const googleId = this.requireGoogleId();
+        const rateLimitError = await this.rateLimitError(googleId, 'indexing.status');
+        if (rateLimitError) return rateLimitError;
+        const accessToken = await this.getAccessToken(googleId);
+        const sites = await listSites(accessToken);
+        assertIndexingUrlAuthorized(url, site_url, sites);
+        const notificationMetadata = await getIndexingNotificationMetadata(
+          accessToken,
+          url,
+        );
+        const payload = {
+          notification_metadata: notificationMetadata,
+          notification_receipt_only: true as const,
+          index_coverage_report: false as const,
+          indexing_or_removal_completion_proven: false as const,
+          note: "This reports the latest successful Indexing API notification receipt(s) Google recorded for the URL. It does not report whether Google crawled, indexed, or removed the URL; use URL Inspection for indexed-state evidence.",
+        };
+        return toolResponse(JSON.stringify(payload, null, 2), payload);
+      },
+      );
+
       this.server.registerTool(
       'indexing.request',
       {

package/src/tool-rate-limit.ts

@@ -67,6 +67,15 @@ export const TOOL_RATE_LIMIT_POLICIES = {
     userLimit: 2,
     projectLimit: 200,
   },
+  indexing_metadata: {
+    category: 'indexing-metadata',
+    tools: ['indexing.status'],
+    // Google publishes a default metadata-read quota of 180 requests per
+    // minute per project. Keep per-user headroom inside that shared ceiling.
+    windowMs: MINUTE_MS,
+    userLimit: 30,
+    projectLimit: 180,
+  },
   weekly_digest: {
     category: 'weekly-digest',
     tools: ['reports.weekly_digest'],