@digestseo/mcp-gsc 0.4.27 → 0.4.29

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.29] - 2026-09-23
+
+### Fixed
+- `urls.inspect_many` now rejects exact duplicate URLs before reserving local safety-budget units or calling Google, preventing one batch from wasting URL Inspection quota on repeated identical requests.
+- `analytics.query` now rejects explicit `byPage` aggregation when the request also groups or filters by page, returning deterministic local guidance to use `auto` instead of forwarding a provider-invalid aggregation shape to Google.
+
+## [0.4.28] - 2026-09-23
+
+### Added
+- GitHub Copilot CLI users can now register this repository as the `digestseo` plugin marketplace, discover/install `mcp-gsc` through the marketplace workflow, and still use the supported direct-repository install path.
+- OpenAI Codex CLI and IDE users now have a verified one-command Streamable HTTP setup for the local `mcp-gsc` launcher.
+- MCP initialization now supplies concise server-level workflow instructions so compatible agents preserve Search Console pagination, evidence, and Indexing API semantics across tools.
+
+### Fixed
+- Search Analytics `quotaExceeded` load failures now return provider-specific recovery guidance instead of an opaque raw 403 payload, while remaining outside the short transient retry loop because Google's documented recovery window is measured in minutes rather than seconds.
+
 ## [0.4.27] - 2026-09-23
 
 ### Added

package/README.md

@@ -52,6 +52,14 @@ Self-hosted Cloudflare Worker deployments continue to use `https://<your-worker>
 claude mcp add --transport http gsc http://127.0.0.1:8080/mcp
 ```
 
+**OpenAI Codex CLI / IDE**
+
+```bash
+codex mcp add gsc --url http://127.0.0.1:8080/mcp
+```
+
+Codex CLI and the Codex IDE extension share MCP configuration, so registering the server once makes the same local connection available to both clients. Start the npm launcher before using the connection; Codex will open the server's OAuth flow when authentication is required.
+
 **Cursor**
 
 [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=gsc&config=eyJ1cmwiOiJodHRwOi8vMTI3LjAuMC4xOjgwODAvbWNwIn0%3D)
@@ -61,10 +69,11 @@ When this repository is installed as a Cursor plugin, Cursor also auto-discovers
 **GitHub Copilot CLI**
 
 ```bash
-copilot plugin install AKzar1el/mcp-gsc
+copilot plugin marketplace add AKzar1el/mcp-gsc
+copilot plugin install mcp-gsc@digestseo
 ```
 
-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.
+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.
 
 **Kiro**
 

package/package.json

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

package/src/google.ts

@@ -62,6 +62,19 @@ const GOOGLE_READ_MAX_ATTEMPTS = 3;
 const GOOGLE_READ_BASE_DELAY_MS = 1_000;
 const GOOGLE_READ_MAX_DELAY_MS = 5_000;
 
+function googleErrorReasonsFromText(text: string): string[] {
+  try {
+    const data = JSON.parse(text) as {
+      error?: { errors?: Array<{ reason?: unknown }> };
+    };
+    return (data.error?.errors ?? [])
+      .map((entry) => entry.reason)
+      .filter((reason): reason is string => typeof reason === 'string');
+  } catch {
+    return [];
+  }
+}
+
 async function isGoogleReadRetryableResponse(response: Response): Promise<boolean> {
   if (GOOGLE_READ_RETRYABLE_STATUSES.has(response.status)) return true;
   if (response.status !== 403) return false;
@@ -358,6 +371,12 @@ export function assertSearchAnalyticsQueryCompatible(body: SearchAnalyticsQuery)
     }
   }
 
+  if (body.aggregationType === 'byPage' && hasPageGroupingOrFilter) {
+    throw new Error(
+      'Search Analytics aggregationType byPage cannot be combined with page grouping or filtering; use auto instead.',
+    );
+  }
+
   if (body.aggregationType === 'byProperty') {
     if (hasPageGroupingOrFilter) {
       throw new Error(
@@ -645,6 +664,12 @@ export async function querySearchAnalytics(
   }
   if (!resp.ok) {
     const text = await resp.text();
+    const reasons = googleErrorReasonsFromText(text);
+    if (resp.status === 403 && reasons.includes('quotaExceeded')) {
+      throw new Error(
+        'Search Analytics load quota exceeded. Google recommends waiting about 15 minutes before retrying a short-term load-quota failure. If the error persists, reduce expensive page/query grouping or filtering, shorten the date range, and avoid repeatedly requesting the same data.',
+      );
+    }
     throw new Error(`Search analytics query failed: ${resp.status} ${text}`);
   }
   const data = (await resp.json()) as {

package/src/index.ts

@@ -111,6 +111,8 @@ export interface AgentProps extends Record<string, unknown> {
 
 const SERVER_NAME = 'mcp-gsc';
 const SERVER_VERSION = pkg.version;
+const SERVER_INSTRUCTIONS =
+  'If the exact Search Console site_url is unknown, call sites.list before property-scoped tools. Search Analytics can omit rows: page while has_more is true, and never treat a row missing from one bounded period as zero traffic. indexing.list_pages reports Search performance visibility, not index coverage; use urls.inspect or urls.inspect_many for indexed-state evidence. The Indexing API is restricted to eligible JobPosting/livestream pages; a receipt is not proof of indexing or removal.';
 
 const NOT_AUTHENTICATED_MESSAGE =
   `Not authenticated. ${MCP_RECONNECT_INSTRUCTION}`;
@@ -765,10 +767,15 @@ const TOOL_CATALOG = [
 ] as const;
 
 class GscMcpRuntime {
-  server = new McpServer({
-    name: SERVER_NAME,
-    version: SERVER_VERSION,
-  });
+  server = new McpServer(
+    {
+      name: SERVER_NAME,
+      version: SERVER_VERSION,
+    },
+    {
+      instructions: SERVER_INSTRUCTIONS,
+    },
+  );
 
   constructor(
     private readonly env: Env,
@@ -980,8 +987,11 @@ class GscMcpRuntime {
             .array(z.string().url())
             .min(1)
             .max(10)
+            .refine((urls) => new Set(urls).size === urls.length, {
+              message: 'inspection_urls must not contain duplicate URLs.',
+            })
             .describe(
-              'Between 1 and 10 fully-qualified URLs to inspect. Each URL must belong to the site_url property.',
+              'Between 1 and 10 unique fully-qualified URLs to inspect. Each URL must belong to the site_url property.',
             ),
           language_code: z
             .string()
@@ -1209,7 +1219,7 @@ class GscMcpRuntime {
             .enum(['auto', 'byNewsShowcasePanel', 'byPage', 'byProperty'])
             .default('auto')
             .describe(
-              "How Google aggregates metrics. Leave as 'auto' unless specific semantics are needed. 'byProperty' cannot be used with page grouping/filtering or search_type discover/googleNews. 'byNewsShowcasePanel' requires search_type discover/googleNews plus a searchAppearance equals NEWS_SHOWCASE filter, and cannot be combined with page grouping/filtering or another searchAppearance filter.",
+              "How Google aggregates metrics. Leave as 'auto' unless specific semantics are needed. When grouping/filtering by page, use 'auto'; explicit 'byPage' and 'byProperty' are rejected for that request shape. 'byProperty' is also unavailable for search_type discover/googleNews. 'byNewsShowcasePanel' requires search_type discover/googleNews plus a searchAppearance equals NEWS_SHOWCASE filter, and cannot be combined with page grouping/filtering or another searchAppearance filter.",
             ),
           dimension_filter_groups: z
             .array(