@digestseo/mcp-gsc 0.4.13 → 0.4.15

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.15] - 2026-09-22
+
+### Fixed
+- `analytics.query` now distinguishes fresh preliminary Search Analytics data from finalized-data lag, echoes the requested `data_state`, and reports whether preliminary data is possible instead of implying a blanket 2-3 day delay.
+- Repo-owned quick-connect configs and client docs now use the verified loopback npm launcher instead of routing new users to the intentionally unadvertised hosted remote while that deployment lags the current package.
+
+## [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

@@ -30,35 +30,37 @@ The local launcher defaults to `GSC_ACCESS_MODE=readwrite`. For least-privilege
 
 For Google OAuth and Cloudflare deployment configuration, follow [SETUP.md](SETUP.md).
 
-### Connect in 30 seconds
+### Connect the local launcher
 
-Every deployed instance exposes the same endpoint shape:
+For the current verified quick-connect path, start the npm launcher first after supplying the Google OAuth and token-encryption environment variables described in [SETUP.md](SETUP.md):
 
-```
-https://<your-worker>.workers.dev/mcp
+```bash
+npx -y @digestseo/mcp-gsc
 ```
 
-The DigestSEO-hosted instance is available at:
+Then connect your MCP client to the launcher's loopback endpoint:
 
 ```
-https://mcp-gsc.digestseo.com/mcp
+http://127.0.0.1:8080/mcp
 ```
 
+Self-hosted Cloudflare Worker deployments continue to use `https://<your-worker>.workers.dev/mcp`. The repo does not currently advertise the owner-hosted remote as a quick-connect path because its deployed tool contract is behind the published package.
+
 **Claude Code**
 
 ```bash
-claude mcp add --transport http gsc https://<your-worker>.workers.dev/mcp
+claude mcp add --transport http gsc http://127.0.0.1:8080/mcp
 ```
 
 **Cursor**
 
-[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=gsc&config=eyJ1cmwiOiJodHRwczovL21jcC1nc2MuZGlnZXN0c2VvLmNvbS9tY3AifQ%3D%3D)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=gsc&config=eyJ1cmwiOiJodHRwOi8vMTI3LjAuMC4xOjgwODAvbWNwIn0%3D)
 
 **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%22https%3A%2F%2Fmcp-gsc.digestseo.com%2Fmcp%22%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)
+[![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)
 
-Uses the hosted endpoint above; complete its Google OAuth flow on first use.
+Start the npm launcher before using either install button. Complete its Google OAuth flow on first use.
 
 **ChatGPT** — add it as a custom MCP app in developer mode; see [Connect in your AI client](#connect-in-your-ai-client) below.
 
@@ -77,7 +79,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. 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`. |
+| **`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. `data_state: "all"` can include fresh preliminary data, while `final` returns only finalized data; responses echo `data_state` plus `preliminary_data_possible`, and date/hour groupings preserve Google's incomplete-data boundary metadata when returned. 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. |
@@ -85,7 +87,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.15",
   "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.";
 
@@ -241,6 +244,12 @@ const SEARCH_ANALYTICS_OUTPUT_SCHEMA = {
   row_count: z.number().int().nonnegative(),
   start_row: z.number().int().nonnegative(),
   rows: z.array(z.object(SEARCH_ROW_OUTPUT_SCHEMA)),
+  data_state: z.enum(['all', 'final', 'hourly_all']).describe(
+    'The Search Analytics dataState requested from Google for this response.',
+  ),
+  preliminary_data_possible: z.boolean().describe(
+    'True when the requested data state can include fresh data that is still being collected and processed. This does not assert that every returned row is incomplete.',
+  ),
   position_supported: z.boolean().describe(
     'Whether average position is supported for the selected Search Analytics search type. False for Google Discover and Google News.',
   ),
@@ -279,6 +288,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 +588,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',
@@ -980,10 +995,13 @@ class GscMcpRuntime {
           '  matching dimension. Expect the returned rows to cover only a',
           '  subset of total impressions; this is normal Google behavior, not',
           '  a data error.',
-          '- DATA FRESHNESS: Search Console data lags about 2-3 days behind',
-          '  real time. If the user asks about "today" or "yesterday", expect',
-          '  empty or partial rows for the most recent days; the latest',
-          '  reliably-complete date is usually 3 days ago.',
+          '- DATA FRESHNESS: data_state "all" can include fresh preliminary',
+          '  data instead of imposing the finalized-data lag; "final" returns',
+          '  only finalized data and can therefore lag recent activity. When',
+          '  Google returns metadata.first_incomplete_date or',
+          '  metadata.first_incomplete_hour for date/hour groupings, treat',
+          '  that boundary and later rows as still subject to change. The',
+          '  response also echoes data_state and preliminary_data_possible.',
           '- AVERAGE POSITION is impression-weighted. To compute an overall',
           '  position across multiple rows, use',
           '  sum(position * impressions) / sum(impressions). Never plain-average',
@@ -1036,7 +1054,7 @@ class GscMcpRuntime {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
           start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date (inclusive) in YYYY-MM-DD format.'),
           end_date: SEARCH_CONSOLE_DATE_SCHEMA.describe(
-            'End date (inclusive) in YYYY-MM-DD format. Note the 2-3 day data lag: the most recent complete date is usually 3 days ago.',
+            'End date (inclusive) in YYYY-MM-DD format. Recent dates are allowed: data_state all/hourly_all can include preliminary data, while final returns only finalized data.',
           ),
           dimensions: z
             .array(
@@ -1164,6 +1182,8 @@ class GscMcpRuntime {
           row_count: bounded.items.length,
           start_row,
           rows: bounded.items,
+          data_state,
+          preliminary_data_possible: data_state !== 'final',
           position_supported:
             search_type !== 'discover' && search_type !== 'googleNews',
           ...(search_type === 'discover' || search_type === 'googleNews'
@@ -1356,11 +1376,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 +1390,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,
   },