gogcli-mcp 2.18.4 → 2.19.1

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
-    "version": "2.18.4"
+    "version": "2.19.1"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli",
       "source": "./",
       "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
-      "version": "2.18.4",
+      "version": "2.19.1",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp",
   "displayName": "gogcli",
-  "version": "2.18.4",
+  "version": "2.19.1",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",

package/dist/index.js

@@ -3644,7 +3644,12 @@ var require_fast_uri = __commonJS({
     }
     function resolve(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
-      const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
+      const { parsed: baseParsed, malformedAuthorityOrPort: baseMalformed } = parseWithStatus(baseURI, schemelessOptions);
+      const { parsed: relativeParsed, malformedAuthorityOrPort: relativeMalformed } = parseWithStatus(relativeURI, schemelessOptions);
+      if (baseMalformed || relativeMalformed) {
+        throw new Error(baseParsed.error || relativeParsed.error || "URI is malformed.");
+      }
+      const resolved = resolveComponent(baseParsed, relativeParsed, schemelessOptions, true);
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
@@ -3770,6 +3775,7 @@ var require_fast_uri = __commonJS({
     }
     var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
     var AUTHORITY_PREFIX = /^(?:[^#/:?]+:)?\/\/([^/?#]*)/;
+    var AUTHORITY_INTRODUCER_REGION = /^(?:[^#/:?]+:)?([/\\\t\n\r]*)/;
     function getParseError(parsed, matches) {
       if (matches[2] !== void 0 && parsed.path && parsed.path[0] !== "/") {
         return 'URI path must start with "/" when authority is present.';
@@ -3804,6 +3810,20 @@ var require_fast_uri = __commonJS({
         parsed.error = "URI authority must not contain a literal backslash.";
         malformedAuthorityOrPort = true;
       }
+      const introducerMatch = uri.match(AUTHORITY_INTRODUCER_REGION);
+      if (introducerMatch !== null) {
+        const region = introducerMatch[1];
+        const normalizedRegion = region.replace(/[\t\n\r]/g, "");
+        if (normalizedRegion.length >= 2) {
+          if (normalizedRegion.slice(0, 2) !== "//") {
+            parsed.error = parsed.error || "URI authority must not contain a literal backslash.";
+            malformedAuthorityOrPort = true;
+          } else if (region.length !== normalizedRegion.length) {
+            parsed.error = parsed.error || "URI authority introducer must not contain whitespace.";
+            malformedAuthorityOrPort = true;
+          }
+        }
+      }
       const matches = uri.match(URI_PARSE);
       if (matches) {
         parsed.scheme = matches[1];
@@ -33052,7 +33072,7 @@ function registerTasksTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "2.18.4" : "0.0.0";
+var VERSION = true ? "2.19.1" : "0.0.0";
 var BASE_TOOL_REGISTRARS = [
   registerApiTools,
   registerAuthTools,
@@ -33067,7 +33087,69 @@ var BASE_TOOL_REGISTRARS = [
   registerTasksTools
 ];
 
+// src/connector-runtime.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEADLINE_GRACE_MS = 5e3;
+var RUNNER_GOG_FAILED = 422;
+var RUNNER_DRAINING = 503;
+function makeFlyExecutor(endpoint, key) {
+  return async (args, opts) => {
+    const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
+    let res;
+    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) {
+      const name = err instanceof Error ? err.name : "";
+      if (name === "TimeoutError" || name === "AbortError") {
+        throw new Error(
+          `gog-runner did not respond within ${deadlineMs}ms (${endpoint}) \u2014 the Fly backend may be cold or wedged`
+        );
+      }
+      throw err;
+    }
+    if (!res.ok) {
+      const body = await res.json().catch(() => null);
+      const detail = body && typeof body.error === "string" ? body.stderr && body.stderr.trim() && body.stderr.trim() !== body.error.trim() ? `${body.error}
+${body.stderr}` : body.error : "";
+      if (res.status === RUNNER_GOG_FAILED) {
+        throw new Error(detail || "gog failed on the runner (no detail supplied)");
+      }
+      if (res.status === RUNNER_DRAINING || body?.retryable === true) {
+        throw new Error(
+          `gog-runner is restarting; retry this call.${detail ? ` ${detail}` : ""}`
+        );
+      }
+      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 \u2014 this is transient, retry the same call.`
+      );
+    }
+    const { stdout } = await res.json();
+    return stdout;
+  };
+}
+
+// src/remote-runner.ts
+function useRemoteGogRunner(env = process.env) {
+  const endpoint = readEnvVar("GOG_RUNNER_URL", { env });
+  const key = readEnvVar("GOG_RUNNER_KEY", { env });
+  if (!endpoint || !key) return false;
+  runExecutor.enterWith({ executor: makeFlyExecutor(endpoint.replace(/\/+$/, ""), key) });
+  return true;
+}
+
 // src/index.ts
+useRemoteGogRunner();
 await runMcp({
   name: "gogcli",
   version: VERSION,

package/dist/lib.js

@@ -3643,7 +3643,12 @@ var require_fast_uri = __commonJS({
     }
     function resolve(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
-      const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
+      const { parsed: baseParsed, malformedAuthorityOrPort: baseMalformed } = parseWithStatus(baseURI, schemelessOptions);
+      const { parsed: relativeParsed, malformedAuthorityOrPort: relativeMalformed } = parseWithStatus(relativeURI, schemelessOptions);
+      if (baseMalformed || relativeMalformed) {
+        throw new Error(baseParsed.error || relativeParsed.error || "URI is malformed.");
+      }
+      const resolved = resolveComponent(baseParsed, relativeParsed, schemelessOptions, true);
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
@@ -3769,6 +3774,7 @@ var require_fast_uri = __commonJS({
     }
     var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
     var AUTHORITY_PREFIX = /^(?:[^#/:?]+:)?\/\/([^/?#]*)/;
+    var AUTHORITY_INTRODUCER_REGION = /^(?:[^#/:?]+:)?([/\\\t\n\r]*)/;
     function getParseError(parsed, matches) {
       if (matches[2] !== void 0 && parsed.path && parsed.path[0] !== "/") {
         return 'URI path must start with "/" when authority is present.';
@@ -3803,6 +3809,20 @@ var require_fast_uri = __commonJS({
         parsed.error = "URI authority must not contain a literal backslash.";
         malformedAuthorityOrPort = true;
       }
+      const introducerMatch = uri.match(AUTHORITY_INTRODUCER_REGION);
+      if (introducerMatch !== null) {
+        const region = introducerMatch[1];
+        const normalizedRegion = region.replace(/[\t\n\r]/g, "");
+        if (normalizedRegion.length >= 2) {
+          if (normalizedRegion.slice(0, 2) !== "//") {
+            parsed.error = parsed.error || "URI authority must not contain a literal backslash.";
+            malformedAuthorityOrPort = true;
+          } else if (region.length !== normalizedRegion.length) {
+            parsed.error = parsed.error || "URI authority introducer must not contain whitespace.";
+            malformedAuthorityOrPort = true;
+          }
+        }
+      }
       const matches = uri.match(URI_PARSE);
       if (matches) {
         parsed.scheme = matches[1];
@@ -24958,7 +24978,7 @@ function registerTasksTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "2.18.4" : "0.0.0";
+var VERSION = true ? "2.19.1" : "0.0.0";
 var BASE_TOOL_REGISTRARS = [
   registerApiTools,
   registerAuthTools,
@@ -24972,6 +24992,67 @@ var BASE_TOOL_REGISTRARS = [
   registerSlidesTools,
   registerTasksTools
 ];
+
+// src/connector-runtime.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEADLINE_GRACE_MS = 5e3;
+var RUNNER_GOG_FAILED = 422;
+var RUNNER_DRAINING = 503;
+function makeFlyExecutor(endpoint, key) {
+  return async (args, opts) => {
+    const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
+    let res;
+    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) {
+      const name = err instanceof Error ? err.name : "";
+      if (name === "TimeoutError" || name === "AbortError") {
+        throw new Error(
+          `gog-runner did not respond within ${deadlineMs}ms (${endpoint}) \u2014 the Fly backend may be cold or wedged`
+        );
+      }
+      throw err;
+    }
+    if (!res.ok) {
+      const body = await res.json().catch(() => null);
+      const detail = body && typeof body.error === "string" ? body.stderr && body.stderr.trim() && body.stderr.trim() !== body.error.trim() ? `${body.error}
+${body.stderr}` : body.error : "";
+      if (res.status === RUNNER_GOG_FAILED) {
+        throw new Error(detail || "gog failed on the runner (no detail supplied)");
+      }
+      if (res.status === RUNNER_DRAINING || body?.retryable === true) {
+        throw new Error(
+          `gog-runner is restarting; retry this call.${detail ? ` ${detail}` : ""}`
+        );
+      }
+      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 \u2014 this is transient, retry the same call.`
+      );
+    }
+    const { stdout } = await res.json();
+    return stdout;
+  };
+}
+
+// src/remote-runner.ts
+function useRemoteGogRunner(env = process.env) {
+  const endpoint = readEnvVar("GOG_RUNNER_URL", { env });
+  const key = readEnvVar("GOG_RUNNER_KEY", { env });
+  if (!endpoint || !key) return false;
+  runExecutor.enterWith({ executor: makeFlyExecutor(endpoint.replace(/\/+$/, ""), key) });
+  return true;
+}
 export {
   BASE_TOOL_REGISTRARS,
   MIN_GOG_VERSION,
@@ -25001,5 +25082,6 @@ export {
   run,
   runBinary,
   runExecutor,
-  runOrDiagnose
+  runOrDiagnose,
+  useRemoteGogRunner
 };

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "2.18.4",
+  "version": "2.19.1",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp",
-  "version": "2.18.4",
+  "version": "2.19.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>",
@@ -46,7 +46,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.1.2",
     "@vitest/coverage-v8": "^4.1.8",
     "esbuild": "^0.28.1",
     "typescript": "^7.0.2",

package/server.json

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

package/src/index.ts

@@ -1,6 +1,12 @@
 #!/usr/bin/env node
 import { runMcp } from '@chrischall/mcp-utils';
 import { BASE_TOOL_REGISTRARS, VERSION } from './server.js';
+import { useRemoteGogRunner } from './remote-runner.js';
+
+
+// Execute `gog` on the Fly backend when the host points us at one; without
+// it, nothing changes and we spawn the local binary as before.
+useRemoteGogRunner();
 
 await runMcp({
   name: 'gogcli',

package/src/lib.ts

@@ -15,6 +15,7 @@ export {
   registerTasksTools,
 } from './server.js';
 export { run, runBinary, runExecutor, isGogFileArg, MIN_GOG_VERSION } from './runner.js';
+export { useRemoteGogRunner } from './remote-runner.js';
 export type { RunOptions, Spawner, GogExecutor, GogArg, GogFileArg } from './runner.js';
 export {
   PAYLOAD_INLINE_MAX,

package/src/remote-runner.ts

@@ -0,0 +1,49 @@
+import { readEnvVar } from '@chrischall/mcp-utils';
+import { runExecutor } from './runner.js';
+import { makeFlyExecutor } from './connector-runtime.js';
+
+/**
+ * Let a stdio server run `gog` on the Fly backend instead of spawning it.
+ *
+ * The default stdio path shells out to the `gog` binary (`runner.ts`,
+ * `spawn(GOG_PATH ?? 'gog')`), which is right on a laptop and impossible
+ * anywhere the binary is not installed — notably mcp-host, whose runner image
+ * is deliberately Node + git + tar and nothing else. Baking a Go binary into a
+ * generic runner for one MCP's sake, or curling an unpinned release tarball
+ * inside an install, are both worse than using the seam that already exists:
+ * `makeFlyExecutor` has forwarded arg-arrays to `<runner>/run` for the
+ * Cloudflare connector since that connector shipped, and it touches nothing
+ * Worker-only.
+ *
+ * So this is wiring, not new machinery. Set both variables and the process
+ * executes remotely; leave either unset and nothing changes, which is what
+ * keeps every existing local install on the binary it already has.
+ *
+ * ## Why `enterWith` and not `run`
+ *
+ * `runExecutor` is an AsyncLocalStorage. The Worker wraps each REQUEST in
+ * `runExecutor.run(...)` because a Worker isolate serves many of them and the
+ * executor differs per user. A stdio process is one user for its whole life,
+ * and its tool calls arrive later as I/O callbacks — which would NOT inherit a
+ * store established by a `run()` that had already returned. `enterWith` sets it
+ * for the remainder of this execution and everything descending from it, which
+ * is the whole process. Using `run()` here would look correct and then fall
+ * back to spawning on the first actual tool call.
+ *
+ * Call before the server starts, so no tool can be serviced ahead of it.
+ */
+export function useRemoteGogRunner(env: NodeJS.ProcessEnv = process.env): boolean {
+  // The shared reader, not a local trim: it already treats blanks, unexpanded
+  // `${...}` placeholders AND the literal strings "undefined"/"null" as unset.
+  // Those last two are what a hand-rolled check misses, and they arrive whenever
+  // a host stringifies a missing value into an env block.
+  const endpoint = readEnvVar('GOG_RUNNER_URL', { env });
+  const key = readEnvVar('GOG_RUNNER_KEY', { env });
+  // Both or neither. A URL with no key would send unauthenticated requests the
+  // runner rejects, and a key with no URL is a credential configured for
+  // nothing — either alone is a misconfiguration, and silently spawning
+  // instead would hide it until someone wondered why the binary was needed.
+  if (!endpoint || !key) return false;
+  runExecutor.enterWith({ executor: makeFlyExecutor(endpoint.replace(/\/+$/, ''), key) });
+  return true;
+}

package/src/worker.ts

@@ -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.18.4'; // x-release-please-version
+const VERSION = '2.19.1'; // 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.

package/tests/remote-runner.test.ts

@@ -0,0 +1,90 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { useRemoteGogRunner } from '../src/remote-runner.js';
+import { runExecutor } from '../src/runner.js';
+
+/**
+ * The whole point of this seam is that a host without the `gog` binary can
+ * still serve. Two ways it silently fails: a half-configured env that falls
+ * back to spawning, and using `run()` instead of `enterWith()` so the store is
+ * gone by the time a tool call arrives.
+ */
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe('useRemoteGogRunner', () => {
+  it('does nothing unless BOTH variables are set, so local installs are untouched', () => {
+    expect(useRemoteGogRunner({})).toBe(false);
+    expect(useRemoteGogRunner({ GOG_RUNNER_URL: 'https://r.test' })).toBe(false);
+    expect(useRemoteGogRunner({ GOG_RUNNER_KEY: 'k' })).toBe(false);
+  });
+
+  it('treats blanks, placeholders and stringified nothings as unset', () => {
+    // MCP hosts pass env blocks through verbatim, so all three of these arrive
+    // in practice: a blank, a literal `${...}` that never expanded, and the
+    // string "undefined" from a host that stringified a missing value. The
+    // shared readEnvVar knows all three; a hand-rolled trim knew only the first
+    // two, which is why this uses the shared one.
+    expect(useRemoteGogRunner({ GOG_RUNNER_URL: '  ', GOG_RUNNER_KEY: 'k' })).toBe(false);
+    expect(useRemoteGogRunner({ GOG_RUNNER_URL: 'https://r.test', GOG_RUNNER_KEY: '${GOG_RUNNER_KEY}' })).toBe(false);
+    expect(useRemoteGogRunner({ GOG_RUNNER_URL: 'https://r.test', GOG_RUNNER_KEY: 'undefined' })).toBe(false);
+    expect(useRemoteGogRunner({ GOG_RUNNER_URL: 'null', GOG_RUNNER_KEY: 'k' })).toBe(false);
+  });
+
+  it('installs an executor that survives into a LATER async callback', async () => {
+    // The real failure mode this guards: with `run()` the store would be gone
+    // by the time a tool call arrives as an I/O callback, and the server would
+    // quietly go back to spawning a binary that is not installed.
+    const fetchMock = vi.fn(async () => new Response(JSON.stringify({ stdout: 'ok' }), { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    expect(useRemoteGogRunner({ GOG_RUNNER_URL: 'https://r.test/', GOG_RUNNER_KEY: 'secret' })).toBe(true);
+
+    // Cross a macrotask boundary, the way a stdio tool call does.
+    await new Promise((r) => setTimeout(r, 0));
+    const store = runExecutor.getStore();
+    expect(store?.executor).toBeTypeOf('function');
+
+    await store!.executor(['--version'], {});
+    const [url, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit];
+    // Trailing slash trimmed, so the endpoint is never `…//run`.
+    expect(url).toBe('https://r.test/run');
+    expect((init.headers as Record<string, string>).Authorization).toBe('Bearer secret');
+  });
+});
+
+/**
+ * The seam is opt-in PER BIN — `useRemoteGogRunner()` is a call in each
+ * package's `index.ts`, and a package that omits it spawns the binary no
+ * matter what the host sets. That shipped: 2.19.0 wired base, sheets, docs,
+ * drive and gmail, and left calendar, classroom, contacts and slides behind,
+ * so those four answered every tool call on mcp-host with "gog executable not
+ * found" — a host with no binary and no way to ask for the backend.
+ *
+ * Nothing caught it because each package's suite covers its TOOLS, and
+ * `src/index.ts` is excluded from the coverage gate in every package (it is
+ * the bin: it boots a server and cannot be imported under test). So this
+ * asserts on the source text instead, across the whole workspace — the one
+ * check that scales to the next sub-package, which will otherwise be added by
+ * copying an index.ts that predates the seam.
+ */
+describe('every package bin', () => {
+  const packagesDir = fileURLToPath(new URL('../../', import.meta.url));
+  const bins = readdirSync(packagesDir)
+    .filter((name) => name.startsWith('gogcli-mcp'))
+    .map((name) => [name, join(packagesDir, name, 'src', 'index.ts')] as const);
+
+  it('finds every package (guards the glob itself against silently matching nothing)', () => {
+    expect(bins.length).toBeGreaterThanOrEqual(9);
+  });
+
+  it.each(bins)('%s installs the remote executor before starting the server', (_name, path) => {
+    const source = readFileSync(path, 'utf8');
+    expect(source).toContain('useRemoteGogRunner()');
+    // Order matters as much as presence: `runMcp` starts serving, so a call
+    // placed after it could be beaten by a tool call and fall back to spawning.
+    expect(source.indexOf('useRemoteGogRunner()')).toBeLessThan(source.indexOf('runMcp({'));
+  });
+});