gogcli-mcp 2.21.1 → 2.22.0

package/src/tools/auth.ts

@@ -31,7 +31,10 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
   });
 
   server.registerTool('gog_auth_status', {
-    description: 'Show gogcli auth configuration: keyring backend, credential files, and auth setup.',
+    description:
+      'Show gogcli auth CONFIGURATION: keyring backend, credential files, and auth setup. Despite the ' +
+      'name this is not a health check — it reads local setup and does not contact Google, so it says ' +
+      'nothing about whether an account can still authenticate. Use gog_auth_health for that.',
     annotations: { readOnlyHint: true },
     inputSchema: {},
   }, async () => {
@@ -50,7 +53,10 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
       'service. Reports per account: whether the token is currently valid, the mapped cause when it is ' +
       'not, how long ago it was authorized, and a warning as it approaches the 7-day refresh-token limit ' +
       'that applies to OAuth apps whose consent screen is still in "Testing" mode. Run it proactively to ' +
-      're-authorize on your own schedule instead of mid-task.',
+      're-authorize on your own schedule instead of mid-task. On the hosted connector this is the ONLY ' +
+      'check that measures Google: a connector showing "connected" or "refreshed" has verified the ' +
+      'connector key that reaches the gog machine, and nothing else — the Google credential lives on ' +
+      'that machine and can be dead while the connection looks perfectly healthy.',
     annotations: { readOnlyHint: true },
     inputSchema: {},
   }, async () => {

package/src/worker.ts

@@ -16,7 +16,7 @@ import { registerExtraGmailTools } from '../../gogcli-mcp-gmail/src/tools/gmail-
 import { registerExtraDriveTools } from '../../gogcli-mcp-drive/src/tools/drive-extra.js';
 import { registerExtraDocsTools } from '../../gogcli-mcp-docs/src/tools/docs-extra.js';
 import { makeFlyExecutor, wrapServer } from './connector-runtime.js';
-import { gogAuth, type GogProps } from './connector-auth.js';
+import { gogAuth, CONNECTOR_INSTRUCTIONS, type GogProps } from './connector-auth.js';
 
 // The Cloudflare remote-connector entrypoint for gogcli-mcp.
 //
@@ -38,7 +38,7 @@ import { gogAuth, type GogProps } from './connector-auth.js';
 // connector with all ~360 tools at once. Add whichever paths you want as separate
 // connectors in claude.ai (each authorizes with the same connector key).
 
-const VERSION = '2.21.1'; // x-release-please-version
+const VERSION = '2.22.0'; // x-release-please-version
 
 // Build an McpAgent subclass whose init() registers `registrars` onto its server,
 // each handler wrapped in the ALS scope carrying the per-session Fly executor.
@@ -46,7 +46,14 @@ const VERSION = '2.21.1'; // x-release-please-version
 // `agents` runtime; the node-testable helpers stay in connector-runtime.ts.)
 function makeAgent(registrars: ToolRegistrar[]): typeof McpAgent {
   class GogAgent extends McpAgent<unknown, unknown, GogProps> {
-    server = new McpServer({ name: 'gogcli-mcp', version: VERSION });
+    // `instructions` is the connector's only channel to the model that is not a
+    // tool description, and it carries the one thing the client UI gets wrong:
+    // "connected"/"refreshed" is a statement about the connector key, not about
+    // Google. See CONNECTOR_INSTRUCTIONS for why that has to be said out loud.
+    server = new McpServer(
+      { name: 'gogcli-mcp', version: VERSION },
+      { instructions: CONNECTOR_INSTRUCTIONS },
+    );
     async init() {
       // NO third argument, deliberately: the hosted connector supplies no
       // per-caller access token, so `gog` runs as the Fly volume's own identity
@@ -56,9 +63,21 @@ function makeAgent(registrars: ToolRegistrar[]): typeof McpAgent {
       // 401 on this path stops at the `no access token was supplied` guard and
       // logs `replay.declined`. That record is the expected outcome for a
       // hosted connector, not a bug; the transport-failure classification and
-      // the auth log itself do apply here. (docs/DEPLOY-CONNECTOR.md,
-      // "Reading the auth log", says the same thing for whoever is reading logs
-      // rather than code.)
+      // the auth log itself do apply here.
+      //
+      // Inert is not the same as unobserved. Because `gog` is spawned fresh per
+      // /run and re-reads the keyring each time, a Google 401 here means the
+      // STORED credential was refused — which no retry can repair, so no retry
+      // is built. Instead that same guard first takes one live reading of the
+      // Google layer (`GET /health/google` on the runner) and records it as
+      // `refusal.google-ok` / `-unhealthy` / `-unmeasured`. It is throttled,
+      // deadline-bounded, cannot throw, and leaves the caller's error
+      // byte-identical; its whole job is to answer, in the log, the question
+      // that could not be answered after the incident: at the moment Google
+      // refused, was the refresh token on the volume alive or dead?
+      // (docs/DEPLOY-CONNECTOR.md, "Reading the auth log" and "Why a hosted
+      // Google 401 is measured rather than retried", says this for whoever is
+      // reading logs rather than code.)
       const executor = makeFlyExecutor((this.env as { FLY_ENDPOINT: string }).FLY_ENDPOINT, this.props.key);
       const wrapped = wrapServer(this.server, executor);
       for (const register of registrars) register(wrapped);

package/tests/auth-log.test.ts

@@ -129,6 +129,20 @@ describe('logAuthTransition', () => {
     expect(log.emitted.map((e) => e.method)).toEqual(['warn', 'error']);
   });
 
+  it('separates a MEASURED dead Google layer from one nobody could measure', () => {
+    // The connect-time probe has three honest answers, and conflating the last
+    // two is exactly the defect it exists to remove: "I asked Google and it said
+    // no" is a failure, while "I could not ask" is not evidence of anything.
+    const log = captureLog();
+    logAuthTransition('connect.google-ok', { endpoint: 'https://runner.example' });
+    logAuthTransition('connect.google-unhealthy', { endpoint: 'https://runner.example', reason: 'invalid_grant' });
+    logAuthTransition('connect.google-unmeasured', { endpoint: 'https://runner.example', reason: 'HTTP 404' });
+
+    expect(log.events()).toEqual(['connect.google-ok', 'connect.google-unhealthy', 'connect.google-unmeasured']);
+    expect(log.emitted.map((e) => e.method)).toEqual(['warn', 'error', 'warn']);
+    expect(log.toStdout).toEqual([]);
+  });
+
   it('omits absent context rather than writing nulls', () => {
     const log = captureLog();
     logAuthTransition('token.evicted', { credential: 'abc' });
@@ -370,8 +384,16 @@ describe('connector-runtime records the transitions the runner path authors', ()
       vi.stubGlobal('fetch', vi.fn(async () => gogFailed(stderr)));
       const log = captureLog();
       await expect(invoke()).rejects.toThrow();
-      expect(log.emitted, name).toHaveLength(1);
-      const [record] = log.records();
+      // The 'no token' case — the HOSTED shape — now writes a second record
+      // BEFORE its decision: the live reading of the Google layer this branch
+      // added, which here reports `refusal.google-unmeasured` because the stub
+      // answers /health/google with the same non-2xx it answers /run with. The
+      // decision is still the LAST word in every case, which is what this test
+      // is about.
+      const records = log.records();
+      expect(records.length, name).toBe(name === 'no token' ? 2 : 1);
+      if (name === 'no token') expect(records[0].event).toBe('refusal.google-unmeasured');
+      const record = records[records.length - 1];
       expect(record.event, name).toBe(name === 'invalid_grant' ? 'grant.dead' : 'replay.declined');
       expect(record.reason as string, name).toMatch(expected);
     }