@digestseo/mcp-gsc 0.4.29 → 0.4.31

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.31] - 2026-09-24
+
+### Added
+- Gemini CLI can now install this repository as a native extension, bundling the verified local Streamable HTTP MCP connection with the existing `gsc-weekly-review`, `gsc-indexing-triage`, and `gsc-search-opportunities` Agent Skills.
+
+### Changed
+- Exact Search Analytics country and device filters now reject malformed provider values before reserving local Search Analytics budget, resolving Google credentials, or calling Search Console; substring and RE2 regex operators remain unrestricted.
+- `sites.list` and `sites.get` now expose explicit `verification_state` and `owner` fields alongside Google's raw `permissionLevel`, so agents can distinguish unverified properties and owner-only Indexing API prerequisites before choosing a property workflow.
+
+## [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
@@ -192,6 +207,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.4.2] - 2026-09-21
 
 ### Fixed
+- Search Analytics now rejects malformed exact-match country/device filters during MCP input validation, before local rate-limit, credential, or Google API work, while preserving contains and regex filter semantics.
 - Cannibalization totals and impression shares now expose their query/page-row aggregation scope explicitly so clients do not mistake summed page impressions for a true query-level Search Console total.
 - Discover Search Analytics calls now reject unsupported query grouping/filtering before reaching Google, and query-centric/comparison tools no longer advertise Discover where their contracts depend on query or average-position data that Discover does not provide.
 - Quick-win guidance now treats Search Console position as an aggregate average-position metric rather than a literal current rank, and metadata no longer implies CTR is an eligibility filter when the implementation does not filter on CTR.

package/README.md

@@ -75,6 +75,14 @@ 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.
 
+**Gemini CLI**
+
+```bash
+gemini extensions install https://github.com/AKzar1el/mcp-gsc --ref main
+```
+
+The Gemini CLI extension bundles the verified local loopback MCP configuration plus the same three Agent Skills: `gsc-weekly-review`, `gsc-indexing-triage`, and `gsc-search-opportunities`. Start the npm launcher before using the extension; the extension 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)

package/package.json

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

package/src/google.ts

@@ -314,6 +314,27 @@ export interface DimensionFilter {
   expression: string;
 }
 
