@digestseo/mcp-gsc 0.4.33 → 0.4.35

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.35] - 2026-09-24
+
+### Fixed
+- Search Analytics pagination now treats provider responses shorter than the requested page size as terminal, matching Google's documented contract and avoiding false continuations or unnecessary follow-up requests across direct and higher-level workflows.
+- `insights.page_queries` now rejects exact page URLs outside the supplied Search Console property before reserving local Search Analytics safety budget, resolving Google credentials, or calling the provider, preventing misleading empty cross-property drilldowns.
+
+## [0.4.34] - 2026-09-24
+
+### Fixed
+- `analytics.query` now rejects documented-invalid cross-field request combinations before reserving local Search Analytics safety budget or resolving Google credentials, while retaining the lower-level provider compatibility guard for internal callers.
+- `indexing.status`, `indexing.request`, and `indexing.remove` now reject URLs outside the supplied Search Console property before reserving local safety budget, resolving Google credentials, or calling Search Console for owner authorization.
+
 ## [0.4.33] - 2026-09-24
 
 ### Changed

package/README.md

@@ -66,6 +66,8 @@ Codex CLI and the Codex IDE extension share MCP configuration, so registering th
 
 When this repository is installed as a Cursor plugin, Cursor also auto-discovers three bundled Agent Skills that compose the MCP tools into evidence-safe workflows: `gsc-weekly-review`, `gsc-indexing-triage`, and `gsc-search-opportunities`. The **Add to Cursor** button above installs the MCP connection only; the bundled skills are part of the repository's Cursor plugin package.
 
