gogcli-mcp 2.8.0 → 2.18.1

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "2.8.0",
+  "version": "2.18.1",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",
@@ -56,10 +56,34 @@
     }
   },
   "tools": [
+    {
+      "name": "gog_api_list",
+      "description": "List the Google Discovery APIs available for generic api calls."
+    },
+    {
+      "name": "gog_api_describe",
+      "description": "Describe a Google Discovery API or one of its methods (params, schema, scopes)."
+    },
+    {
+      "name": "gog_api_call",
+      "description": "Call any Discovery-described Google API method (escape hatch; write opt-in + dry-run)."
+    },
     {
       "name": "gog_auth_add",
       "description": "Authorize a Google account via browser-based OAuth"
     },
+    {
+      "name": "gog_auth_health",
+      "description": "Live per-account token health: validity, age, and pre-expiry warnings (detects invalid_grant)"
+    },
+    {
+      "name": "gog_auth_add_url",
+      "description": "Begin remote/headless OAuth (step 1): return a sign-in URL to open in any browser"
+    },
+    {
+      "name": "gog_auth_add_complete",
+      "description": "Complete remote/headless OAuth (step 2): exchange the pasted redirect URL and store the token"
+    },
     {
       "name": "gog_auth_list",
       "description": "List all Google accounts stored in gogcli"
@@ -228,6 +252,14 @@
       "name": "gog_drive_search",
       "description": "Search Google Drive files"
     },
+    {
+      "name": "gog_drive_extract_text",
+      "description": "Extract readable text from a Drive PDF/image/doc (OCR-converts, returns text; no host FS)"
+    },
+    {
+      "name": "gog_drive_read_bytes",
+      "description": "Fetch a Drive file's raw bytes as a base64 resource (local stdio only; connector returns text-only notice)"
+    },
     {
       "name": "gog_drive_get",
       "description": "Get Google Drive file metadata"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp",
-  "version": "2.8.0",
+  "version": "2.18.1",
   "mcpName": "io.github.chrischall/gogcli-mcp",
   "description": "MCP server wrapping gogcli for Google service access",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -36,19 +36,20 @@
     "build": "tsc --noEmit && npm run bundle",
     "bundle": "node ../../scripts/bundle.js src/index.ts dist/index.js && node ../../scripts/bundle.js src/lib.ts dist/lib.js",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "vitest run --coverage",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
+    "@chrischall/mcp-utils": "^0.13.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.2",
+    "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "^4.1.8",
-    "esbuild": "^0.28.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.8"
+    "esbuild": "^0.28.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   }
 }

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp"
   },
-  "version": "2.8.0",
+  "version": "2.18.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp",
-      "version": "2.8.0",
+      "version": "2.18.1",
       "transport": {
         "type": "stdio"
       },

package/src/connector-auth.ts

@@ -0,0 +1,46 @@
+import type { ConnectorAuth } from '@chrischall/mcp-connector';
+
+/**
+ * OAuth props stored per user by the Cloudflare connector's OAuth provider.
+ *
+ * The gogcli remote connector authenticates each user with a single long-lived
+ * personal "connector key" — a shared secret (the Fly backend's `RUNNER_KEY`)
+ * that authorizes calls to that user's own `gog` backend on Fly.io. There is no
+ * refresh cycle: `worker.ts`'s `buildClient` turns this key straight into a
+ * per-session Fly executor. These props are encrypted at rest in `OAUTH_KV` by
+ * the OAuth provider.
+ *
+ * NOTE: this is a FIELD LOGIN (a personal key), NOT Google OAuth. The Google
+ * OAuth handshake lives entirely inside the Fly backend's `gog` install; the
+ * connector never sees a Google token.
+ *
+ * The index signature satisfies `createConnector`'s
+ * `Props extends Record<string, unknown>` constraint.
+ */
+export interface GogProps {
+  key: string;
+  [k: string]: unknown;
+}
+
+/**
+ * `ConnectorAuth` for the gogcli remote connector: the login page collects the
+ * user's connector key, verifies it by hitting the Fly backend's `/health`
+ * endpoint with the key as a bearer token (a bad key makes the backend answer
+ * non-2xx, which surfaces back on the login page), and stores `{ key }` as the
+ * OAuth props that `worker.ts`'s `buildClient` turns into a per-session Fly
+ * executor.
+ */
+export const gogAuth: ConnectorAuth<GogProps> = {
+  service: 'gogcli (Google Workspace)',
+  accent: '#4285F4',
+  privacyNote:
+    'Your connector key is stored encrypted and used only to reach your own gog backend.',
+  fields: [{ name: 'key', label: 'gogcli connector key', type: 'password' }],
+  async login(fields, env) {
+    const res = await fetch(`${(env as any).FLY_ENDPOINT}/health`, {
+      headers: { Authorization: `Bearer ${fields.key}` },
+    });
+    if (!res.ok) throw new Error('Invalid connector key (backend rejected it)');
+    return { key: fields.key };
+  },
+};

package/src/connector-runtime.ts

