@digestseo/mcp-gsc 0.4.17 → 0.4.19

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.19] - 2026-09-22
+
+### Fixed
+- Search Analytics freshness metadata now normalizes Google's camelCase `firstIncompleteDate` / `firstIncompleteHour` wire fields into the stable MCP `first_incomplete_date` / `first_incomplete_hour` response contract.
+- The npm launcher now exits deterministically after its Wrangler child terminates by signal instead of re-signalling itself while its own `SIGINT`/`SIGTERM` listeners are installed, preventing wrapper processes from lingering after Ctrl+C or supervisor shutdown on POSIX systems.
+- ChatGPT local-launcher guidance now explicitly requires Secure MCP Tunnel for the loopback `127.0.0.1` endpoint, or a separately deployed remote Worker, instead of implying that ChatGPT can connect directly to localhost.
+
+## [0.4.18] - 2026-09-22
+
+### Fixed
+- The published npm launcher now keeps `GOOGLE_CLIENT_SECRET` and `TOKEN_ENCRYPTION_KEY` out of Wrangler `--var` command-line arguments; Wrangler loads those declared local secrets directly from the child process environment instead.
+- `server.capabilities` now distinguishes stored local Google credentials from live provider authorization, exposing the credential-state basis and explicitly reporting that the discovery call does not probe Google before claiming a connection is usable.
+
 ## [0.4.17] - 2026-09-22
 
 ### Added

package/README.md

