@digestseo/mcp-gsc 0.4.13 → 0.4.14

package/CHANGELOG.md

@@ -7,6 +7,12 @@ 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

package/README.md

@@ -85,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. |
 

package/package.json

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

package/src/index.ts

@@ -210,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.";
 
@@ -279,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(),
@@ -573,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',
@@ -1356,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 }) => {
@@ -1370,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,
   },