@digestseo/mcp-gsc 0.4.26 → 0.4.28

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.28] - 2026-09-23
+
+### Added
+- GitHub Copilot CLI users can now register this repository as the `digestseo` plugin marketplace, discover/install `mcp-gsc` through the marketplace workflow, and still use the supported direct-repository install path.
+- OpenAI Codex CLI and IDE users now have a verified one-command Streamable HTTP setup for the local `mcp-gsc` launcher.
+- MCP initialization now supplies concise server-level workflow instructions so compatible agents preserve Search Console pagination, evidence, and Indexing API semantics across tools.
+
+### Fixed
+- Search Analytics `quotaExceeded` load failures now return provider-specific recovery guidance instead of an opaque raw 403 payload, while remaining outside the short transient retry loop because Google's documented recovery window is measured in minutes rather than seconds.
+
+## [0.4.27] - 2026-09-23
+
+### Added
+- GitHub Copilot CLI can now install this repository directly as a plugin, bundling the existing `gsc-weekly-review`, `gsc-indexing-triage`, and `gsc-search-opportunities` Agent Skills with the verified local loopback MCP configuration.
+
+### Fixed
+- Direct Search Analytics-backed pagination in `analytics.query` and `indexing.list_pages` now treats short non-empty provider pages as potentially continuable and advances `next_start_row` by Google's requested page size, stopping only after an explicit empty provider page when no local response truncation remains.
+- Idempotent Google read calls now apply the existing bounded retry policy when Search Console returns documented transient 403 rate-limit reasons, while permission/configuration 403 responses and write calls remain non-retried.
+
 ## [0.4.26] - 2026-09-23
 
 ### Fixed

package/README.md

@@ -52,17 +52,34 @@ Self-hosted Cloudflare Worker deployments continue to use `https://<your-worker>
 claude mcp add --transport http gsc http://127.0.0.1:8080/mcp
 ```
 
+**OpenAI Codex CLI / IDE**
+
+```bash
+codex mcp add gsc --url http://127.0.0.1:8080/mcp
+```
+
+Codex CLI and the Codex IDE extension share MCP configuration, so registering the server once makes the same local connection available to both clients. Start the npm launcher before using the connection; Codex will open the server's OAuth flow when authentication is required.
+
 **Cursor**
 
 [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=gsc&config=eyJ1cmwiOiJodHRwOi8vMTI3LjAuMC4xOjgwODAvbWNwIn0%3D)
 
 When this repository is installed as a Cursor plugin, Cursor also auto-discovers three bundled Agent Skills that compose the MCP tools into evidence-safe workflows: `gsc-weekly-review`, `gsc-indexing-triage`, and `gsc-search-opportunities`. The **Add to Cursor** button above installs the MCP connection only; the bundled skills are part of the repository's Cursor plugin package.
 
+**GitHub Copilot CLI**
+
+```bash
+copilot plugin marketplace add AKzar1el/mcp-gsc
+copilot plugin install mcp-gsc@digestseo
+```
+
+The marketplace path makes the plugin discoverable and updateable through Copilot's marketplace workflow. Direct repository install also remains supported with `copilot plugin install AKzar1el/mcp-gsc`. The Copilot plugin bundles the same three Agent Skills plus the local loopback MCP configuration. Start the npm launcher before using the plugin's MCP server; the plugin does not start or deploy mcp-gsc for you.
+
 **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%22http%3A%2F%2F127.0.0.1%3A8080%2Fmcp%22%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)
 
-Start the npm launcher before using either install button. Complete its Google OAuth flow on first use.
+Start the npm launcher before using either install button or the Copilot plugin. Complete its Google OAuth flow on first use.
 
 **ChatGPT** — ChatGPT cannot connect directly to this loopback `127.0.0.1` endpoint. Use OpenAI's **Secure MCP Tunnel** for the local launcher, or deploy your own remote Cloudflare Worker and add that `/mcp` URL as a custom MCP app in Developer mode; see [Connect in your AI client](#connect-in-your-ai-client) below.
 

package/package.json

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

package/src/google.ts

@@ -52,10 +52,47 @@ export class GoogleRefreshTokenRevokedError extends Error {
 }
 
 const GOOGLE_READ_RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+const GOOGLE_READ_RETRYABLE_403_REASONS = new Set([
+  'concurrentLimitExceeded',
+  'rateLimitExceeded',
+  'servingLimitExceeded',
+  'userRateLimitExceeded',
+]);
 const GOOGLE_READ_MAX_ATTEMPTS = 3;
 const GOOGLE_READ_BASE_DELAY_MS = 1_000;
 const GOOGLE_READ_MAX_DELAY_MS = 5_000;
 
