@digestseo/mcp-gsc 0.4.15 → 0.4.16

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.16] - 2026-09-22
+
+### Fixed
+- High-level Search Analytics helpers now reserve their worst-case upstream request fan-out against the shared local safety budget, so paginated comparison/cannibalization/decay workflows cannot bypass the 10-minute limiter by hiding multiple Google API calls behind one MCP tool call.
+- `indexing.request` now exposes Google's current Indexing API usage boundary: the default 200 publish requests/day/project is onboarding/testing capacity rather than ongoing-use approval, ongoing usage/resource provisioning requires approval, and all submissions are subject to spam detection.
+
 ## [0.4.15] - 2026-09-22
 
 ### Fixed

package/README.md

@@ -89,7 +89,7 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 21 tools. Read-onl
 | **`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. |
 | **`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. |
+| **`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.
 
@@ -97,7 +97,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 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.
+> **`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.
 
 ## What you can ask
 

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.
+   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.
 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).
 
 ---

package/package.json

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

package/src/index.ts

@@ -41,7 +41,11 @@ import {
   PendingAuthStateStore,
   stashPendingAuth,
 } from './pending-auth-state';
-import { enforceToolRateLimit, type RateLimitedToolName } from './tool-rate-limit';
+import {
+  enforceToolRateLimit,
+  getToolRateLimitUnits,
+  type RateLimitedToolName,
+} from './tool-rate-limit';
 export { ToolRateLimiter } from './tool-rate-limiter-do';
 import { generateWeeklyDigest, resolveWeeklyDigestEndDate } from './digest';
 import {
@@ -213,6 +217,9 @@ const SITE_DETAIL_OUTPUT_SCHEMA = {
 const SITE_ADD_VERIFICATION_NOTE =
   "Google Search Console Sites.add only adds the property to the user's Search Console site set; it does not verify ownership. Ownership verification is a separate Google Site Verification/Search Console workflow.";
 
+const INDEXING_PROVIDER_USAGE_NOTE =
+  "Google describes the Indexing API's default 200 publish-requests-per-day project quota as onboarding/testing capacity, not approval for ongoing usage. Additional approval is required for usage/resource provisioning. Google also applies spam detection to all submissions and warns that abuse or attempts to exceed quotas through multiple accounts or other means can result in revoked access.";
+
 const URL_INSPECTION_SCOPE_NOTE =
   "Google's URL Inspection API reports the version currently known in Google's index; it does not run a live URL test or prove current live-page indexability. The mobileUsabilityResult field is deprecated and may be absent.";
 
@@ -440,6 +447,10 @@ const CONTENT_DECAY_OUTPUT_SCHEMA = {
 const INDEXING_OUTPUT_SCHEMA = {
   result: z.unknown(),
   note: z.string(),
+  provider_default_quota_for_testing_only: z.literal(true),
+  provider_usage_approval_required: z.literal(true),
+  provider_spam_detection_applies: z.literal(true),
+  provider_usage_note: z.string(),
 };
 
 const INDEXED_PAGES_OUTPUT_SCHEMA = {
@@ -658,7 +669,7 @@ const TOOL_CATALOG = [
   {
     name: 'indexing.request',
     description:
-      'Request an eligible JobPosting or livestream URL update through Google\'s restricted Indexing API; this is not a general webpage submission tool.',
+      '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.list_pages',
@@ -704,7 +715,7 @@ class GscMcpRuntime {
   private async rateLimitError(
     googleId: string,
     toolName: RateLimitedToolName,
-    units = 1,
+    units = getToolRateLimitUnits(toolName),
   ) {
     const result = await enforceToolRateLimit(this.env, googleId, toolName, units);
     if (result.allowed) return null;
@@ -1660,7 +1671,7 @@ class GscMcpRuntime {
       'indexing.request',
       {
         title: 'Request Indexing',
-        description: "Requests indexing through Google's Indexing API for a URL within an owner-level Search Console property accessible to the connected Google account. 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.",
+        description: "Requests indexing through Google's Indexing API for a URL within an owner-level Search Console property accessible to the connected Google account. 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-per-day project quota is for onboarding/testing rather than ongoing-use approval; additional approval is required for usage/resource provisioning, and all submissions are subject to spam detection.",
         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) => {
@@ -1688,6 +1699,10 @@ class GscMcpRuntime {
         const payload = {
           result,
           note: "Google accepting this notification does not guarantee the URL will be indexed. Indexing remains at Google's discretion.",
+          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,
         };
         return toolResponse(JSON.stringify(payload, null, 2), payload);
       },

package/src/tool-rate-limit.ts

@@ -60,8 +60,9 @@ export const TOOL_RATE_LIMIT_POLICIES = {
   indexing_request: {
     category: 'indexing-request',
     tools: ['indexing.request'],
-    // Google defaults to 200 publish requests per project per day. Two per
-    // user reserves the default quota for up to 100 authenticated users.
+    // 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.
     windowMs: DAY_MS,
     userLimit: 2,
     projectLimit: 200,
@@ -79,6 +80,16 @@ export type ToolRateLimitCategory = keyof typeof TOOL_RATE_LIMIT_POLICIES;
 export type RateLimitedToolName =
   (typeof TOOL_RATE_LIMIT_POLICIES)[ToolRateLimitCategory]['tools'][number];
 
+const TOOL_RATE_LIMIT_UNITS: Partial<Record<RateLimitedToolName, number>> = {
+  // These helpers can fan one MCP call out into several Search Analytics
+  // requests. Reserve the worst-case upstream call count before starting so
+  // a single helper cannot bypass the shared 10-minute safety budget.
+  'insights.quick_wins': 4,
+  'insights.cannibalization': 4,
+  'insights.content_decay': 8,
+  'analytics.compare': 8,
+};
+
 const POLICY_BY_TOOL = new Map<string, ToolRateLimitPolicy>(
   Object.values(TOOL_RATE_LIMIT_POLICIES).flatMap((policy) =>
     policy.tools.map((tool) => [tool, policy] as const),
@@ -194,6 +205,10 @@ export function getToolRateLimitPolicy(toolName: string): ToolRateLimitPolicy |
   return POLICY_BY_TOOL.get(toolName);
 }
 
+export function getToolRateLimitUnits(toolName: RateLimitedToolName): number {
+  return TOOL_RATE_LIMIT_UNITS[toolName] ?? 1;
+}
+
 async function userBucketFor(googleId: string): Promise<string> {
   const digest = await crypto.subtle.digest(
     'SHA-256',