@digestseo/mcp-gsc 0.4.14 → 0.4.16

package/CHANGELOG.md

@@ -7,6 +7,18 @@ 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
+- `analytics.query` now distinguishes fresh preliminary Search Analytics data from finalized-data lag, echoes the requested `data_state`, and reports whether preliminary data is possible instead of implying a blanket 2-3 day delay.
+- Repo-owned quick-connect configs and client docs now use the verified loopback npm launcher instead of routing new users to the intentionally unadvertised hosted remote while that deployment lags the current package.
+
 ## [0.4.14] - 2026-09-22
 
 ### Fixed

package/README.md

@@ -30,35 +30,37 @@ The local launcher defaults to `GSC_ACCESS_MODE=readwrite`. For least-privilege
 
 For Google OAuth and Cloudflare deployment configuration, follow [SETUP.md](SETUP.md).
 
-### Connect in 30 seconds
+### Connect the local launcher
 
-Every deployed instance exposes the same endpoint shape:
+For the current verified quick-connect path, start the npm launcher first after supplying the Google OAuth and token-encryption environment variables described in [SETUP.md](SETUP.md):
 
-```
-https://<your-worker>.workers.dev/mcp
+```bash
+npx -y @digestseo/mcp-gsc
 ```
 
-The DigestSEO-hosted instance is available at:
+Then connect your MCP client to the launcher's loopback endpoint:
 
 ```
-https://mcp-gsc.digestseo.com/mcp
+http://127.0.0.1:8080/mcp
 ```
 
+Self-hosted Cloudflare Worker deployments continue to use `https://<your-worker>.workers.dev/mcp`. The repo does not currently advertise the owner-hosted remote as a quick-connect path because its deployed tool contract is behind the published package.
+
 **Claude Code**
 
 ```bash
-claude mcp add --transport http gsc https://<your-worker>.workers.dev/mcp
+claude mcp add --transport http gsc http://127.0.0.1:8080/mcp
 ```
 
 **Cursor**
 
-[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=gsc&config=eyJ1cmwiOiJodHRwczovL21jcC1nc2MuZGlnZXN0c2VvLmNvbS9tY3AifQ%3D%3D)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=gsc&config=eyJ1cmwiOiJodHRwOi8vMTI3LjAuMC4xOjgwODAvbWNwIn0%3D)
 
 **Kiro**
 
-[![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=mcp-gsc&config=%7B%22url%22%3A%22https%3A%2F%2Fmcp-gsc.digestseo.com%2Fmcp%22%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)
+[![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=mcp-gsc&config=%7B%22url%22%3A%22http%3A%2F%2F127.0.0.1%3A8080%2Fmcp%22%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)
 
-Uses the hosted endpoint above; complete its Google OAuth flow on first use.
+Start the npm launcher before using either install button. Complete its Google OAuth flow on first use.
 
 **ChatGPT** — add it as a custom MCP app in developer mode; see [Connect in your AI client](#connect-in-your-ai-client) below.
 
@@ -77,7 +79,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. 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, 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. |
@@ -87,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.
 
@@ -95,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.14",
+  "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.";
 
@@ -244,6 +251,12 @@ 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)),
+  data_state: z.enum(['all', 'final', 'hourly_all']).describe(
+    'The Search Analytics dataState requested from Google for this response.',
+  ),
+  preliminary_data_possible: z.boolean().describe(
+    'True when the requested data state can include fresh data that is still being collected and processed. This does not assert that every returned row is incomplete.',
+  ),
   position_supported: z.boolean().describe(
     'Whether average position is supported for the selected Search Analytics search type. False for Google Discover and Google News.',
   ),
@@ -434,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 = {
@@ -652,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',
@@ -698,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;
@@ -989,10 +1006,13 @@ class GscMcpRuntime {
           '  matching dimension. Expect the returned rows to cover only a',
           '  subset of total impressions; this is normal Google behavior, not',
           '  a data error.',
-          '- DATA FRESHNESS: Search Console data lags about 2-3 days behind',
-          '  real time. If the user asks about "today" or "yesterday", expect',
-          '  empty or partial rows for the most recent days; the latest',
-          '  reliably-complete date is usually 3 days ago.',
+          '- DATA FRESHNESS: data_state "all" can include fresh preliminary',
+          '  data instead of imposing the finalized-data lag; "final" returns',
+          '  only finalized data and can therefore lag recent activity. When',
+          '  Google returns metadata.first_incomplete_date or',
+          '  metadata.first_incomplete_hour for date/hour groupings, treat',
+          '  that boundary and later rows as still subject to change. The',
+          '  response also echoes data_state and preliminary_data_possible.',
           '- AVERAGE POSITION is impression-weighted. To compute an overall',
           '  position across multiple rows, use',
           '  sum(position * impressions) / sum(impressions). Never plain-average',
@@ -1045,7 +1065,7 @@ class GscMcpRuntime {
           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 data lag: the most recent complete date is usually 3 days ago.',
+            '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(
@@ -1173,6 +1193,8 @@ class GscMcpRuntime {
           row_count: bounded.items.length,
           start_row,
           rows: bounded.items,
+          data_state,
+          preliminary_data_possible: data_state !== 'final',
           position_supported:
             search_type !== 'discover' && search_type !== 'googleNews',
           ...(search_type === 'discover' || search_type === 'googleNews'
@@ -1649,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) => {
@@ -1677,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',