+export function assertSearchAnalyticsFilterCompatible(
+  filter: DimensionFilter,
+): void {
+  if (filter.operator !== 'equals' && filter.operator !== 'notEquals') return;
+
+  if (filter.dimension === 'country' && !/^[A-Za-z]{3}$/.test(filter.expression)) {
+    throw new Error(
+      'Search Analytics exact country filters must use a three-letter ISO 3166-1 alpha-3 code.',
+    );
+  }
+
+  if (
+    filter.dimension === 'device' &&
+    !['DESKTOP', 'MOBILE', 'TABLET'].includes(filter.expression.toUpperCase())
+  ) {
+    throw new Error(
+      'Search Analytics exact device filters must use DESKTOP, MOBILE, or TABLET.',
+    );
+  }
+}
+
 export interface DimensionFilterGroup {
   groupType: 'and';
   filters: DimensionFilter[];
@@ -369,6 +390,7 @@ export function assertSearchAnalyticsQueryCompatible(body: SearchAnalyticsQuery)
     if (filter.expression.length > 4096) {
       throw new Error('Search Analytics filter expressions must be at most 4096 characters.');
     }
+    assertSearchAnalyticsFilterCompatible(filter);
   }
 
   if (body.aggregationType === 'byPage' && hasPageGroupingOrFilter) {

package/src/index.ts

@@ -32,6 +32,7 @@ import {
   requestIndexingRemoval,
   getIndexingNotificationMetadata,
   processPerformanceComparison,
+  assertSearchAnalyticsFilterCompatible,
   type PaginatedSearchAnalyticsResult,
 } from './google';
 import {
@@ -66,6 +67,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,9 +150,57 @@ 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),
+  })
+  .superRefine((filter, ctx) => {
+    try {
+      assertSearchAnalyticsFilterCompatible(filter);
+    } catch (error) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['expression'],
+        message: (error as Error).message,
+      });
+    }
+  });
+
+const SEARCH_ANALYTICS_FILTER_GROUP_SCHEMA = z.object({
+  groupType: z.literal('and').default('and'),
+  filters: z.array(SEARCH_ANALYTICS_FILTER_SCHEMA),
+});
+
+const SITE_VERIFICATION_STATE_SCHEMA = z
+  .enum(['verified', 'unverified', 'unknown'])
+  .describe(
+    "Derived from Google's permissionLevel. siteOwner/siteFullUser/siteRestrictedUser are verified, siteUnverifiedUser is unverified, and any future undocumented permission level is reported as unknown.",
+  );
+
 const SITE_OUTPUT_SCHEMA = {
   siteUrl: z.string(),
   permissionLevel: z.string(),
+  verification_state: SITE_VERIFICATION_STATE_SCHEMA,
+  owner: z.boolean().describe(
+    "True only when Google returns permissionLevel 'siteOwner'. Restricted Indexing API workflows require owner-level Search Console access.",
+  ),
 };
 
 const LISTED_SITE_OUTPUT_SCHEMA = {
@@ -163,6 +213,26 @@ const LISTED_SITE_OUTPUT_SCHEMA = {
 const PLATFORM_PROPERTY_API_NOTE =
   "Google Search Console now has platform properties for social/video accounts in its UI, but the current Search Console API documentation still defines siteUrl using URL-prefix and sc-domain website-property forms. mcp-gsc preserves any other identifier returned by sites.list but will not pass an undocumented property identifier to API tools until Google publishes that contract.";
 
+function sitePermissionState(permissionLevel: string): {
+  verification_state: 'verified' | 'unverified' | 'unknown';
+  owner: boolean;
+} {
+  if (permissionLevel === 'siteUnverifiedUser') {
+    return { verification_state: 'unverified', owner: false };
+  }
+  if (
+    permissionLevel === 'siteOwner' ||
+    permissionLevel === 'siteFullUser' ||
+    permissionLevel === 'siteRestrictedUser'
+  ) {
+    return {
+      verification_state: 'verified',
+      owner: permissionLevel === 'siteOwner',
+    };
+  }
+  return { verification_state: 'unknown', owner: false };
+}
+
 const SITEMAP_PROVIDER_NOTE =
   "Google's lastSubmitted is the time the sitemap was submitted to Search Console; it is not the sitemap file's generation, deployment, or last-modified time. lastDownloaded is the time Google last downloaded the sitemap; it is not a page crawl or indexing timestamp.";
 
@@ -887,7 +957,7 @@ class GscMcpRuntime {
       {
         title: 'List Search Console properties',
         description:
-          "List the Google Search Console properties (sites) the connected Google account has access to. Each entry preserves Google's siteUrl and permissionLevel and adds api_identifier_kind plus mcp_site_url_accepted. Google now exposes platform properties for social/video accounts in the Search Console UI, but its current API documentation still defines siteUrl using URL-prefix and sc-domain website-property forms; identifiers outside those documented forms are preserved here but marked unsupported rather than guessed. Call this when the user asks 'what sites do I have?' or 'what properties are connected?', or before another tool that requires site_url.",
+          "List the Google Search Console properties (sites) the connected Google account has access to. Each entry preserves Google's siteUrl and permissionLevel, derives verification_state plus owner from Google's documented permission levels, and adds api_identifier_kind plus mcp_site_url_accepted. Treat verification_state='unverified' as not ready for normal property-scoped Search Console workflows; owner=true is required by this server's restricted Indexing API workflows. Google now exposes platform properties for social/video accounts in the Search Console UI, but its current API documentation still defines siteUrl using URL-prefix and sc-domain website-property forms; identifiers outside those documented forms are preserved here but marked unsupported rather than guessed. Call this when the user asks 'what sites do I have?' or 'what properties are connected?', or before another tool that requires site_url.",
         inputSchema: {},
         outputSchema: SITES_OUTPUT_SCHEMA,
         annotations: READ_ONLY_ANNOTATIONS,
@@ -900,6 +970,7 @@ class GscMcpRuntime {
           const mcpSiteUrlAccepted = apiIdentifierKind !== 'undocumented';
           return {
             ...site,
+            ...sitePermissionState(site.permissionLevel),
             api_identifier_kind: apiIdentifierKind,
             mcp_site_url_accepted: mcpSiteUrlAccepted,
             ...(!mcpSiteUrlAccepted
@@ -916,7 +987,7 @@ class GscMcpRuntime {
       {
         title: 'Get Search Console property',
         description:
-          "Retrieve one exact Google Search Console property and the connected account's permission level for it. Use this when the user has already named a property and you need to confirm that exact property or its access level without listing every property first.",
+          "Retrieve one exact Google Search Console property and its connected-account access state. The response preserves Google's permissionLevel and derives verification_state plus owner so callers can distinguish an unverified property and recognize owner-only Indexing API prerequisites without listing every property first.",
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
         },
@@ -927,7 +998,13 @@ class GscMcpRuntime {
         const googleId = this.requireGoogleId();
         const accessToken = await this.getAccessToken(googleId);
         const site = await getSite(accessToken, site_url);
-        return toolResponse(JSON.stringify(site, null, 2), { site });
+        const siteWithPermissionState = {
+          ...site,
+          ...sitePermissionState(site.permissionLevel),
+        };
+        return toolResponse(JSON.stringify(siteWithPermissionState, null, 2), {
+          site: siteWithPermissionState,
+        });
       },
     );
 
@@ -943,12 +1020,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,
@@ -993,12 +1065,7 @@ class GscMcpRuntime {
             .describe(
               'Between 1 and 10 unique 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'.",
-            ),
+          language_code: URL_INSPECTION_LANGUAGE_CODE_SCHEMA,
         },
         outputSchema: INSPECTION_BATCH_OUTPUT_SCHEMA,
         annotations: READ_ONLY_ANNOTATIONS,
@@ -1222,34 +1289,10 @@ class GscMcpRuntime {
               "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,
@@ -2021,34 +2064,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'.",
+  );