@digestseo/mcp-gsc 0.4.24 → 0.4.25

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

@@ -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/package.json

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

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 {
@@ -812,6 +825,7 @@ export function processQuickWins(
   maxPosition: number,
 ): QuickWinResult[] {
   return rows
+    .filter(hasRecordedPosition)
     .filter(
       (row) =>
         (row.keys?.length ?? 0) >= 2 &&
@@ -860,7 +874,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 +1024,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 +1036,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 +1702,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 +1714,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,