+The button and plugin MCP configuration above are for Cursor running on the same machine as the npm launcher. **Cursor Cloud Agents run in isolated cloud VMs, so they cannot reach `127.0.0.1` on your computer.** For Cloud Agents, deploy your own externally reachable HTTPS Worker and add its `/mcp` URL from the MCP controls at [cursor.com/agents](https://cursor.com/agents); Cursor supports HTTP MCP servers and OAuth there. Do not reuse the loopback URL for a Cloud Agent.
+
 **GitHub Copilot CLI**
 
 ```bash
@@ -89,7 +91,9 @@ The Gemini CLI extension bundles the verified local loopback MCP configuration p
 
 Start the npm launcher before using either install button or the Copilot plugin. Complete its Google OAuth flow on first use.
 
-**ChatGPT** — ChatGPT cannot connect directly to this loopback `127.0.0.1` endpoint. Use OpenAI's **Secure MCP Tunnel** for the local launcher, or deploy your own remote Cloudflare Worker and add that `/mcp` URL as a custom MCP app in Developer mode; see [Connect in your AI client](#connect-in-your-ai-client) below.
+**ChatGPT** — ChatGPT cannot connect directly to this loopback `127.0.0.1` endpoint. For private/local use, create an OpenAI **Secure MCP Tunnel**, then run `tunnel-client` on the same machine as the launcher so it can reach `http://127.0.0.1:8080/mcp`; when creating the ChatGPT app, choose the **Tunnel** connection and select that tunnel. The tunnel setup requires an OpenAI `tunnel_id` and runtime API key; see OpenAI's [Secure MCP Tunnel guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels). The tunnel keeps the MCP server private and is intended for private/developer-mode connectivity, not public plugin distribution.
+
+Alternatively, deploy your own remote Cloudflare Worker and add its HTTPS `/mcp` URL as a custom MCP app in Developer mode; see [Connect in your AI client](#connect-in-your-ai-client) below.
 
 A self-hostable [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **Google Search Console**. Connect it to Claude.ai, Cursor, ChatGPT, or any MCP-compatible client and ask your AI assistant about your site's organic search performance — impressions, clicks, top queries, index status, and sitemap health — straight from your own Google account.
 

package/package.json

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

package/src/google.ts

@@ -785,10 +785,9 @@ export async function querySearchAnalytics(
 
 /**
  * Fetches Search Analytics rows in 25,000-row pages for higher-level tools.
- * Google's documented pagination contract uses an explicit empty response as
- * the terminal page, so a short non-empty page is not treated as exhaustion.
- * A full final page conservatively reports localLimitReached because the API
- * can have more rows even when Search Console's own internal limits apply.
+ * Google's documented pagination contract treats a response shorter than the
+ * requested rowLimit as exhausted. An exactly full final page still requires
+ * a following empty-page probe unless the local safety ceiling is reached.
  */
 export async function querySearchAnalyticsPaginated(
   accessToken: string,
@@ -820,7 +819,7 @@ export async function querySearchAnalyticsPaginated(
 
     const acceptedRows = page.rows.slice(0, requestedRows);
     rows.push(...acceptedRows);
-    if (page.rows.length === 0) {
+    if (page.rows.length < requestedRows) {
       return { rows, pagesFetched, localLimitReached: false };
     }
     if (rows.length >= maximumRows || page.rows.length > requestedRows) {

package/src/index.ts

@@ -34,6 +34,7 @@ import {
   getIndexingNotificationMetadata,
   processPerformanceComparison,
   assertSearchAnalyticsFilterCompatible,
+  assertSearchAnalyticsQueryCompatible,
   type PaginatedSearchAnalyticsResult,
 } from './google';
 import {
@@ -1387,12 +1388,8 @@ class GscMcpRuntime {
         dimension_filter_groups,
       }) => {
         assertDateRange(start_date, end_date);
-        const googleId = this.requireGoogleId();
-        const rateLimitError = await this.rateLimitError(googleId, 'analytics.query');
-        if (rateLimitError) return rateLimitError;
-        const accessToken = await this.getAccessToken(googleId);
         const sourceRowLimit = Math.min(row_limit, MAX_DIRECT_SOURCE_ROWS);
-        const response = await querySearchAnalytics(accessToken, site_url, {
+        const query = {
           startDate: start_date,
           endDate: end_date,
           dimensions,
@@ -1404,12 +1401,17 @@ class GscMcpRuntime {
           ...(dimension_filter_groups !== undefined
             ? { dimensionFilterGroups: dimension_filter_groups }
             : {}),
-        });
-        // Search Analytics pagination is complete only after Google returns an
-        // explicit empty page. A short non-empty page can still be followed by
-        // later rows, so preserve a continuation for dimensioned queries.
+        };
+        assertSearchAnalyticsQueryCompatible(query);
+        const googleId = this.requireGoogleId();
+        const rateLimitError = await this.rateLimitError(googleId, 'analytics.query');
+        if (rateLimitError) return rateLimitError;
+        const accessToken = await this.getAccessToken(googleId);
+        const response = await querySearchAnalytics(accessToken, site_url, query);
+        // Google documents a short page as terminal. An exactly full page can
+        // still have a following page, so expose continuation only then.
         const sourceMayHaveMore =
-          dimensions.length > 0 && response.rows.length > 0;
+          dimensions.length > 0 && response.rows.length === sourceRowLimit;
         const bounded = windowSourceRows(
           response.rows,
           start_row,
@@ -1460,10 +1462,10 @@ class GscMcpRuntime {
       'insights.page_queries',
       {
         title: 'Find queries for a page',
-        description: 'For one exact page URL, return the Search Console queries that produced impressions for it over a date range. This wraps an exact page dimension filter so agents do not need to construct analytics.query filter groups manually. Exact page matching is case-sensitive in Search Console. Use row_limit and start_row to page through bounded results; Search Console can still omit anonymized queries. Google Discover and Google News are intentionally unavailable because those reports do not expose query data.',
+        description: 'For one exact page URL within the supplied Search Console property, return the queries that produced impressions for it over a date range. This wraps an exact page dimension filter so agents do not need to construct analytics.query filter groups manually. Exact page matching is case-sensitive in Search Console. Use row_limit and start_row to page through bounded results; Search Console can still omit anonymized queries. Google Discover and Google News are intentionally unavailable because those reports do not expose query data.',
         inputSchema: {
           site_url: SEARCH_CONSOLE_PROPERTY_SCHEMA,
-          page_url: z.string().url().describe('Exact fully-qualified page URL to filter on, e.g. https://example.com/guides/seo/. Search Console exact page filters are case-sensitive.'),
+          page_url: z.string().url().describe('Exact fully-qualified page URL to filter on, e.g. https://example.com/guides/seo/. The URL must belong to site_url; Search Console exact page filters are case-sensitive.'),
           start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe(
             searchConsoleDateDescription('Start date (inclusive) in YYYY-MM-DD format.'),
           ),
@@ -1495,6 +1497,7 @@ class GscMcpRuntime {
       },
       async ({ site_url, page_url, start_date, end_date, search_type, row_limit = 100, start_row = 0 }) => {
         assertDateRange(start_date, end_date);
+        assertUrlWithinSearchConsoleProperty(page_url, site_url, 'page_url');
         const googleId = this.requireGoogleId();
         const rateLimitError = await this.rateLimitError(googleId, 'insights.page_queries');
         if (rateLimitError) return rateLimitError;
@@ -1957,6 +1960,7 @@ class GscMcpRuntime {
         annotations: READ_ONLY_ANNOTATIONS,
       },
       async ({ site_url, url }) => {
+        assertUrlWithinSearchConsoleProperty(url, site_url);
         const googleId = this.requireGoogleId();
         const rateLimitError = await this.rateLimitError(googleId, 'indexing.status');
         if (rateLimitError) return rateLimitError;
@@ -2000,6 +2004,7 @@ class GscMcpRuntime {
         annotations: WRITE_TOOL_ANNOTATIONS['indexing.request'],
       },
       async ({ site_url, url }) => {
+        assertUrlWithinSearchConsoleProperty(url, site_url);
         const googleId = this.requireGoogleId();
         const rateLimitError = await this.rateLimitError(googleId, 'indexing.request');
         if (rateLimitError) return rateLimitError;
@@ -2041,6 +2046,7 @@ class GscMcpRuntime {
         annotations: WRITE_TOOL_ANNOTATIONS['indexing.remove'],
       },
       async ({ site_url, url }) => {
+        assertUrlWithinSearchConsoleProperty(url, site_url);
         const googleId = this.requireGoogleId();
         const rateLimitError = await this.rateLimitError(googleId, 'indexing.remove');
         if (rateLimitError) return rateLimitError;
@@ -2118,7 +2124,7 @@ class GscMcpRuntime {
           pages,
           start_row,
           row_limit,
-          response.rows.length > 0,
+          response.rows.length === sourceRowLimit,
           start_row + sourceRowLimit,
         );