@digestseo/mcp-gsc 0.4.25 → 0.4.27

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- The published `npx` launcher now rejects malformed `TOKEN_ENCRYPTION_KEY` values before starting Wrangler, requiring valid base64 that decodes to exactly the documented 32-byte AES-256 key without logging the secret value.
+- Higher-level Search Analytics pagination now follows Google's documented empty-page termination contract instead of stopping on any short non-empty page, preventing premature truncation when another provider page is still available.
+
 ## [0.4.25] - 2026-09-23
 
 ### Fixed

package/README.md

@@ -22,7 +22,7 @@ The self-hosting launcher is available as [`@digestseo/mcp-gsc`](https://www.npm
 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. You can run the `npx` command from any directory because the launcher resolves its bundled Worker configuration from the installed package. 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). The launcher exits before starting Wrangler if `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, or `TOKEN_ENCRYPTION_KEY` is missing or blank, naming only the missing variables so a broken OAuth session is not started. It keeps secret values in the child process environment and Wrangler loads them through declared local secrets; their values are not copied into Wrangler `--var` command-line arguments. 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 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. You can run the `npx` command from any directory because the launcher resolves its bundled Worker configuration from the installed package. 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). The launcher exits before starting Wrangler if `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, or `TOKEN_ENCRYPTION_KEY` is missing or blank, and it also rejects a nonblank `TOKEN_ENCRYPTION_KEY` unless it is valid base64 that decodes to exactly 32 bytes. Errors identify only the invalid or missing setting, never its secret value, so a broken OAuth session is not started. It keeps secret values in the child process environment and Wrangler loads them through declared local secrets; their values are not copied into Wrangler `--var` command-line arguments. 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.
 
 Local KV and Durable Object state, including the encrypted Google session, is stored in `~/.mcp-gsc/state` by default instead of inside the versioned npm cache. That keeps the local connection available across package upgrades and ordinary npm cache cleanup. Set `MCP_GSC_STATE_DIR` to use another directory; keep the same `TOKEN_ENCRYPTION_KEY` when reusing existing state because stored refresh tokens are encrypted with that key. The launcher prints the effective state directory at startup. The first release with this stable path may require one Google reconnect because older launcher releases stored local state under the npm package cache.
 
@@ -58,11 +58,19 @@ claude mcp add --transport http gsc http://127.0.0.1:8080/mcp
 
 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 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/SETUP.md

@@ -111,6 +111,8 @@ openssl rand -base64 32
 
 Paste that value when prompted. Keep it safe — if you lose it, the refresh tokens already in KV become undecryptable and every user has to reconnect.
 
+The published `npx` launcher validates this exact key format before starting Wrangler. A malformed base64 value or a value that does not decode to exactly 32 bytes is rejected without printing the secret value.
+
 For **local development**, put the same three values in `.dev.vars` instead — copy `.dev.vars.example` to `.dev.vars` (it's gitignored). The published npm launcher can also read them from the process environment; its bundled Wrangler config declares `GOOGLE_CLIENT_SECRET` and `TOKEN_ENCRYPTION_KEY` as required local secrets so those sensitive values do not need to be serialized into `--var` command-line arguments:
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digestseo/mcp-gsc",
-  "version": "0.4.25",
+  "version": "0.4.27",
   "private": false,
   "main": "scripts/glama-start.mjs",
   "bin": {
@@ -50,6 +50,7 @@
     "build": "npm run typecheck",
     "start": "node scripts/glama-start.mjs",
     "typecheck": "tsc --noEmit",
+    "test:launcher": "node --test tests/launcher.test.mjs",
     "test:oauth-state": "tsx --test tests/pending-auth-state.test.ts",
     "test:comparison": "tsx --test tests/performance-comparison.test.ts",
     "test:annotations": "tsx --test tests/write-tool-annotations.test.ts",
@@ -61,7 +62,7 @@
     "test:indexing-eligibility": "tsx --test tests/indexing-eligibility.test.ts",
     "test:insight-pagination": "tsx --test tests/insight-pagination.test.ts",
     "test:tool-rate-limits": "tsx --test tests/tool-rate-limit.test.ts",
-    "test": "npm run typecheck && npm run test:metadata && npm run test:oauth-state && npm run test:comparison && npm run test:annotations && npm run test:worker && npm run test:access-mode && npm run test:access-token-lifecycle && npm run test:analytics-response-metadata && npm run test:indexing-authorization && npm run test:indexing-eligibility && npm run test:insight-pagination && npm run test:tool-rate-limits && npm run test:unit",
+    "test": "npm run typecheck && npm run test:metadata && npm run test:launcher && npm run test:oauth-state && npm run test:comparison && npm run test:annotations && npm run test:worker && npm run test:access-mode && npm run test:access-token-lifecycle && npm run test:analytics-response-metadata && npm run test:indexing-authorization && npm run test:indexing-eligibility && npm run test:insight-pagination && npm run test:tool-rate-limits && npm run test:unit",
     "test:metadata": "tsx --test tests/metadata.test.ts",
     "test:unit": "tsx --test tests/unit.test.ts",
     "test:smoke": "node --test tests/smoke.test.mjs",

package/scripts/glama-start.mjs

@@ -19,6 +19,19 @@ if (missingRequiredEnvironmentVariables.length > 0) {
   process.exit(1);
 }
 
+const tokenEncryptionKey = process.env.TOKEN_ENCRYPTION_KEY;
+const tokenEncryptionKeyPattern =
+  /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+if (
+  !tokenEncryptionKeyPattern.test(tokenEncryptionKey)
+  || Buffer.from(tokenEncryptionKey, 'base64').byteLength !== 32
+) {
+  console.error(
+    '[mcp-gsc] Invalid TOKEN_ENCRYPTION_KEY: expected a valid base64-encoded 32-byte (256-bit) AES key. See SETUP.md for local launcher configuration.',
+  );
+  process.exit(1);
+}
+
 const port = process.env.PORT || '8080';
 const localBaseUrl = `http://127.0.0.1:${port}`;
 const mcpUrl = `${localBaseUrl}/mcp`;

package/src/google.ts

@@ -52,10 +52,34 @@ 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;
 
+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 +103,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;
       }
 
@@ -652,6 +674,8 @@ export async function querySearchAnalytics(
 
 /**
  * Fetches Search Analytics rows in 25,000-row pages for higher-level tools.
+ * Google's documented pagination contract uses an explicit empty response as
+ * the terminal page, so a short non-empty page is not treated as exhaustion.
  * A full final page conservatively reports localLimitReached because the API
  * can have more rows even when Search Console's own internal limits apply.
  */
@@ -685,14 +709,14 @@ export async function querySearchAnalyticsPaginated(
 
     const acceptedRows = page.rows.slice(0, requestedRows);
     rows.push(...acceptedRows);
-    if (page.rows.length < requestedRows) {
+    if (page.rows.length === 0) {
       return { rows, pagesFetched, localLimitReached: false };
     }
     if (rows.length >= maximumRows || page.rows.length > requestedRows) {
       return { rows, pagesFetched, localLimitReached: true };
     }
 
-    startRow += page.rows.length;
+    startRow += requestedRows;
   }
 
   return { rows, pagesFetched, localLimitReached: true };

package/src/index.ts

@@ -611,22 +611,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,
   };
 }
 
@@ -1268,13 +1276,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 +1973,8 @@ class GscMcpRuntime {
           pages,
           start_row,
           row_limit,
-          response.rows.length === sourceRowLimit,
+          response.rows.length > 0,
+          start_row + sourceRowLimit,
         );
 
         const payload = {