@digestseo/mcp-gsc 0.4.28 → 0.4.30

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.30] - 2026-09-23
+
+### Changed
+- Search Analytics filters now default an omitted operator to Google's documented `equals` behavior in both `analytics.query` and `analytics.compare`, while both tools enforce the provider's 4096-character filter-expression ceiling through one shared schema.
+- URL Inspection language codes are now validated as BCP-47 language tags before `urls.inspect` or `urls.inspect_many` can reserve local inspection budget, resolve Google credentials, or call the provider.
+
+## [0.4.29] - 2026-09-23
+
+### Fixed
+- `urls.inspect_many` now rejects exact duplicate URLs before reserving local safety-budget units or calling Google, preventing one batch from wasting URL Inspection quota on repeated identical requests.
+- `analytics.query` now rejects explicit `byPage` aggregation when the request also groups or filters by page, returning deterministic local guidance to use `auto` instead of forwarding a provider-invalid aggregation shape to Google.
+
 ## [0.4.28] - 2026-09-23
 
 ### Added

package/package.json

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

package/src/google.ts

@@ -371,6 +371,12 @@ export function assertSearchAnalyticsQueryCompatible(body: SearchAnalyticsQuery)
     }
   }
 
+  if (body.aggregationType === 'byPage' && hasPageGroupingOrFilter) {
+    throw new Error(
+      'Search Analytics aggregationType byPage cannot be combined with page grouping or filtering; use auto instead.',
+    );
+  }
+
   if (body.aggregationType === 'byProperty') {
     if (hasPageGroupingOrFilter) {
       throw new Error(

package/src/index.ts

@@ -66,6 +66,7 @@ import { CONTENT_DECAY_COMPARE_DAYS_SCHEMA } from './content-decay-schema';
 import { resolveIndexedPagesDateRange } from './indexed-pages-range';
 import { createQuickWinsInputSchema } from './quick-wins-schema';
 import { SITEMAP_URL_SCHEMA } from './sitemap-url-schema';
+import { URL_INSPECTION_LANGUAGE_CODE_SCHEMA } from './url-inspection-language-schema';
 import {
   classifySearchConsolePropertyIdentifier,
   SEARCH_CONSOLE_PROPERTY_DESCRIPTION,
@@ -148,6 +149,32 @@ const SEARCH_ROW_OUTPUT_SCHEMA = {
     ),
 };
 
+const SEARCH_ANALYTICS_FILTER_SCHEMA = z.object({
+  dimension: z.enum([
+    'query',
+    'page',
+    'country',
+    'device',
+    'searchAppearance',
+  ]),
+  operator: z
+    .enum([
+      'equals',
+      'notEquals',
+      'contains',
+      'notContains',
+      'includingRegex',
+      'excludingRegex',
+    ])
+    .default('equals'),
+  expression: z.string().max(4096),
+});
+
+const SEARCH_ANALYTICS_FILTER_GROUP_SCHEMA = z.object({
+  groupType: z.literal('and').default('and'),
+  filters: z.array(SEARCH_ANALYTICS_FILTER_SCHEMA),
+});
+
 const SITE_OUTPUT_SCHEMA = {
   siteUrl: z.string(),
   permissionLevel: z.string(),
@@ -943,12 +970,7 @@ class GscMcpRuntime {
             .describe(
               'The fully-qualified URL to inspect. Must belong to the site_url property: same domain for sc-domain properties, same URL prefix for URL-prefix properties.',
             ),
-          language_code: z
-            .string()
-            .default('en-US')
-            .describe(
-              "BCP-47 language code for translatable strings in the result, e.g. 'en-US' or 'de-DE'.",
-            ),
+          language_code: URL_INSPECTION_LANGUAGE_CODE_SCHEMA,
         },
         outputSchema: INSPECTION_OUTPUT_SCHEMA,
         annotations: READ_ONLY_ANNOTATIONS,
@@ -987,15 +1009,13 @@ class GscMcpRuntime {
             .array(z.string().url())
             .min(1)
             .max(10)
+            .refine((urls) => new Set(urls).size === urls.length, {
+              message: 'inspection_urls must not contain duplicate URLs.',
+            })
             .describe(
-              'Between 1 and 10 fully-qualified URLs to inspect. Each URL must belong to the site_url property.',
-            ),
-          language_code: z
-            .string()
-            .default('en-US')
-            .describe(
-              "BCP-47 language code for translatable strings in the results, e.g. 'en-US' or 'de-DE'.",
+              'Between 1 and 10 unique fully-qualified URLs to inspect. Each URL must belong to the site_url property.',
             ),
+          language_code: URL_INSPECTION_LANGUAGE_CODE_SCHEMA,
         },
         outputSchema: INSPECTION_BATCH_OUTPUT_SCHEMA,
         annotations: READ_ONLY_ANNOTATIONS,
@@ -1216,37 +1236,13 @@ class GscMcpRuntime {
             .enum(['auto', 'byNewsShowcasePanel', 'byPage', 'byProperty'])
             .default('auto')
             .describe(
-              "How Google aggregates metrics. Leave as 'auto' unless specific semantics are needed. 'byProperty' cannot be used with page grouping/filtering or search_type discover/googleNews. 'byNewsShowcasePanel' requires search_type discover/googleNews plus a searchAppearance equals NEWS_SHOWCASE filter, and cannot be combined with page grouping/filtering or another searchAppearance filter.",
+              "How Google aggregates metrics. Leave as 'auto' unless specific semantics are needed. When grouping/filtering by page, use 'auto'; explicit 'byPage' and 'byProperty' are rejected for that request shape. 'byProperty' is also unavailable for search_type discover/googleNews. 'byNewsShowcasePanel' requires search_type discover/googleNews plus a searchAppearance equals NEWS_SHOWCASE filter, and cannot be combined with page grouping/filtering or another searchAppearance filter.",
             ),
           dimension_filter_groups: z
-            .array(
-              z.object({
-                groupType: z.literal('and').default('and'),
-                filters: z.array(
-                  z.object({
-                    dimension: z.enum([
-                      'query',
-                      'page',
-                      'country',
-                      'device',
-                      'searchAppearance',
-                    ]),
-                    operator: z.enum([
-                      'equals',
-                      'notEquals',
-                      'contains',
-                      'notContains',
-                      'includingRegex',
-                      'excludingRegex',
-                    ]),
-                    expression: z.string().max(4096),
-                  }),
-                ),
-              }),
-            )
+            .array(SEARCH_ANALYTICS_FILTER_GROUP_SCHEMA)
             .optional()
             .describe(
-              "Optional filters ANDed together, e.g. [{ groupType: 'and', filters: [{ dimension: 'country', operator: 'equals', expression: 'usa' }] }]. Countries use ISO 3166-1 alpha-3 codes. Query filters are not supported when search_type is discover or googleNews.",
+              "Optional filters ANDed together, e.g. [{ groupType: 'and', filters: [{ dimension: 'country', expression: 'usa' }] }]. Filter operator defaults to 'equals' when omitted, matching Search Console. Expressions are limited to 4096 characters. Countries use ISO 3166-1 alpha-3 codes. Query filters are not supported when search_type is discover or googleNews.",
             ),
         },
         outputSchema: SEARCH_ANALYTICS_OUTPUT_SCHEMA,
@@ -2018,34 +2014,10 @@ class GscMcpRuntime {
             .default('web')
             .describe('Which Search Console search index to compare. The same search type is used for both periods. Discover and Google News are excluded because this tool returns average-position comparisons.'),
           dimension_filter_groups: z
-            .array(
-              z.object({
-                groupType: z.literal('and').default('and'),
-                filters: z.array(
-                  z.object({
-                    dimension: z.enum([
-                      'query',
-                      'page',
-                      'country',
-                      'device',
-                      'searchAppearance',
-                    ]),
-                    operator: z.enum([
-                      'equals',
-                      'notEquals',
-                      'contains',
-                      'notContains',
-                      'includingRegex',
-                      'excludingRegex',
-                    ]),
-                    expression: z.string(),
-                  }),
-                ),
-              }),
-            )
+            .array(SEARCH_ANALYTICS_FILTER_GROUP_SCHEMA)
             .optional()
             .describe(
-              "Optional Search Console filters applied identically to both periods. A caller-supplied query regex can approximate a manual brand/non-brand split, but it is not equivalent to Search Console's AI-assisted native Branded/Non-branded filter, which the Search Analytics API does not expose. Countries use ISO 3166-1 alpha-3 codes.",
+              "Optional Search Console filters applied identically to both periods. Filter operator defaults to 'equals' when omitted, and expressions are limited to 4096 characters. A caller-supplied query regex can approximate a manual brand/non-brand split, but it is not equivalent to Search Console's AI-assisted native Branded/Non-branded filter, which the Search Analytics API does not expose. Countries use ISO 3166-1 alpha-3 codes.",
             ),
           limit: ANALYSIS_RESULT_LIMIT_SCHEMA,
           start_row: RESULT_START_ROW_SCHEMA,

package/src/url-inspection-language-schema.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+export const URL_INSPECTION_LANGUAGE_CODE_SCHEMA = z
+  .string()
+  .superRefine((value, ctx) => {
+    try {
+      if (Intl.getCanonicalLocales(value).length !== 1) {
+        throw new RangeError('Invalid language tag');
+      }
+    } catch {
+      ctx.addIssue({
+        code: 'custom',
+        message:
+          "language_code must be a valid BCP-47 language tag, e.g. 'en-US' or 'de-CH'.",
+      });
+    }
+  })
+  .default('en-US')
+  .describe(
+    "BCP-47 language code for translatable strings in the result, e.g. 'en-US' or 'de-CH'.",
+  );