@digestseo/mcp-gsc 0.4.12 → 0.4.14

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.14] - 2026-09-22
+
+### Fixed
+- `sites.add` now explicitly reports that adding a Search Console property does not perform ownership verification, preventing agents from confusing the Search Console Sites API with Google's separate Site Verification workflow.
+- MCP write annotations now classify `sites.add` and `sitemaps.submit` as additive (`destructiveHint: false`) while keeping the delete tools destructive, matching the protocol's risk vocabulary instead of labeling every external mutation as destructive.
+
+## [0.4.13] - 2026-09-22
+
+### Fixed
+- The published `npx` launcher now persists local Wrangler/KV/Durable Object state in a stable per-user directory instead of the versioned npm package cache, preserving the encrypted Google session across later package upgrades and ordinary npm cache cleanup; `MCP_GSC_STATE_DIR` can override the location. The first release with this change may require one Google reconnect because older launcher releases used the package cache for local state.
+- Official MCP Registry discovery no longer advertises the owner-hosted remote while that deployment's tool contract lags the current npm package; the verified npm launcher remains the Registry installation path until hosted parity is restored.
+- Search Analytics now exposes a machine-readable Generative AI report boundary instead of inviting agents to invent an unsupported selector: the current documented API has no dedicated Generative AI search type/filter, while AI Overviews and AI Mode remain included in overall web Search performance data.
+
 ## [0.4.12] - 2026-09-22
 
 ### Fixed

package/README.md

@@ -24,6 +24,8 @@ 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). 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.
+
 The local launcher defaults to `GSC_ACCESS_MODE=readwrite`. For least-privilege analytics/reporting-only use, set `GSC_ACCESS_MODE=readonly` in the environment before running `npx`; the launcher forwards that value into the local Worker so OAuth requests only the read-only Search Console scope and the five mutation tools stay unregistered.
 
 For Google OAuth and Cloudflare deployment configuration, follow [SETUP.md](SETUP.md).
@@ -75,7 +77,7 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 21 tools. Read-onl
 | **`server.capabilities`** | Read | List every tool this server exposes and report whether your Google connection is currently authenticated (`connected` / `not_connected`). Takes no arguments — a good first call for discovery. |
 | **`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. 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. |
+| **`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. 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`. |
 | **`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. |
@@ -83,7 +85,7 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 21 tools. Read-onl
 | **`insights.quick_wins`** / **`insights.cannibalization`** / **`insights.content_decay`** | Read | Surface average-position opportunity rows, query/page overlap, and evidence-ranked click declines. Quick-win candidates are observed query/page rows selected by aggregate Search Console average position, not proof of a stable current rank, and CTR is context rather than an eligibility filter. Cannibalization candidate totals/shares are scoped to observed query/page rows rather than true query-level property totals; content-decay results compare only pages returned in both periods and do not turn one-sided row absence into zero traffic. |
 | **`indexing.list_pages`** / **`analytics.compare`** | Read | Analyze pages receiving Search Console impressions and compare two periods, optionally using the same search type and query/page/country/device/search-appearance filters for both periods. `analytics.compare` compares only dimension keys returned in both period responses; a key absent from one non-exhaustive Search Analytics response is not assumed to have zero metrics. Because its comparison contract includes average position, it excludes Discover and Google News. `indexing.list_pages` is performance data, not index coverage: a missing URL may still be indexed; use `urls.inspect` / `urls.inspect_many` for URL-level index status. |
 | **`reports.weekly_digest`** | Read | Generate a plain-language seven-day performance report with movers, top pages, and one recommended action. Query movers compare only rows returned in both weekly Search Analytics result sets; a query missing from one bounded response is not treated as zero because Google does not guarantee every data row. |
-| **`sites.add`** / **`sites.delete`** | Write | Add or remove a Search Console property. |
+| **`sites.add`** / **`sites.delete`** | Write | Add or remove a Search Console property. `sites.add` only adds the property to the connected account's Search Console site set; it returns `ownership_verification_performed: false` because ownership verification is a separate Google Site Verification/Search Console workflow. |
 | **`sitemaps.submit`** / **`sitemaps.delete`** | Write | Submit or remove a sitemap. |
 | **`indexing.request`** | Write | Requests indexing through Google's Indexing API. Google currently restricts this API to pages containing `JobPosting` structured data or livestream pages containing `BroadcastEvent` inside `VideoObject`. It is not available for general webpage submission. |
 
