@digestseo/mcp-gsc 0.4.7 → 0.4.9

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [Unreleased]
+
+## [0.4.9] - 2026-09-21
+
+### Changed
+- `sites.list` now marks whether each returned property identifier matches the URL-prefix / `sc-domain:` forms currently documented by the Search Console API, and the docs explicitly avoid guessing an undocumented API identifier for Search Console platform properties.
+
+### Fixed
+- `analytics.query` now exposes `position_supported: false` plus an explicit note for Google Discover responses so agents do not interpret the generic row `position` field as a supported Discover metric.
+
+## [0.4.8] - 2026-09-21
+
+### Fixed
+- Safe Google read operations now make a tightly bounded retry on transient `408`, `429`, and `5xx` provider failures while leaving Search Console writes and OAuth/token mutation paths single-attempt; long `Retry-After` windows are surfaced immediately instead of stalling an MCP call.
+- The published `npx` launcher now forwards `GSC_ACCESS_MODE`, and MCP Registry package metadata exposes the same setting, so local self-hosters can actually select least-privilege `readonly` mode instead of silently inheriting the template's `readwrite` binding.
+
 ## [0.4.7] - 2026-09-21
 
 ### Fixed

package/README.md

@@ -24,6 +24,8 @@ npx -y @digestseo/mcp-gsc
 
 The npm launcher starts a loopback-only **Streamable HTTP** Worker on `127.0.0.1` (port `8080` by default); it is not a stdio MCP process. Clients that launch the package should connect to `http://127.0.0.1:8080/mcp` after supplying the Google OAuth and token-encryption environment variables described in [SETUP.md](SETUP.md). Before the first OAuth sign-in, authorize the exact callback `http://127.0.0.1:8080/google/callback` in Google Cloud (or use the same custom `PORT` you launch with); the launcher prints both URLs at startup.
 
+The local launcher defaults to `GSC_ACCESS_MODE=readwrite`. For least-privilege analytics/reporting-only use, set `GSC_ACCESS_MODE=readonly` in the environment before running `npx`; the launcher forwards that value into the local Worker so OAuth requests only the read-only Search Console scope and the five mutation tools stay unregistered.
+
 For Google OAuth and Cloudflare deployment configuration, follow [SETUP.md](SETUP.md).
 
 ### Connect in 30 seconds
@@ -73,7 +75,7 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 21 tools. Read-onl
 | **`server.capabilities`** | Read | List every tool this server exposes and report whether your Google connection is currently authenticated (`connected` / `not_connected`). Takes no arguments — a good first call for discovery. |
 | **`sites.list`** | Read | List the Search Console properties the connected Google account can access (`siteUrl`, `permissionLevel`). |
 | **`sites.get`** | Read | Retrieve one exact Search Console property and the connected account's permission level for it. |
-| **`analytics.query`** | Read | Impressions, clicks, CTR, and average position over a date range, with dimensions, filters, safe pagination, and selectable search type. Pass `dimensions: []` for true site totals; Google's aggregate row may omit `keys`. Search Analytics does not guarantee every data row and can return only top rows, so exhausting local pagination is not proof that the provider dataset is exhaustive. |
+| **`analytics.query`** | Read | Impressions, clicks, CTR, and average position over a date range, with dimensions, filters, safe pagination, and selectable search type. Pass `dimensions: []` for true site totals; Google's aggregate row may omit `keys`. Search Analytics does not guarantee every data row and can return only top rows, so exhausting local pagination is not proof that the provider dataset is exhaustive. For `search_type: "discover"`, `position_supported` is `false` because Google Discover does not support average position. |
 | **`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. |
 | **`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. |
