@digestseo/mcp-gsc 0.4.30 → 0.4.31

package/CHANGELOG.md

@@ -7,6 +7,15 @@ 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
@@ -198,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.30",
+  "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 {
@@ -149,35 +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),
-});
+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 = {
@@ -190,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.";
 
@@ -914,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,
@@ -927,6 +970,7 @@ class GscMcpRuntime {
           const mcpSiteUrlAccepted = apiIdentifierKind !== 'undocumented';
           return {
             ...site,
+            ...sitePermissionState(site.permissionLevel),
             api_identifier_kind: apiIdentifierKind,
             mcp_site_url_accepted: mcpSiteUrlAccepted,
             ...(!mcpSiteUrlAccepted
@@ -943,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,
         },
@@ -954,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,
+        });
       },
     );