@@ -110,6 +112,8 @@ Once connected, ask your assistant things like:
 
 Query regexes are a manual approximation only. Search Console's native Branded/Non-branded filter uses Google's own AI-assisted classification (including language variants, typos, and associated products/services), and that native classifier is not exposed as a Search Analytics API filter.
 
+Search Console also has dedicated Generative AI performance reports for Search and Discover. The current documented Search Analytics API does not expose a dedicated Generative AI search type or filter selector, so this MCP does not guess one. AI Overviews and AI Mode remain included in overall web Search performance data; use the Search Console UI for the dedicated Generative AI report until Google documents API access.
+
 ## Connect in your AI client
 
 Once you've deployed the server (see **[SETUP.md](SETUP.md)**), connect it by pasting your Worker's `/mcp` URL into your client:

package/SETUP.md

@@ -81,6 +81,7 @@ npx wrangler login
    - Replace `<your-worker>` with your Worker's name + subdomain. If you don't know it yet, deploy once (Step 6) to see the assigned `*.workers.dev` URL, then come back and add it here. The default Worker name is `mcp-gsc` (set in `wrangler.jsonc`).
    - The `http://localhost:8787/google/callback` entry is for local development with `npm run dev`.
    - The `http://127.0.0.1:8080/google/callback` entry is for the published `npx -y @digestseo/mcp-gsc` launcher, whose Registry transport is `http://127.0.0.1:8080/mcp` by default. If you set `PORT`, replace `8080` with that exact port.
+   - The `npx` launcher persists its local KV and Durable Object state in `~/.mcp-gsc/state` by default so npm package upgrades or cache cleanup do not discard the encrypted Google session. Set `MCP_GSC_STATE_DIR` to use another directory, and keep the same `TOKEN_ENCRYPTION_KEY` when reusing existing state. The first release with this stable path may require one Google reconnect because older launcher releases stored local state under the npm package cache.
    - The Worker derives Google's redirect URI from the MCP request URL. Google requires an exact authorized-URI match, so keep the same scheme, host, port, and `/google/callback` path. `localhost` and `127.0.0.1` are different hosts for this check.
    - The path must be exactly `/google/callback` — that's the route this server handles.
    - The DigestSEO-hosted instance also requires this exact callback URI in the OAuth client configured on its Worker: `https://mcp-gsc.digestseo.com/google/callback`.

package/package.json

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

package/scripts/glama-start.mjs

@@ -1,5 +1,7 @@
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const port = process.env.PORT || '8080';
@@ -9,6 +11,9 @@ const googleRedirectUri = `${localBaseUrl}/google/callback`;
 const wranglerConfig = fileURLToPath(
   new URL('../wrangler.example.jsonc', import.meta.url),
 );
+const stateDir = process.env.MCP_GSC_STATE_DIR
+  ? resolve(process.env.MCP_GSC_STATE_DIR)
+  : resolve(homedir(), '.mcp-gsc', 'state');
 const forwardedVariables = [
   'GOOGLE_CLIENT_ID',
   'GOOGLE_CLIENT_SECRET',
@@ -20,6 +25,8 @@ const args = [
   'dev',
   '--config',
   wranglerConfig,
+  '--persist-to',
+  stateDir,
   '--local',
   '--ip',
   '127.0.0.1',
@@ -35,6 +42,7 @@ for (const name of forwardedVariables) {
 
 console.error(`[mcp-gsc] Local MCP endpoint: ${mcpUrl}`);
 console.error(`[mcp-gsc] Google OAuth redirect URI: ${googleRedirectUri}`);
+console.error(`[mcp-gsc] Local state directory: ${stateDir}`);
 
 const wranglerCli = createRequire(import.meta.url).resolve('wrangler');
 const child = spawn(process.execPath, [wranglerCli, ...args], { stdio: 'inherit' });

package/src/index.ts

@@ -193,6 +193,12 @@ const CAPABILITIES_OUTPUT_SCHEMA = {
       description: z.string(),
     }),
   ),
+  provider_limits: z.object({
+    generative_ai_performance_report: z.object({
+      dedicated_api_supported: z.literal(false),
+      note: z.string(),
+    }),
+  }),
   hint: z.string(),
 };
 
@@ -204,6 +210,9 @@ const SITE_DETAIL_OUTPUT_SCHEMA = {
   site: z.object(SITE_OUTPUT_SCHEMA),
 };
 