@@ -85,6 +87,8 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 21 tools. Read-onl
 | **`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. |
 
+> **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.
 
 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/package.json

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

package/scripts/glama-start.mjs

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

package/src/google.ts

@@ -51,6 +51,63 @@ export class GoogleRefreshTokenRevokedError extends Error {
   }
 }
 
+const GOOGLE_READ_RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+const GOOGLE_READ_MAX_ATTEMPTS = 3;
+const GOOGLE_READ_BASE_DELAY_MS = 1_000;
+const GOOGLE_READ_MAX_DELAY_MS = 5_000;
+
+function googleReadRetryDelayMs(response: Response, retryNumber: number): number | null {
+  const retryAfter = response.headers.get('retry-after')?.trim();
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    const requestedDelay = Number.isFinite(seconds)
+      ? Math.max(0, seconds * 1_000)
+      : Math.max(0, Date.parse(retryAfter) - Date.now());
+    if (Number.isFinite(requestedDelay)) {
+      return requestedDelay <= GOOGLE_READ_MAX_DELAY_MS ? requestedDelay : null;
+    }
+  }
+
+  const exponentialDelay = GOOGLE_READ_BASE_DELAY_MS * 2 ** (retryNumber - 1);
+  const jitterMs = Math.floor(Math.random() * 250);
+  return Math.min(exponentialDelay + jitterMs, GOOGLE_READ_MAX_DELAY_MS);
+}
+
+async function fetchGoogleRead(url: string, init?: RequestInit): Promise<Response> {
+  let lastNetworkError: unknown;
+
+  for (let attempt = 1; attempt <= GOOGLE_READ_MAX_ATTEMPTS; attempt += 1) {
+    try {
+      const response = await fetch(url, init);
+      if (
+        !GOOGLE_READ_RETRYABLE_STATUSES.has(response.status) ||
+        attempt === GOOGLE_READ_MAX_ATTEMPTS
+      ) {
+        return response;
+      }
+
+      const delayMs = googleReadRetryDelayMs(response, attempt);
+      if (delayMs === null) return response;
+      try {
+        await response.body?.cancel();
+      } catch {
+        // Best-effort cleanup before retrying a transient provider response.
+      }
+      if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+    } catch (error) {
+      lastNetworkError = error;
+      if (attempt === GOOGLE_READ_MAX_ATTEMPTS) throw error;
+      const delayMs = Math.min(
+        GOOGLE_READ_BASE_DELAY_MS * 2 ** (attempt - 1) + Math.floor(Math.random() * 250),
+        GOOGLE_READ_MAX_DELAY_MS,
+      );
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
+  throw lastNetworkError;
+}
+
 export async function exchangeCodeForTokens(
   code: string,
   clientId: string,
@@ -89,7 +146,7 @@ export interface GoogleUserInfo {
 export async function fetchGoogleUserInfo(
   accessToken: string,
 ): Promise<GoogleUserInfo> {
-  const resp = await fetch(GOOGLE_USERINFO_URL, {
+  const resp = await fetchGoogleRead(GOOGLE_USERINFO_URL, {
     headers: { authorization: `Bearer ${accessToken}` },
   });
   if (!resp.ok) {
@@ -141,7 +198,7 @@ export interface SiteEntry {
 }
 
 export async function listSites(accessToken: string): Promise<SiteEntry[]> {
-  const resp = await fetch('https://www.googleapis.com/webmasters/v3/sites', {
+  const resp = await fetchGoogleRead('https://www.googleapis.com/webmasters/v3/sites', {
     headers: { authorization: `Bearer ${accessToken}` },
   });
   if (resp.status === 401) {
@@ -160,7 +217,7 @@ export async function getSite(
   siteUrl: string,
 ): Promise<SiteEntry> {
   const encoded = encodeURIComponent(siteUrl);
-  const resp = await fetch(
+  const resp = await fetchGoogleRead(
     `https://www.googleapis.com/webmasters/v3/sites/${encoded}`,
     {
       headers: { authorization: `Bearer ${accessToken}` },
@@ -381,7 +438,7 @@ export async function inspectUrl(
     siteUrl,
   };
   if (languageCode) body.languageCode = languageCode;
-  const resp = await fetch(
+  const resp = await fetchGoogleRead(
     'https://searchconsole.googleapis.com/v1/urlInspection/index:inspect',
     {
       method: 'POST',
@@ -477,7 +534,7 @@ export async function listSitemaps(
   const query = sitemapIndex
     ? `?sitemapIndex=${encodeURIComponent(sitemapIndex)}`
     : '';
-  const resp = await fetch(
+  const resp = await fetchGoogleRead(
     `https://www.googleapis.com/webmasters/v3/sites/${encoded}/sitemaps${query}`,
     {
       headers: { authorization: `Bearer ${accessToken}` },
@@ -501,7 +558,7 @@ export async function querySearchAnalytics(
 ): Promise<SearchAnalyticsResponse> {
   assertSearchAnalyticsQueryCompatible(body);
   const encoded = encodeURIComponent(siteUrl);
-  const resp = await fetch(
+  const resp = await fetchGoogleRead(
     `https://www.googleapis.com/webmasters/v3/sites/${encoded}/searchAnalytics/query`,
     {
       method: 'POST',
@@ -676,7 +733,7 @@ export async function getSitemap(
 ): Promise<SitemapEntry> {
   const encodedSite = encodeURIComponent(siteUrl);
   const encodedFeed = encodeURIComponent(feedpath);
-  const resp = await fetch(
+  const resp = await fetchGoogleRead(
     `https://www.googleapis.com/webmasters/v3/sites/${encodedSite}/sitemaps/${encodedFeed}`,
     {
       headers: { authorization: `Bearer ${accessToken}` },

package/src/index.ts

@@ -58,6 +58,7 @@ import { resolveIndexedPagesDateRange } from './indexed-pages-range';
 import { createQuickWinsInputSchema } from './quick-wins-schema';
 import { SITEMAP_URL_SCHEMA } from './sitemap-url-schema';
 import {
+  classifySearchConsolePropertyIdentifier,
   SEARCH_CONSOLE_PROPERTY_DESCRIPTION,
   SEARCH_CONSOLE_PROPERTY_SCHEMA,
 } from './search-console-property-schema';
@@ -132,6 +133,16 @@ const SITE_OUTPUT_SCHEMA = {
   permissionLevel: z.string(),
 };
 
+const LISTED_SITE_OUTPUT_SCHEMA = {
+  ...SITE_OUTPUT_SCHEMA,
+  api_identifier_kind: z.enum(['domain', 'url_prefix', 'undocumented']),
+  mcp_site_url_accepted: z.boolean(),
+  unsupported_reason: z.string().optional(),
+};
+
+const PLATFORM_PROPERTY_API_NOTE =
+  "Google Search Console now has platform properties for social/video accounts in its UI, but the current Search Console API documentation still defines siteUrl using URL-prefix and sc-domain website-property forms. mcp-gsc preserves any other identifier returned by sites.list but will not pass an undocumented property identifier to API tools until Google publishes that contract.";
+
 const SITEMAP_OUTPUT_SCHEMA = z
   .object({
     path: z.string(),
@@ -168,7 +179,7 @@ const CAPABILITIES_OUTPUT_SCHEMA = {
 };
 
 const SITES_OUTPUT_SCHEMA = {
-  sites: z.array(z.object(SITE_OUTPUT_SCHEMA)),
+  sites: z.array(z.object(LISTED_SITE_OUTPUT_SCHEMA)),
 };
 
 const SITE_DETAIL_OUTPUT_SCHEMA = {
@@ -205,6 +216,10 @@ const SEARCH_ANALYTICS_OUTPUT_SCHEMA = {
   row_count: z.number().int().nonnegative(),
   start_row: z.number().int().nonnegative(),
   rows: z.array(z.object(SEARCH_ROW_OUTPUT_SCHEMA)),
+  position_supported: z.boolean().describe(
+    'Whether average position is supported for the selected Search Analytics search type. False for Google Discover.',
+  ),
+  position_note: z.string().optional(),
   provider_exhaustiveness_guaranteed: z.literal(false).describe(
     'False because the Search Analytics API does not guarantee every data row; Google can return only top rows even after local pagination is exhausted.',
   ),
@@ -516,7 +531,7 @@ const TOOL_CATALOG = [
   {
     name: 'sites.list',
     description:
-      'List the Google Search Console properties (sites) the connected Google account can access.',
+      'List the Google Search Console properties (sites) the connected Google account can access, including whether each returned identifier matches the website-property siteUrl forms currently documented by the Search Console API.',
   },
   {
     name: 'sites.get',
@@ -710,7 +725,7 @@ class GscMcpRuntime {
       {
         title: 'List Search Console properties',
         description:
-          "List the Google Search Console properties (sites) the connected Google account has access to. Returns an array of { siteUrl, permissionLevel }. Call this when the user asks 'what sites do I have?' or 'what properties are connected?', or when the user asks about SEO for a site and hasn't specified which property. Also useful as a discovery step before calling other tools that require a site_url argument.",
+          "List the Google Search Console properties (sites) the connected Google account has access to. Each entry preserves Google's siteUrl and permissionLevel and adds api_identifier_kind plus mcp_site_url_accepted. Google now exposes platform properties for social/video accounts in the Search Console UI, but its current API documentation still defines siteUrl using URL-prefix and sc-domain website-property forms; identifiers outside those documented forms are preserved here but marked unsupported rather than guessed. Call this when the user asks 'what sites do I have?' or 'what properties are connected?', or before another tool that requires site_url.",
         inputSchema: {},
         outputSchema: SITES_OUTPUT_SCHEMA,
         annotations: READ_ONLY_ANNOTATIONS,
@@ -718,7 +733,18 @@ class GscMcpRuntime {
       async () => {
         const googleId = this.requireGoogleId();
         const accessToken = await this.getAccessToken(googleId);
-        const sites = await listSites(accessToken);
+        const sites = (await listSites(accessToken)).map((site) => {
+          const apiIdentifierKind = classifySearchConsolePropertyIdentifier(site.siteUrl);
+          const mcpSiteUrlAccepted = apiIdentifierKind !== 'undocumented';
+          return {
+            ...site,
+            api_identifier_kind: apiIdentifierKind,
+            mcp_site_url_accepted: mcpSiteUrlAccepted,
+            ...(!mcpSiteUrlAccepted
+              ? { unsupported_reason: PLATFORM_PROPERTY_API_NOTE }
+              : {}),
+          };
+        });
         return toolResponse(JSON.stringify(sites, null, 2), { sites });
       },
     );
@@ -1079,6 +1105,13 @@ class GscMcpRuntime {
           row_count: bounded.items.length,
           start_row,
           rows: bounded.items,
+          position_supported: search_type !== 'discover',
+          ...(search_type === 'discover'
+            ? {
+                position_note:
+                  "Google Discover does not support average position. Do not interpret rows[].position for search_type='discover'.",
+              }
+            : {}),
           provider_exhaustiveness_guaranteed: false,
           provider_note: SEARCH_ANALYTICS_PROVIDER_NOTE,
           has_more: bounded.resultPage.has_more,

package/src/search-console-property-schema.ts

@@ -1,7 +1,12 @@
 import { z } from 'zod';
 
 export const SEARCH_CONSOLE_PROPERTY_DESCRIPTION =
-  "The Search Console property identifier, exactly as returned by sites.list. Domain properties use 'sc-domain:example.com'; URL-prefix properties use an HTTP or HTTPS URL, typically including the trailing slash, e.g. 'https://www.example.com/'. Passing the wrong property form can return a permission error even when the user owns the site - call sites.list first if unsure.";
+  "The Search Console property identifier, exactly as returned by sites.list. The current Search Console API documents Domain properties as 'sc-domain:example.com' and URL-prefix properties as an HTTP or HTTPS URL, typically including the trailing slash, e.g. 'https://www.example.com/'. Search Console platform properties for social/video accounts are available in the Search Console UI, but Google has not documented an API siteUrl identifier contract for them; mcp-gsc therefore does not guess one. Call sites.list first if unsure.";
+
+export type SearchConsolePropertyIdentifierKind =
+  | 'domain'
+  | 'url_prefix'
+  | 'undocumented';
 
 function isDomainPropertyIdentifier(value: string): boolean {
   if (!value.startsWith('sc-domain:')) return false;
@@ -36,10 +41,18 @@ export function isSearchConsolePropertyIdentifier(value: string): boolean {
   return isDomainPropertyIdentifier(value) || isUrlPrefixPropertyIdentifier(value);
 }
 
+export function classifySearchConsolePropertyIdentifier(
+  value: string,
+): SearchConsolePropertyIdentifierKind {
+  if (isDomainPropertyIdentifier(value)) return 'domain';
+  if (isUrlPrefixPropertyIdentifier(value)) return 'url_prefix';
+  return 'undocumented';
+}
+
 export const SEARCH_CONSOLE_PROPERTY_SCHEMA = z
   .string()
   .refine(isSearchConsolePropertyIdentifier, {
     message:
-      "Expected a Search Console property identifier such as 'sc-domain:example.com' or an HTTP/HTTPS URL-prefix property such as 'https://www.example.com/'.",
+      "Expected a Search Console API property identifier such as 'sc-domain:example.com' or an HTTP/HTTPS URL-prefix property such as 'https://www.example.com/'. Platform-property identifiers are not accepted until Google documents their API siteUrl contract.",
   })
   .describe(SEARCH_CONSOLE_PROPERTY_DESCRIPTION);