@@ -0,0 +1,177 @@
+import { runExecutor } from './runner.js';
+import type { GogArg, GogExecutor } from './runner.js';
+
+// Runtime helpers for the Cloudflare connector (worker.ts), split out here so
+// they can be unit-tested under the node pool — worker.ts itself imports the
+// Worker-only `@chrischall/mcp-connector`/`agents` runtime and cannot load in
+// node. These helpers touch only the `runExecutor` seam and global `fetch`.
+
+// Mirrors runner.ts's TIMEOUT_MS: the budget the stdio path gives a `gog` call
+// before it kills the child. Duplicated rather than imported to keep this module
+// free of the spawn-side surface.
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+// Headroom on top of the backend's own budget. The Fly runner kills `gog` and
+// returns a real error; we only want the client deadline to fire when the
+// backend cannot answer at all (scale-to-zero cold start that never wakes, or a
+// wedged machine). Firing first would turn a useful "gog exited 1" into an
+// opaque timeout.
+//
+// This grace is deliberately NOT widened for GogFileArg payloads. The deadline
+// now covers a request body that carries the payload inline, so upload happens
+// before `gog` starts — but the payloads that take this path are text (a mail
+// body, slide notes), bounded by the MCP request that carried them, and the hop
+// is Cloudflare edge → Fly datacenter, so upload is milliseconds, not seconds.
+// Widening the grace would weaken the property this constant exists to protect:
+// the backend must lose the race only when it genuinely cannot answer, and every
+// extra second is a second of an opaque client timeout replacing a real error.
+// If a payload class ever appears that does NOT upload in well under 5s, the fix
+// is to raise the caller's `opts.timeout` (which this deadline tracks) rather
+// than to inflate the grace, so the runner still gets to answer first.
+const DEADLINE_GRACE_MS = 5_000;
+
+// Status codes the Fly runner uses to classify its OWN failures. These must stay
+// in sync with fly-gog-runner/server.mjs — they are the contract that lets this
+// side tell "gog ran and failed" apart from "the request never arrived", without
+// having to guess from the response body.
+//
+// 422: `gog` executed and exited non-zero. Deterministic — never retry.
+// 503: the runner is draining (SIGINT from Fly's autostop). Transient — retry.
+// Any other non-2xx: infrastructure, i.e. Fly's edge, not us.
+const RUNNER_GOG_FAILED = 422;
+const RUNNER_DRAINING = 503;
+
+// Build a GogExecutor that forwards a fully-assembled `gog` arg-array to the Fly
+// backend's `/run` endpoint.
+//
+// The backend (and the `gog` process it spawns) own timeout/interactive
+// behaviour, so `opts` does not change what the backend does — but `timeout`
+// still has to be honoured HERE as a client-side deadline. Workers' `fetch` has
+// no default timeout, and the stdio path's kill lives in a child process this
+// path never spawns, so without an explicit signal a cold or wedged backend
+// hangs the MCP request indefinitely with nothing to interrupt it.
+//
+// GogFileArg elements pass through STRUCTURED, as objects inside the JSON body.
+// Every other executor materializes them to a temp file itself; this one cannot
+// and must not. A Worker has no filesystem and does not host the `gog` binary,
+// so there is nowhere to put a file that the process which needs it could read.
+// The Fly runner is the only box with both, so it owns materialization — this
+// layer's whole job is to hand the elements over unaltered, in order. Anything
+// clever here (flattening to `--flag=<inline>`, truncating, re-encoding) would
+// put the payload straight back into argv and re-create the size cap this whole
+// change exists to escape.
+export function makeFlyExecutor(endpoint: string, key: string): GogExecutor {
+  return async (args: GogArg[], opts) => {
+    const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
+    let res: Response;
+    try {
+      res = await fetch(endpoint + '/run', {
+        method: 'POST',
+        headers: {
+          Authorization: 'Bearer ' + key,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ args }),
+        signal: AbortSignal.timeout(deadlineMs),
+      });
+    } catch (err) {
+      // AbortSignal.timeout rejects with a TimeoutError; a caller-supplied abort
+      // surfaces as AbortError. Either way the bare message ("The operation was
+      // aborted") says nothing about which backend failed to answer.
+      const name = err instanceof Error ? err.name : '';
+      if (name === 'TimeoutError' || name === 'AbortError') {
+        throw new Error(
+          `gog-runner did not respond within ${deadlineMs}ms (${endpoint}) — the Fly backend may be cold or wedged`,
+        );
+      }
+      throw err;
+    }
+    if (!res.ok) {
+      // Two very different failures arrive as non-2xx, and collapsing them (as
+      // this used to) is what made a real bug look like random flakiness:
+      //
+      //  a) The runner answered with its own JSON — `gog` actually ran on the
+      //     box and failed. Deterministic: the same call will fail the same way.
+      //  b) The body is NOT the runner's JSON (Fly's HTML error page, or empty).
+      //     Then the request never reached `gog` at all; Fly's edge proxy is
+      //     reporting that it could not reach the Machine — typically because
+      //     the Machine was starting from scale-to-zero, or was mid-shutdown.
+      //     Genuinely transient, and the only case worth retrying.
+      const body = (await res.json().catch(() => null)) as
+        | { error?: string; stderr?: string; retryable?: boolean }
+        | null;
+      const detail =
+        body && typeof body.error === 'string'
+          ? body.stderr && body.stderr.trim() && body.stderr.trim() !== body.error.trim()
+            ? `${body.error}\n${body.stderr}`
+            : body.error
+          : '';
+
+      // 422 is the runner's "gog ran and exited non-zero" status. It is only
+      // ever produced by our own handler, so reaching here proves the request
+      // was delivered and executed. Deterministic — say so, and say nothing
+      // that invites a retry.
+      if (res.status === RUNNER_GOG_FAILED) {
+        throw new Error(detail || 'gog failed on the runner (no detail supplied)');
+      }
+
+      // The runner's drain response: it is up, but deliberately refusing new
+      // work while it shuts down. The one runner-authored failure worth retrying.
+      if (res.status === RUNNER_DRAINING || body?.retryable === true) {
+        throw new Error(
+          `gog-runner is restarting; retry this call.${detail ? ` ${detail}` : ''}`,
+        );
+      }
+
+      // Anything else non-2xx is infrastructure: Fly's edge could not reach the
+      // Machine, or the Machine answered with something that is not ours. Only
+      // claim the request never arrived when there is genuinely no runner body
+      // — a runner that did answer deserves to have its own words repeated.
+      //
+      // The status is deliberately NOT interpolated here. A runner body proves
+      // gog ran, so this is a deterministic failure; embedding the literal
+      // status would put "502" into the message, which matches
+      // TRANSIENT_ERROR_PATTERN (/\b5\d\d\b/) in tools/utils.ts and re-attaches
+      // the very "this is transient, retry the same call" hint this change
+      // exists to remove — reintroducing the bug during the rollout window this
+      // branch exists to cover. Anything genuinely transient in gog's own text
+      // (a Google 5xx, say) still matches on its own merits, which is correct.
+      if (detail) {
+        throw new Error(detail);
+      }
+      throw new Error(
+        `gog-runner HTTP ${res.status}: the response did not come from the runner, ` +
+        'so the request never reached gog. The backend Machine was most likely starting ' +
+        'or shutting down — this is transient, retry the same call.',
+      );
+    }
+    const { stdout } = (await res.json()) as { stdout: string };
+    return stdout;
+  };
+}
+
+// Wrap an McpServer in a Proxy whose `registerTool` (and `tool`, if any
+// registrar uses it) intercepts the tool handler so it runs inside the
+// `runExecutor` ALS scope. This is the crux of the connector: it lets the
+// UNCHANGED base registrars forward every `gog` call to the per-session Fly
+// executor without any change to the registrars or `runner.ts` — when a
+// handler's `run()` looks up `runExecutor.getStore()` it finds `executor` and
+// forwards instead of spawning. Everything else proxies through via Reflect.
+export function wrapServer<T extends object>(server: T, executor: GogExecutor): T {
+  return new Proxy(server, {
+    get(target, prop, receiver) {
+      if (prop === 'registerTool' || prop === 'tool') {
+        const orig = (target as Record<string | symbol, (...a: unknown[]) => unknown>)[prop].bind(target);
+        return (...args: unknown[]) => {
+          const handler = args[args.length - 1];
+          if (typeof handler === 'function') {
+            args[args.length - 1] = (...h: unknown[]) =>
+              runExecutor.run({ executor }, () => (handler as (...a: unknown[]) => unknown)(...h));
+          }
+          return orig(...args);
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+}

package/src/index.ts

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createBaseServer } from './server.js';
+import { runMcp } from '@chrischall/mcp-utils';
+import { BASE_TOOL_REGISTRARS, VERSION } from './server.js';
 
-const server = createBaseServer();
-const transport = new StdioServerTransport();
-await server.connect(transport);
+await runMcp({
+  name: 'gogcli',
+  version: VERSION,
+  tools: BASE_TOOL_REGISTRARS,
+});

package/src/lib.ts

@@ -1,8 +1,9 @@
 export {
-  createServer,
-  createBaseServer,
+  BASE_TOOL_REGISTRARS,
   VERSION,
+  registerApiTools,
   registerAuthTools,
+  authToolsFor,
   registerCalendarTools,
   registerClassroomTools,
   registerContactsTools,
@@ -13,17 +14,17 @@ export {
   registerSlidesTools,
   registerTasksTools,
 } from './server.js';
-export { run, MIN_GOG_VERSION } from './runner.js';
-export type { RunOptions, Spawner } from './runner.js';
+export { run, runBinary, runExecutor, isGogFileArg, MIN_GOG_VERSION } from './runner.js';
+export type { RunOptions, Spawner, GogExecutor, GogArg, GogFileArg } from './runner.js';
 export {
+  PAYLOAD_INLINE_MAX,
+  payloadArg,
   accountParam,
   runOrDiagnose,
   diagnose,
-  toText,
-  toError,
+  errorText,
   ids,
   paginationParams,
   pushPaginationFlags,
   registerRunTool,
 } from './tools/utils.js';
-export type { ToolResult } from './tools/utils.js';