+const SITE_ADD_VERIFICATION_NOTE =
+  "Google Search Console Sites.add only adds the property to the user's Search Console site set; it does not verify ownership. Ownership verification is a separate Google Site Verification/Search Console workflow.";
+
 const URL_INSPECTION_SCOPE_NOTE =
   "Google's URL Inspection API reports the version currently known in Google's index; it does not run a live URL test or prove current live-page indexability. The mobileUsabilityResult field is deprecated and may be absent.";
 
@@ -243,6 +252,10 @@ const SEARCH_ANALYTICS_OUTPUT_SCHEMA = {
     'False because the Search Analytics API does not guarantee every data row; Google can return only top rows even after local pagination is exhausted.',
   ),
   provider_note: z.string(),
+  generative_ai_report_isolatable: z.literal(false).describe(
+    'False because the current documented Search Analytics API exposes no dedicated Generative AI report search type or filter selector.',
+  ),
+  generative_ai_note: z.string(),
   next_start_row: z.number().int().nonnegative().optional(),
   has_more: z.boolean(),
   truncated: z.boolean(),
@@ -269,6 +282,12 @@ const MESSAGE_OUTPUT_SCHEMA = {
   message: z.string(),
 };
 
+const SITE_ADD_OUTPUT_SCHEMA = {
+  message: z.string(),
+  ownership_verification_performed: z.literal(false),
+  ownership_verification_note: z.string(),
+};
+
 const SEARCH_ANALYTICS_PAGINATION_OUTPUT_SCHEMA = z.object({
   rows_fetched: z.number().int().nonnegative(),
   pages_fetched: z.number().int().positive(),
@@ -480,6 +499,9 @@ function toolResponse<T extends Record<string, unknown>>(
 const SEARCH_ANALYTICS_PROVIDER_NOTE =
   'Google Search Analytics does not guarantee all data rows and can return only top rows. Local pagination fields describe what this server fetched or bounded; they do not prove provider-level exhaustiveness.';
 
+const GENERATIVE_AI_REPORT_API_NOTE =
+  "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. AI Overviews and AI Mode remain included in overall web Search performance data. Do not infer isolated Generative AI metrics from analytics.query or guess a searchAppearance identifier.";
+
 function paginationMetadata(result: PaginatedSearchAnalyticsResult) {
   return {
     rows_fetched: result.rows.length,
@@ -560,7 +582,7 @@ const TOOL_CATALOG = [
   {
     name: 'sites.add',
     description:
-      'Add a new website property to your Google Search Console account.',
+      'Add a website property to the connected Google account\'s Search Console site set. This does not verify ownership; Google handles ownership verification through a separate Site Verification/Search Console workflow.',
   },
   {
     name: 'sites.delete',
@@ -570,7 +592,7 @@ const TOOL_CATALOG = [
   {
     name: 'analytics.query',
     description:
-      'Query Search Console search analytics (impressions, clicks, CTR, average position) over a date range, broken down by query, page, country, device, date, or search appearance. Supports filters and pagination. Google does not guarantee every data row and can return only top rows.',
+      'Query Search Console search analytics (impressions, clicks, CTR, average position) over a date range, broken down by query, page, country, device, date, or search appearance. Supports filters and pagination. Google does not guarantee every data row and can return only top rows. The current documented API does not expose a dedicated Generative AI performance-report selector; do not invent one.',
   },
   {
     name: 'insights.page_queries',
@@ -733,6 +755,12 @@ class GscMcpRuntime {
           access_mode: accessMode,
           auth_status: authStatus,
           tools: getToolCatalogForAccessMode(TOOL_CATALOG, accessMode),
+          provider_limits: {
+            generative_ai_performance_report: {
+              dedicated_api_supported: false as const,
+              note: GENERATIVE_AI_REPORT_API_NOTE,
+            },
+          },
           hint: "If auth_status is not 'connected', the user should reconnect this server in their MCP client to sign in with Google.",
         };
         return toolResponse(JSON.stringify(capabilities, null, 2), capabilities);
@@ -993,6 +1021,13 @@ class GscMcpRuntime {
           '  value in a separate query and group by page/query/country/device/',
           '  date/hour as needed. Do not guess new appearance identifiers;',
           '  discover the values Google returns for the property first.',
+          '- GENERATIVE AI REPORT: Search Console now has dedicated',
+          '  Generative AI performance reports in its UI, but the current',
+          '  documented Search Analytics API exposes no dedicated Generative',
+          '  AI search type or filter selector. AI Overviews and AI Mode remain',
+          '  included in overall web Search performance data. Do not guess a',
+          '  searchAppearance identifier or claim analytics.query isolates the',
+          '  dedicated Generative AI report.',
           '- Use dimension_filter_groups to filter by country, device, query',
           '  content, page URL, or search feature. includingRegex and',
           '  excludingRegex use RE2 syntax. A query regex can provide a manual',
@@ -1054,7 +1089,7 @@ class GscMcpRuntime {
           search_type: z
             .enum(['web', 'image', 'video', 'news', 'discover', 'googleNews'])
             .default('web')
-            .describe('Which search index to query. Defaults to web. Google Discover and Google News do not support query grouping/filtering or average position.'),
+            .describe('Which documented Search Analytics search index to query. Defaults to web. Google Discover and Google News do not support query grouping/filtering or average position. The current API does not expose a dedicated Generative AI performance-report search type.'),
           aggregation_type: z
             .enum(['auto', 'byNewsShowcasePanel', 'byPage', 'byProperty'])
             .default('auto')
@@ -1148,6 +1183,8 @@ class GscMcpRuntime {
             : {}),
           provider_exhaustiveness_guaranteed: false,
           provider_note: SEARCH_ANALYTICS_PROVIDER_NOTE,
+          generative_ai_report_isolatable: false,
+          generative_ai_note: GENERATIVE_AI_REPORT_API_NOTE,
           has_more: bounded.resultPage.has_more,
           truncated: bounded.resultPage.truncated,
           byte_limit_reached: bounded.resultPage.byte_limit_reached,
@@ -1328,11 +1365,11 @@ class GscMcpRuntime {
       'sites.add',
       {
         title: 'Add Search Console property',
-        description: 'Add a new website property to your Google Search Console account. Note: Domain properties require sc-domain prefix (e.g., sc-domain:example.com), URL-prefix properties require full URL (e.g., https://example.com/).',
+        description: 'Add a website property to the connected Google account\'s Search Console site set. This does not verify ownership. Domain properties require an sc-domain prefix (e.g., sc-domain:example.com); URL-prefix properties require a full URL (e.g., https://example.com/).',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
         },
-        outputSchema: MESSAGE_OUTPUT_SCHEMA,
+        outputSchema: SITE_ADD_OUTPUT_SCHEMA,
         annotations: WRITE_TOOL_ANNOTATIONS['sites.add'],
       },
       async ({ site_url }) => {
@@ -1342,7 +1379,12 @@ class GscMcpRuntime {
         const accessToken = await this.getAccessToken(googleId);
         await addSite(accessToken, site_url);
         const message = `Successfully added site property: ${site_url}`;
-        return toolResponse(message, { message });
+        const payload = {
+          message,
+          ownership_verification_performed: false as const,
+          ownership_verification_note: SITE_ADD_VERIFICATION_NOTE,
+        };
+        return toolResponse(`${message}\n\n${SITE_ADD_VERIFICATION_NOTE}`, payload);
       },
     );
 

package/src/write-tool-annotations.ts

@@ -1,17 +1,18 @@
 /**
  * MCP hints for each mutation exposed by this server.
  *
- * Search Console's sites and sitemaps APIs use PUT for additions and DELETE
- * for removals, so repeating the same request has the same intended effect.
- * Indexing publishes a URL_UPDATED notification with POST; each call can
- * consume quota and update Google's notification state, so it is not marked
- * idempotent. Every mutation is marked destructive so MCP clients require
- * explicit confirmation before changing external Google state.
+ * MCP defines destructiveHint=false for non-read-only tools that perform only
+ * additive updates. Search Console's site addition and sitemap submission are
+ * additive PUT operations; the corresponding DELETE operations remain
+ * destructive. Indexing publishes a URL_UPDATED notification with POST; each
+ * call can consume quota and change Google's indexing state, so it remains
+ * conservative (destructive + non-idempotent). Tool annotations are client
+ * hints, not an enforcement or confirmation mechanism.
  */
 export const WRITE_TOOL_ANNOTATIONS = {
   'sites.add': {
     readOnlyHint: false,
-    destructiveHint: true,
+    destructiveHint: false,
     idempotentHint: true,
     openWorldHint: true,
   },
@@ -23,7 +24,7 @@ export const WRITE_TOOL_ANNOTATIONS = {
   },
   'sitemaps.submit': {
     readOnlyHint: false,
-    destructiveHint: true,
+    destructiveHint: false,
     idempotentHint: true,
     openWorldHint: true,
   },