@digestseo/mcp-gsc 0.4.24 → 0.4.26

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Access-mode onboarding and Official MCP Registry metadata now identify all six read-write mutation tools after `indexing.remove` became part of the public tool surface.
+- `analytics.query` now accepts provider-valid Discover and Google News rows with no `position` field instead of failing MCP structured-output validation; Search Console does not record average position for those surfaces.
+
 ## [0.4.24] - 2026-09-23
 
 ### Added

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.
 
@@ -79,7 +79,7 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 23 tools. Read-onl
 | **`server.capabilities`** | Read | List every tool this server exposes and report local Google credential state. `connected` means a stored refresh credential is present; the response also exposes `auth_status_basis` and `provider_auth_live_verified: false` because this discovery call does not probe Google. A later Google tool call can still require reconnection if the credential expired or was revoked. Takes no arguments. |
 | **`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. `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`. |
+| **`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, so returned rows can omit `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. |

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.24",
+  "version": "0.4.26",
   "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/digest.ts

@@ -1,4 +1,8 @@
-import { querySearchAnalytics, type SearchAnalyticsRow } from './google';
+import {
+  hasRecordedPosition,
+  querySearchAnalytics,
+  type SearchAnalyticsRow,
+} from './google';
 import type { GoogleAccessTokenProvider } from './access-token-lifecycle';
 import { getSearchConsoleCalendarDate } from './date-validation';
 
@@ -180,13 +184,15 @@ function totalsFromRow(row: SearchAnalyticsRow | undefined): SiteTotals {
 }
 
 function rowsToQueries(rows: SearchAnalyticsRow[]): QueryRow[] {
-  return rows.map((r) => ({
-    query: r.keys?.[0] ?? '',
-    clicks: r.clicks,
-    impressions: r.impressions,
-    ctr: r.ctr,
-    position: r.position,
-  }));
+  return rows
+    .filter(hasRecordedPosition)
+    .map((r) => ({
+      query: r.keys?.[0] ?? '',
+      clicks: r.clicks,
+      impressions: r.impressions,
+      ctr: r.ctr,
+      position: r.position,
+    }));
 }
 
 function rowsToPages(rows: SearchAnalyticsRow[]): PageRow[] {

package/src/google.ts

@@ -399,7 +399,20 @@ export interface SearchAnalyticsRow {
   clicks: number;
   impressions: number;
   ctr: number;
-  position: number;
+  /**
+   * Average position when Google records it. Search Console does not record
+   * position for Discover or the Google News app/news.google.com, so those
+   * Search Analytics rows can legitimately omit this field.
+   */
+  position?: number;
+}
+
+export type PositionedSearchAnalyticsRow = SearchAnalyticsRow & { position: number };
+
+export function hasRecordedPosition(
+  row: SearchAnalyticsRow,
+): row is PositionedSearchAnalyticsRow {
+  return row.position !== undefined;
 }
 
 export interface SearchAnalyticsResponseMetadata {
@@ -639,6 +652,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.
  */
@@ -672,14 +687,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 };
@@ -812,6 +827,7 @@ export function processQuickWins(
   maxPosition: number,
 ): QuickWinResult[] {
   return rows
+    .filter(hasRecordedPosition)
     .filter(
       (row) =>
         (row.keys?.length ?? 0) >= 2 &&
@@ -860,7 +876,7 @@ export function processCannibalization(
 ): CannibalizationResult[] {
   const queryGroups = new Map<string, Array<{ page: string; clicks: number; impressions: number; ctr: number; position: number }>>();
   for (const row of rows) {
-    if ((row.keys?.length ?? 0) < 2) continue;
+    if ((row.keys?.length ?? 0) < 2 || row.position === undefined) continue;
     const query = row.keys![0];
     const page = row.keys![1];
     if (!queryGroups.has(query)) {
@@ -1010,7 +1026,7 @@ export function processContentDecay(
 ): DecayPageResult[] {
   const recentMap = new Map<string, { clicks: number; impressions: number; ctr: number; position: number }>();
   for (const row of recentRows) {
-    if ((row.keys?.length ?? 0) < 1) continue;
+    if ((row.keys?.length ?? 0) < 1 || row.position === undefined) continue;
     recentMap.set(row.keys![0], {
       clicks: row.clicks,
       impressions: row.impressions,
@@ -1022,7 +1038,7 @@ export function processContentDecay(
   const decayCandidates: DecayPageResult[] = [];
 
   for (const row of previousRows) {
-    if ((row.keys?.length ?? 0) < 1) continue;
+    if ((row.keys?.length ?? 0) < 1 || row.position === undefined) continue;
     const page = row.keys![0];
     const prevClicks = row.clicks;
     const prevImps = row.impressions;
@@ -1688,7 +1704,7 @@ export function processPerformanceComparison(
 ): PerformanceComparisonRow[] {
   const mapB = new Map<string, { clicks: number; impressions: number; ctr: number; position: number }>();
   for (const row of rowsB) {
-    if ((row.keys?.length ?? 0) < 1) continue;
+    if ((row.keys?.length ?? 0) < 1 || row.position === undefined) continue;
     mapB.set(row.keys![0], {
       clicks: row.clicks,
       impressions: row.impressions,
@@ -1700,7 +1716,7 @@ export function processPerformanceComparison(
   const comparison: PerformanceComparisonRow[] = [];
 
   for (const row of rowsA) {
-    if ((row.keys?.length ?? 0) < 1) continue;
+    if ((row.keys?.length ?? 0) < 1 || row.position === undefined) continue;
     const key = row.keys![0];
     const clicksA = row.clicks;
     const impsA = row.impressions;

package/src/index.ts

@@ -24,6 +24,7 @@ import {
   submitSitemap,
   deleteSitemap,
   getSitemap,
+  hasRecordedPosition,
   processQuickWins,
   processCannibalization,
   processContentDecay,
@@ -134,7 +135,15 @@ const SEARCH_ROW_OUTPUT_SCHEMA = {
     .describe(
       'Dimension values returned by Google. Aggregate queries with dimensions: [] may legitimately omit this field.',
     ),
-  ...METRIC_OUTPUT_SCHEMA,
+  clicks: z.number(),
+  impressions: z.number(),
+  ctr: z.number(),
+  position: z
+    .number()
+    .optional()
+    .describe(
+      'Average position when Google records it. Omitted for Discover and Google News, where Search Console does not record position.',
+    ),
 };
 
 const SITE_OUTPUT_SCHEMA = {
@@ -1364,7 +1373,7 @@ class GscMcpRuntime {
           ],
         }, { maxRows: sourceRowLimit });
         const rows = source.rows
-          .filter((row) => (row.keys?.length ?? 0) > 0)
+          .filter((row) => (row.keys?.length ?? 0) > 0 && hasRecordedPosition(row))
           .map((row) => ({
             query: row.keys![0],
             clicks: row.clicks,
@@ -1448,7 +1457,7 @@ class GscMcpRuntime {
           ],
         }, { maxRows: sourceRowLimit });
         const rows = source.rows
-          .filter((row) => (row.keys?.length ?? 0) > 0)
+          .filter((row) => (row.keys?.length ?? 0) > 0 && hasRecordedPosition(row))
           .map((row) => ({
             page: row.keys![0],
             clicks: row.clicks,
@@ -1940,7 +1949,7 @@ class GscMcpRuntime {
         });
 
         const pages = response.rows
-          .filter((row) => (row.keys?.length ?? 0) > 0)
+          .filter((row) => (row.keys?.length ?? 0) > 0 && hasRecordedPosition(row))
           .map((row) => ({
             page: row.keys![0],
             clicks: row.clicks,