+function googleErrorReasonsFromText(text: string): string[] {
+  try {
+    const data = JSON.parse(text) as {
+      error?: { errors?: Array<{ reason?: unknown }> };
+    };
+    return (data.error?.errors ?? [])
+      .map((entry) => entry.reason)
+      .filter((reason): reason is string => typeof reason === 'string');
+  } catch {
+    return [];
+  }
+}
+
+async function isGoogleReadRetryableResponse(response: Response): Promise<boolean> {
+  if (GOOGLE_READ_RETRYABLE_STATUSES.has(response.status)) return true;
+  if (response.status !== 403) return false;
+
+  try {
+    const data = (await response.clone().json()) as {
+      error?: { errors?: Array<{ reason?: unknown }> };
+    };
+    return data.error?.errors?.some(
+      (entry) =>
+        typeof entry.reason === 'string' &&
+        GOOGLE_READ_RETRYABLE_403_REASONS.has(entry.reason),
+    ) ?? false;
+  } catch {
+    return false;
+  }
+}
+
 function googleReadRetryDelayMs(response: Response, retryNumber: number): number | null {
   const retryAfter = response.headers.get('retry-after')?.trim();
   if (retryAfter) {
@@ -79,10 +116,8 @@ async function fetchGoogleRead(url: string, init?: RequestInit): Promise<Respons
   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
-      ) {
+      const retryable = await isGoogleReadRetryableResponse(response);
+      if (!retryable || attempt === GOOGLE_READ_MAX_ATTEMPTS) {
         return response;
       }
 
@@ -623,6 +658,12 @@ export async function querySearchAnalytics(
   }
   if (!resp.ok) {
     const text = await resp.text();
+    const reasons = googleErrorReasonsFromText(text);
+    if (resp.status === 403 && reasons.includes('quotaExceeded')) {
+      throw new Error(
+        'Search Analytics load quota exceeded. Google recommends waiting about 15 minutes before retrying a short-term load-quota failure. If the error persists, reduce expensive page/query grouping or filtering, shorten the date range, and avoid repeatedly requesting the same data.',
+      );
+    }
     throw new Error(`Search analytics query failed: ${resp.status} ${text}`);
   }
   const data = (await resp.json()) as {

package/src/index.ts

@@ -111,6 +111,8 @@ export interface AgentProps extends Record<string, unknown> {
 
 const SERVER_NAME = 'mcp-gsc';
 const SERVER_VERSION = pkg.version;
+const SERVER_INSTRUCTIONS =
+  'If the exact Search Console site_url is unknown, call sites.list before property-scoped tools. Search Analytics can omit rows: page while has_more is true, and never treat a row missing from one bounded period as zero traffic. indexing.list_pages reports Search performance visibility, not index coverage; use urls.inspect or urls.inspect_many for indexed-state evidence. The Indexing API is restricted to eligible JobPosting/livestream pages; a receipt is not proof of indexing or removal.';
 
 const NOT_AUTHENTICATED_MESSAGE =
   `Not authenticated. ${MCP_RECONNECT_INSTRUCTION}`;
@@ -611,22 +613,30 @@ function windowSourceRows<T>(
   sourceStartRow: number,
   requestedLimit: number,
   sourceMayHaveMore: boolean,
+  sourceNextStartRow?: number,
 ) {
   const bounded = takeBoundedItems(items, requestedLimit);
   const returnedCount = bounded.items.length;
-  const hasMore =
-    bounded.byteLimitReached ||
-    returnedCount < items.length ||
-    sourceMayHaveMore;
+  const localContinuation =
+    bounded.byteLimitReached || returnedCount < items.length;
+  const hasMore = localContinuation || sourceMayHaveMore;
+  const resultPage = resultPageMetadata({
+    startRow: sourceStartRow,
+    limit: requestedLimit,
+    returnedCount,
+    hasMore,
+    byteLimitReached: bounded.byteLimitReached,
+  });
+  if (
+    !localContinuation &&
+    sourceMayHaveMore &&
+    sourceNextStartRow !== undefined
+  ) {
+    resultPage.next_start_row = sourceNextStartRow;
+  }
   return {
     items: bounded.items,
-    resultPage: resultPageMetadata({
-      startRow: sourceStartRow,
-      limit: requestedLimit,
-      returnedCount,
-      hasMore,
-      byteLimitReached: bounded.byteLimitReached,
-    }),
+    resultPage,
   };
 }
 
@@ -757,10 +767,15 @@ const TOOL_CATALOG = [
 ] as const;
 
 class GscMcpRuntime {
-  server = new McpServer({
-    name: SERVER_NAME,
-    version: SERVER_VERSION,
-  });
+  server = new McpServer(
+    {
+      name: SERVER_NAME,
+      version: SERVER_VERSION,
+    },
+    {
+      instructions: SERVER_INSTRUCTIONS,
+    },
+  );
 
   constructor(
     private readonly env: Env,
@@ -1268,13 +1283,17 @@ class GscMcpRuntime {
             ? { dimensionFilterGroups: dimension_filter_groups }
             : {}),
         });
+        // Search Analytics pagination is complete only after Google returns an
+        // explicit empty page. A short non-empty page can still be followed by
+        // later rows, so preserve a continuation for dimensioned queries.
         const sourceMayHaveMore =
-          dimensions.length > 0 && response.rows.length === sourceRowLimit;
+          dimensions.length > 0 && response.rows.length > 0;
         const bounded = windowSourceRows(
           response.rows,
           start_row,
           row_limit,
           sourceMayHaveMore,
+          start_row + sourceRowLimit,
         );
         const payload: Record<string, unknown> = {
           row_count: bounded.items.length,
@@ -1961,7 +1980,8 @@ class GscMcpRuntime {
           pages,
           start_row,
           row_limit,
-          response.rows.length === sourceRowLimit,
+          response.rows.length > 0,
+          start_row + sourceRowLimit,
         );
 
         const payload = {