@@ -22,7 +22,7 @@ The self-hosting launcher is available as [`@digestseo/mcp-gsc`](https://www.npm
 npx -y @digestseo/mcp-gsc
 ```
 
-The npm launcher starts a loopback-only **Streamable HTTP** Worker on `127.0.0.1` (port `8080` by default); it is not a stdio MCP process. You can run the `npx` command from any directory because the launcher resolves its bundled Worker configuration from the installed package. Clients that launch the package should connect to `http://127.0.0.1:8080/mcp` after supplying the Google OAuth and token-encryption environment variables described in [SETUP.md](SETUP.md). Before the first OAuth sign-in, authorize the exact callback `http://127.0.0.1:8080/google/callback` in Google Cloud (or use the same custom `PORT` you launch with); the launcher prints both URLs at startup.
+The npm launcher starts a loopback-only **Streamable HTTP** Worker on `127.0.0.1` (port `8080` by default); it is not a stdio MCP process. You can run the `npx` command from any directory because the launcher resolves its bundled Worker configuration from the installed package. Clients that launch the package should connect to `http://127.0.0.1:8080/mcp` after supplying the Google OAuth and token-encryption environment variables described in [SETUP.md](SETUP.md). The launcher keeps `GOOGLE_CLIENT_SECRET` and `TOKEN_ENCRYPTION_KEY` in the child process environment and Wrangler loads them through declared local secrets; their values are not copied into Wrangler `--var` command-line arguments. Before the first OAuth sign-in, authorize the exact callback `http://127.0.0.1:8080/google/callback` in Google Cloud (or use the same custom `PORT` you launch with); the launcher prints both URLs at startup.
 
 Local KV and Durable Object state, including the encrypted Google session, is stored in `~/.mcp-gsc/state` by default instead of inside the versioned npm cache. That keeps the local connection available across package upgrades and ordinary npm cache cleanup. Set `MCP_GSC_STATE_DIR` to use another directory; keep the same `TOKEN_ENCRYPTION_KEY` when reusing existing state because stored refresh tokens are encrypted with that key. The launcher prints the effective state directory at startup. The first release with this stable path may require one Google reconnect because older launcher releases stored local state under the npm package cache.
 
@@ -62,7 +62,7 @@ claude mcp add --transport http gsc http://127.0.0.1:8080/mcp
 
 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.
+**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.
 
 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.
 
@@ -76,7 +76,7 @@ By default (`GSC_ACCESS_MODE=readwrite`), this server exposes 22 tools. Read-onl
 
 | Tool | Access | What it does |
 |---|---|---|
-| **`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. |
+| **`server.capabilities`** | Read | List every tool this server exposes and report local Google credential state. `connected` means a stored refresh credential is present; the response also exposes `auth_status_basis` and `provider_auth_live_verified: false` because this discovery call does not probe Google. A later Google tool call can still require reconnection if the credential expired or was revoked. Takes no arguments. |
 | **`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. `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`. |

package/SETUP.md

@@ -112,7 +112,7 @@ openssl rand -base64 32
 
 Paste that value when prompted. Keep it safe — if you lose it, the refresh tokens already in KV become undecryptable and every user has to reconnect.
 
-For **local development**, put the same three values in `.dev.vars` instead — copy `.dev.vars.example` to `.dev.vars` (it's gitignored):
+For **local development**, put the same three values in `.dev.vars` instead — copy `.dev.vars.example` to `.dev.vars` (it's gitignored). The published npm launcher can also read them from the process environment; its bundled Wrangler config declares `GOOGLE_CLIENT_SECRET` and `TOKEN_ENCRYPTION_KEY` as required local secrets so those sensitive values do not need to be serialized into `--var` command-line arguments:
 
 ```
 GOOGLE_CLIENT_ID=...

package/package.json

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

package/scripts/glama-start.mjs

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { homedir } from 'node:os';
+import { constants, homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -16,8 +16,6 @@ const stateDir = process.env.MCP_GSC_STATE_DIR
   : resolve(homedir(), '.mcp-gsc', 'state');
 const forwardedVariables = [
   'GOOGLE_CLIENT_ID',
-  'GOOGLE_CLIENT_SECRET',
-  'TOKEN_ENCRYPTION_KEY',
   'GSC_ACCESS_MODE',
   'GLAMA_INSPECTION_MODE',
 ];
@@ -53,7 +51,8 @@ process.on('SIGTERM', () => forwardSignal('SIGTERM'));
 
 child.on('exit', (code, signal) => {
   if (signal) {
-    process.kill(process.pid, signal);
+    const signalNumber = constants.signals[signal];
+    process.exit(signalNumber === undefined ? 1 : 128 + signalNumber);
   } else {
     process.exit(code ?? 1);
   }

package/src/google.ts

@@ -407,6 +407,11 @@ export interface SearchAnalyticsResponseMetadata {
   first_incomplete_hour?: string;
 }
 
+interface GoogleSearchAnalyticsResponseMetadata {
+  firstIncompleteDate?: string;
+  firstIncompleteHour?: string;
+}
+
 export interface SearchAnalyticsResponse {
   rows: SearchAnalyticsRow[];
   responseAggregationType?: string;
@@ -610,14 +615,25 @@ export async function querySearchAnalytics(
   const data = (await resp.json()) as {
     rows?: SearchAnalyticsRow[];
     responseAggregationType?: string;
-    metadata?: SearchAnalyticsResponseMetadata;
+    metadata?: GoogleSearchAnalyticsResponseMetadata;
   };
+  const metadata: SearchAnalyticsResponseMetadata | undefined =
+    data.metadata === undefined
+      ? undefined
+      : {
+          ...(data.metadata.firstIncompleteDate !== undefined
+            ? { first_incomplete_date: data.metadata.firstIncompleteDate }
+            : {}),
+          ...(data.metadata.firstIncompleteHour !== undefined
+            ? { first_incomplete_hour: data.metadata.firstIncompleteHour }
+            : {}),
+        };
   return {
     rows: data.rows ?? [],
     ...(data.responseAggregationType !== undefined
       ? { responseAggregationType: data.responseAggregationType }
       : {}),
-    ...(data.metadata !== undefined ? { metadata: data.metadata } : {}),
+    ...(metadata !== undefined ? { metadata } : {}),
   };
 }
 

package/src/index.ts

@@ -191,7 +191,18 @@ const CAPABILITIES_OUTPUT_SCHEMA = {
   server: z.string(),
   version: z.string(),
   access_mode: z.enum(['readonly', 'readwrite']),
-  auth_status: z.enum(['connected', 'not_connected', 'unknown']),
+  auth_status: z.enum(['connected', 'not_connected', 'unknown']).describe(
+    "Local credential state: 'connected' means a stored Google refresh credential is present; it does not live-verify that Google still accepts it.",
+  ),
+  auth_status_basis: z.enum([
+    'stored_refresh_token',
+    'no_stored_refresh_token',
+    'local_state_unavailable',
+  ]),
+  provider_auth_live_verified: z.literal(false).describe(
+    'Always false because server.capabilities does not make a Google token or API request merely to probe authorization.',
+  ),
+  auth_note: z.string(),
   tools: z.array(
     z.object({
       name: z.string(),
@@ -719,7 +730,7 @@ const TOOL_CATALOG = [
   {
     name: 'server.capabilities',
     description:
-      "List every tool this server exposes and report whether the user's Google Search Console connection is currently authenticated.",
+      "List every tool this server exposes and report local Google credential state. A connected status means a stored refresh credential is present; it is not a live Google authorization check.",
   },
 ] as const;
 
@@ -776,32 +787,49 @@ class GscMcpRuntime {
       {
         title: 'Get server capabilities and auth status',
         description:
-          "List every tool this server exposes, its configured access mode, and whether the user's Google Search Console connection is currently authenticated. Call this first if you're unsure what tools are available, whether the deployment is read-only, or whether the user is connected. Returns the tool catalog plus an access mode and auth status. Takes no arguments.",
+          "List every tool this server exposes, its configured access mode, and local Google credential state. Call this first if you're unsure what tools are available, whether the deployment is read-only, or whether stored Google credentials are configured. auth_status='connected' means a stored refresh credential is present; this tool does not make a Google token/API request and therefore does not live-verify that Google still accepts it. Takes no arguments.",
         inputSchema: {},
         outputSchema: CAPABILITIES_OUTPUT_SCHEMA,
         annotations: READ_ONLY_ANNOTATIONS,
       },
       async () => {
         let authStatus: 'connected' | 'not_connected' | 'unknown';
+        let authStatusBasis:
+          | 'stored_refresh_token'
+          | 'no_stored_refresh_token'
+          | 'local_state_unavailable';
         try {
           const googleId = this.props?.google_id;
           if (!googleId) {
             authStatus = 'not_connected';
+            authStatusBasis = 'no_stored_refresh_token';
           } else {
             const refreshToken = await getDecryptedRefreshToken(
               this.env,
               googleId,
             );
             authStatus = refreshToken ? 'connected' : 'not_connected';
+            authStatusBasis = refreshToken
+              ? 'stored_refresh_token'
+              : 'no_stored_refresh_token';
           }
         } catch {
           authStatus = 'unknown';
+          authStatusBasis = 'local_state_unavailable';
         }
+        const authNote = authStatus === 'connected'
+          ? "Stored Google refresh credentials are present, but server.capabilities does not live-verify them with Google. Refresh tokens can expire or be revoked; a Google tool call may still require reconnection."
+          : authStatus === 'not_connected'
+            ? 'No stored Google refresh credential is available. Reconnect this server in your MCP client to sign in with Google.'
+            : 'Local Google credential state could not be read. Provider authorization was not checked.';
         const capabilities = {
           server: SERVER_NAME,
           version: SERVER_VERSION,
           access_mode: accessMode,
           auth_status: authStatus,
+          auth_status_basis: authStatusBasis,
+          provider_auth_live_verified: false as const,
+          auth_note: authNote,
           tools: getToolCatalogForAccessMode(TOOL_CATALOG, accessMode),
           provider_limits: {
             generative_ai_performance_report: {
@@ -809,7 +837,9 @@ class GscMcpRuntime {
               note: GENERATIVE_AI_REPORT_API_NOTE,
             },
           },
-          hint: "If auth_status is not 'connected', the user should reconnect this server in their MCP client to sign in with Google.",
+          hint: authStatus === 'connected'
+            ? 'Stored Google credentials are configured. If a Google tool later reports revoked access, reconnect this server in your MCP client.'
+            : 'Reconnect this server in your MCP client to sign in with Google.',
         };
         return toolResponse(JSON.stringify(capabilities, null, 2), capabilities);
       },

package/wrangler.example.jsonc

@@ -8,6 +8,9 @@
   "compatibility_date": "2026-05-19",
   "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
   "observability": { "enabled": true },
+  "secrets": {
+    "required": ["GOOGLE_CLIENT_SECRET", "TOKEN_ENCRYPTION_KEY"]
+  },
   "vars": {
     "GSC_ACCESS_MODE": "readwrite"
   },