@digestseo/mcp-gsc 0.4.27 → 0.4.28

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.28",
   "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;
@@ -645,6 +658,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,