gogcli-mcp 3.0.0 → 4.0.1

package/src/blob-urls.ts

@@ -56,11 +56,9 @@ import { readEnvVar } from '@chrischall/mcp-utils';
  * that is easy to get wrong is exactly the part below — which bytes are signed,
  * and which of them are percent-encoded on the way into the URL.
  *
- * `node:crypto` rather than WebCrypto (which `google-token.ts` uses, for the
- * Worker build): HMAC through `crypto.subtle` is async, and a URL minter that
- * returns a promise infects every call site for no gain here. The Worker build
- * sets `nodejs_compat` (wrangler.jsonc), so `createHmac` resolves there too if
- * this module is ever pulled into that graph.
+ * `node:crypto` rather than WebCrypto: HMAC through `crypto.subtle` is async,
+ * and a URL minter that returns a promise infects every call site for no gain
+ * here.
  */
 
 /**

package/src/bootstrap-auth.ts

@@ -0,0 +1,97 @@
+import { join } from 'node:path';
+import { readEnvVar } from '@chrischall/mcp-utils';
+import { redactSecrets, run, type GogFileArg, type Spawner } from './runner.js';
+import { errorText } from './tools/utils.js';
+
+export type AuthBootstrapStatus = 'unconfigured' | 'incomplete' | 'present' | 'imported' | 'failed';
+
+export interface AuthBootstrapOptions {
+  spawner?: Spawner;
+  /** Where the marker lives. Defaults to the OS home dir, which is mcp-host's persistent dataDir. */
+  home?: string;
+}
+
+export const AUTH_BOOTSTRAP_MARKER = 'auth-bootstrap.sha256';
+
+const VARS = ['GOG_CLIENT_ID', 'GOG_CLIENT_SECRET', 'GOG_REFRESH_TOKEN', 'GOG_ACCOUNT'] as const;
+
+const log = (line: string): void => {
+  process.stderr.write(`[gogcli-mcp] auth bootstrap: ${line}\n`);
+};
+
+const jsonFile = (name: string, payload: unknown): GogFileArg => ({
+  kind: 'file',
+  flag: name,
+  ext: 'json',
+  contents: JSON.stringify(payload),
+  positional: true,
+});
+
+async function accountListed(account: string, spawner: Spawner | undefined): Promise<boolean> {
+  try {
+    const out = await run(['auth', 'list'], { spawner, account });
+    const accounts = (JSON.parse(out) as { accounts?: { email?: string }[] | null }).accounts ?? [];
+    return accounts.some((a) => a.email?.toLowerCase() === account.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Seed gog's keyring from GOG_CLIENT_ID / GOG_CLIENT_SECRET / GOG_REFRESH_TOKEN
+ * / GOG_ACCOUNT, for a host (mcp-host) that can inject secrets but cannot run
+ * `gog auth add` in a browser. Never throws: the server must still start so the
+ * auth tools stay reachable.
+ *
+ * The marker records WHICH secret was last imported, so a rotated secret is
+ * re-imported while an in-connector re-auth (gog_auth_add_url/complete) is left
+ * in effect until the secret itself changes.
+ */
+export async function bootstrapGogAuth(
+  env: NodeJS.ProcessEnv = process.env,
+  options: AuthBootstrapOptions = {},
+): Promise<AuthBootstrapStatus> {
+  const values = VARS.map((key) => readEnvVar(key, { env }));
+  const missing = VARS.filter((_key, i) => values[i] === undefined);
+  if (missing.length === VARS.length) return 'unconfigured';
+  if (missing.length > 0) {
+    log(`skipped, missing ${missing.join(', ')}`);
+    return 'incomplete';
+  }
+  const [clientId, clientSecret, refreshToken, account] = values as string[];
+  const { spawner } = options;
+
+  try {
+    const { createHash } = await import('node:crypto');
+    const { mkdir, readFile, writeFile, chmod } = await import('node:fs/promises');
+    const home = options.home ?? (await import('node:os')).homedir();
+    const dir = join(home, '.gogcli-mcp');
+    const marker = join(dir, AUTH_BOOTSTRAP_MARKER);
+    const fingerprint = createHash('sha256').update(values.join('\0')).digest('hex');
+
+    const previous = await readFile(marker, 'utf8').catch(() => undefined);
+    if (previous === fingerprint && (await accountListed(account, spawner))) return 'present';
+
+    await run(
+      ['auth', 'credentials', 'set', jsonFile('credentials', { installed: { client_id: clientId, client_secret: clientSecret } })],
+      { spawner, account },
+    );
+    await run(
+      ['auth', 'tokens', 'import', jsonFile('token', { email: account, refresh_token: refreshToken })],
+      { spawner, account },
+    );
+
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
+    await writeFile(marker, fingerprint, { mode: 0o600 });
+    await chmod(marker, 0o600);
+    return 'imported';
+  } catch (err) {
+    // run() already redacts; the literal values are scrubbed too in case a
+    // secret shape the redactor does not know (e.g. GOCSPX-…) was echoed.
+    let message = redactSecrets(errorText(err));
+    for (const value of [clientSecret, refreshToken]) message = message.split(value).join('[REDACTED]');
+    log(`failed, ${message}`);
+    return 'failed';
+  }
+}

package/src/index.ts

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
 import { runMcp } from '@chrischall/mcp-utils';
 import { BASE_TOOL_REGISTRARS, VERSION } from './server.js';
-import { useRemoteGogRunner } from './remote-runner.js';
+import { bootstrapGogAuth } from './bootstrap-auth.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();
+// Seed gog's keyring from GOG_CLIENT_ID/SECRET/REFRESH_TOKEN/ACCOUNT when the host injects them.
+await bootstrapGogAuth();
 
 await runMcp({
   name: 'gogcli',

package/src/lib.ts

@@ -31,7 +31,7 @@ export {
   requireGmailDispatchConfirmation,
   resultText,
 } from './gmail-dispatch-guard.js';
-export { run, runBinary, runExecutor, isGogFileArg, MIN_GOG_VERSION } from './runner.js';
+export { run, runBinary, isGogFileArg, MIN_GOG_VERSION } from './runner.js';
 // Sub-package tools that read gog JSON through bare `run()` (rather than the
 // `runOrDiagnose` seam) must still apply this, or their timestamps skip the
 // offset repair and the `<field>Display` sibling every other tool returns.
@@ -42,11 +42,12 @@ export { annotateTruncatedList, stripConsumedPageToken } from './pagination.js';
 // guarantees the base gog_gmail_search makes.
 export { finalizeGmailSearch, fetchGmailPages } from './gmail-results.js';
 export type { FinalizeOptions, GmailListMethod } from './gmail-results.js';
-export { useRemoteGogRunner } from './remote-runner.js';
-export type { RunOptions, Spawner, GogExecutor, GogArg, GogFileArg } from './runner.js';
+export { bootstrapGogAuth, AUTH_BOOTSTRAP_MARKER } from './bootstrap-auth.js';
+export type { AuthBootstrapStatus, AuthBootstrapOptions } from './bootstrap-auth.js';
+export type { RunOptions, Spawner, GogArg, GogFileArg } from './runner.js';
 // Caller-supplied attachment bytes — the only outbound attachment path that
-// works when the caller and gog share no filesystem (hosted connector, or any
-// GOG_RUNNER_URL backend). See src/attachments.ts.
+// works when the caller and gog share no filesystem (a hosted deployment such
+// as mcp-host). See src/attachments.ts.
 export {
   attachInlineParam,
   inlineAttachmentSchema,
@@ -88,8 +89,12 @@ export {
   BLOB_URL_DEFAULT_TTL_MS,
 } from './blob-urls.js';
 export type { BlobStoreConfig, BlobUrlMinter, MintOptions } from './blob-urls.js';
-// The other half of that hop: under the hosted connector the bytes are on the
-// RUNNER's disk and this child never sees them, so the runner is asked to
-// stream them to the URL this process minted. See src/blob-upload.ts.
-export { uploadToBlobStore, RUNNER_UPLOAD_TIMEOUT_MS } from './blob-upload.js';
+// The other half of that hop: stream a downloaded attachment off this machine's
+// disk to the URL this process minted. See src/blob-upload.ts.
+export {
+  uploadToBlobStore,
+  ATTACHMENT_DOWNLOAD_ROOT,
+  BLOB_UPLOAD_TIMEOUT_MS,
+  MAX_BLOB_UPLOAD_BYTES,
+} from './blob-upload.js';
 export type { BlobUploadRequest, BlobUploadOutcome, BlobUploadOptions } from './blob-upload.js';

package/src/runner.ts

@@ -1,7 +1,7 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 import type { ChildProcess } from 'node:child_process';
 import { delimiter, join } from 'node:path';
 import { parseBoolEnv, readEnvVar, redactSecrets as redactSharedSecrets } from '@chrischall/mcp-utils';
+import { naiveSourceTimeZone } from './timestamps.js';
 
 export type Spawner = (
   command: string,
@@ -9,12 +9,11 @@ export type Spawner = (
   options: { env: NodeJS.ProcessEnv },
 ) => ChildProcess;
 
-// A payload too large to live in argv. Every argv element is capped — the Fly
-// runner rejects args over 4 KiB, and the Linux kernel hard-caps a single argv
-// string at MAX_ARG_STRLEN (128 KiB) regardless of ARG_MAX — so big values
-// (a long HTML mail body, slide notes) must leave argv entirely. gog exposes
-// `--x-file` companions for exactly these flags; the executor writes the
-// payload to a private temp file and passes the path instead.
+// A payload too large to live in argv. The Linux kernel hard-caps a single argv
+// string at MAX_ARG_STRLEN (128 KiB) regardless of ARG_MAX, so big values (a
+// long HTML mail body, slide notes) must leave argv entirely. gog exposes
+// `--x-file` companions for exactly these flags; the runner writes the payload
+// to a private temp file and passes the path instead.
 export interface GogFileArg {
   /** Discriminant separating this from a plain argv string. */
   kind: 'file';
@@ -50,9 +49,8 @@ export interface GogFileArg {
    * Emit the materialized path as a BARE argv element instead of `--flag=path`.
    *
    * For subcommands taking the file as a positional argument — `gog drive
-   * upload <localPath>` is the only one today. Argument ORDER is preserved by
-   * every executor, so a positional file arg lands exactly where it sat in the
-   * caller's array.
+   * upload <localPath>` is the only one today. Argument ORDER is preserved, so
+   * a positional file arg lands exactly where it sat in the caller's array.
    */
   positional?: boolean;
 }
@@ -63,114 +61,6 @@ export function isGogFileArg(arg: GogArg): arg is GogFileArg {
   return typeof arg !== 'string';
 }
 
-// An executor runs a FULLY-ASSEMBLED gog arg list (already including
-// --json/--no-input/--color=never, --account, --readonly, and the service
-// subcommand) and returns its stdout as a string (or throws). This is the
-// injection seam that lets the same tool registrars run either by spawning
-// `gog` (stdio transport) or by forwarding the arg list to a remote HTTP
-// backend (hosted Cloudflare-Worker connector, which cannot spawn processes).
-// Elements may be GogFileArgs; EVERY executor is responsible for materializing
-// them to a private temp file and removing that file afterwards.
-export type GogExecutor = (
-  args: GogArg[],
-  opts: { timeout?: number; interactive?: boolean },
-) => Promise<string>;
-
-// Which layer authored a failure, when the layer was OURS and not gog's.
-//
-// A remote executor (the Fly/Worker path) can fail in two categorically
-// different ways, and every consumer downstream needs to tell them apart:
-//
-//   - `gog` ran on the backend and failed. The message is gog's — or Google's,
-//     relayed by gog — so it is PROSE, and the only way to classify it is to
-//     read it. That failure is NOT a RunnerTransportError; it stays a plain
-//     Error so tools/utils.ts keeps applying its patterns to it.
-//   - The request never got that far: the runner rejected our bearer token,
-//     refused the request shape, was draining, or never answered. Nothing was
-//     ever shown to Google, so no amount of re-authorizing a Google account can
-//     help — and the runner's own words ("unauthorized") are indistinguishable
-//     from Google's when read as prose. That is what this type exists for.
-//
-// The kinds, and what each one asks of the caller:
-//   transport-auth      the runner rejected OUR bearer (GOG_RUNNER_KEY on the
-//                       Worker vs RUNNER_KEY on the Fly app). An operator has
-//                       to fix a key; the end user's Google grant is fine.
-//   transport-request   the runner refused the request shape (oversized arg,
-//                       malformed JSON). Deterministic; retrying is pointless.
-//   transport-retryable the runner is draining, could not reach its disk, or
-//                       never answered. The same call can succeed shortly.
-export type RunnerFailureKind = 'transport-auth' | 'transport-request' | 'transport-retryable';
-
-// `Symbol.for`, not a private symbol or a bare `instanceof`: the class can be
-// evaluated more than once in one process (the stdio bundle and the Worker
-// bundle are separate builds of the same source, and vitest can load a module
-// twice across pools), and a second copy of the class would make `instanceof`
-// answer false for an error that IS one. The registry symbol is the same value
-// in every copy, so the brand survives.
-const RUNNER_TRANSPORT_BRAND = Symbol.for('gogcli.RunnerTransportError');
-
-/**
- * A failure authored by the gog-runner itself (or by the hop to it) rather than
- * by `gog`/Google. Carries the runner's HTTP status when there was one.
- */
-export class RunnerTransportError extends Error {
-  readonly kind: RunnerFailureKind;
-  readonly status: number | undefined;
-
-  constructor(message: string, kind: RunnerFailureKind, status?: number) {
-    super(message);
-    this.name = 'RunnerTransportError';
-    this.kind = kind;
-    this.status = status;
-    // Non-enumerable so the brand never shows up in a serialized error body.
-    Object.defineProperty(this, RUNNER_TRANSPORT_BRAND, { value: true });
-  }
-}
-
-/** Structural check for the above — see RUNNER_TRANSPORT_BRAND on why not `instanceof`. */
-export function isRunnerTransportError(err: unknown): err is RunnerTransportError {
-  return err instanceof Error && (err as unknown as Record<symbol, unknown>)[RUNNER_TRANSPORT_BRAND] === true;
-}
-
-// Ambient override for the executor `run()` uses when no options.spawner is
-// given. The Worker/Fly path wraps request handling in
-// `runExecutor.run({ executor }, ...)`; unset, `run()` falls back to spawning.
-export const runExecutor = new AsyncLocalStorage<{ executor: GogExecutor }>();
-
-/**
- * The PROCESS-WIDE executor, for a host that has exactly one backend for the
- * whole process — a stdio bin pointed at a Fly runner (`useRemoteGogRunner`).
- *
- * It exists because AsyncLocalStorage cannot express that. `enterWith` sets the
- * store on the async resource that is current when it runs, and a bin runs it
- * during module evaluation; the tool calls arrive later as I/O events on the
- * transport's own resources, which are not descendants of that evaluation, so
- * `getStore()` is undefined exactly where it is needed. That is not a bug in
- * `enterWith` — a process-lifetime default is simply not a scoped value, and
- * storing it in a scope meant the seam silently reverted to spawning a binary
- * the host does not have.
- *
- * A per-request store still WINS over this (see `activeExecutor`), because the
- * Worker serves many callers from one isolate and each has its own backend
- * credential; this is the fallback for the one-backend case, never a second
- * answer to "whose backend is this".
- */
-let defaultExecutor: { executor: GogExecutor } | undefined;
-
-/** Install the process-wide executor. Passing undefined clears it (tests). */
-export function setDefaultGogExecutor(executor: GogExecutor | undefined): void {
-  defaultExecutor = executor ? { executor } : undefined;
-}
-
-/**
- * Whose executor applies right now: the request's, else the process's, else
- * none (meaning `run()` spawns the local binary). Both call sites ask through
- * here so they can never disagree about which of the three it is.
- */
-function activeExecutor(): { executor: GogExecutor } | undefined {
-  return runExecutor.getStore() ?? defaultExecutor;
-}
-
 export interface RunOptions {
   account?: string;
   spawner?: Spawner;
@@ -238,13 +128,11 @@ function readonlyEnvEnabled(): boolean {
 // cloud / API secrets in scope that the child has no business seeing.
 //
 // `_KEY`, not `_API_KEY|_PRIVATE_KEY`: those were four spellings of "a key"
-// with the bare one missing, and TWO credentials this repo hands its own
-// process fell in that gap. `MCP_BLOB_SIGNING_KEY` mints the signed blob URLs
-// a `deliver="url"` download is uploaded to — a signature IS the whole access
-// control on that store — and `GOG_RUNNER_KEY` is the bearer for the Fly
-// backend, where `POST /run` is arbitrary `gog` argv. Neither is read by the
-// child: both are spent HERE, and when `GOG_RUNNER_URL` is set nothing is
-// spawned at all. `_CREDENTIALS` generalises the named
+// with the bare one missing, and a credential this repo hands its own process
+// fell in that gap. `MCP_BLOB_SIGNING_KEY` mints the signed blob URLs a
+// `deliver="url"` download is uploaded to — a signature IS the whole access
+// control on that store — and it is spent HERE, never read by the child.
+// `_CREDENTIALS` generalises the named
 // GOOGLE_APPLICATION_CREDENTIALS above, which stays named because it is the
 // one gog itself would act on.
 //
@@ -411,10 +299,6 @@ function formatTimeout(ms: number): string {
 // Write every GogFileArg to a private temp file, run gog against the resulting
 // plain argv, and remove the temp dir afterwards — on success, on a non-zero
 // exit, and on timeout alike. A leaked temp file holds user email content.
-//
-// node:fs/promises and node:os are imported LAZILY (matching the lazy
-// node:child_process import below) so a Cloudflare Worker importing this module
-// doesn't eagerly pull node builtins, which would break the Worker bundle.
 async function spawnWithTempFiles(
   args: GogArg[],
   opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean },
@@ -460,7 +344,7 @@ async function spawnWithTempFiles(
   }
 }
 
-// Spawn-based executor. Deliberately NOT async: when no element is a
+// Spawn gog, materializing GogFileArgs first. Deliberately NOT async: when no element is a
 // GogFileArg (the overwhelmingly common case) it must create no temp dir and
 // introduce no extra microtask tick before `spawn` is called — the spawn has
 // to happen synchronously within the `run()` call, which the fake-timer tests
@@ -477,11 +361,8 @@ function spawnExecutor(
 
 // Owns everything process-specific — building the sanitized child env, PATH
 // augmentation, spawning, collecting stdout/stderr, and the timeout kill. It
-// returns raw output (no redaction — `run()` wraps that around whichever
-// executor runs). The child_process import is LAZY so a Cloudflare Worker
-// importing this module doesn't eagerly pull node:child_process (which would
-// break the Worker bundle); the injected `spawner` bypasses it.
-
+// returns raw output (no redaction — `run()` wraps that around it). The
+// injected `spawner` bypasses the real child_process spawn.
 async function spawnGog(
   fullArgs: string[],
   opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean },
@@ -491,7 +372,9 @@ async function spawnGog(
   const effectiveTimeout = timeout ?? TIMEOUT_MS;
 
   return new Promise((resolve, reject) => {
-    const childEnv = { ...sanitizedEnv(), PATH: augmentedPath() };
+    // gog must format naive dates in the zone normalizeTimestamps assumes; left
+    // to itself it falls back to the host's local zone (UTC on mcp-host).
+    const childEnv = { ...sanitizedEnv(), GOG_TIMEZONE: naiveSourceTimeZone(), PATH: augmentedPath() };
     const child = spawn(readEnvVar('GOG_PATH') ?? 'gog', fullArgs, { env: childEnv });
     const stdoutChunks: Buffer[] = [];
     const stderrChunks: Buffer[] = [];
@@ -583,58 +466,26 @@ export async function run(args: GogArg[], options: RunOptions = {}): Promise<str
 
   const fullArgs = assembleArgs(args, { account, interactive, readonly });
 
-  // Pick the executor: an injected spawner keeps the stdio spawn path (and all
-  // its tests) intact and always wins; otherwise an ambient runExecutor store
-  // (the Worker/Fly HTTP-forward path) takes over; otherwise the default lazy
-  // real spawn. Redaction wraps the executor regardless of which one runs — a
-  // successful `gog auth tokens` (or any command echoing a credential) would
-  // otherwise return raw Google tokens (ya29.…/1//…) into model context, where
-  // a sibling tool (gog_gmail_send) could exfiltrate them.
-  const store = activeExecutor();
+  // Redaction wraps the spawn: a successful `gog auth tokens` (or any command
+  // echoing a credential) would otherwise return raw Google tokens (ya29.…/1//…)
+  // into model context, where a sibling tool (gog_gmail_send) could exfiltrate
+  // them.
   try {
-    let output: string;
-    if (spawner) {
-      output = await spawnExecutor(fullArgs, { timeout, interactive, spawner });
-    } else if (store) {
-      output = await store.executor(fullArgs, { timeout, interactive });
-    } else {
-      output = await spawnExecutor(fullArgs, { timeout, interactive });
-    }
-    return redact(output);
+    return redact(await spawnExecutor(fullArgs, { timeout, interactive, spawner }));
   } catch (err) {
     // A thrown non-Error would make `.message` undefined and redact() blow up
     // with a TypeError, masking the real failure. Same instanceof guard the
     // codebase already uses in errorText() (tools/utils.ts).
-    const message = base(err instanceof Error ? err.message : String(err));
-    // Redaction must not cost the error its TYPE. `RunnerTransportError` is the
-    // structural claim "this failure was ours, not Google's"; flattening it to a
-    // bare Error here would put diagnose() straight back to guessing from prose,
-    // which is the bug this type exists to close. Rebuilt rather than mutated so
-    // the un-redacted message never survives anywhere.
-    if (isRunnerTransportError(err)) {
-      throw new RunnerTransportError(message, err.kind, err.status);
-    }
-    throw new Error(message);
+    throw new Error(base(err instanceof Error ? err.message : String(err)));
   }
 }
 
 // Run gog and return its stdout as raw bytes, base64-encoded — for binary
 // payloads (a Drive file's bytes) that run()'s utf8 decode + secret redaction
-// would corrupt. Spawn path only: the hosted-connector executor forwards over
-// HTTP and hands back a decoded string, so binary cannot survive it — callers
-// on that path get a clear error instead of a mangled file. No redaction: the
-// base64 of a user's own binary file is opaque and has no token shapes to leak.
+// would corrupt. No redaction: the base64 of a user's own binary file is opaque
+// and has no token shapes to leak.
 export async function runBinary(args: GogArg[], options: RunOptions = {}): Promise<string> {
   const { account, spawner, timeout, readonly = false } = options;
-  // An injected spawner is the stdio/test path and always wins. Otherwise, if an
-  // ambient forward executor is installed (the Worker/Fly connector), refuse:
-  // its text-only transport can't carry bytes intact.
-  if (!spawner && activeExecutor()) {
-    throw new Error(
-      'Raw byte retrieval is not available over the hosted connector (its transport is text-only). ' +
-      'Use the text-extraction path instead, or run the local stdio server to fetch bytes.',
-    );
-  }
   const fullArgs = assembleArgs(args, { account, interactive: false, readonly });
   return spawnExecutor(fullArgs, { timeout, interactive: false, spawner, binary: true });
 }

package/src/tools/appscript.ts

@@ -61,7 +61,7 @@ export function registerAppScriptTools(server: McpServer): void {
     description:
       'Write a project\'s files into a local directory, for editing a script as ordinary files. '
       + 'THE DIRECTORY IS RESOLVED WHERE GOG RUNS, which is the caller\'s own machine only on a local (stdio) deployment: '
-      + 'on the hosted connector, or any GOG_RUNNER_URL backend, the files land on that server where the caller cannot '
+      + 'on a hosted deployment (e.g. mcp-host) the files land on that server where the caller cannot '
       + 'reach them. Use gog_appscript_content there instead — it returns the same source in the response. Existing files '
       + 'are left alone unless overwrite is set. Read-only as far as Google is concerned: nothing is pushed back.'
       + apiEnableNote,

package/src/tools/auth.ts

@@ -67,10 +67,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. On the hosted connector this is the ONLY ' +
+      're-authorize on your own schedule instead of mid-task. On a hosted deployment 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.',
+      'client\'s connection to the MCP host, and nothing else — the Google credential lives in gog\'s ' +
+      'keyring on that host and can be dead while the connection looks perfectly healthy.',
     annotations: { readOnlyHint: true },
     inputSchema: z.object({}),
   }, async () => {
@@ -129,8 +129,8 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
   server.registerTool('gog_auth_add_url', {
     description:
       'Begin REMOTE/headless Google authorization (step 1 of 2). Returns a sign-in URL to open in any ' +
-      'browser — no local server or terminal on the gogcli host is needed, so this works over the hosted ' +
-      'connector where the interactive gog_auth_add cannot. Hand the URL to the user; after they sign in, ' +
+      'browser — no local server or terminal on the gogcli host is needed, so this works on a hosted ' +
+      'deployment where the interactive gog_auth_add cannot. Hand the URL to the user; after they sign in, ' +
       'the browser is redirected to a localhost URL that fails to load — that is expected. They copy that ' +
       'full redirected URL (from the address bar) and you pass it to gog_auth_add_complete. The link is ' +
       'valid for 10 minutes. If you pass a custom `services` here, pass the SAME value to ' +

package/src/tools/drive.ts

@@ -251,9 +251,7 @@ export function registerDriveTools(server: McpServer): void {
     description:
       'Fetch a Drive file\'s raw bytes and return them base64-encoded as an embedded resource — the ' +
       'generic fallback for callers that want the file itself (to parse locally) rather than extracted ' +
-      'text. For readable text from a PDF, prefer gog_drive_extract_text. NOTE: only works on the local ' +
-      'stdio server; over the hosted connector the transport is text-only and this returns a clear error ' +
-      '(use gog_drive_extract_text there).',
+      'text. For readable text from a PDF, prefer gog_drive_extract_text.',
     annotations: { readOnlyHint: true },
     inputSchema: z.object({
       fileId: z.string().describe('Drive file ID'),

package/src/tools/gmail.ts

@@ -24,7 +24,7 @@ export const replySchema = {
   remove: z.array(z.string()).optional().describe('Remove these recipients from all fields (repeatable) — e.g. to drop someone from a reply-all.'),
   subject: z.string().optional().describe('Override reply subject (default: "Re: <original>"). A changed subject starts a NEW Gmail thread.'),
   noQuote: z.boolean().optional().describe('Do not include the original message quoted below the reply (default: the original is quoted)'),
-  attach: z.array(z.string()).optional().describe('File paths to attach (repeatable), resolved ON THE GOG SERVER\'s filesystem — NOT this client\'s. Only usable when gog runs on the same machine you do (local stdio); on the hosted connector or any GOG_RUNNER_URL backend these paths do not exist and the call fails with "no such file or directory" — use attachInline there. Read on the server, base64-encoded with a MIME type inferred from the extension.'),
+  attach: z.array(z.string()).optional().describe('File paths to attach (repeatable), resolved ON THE GOG SERVER\'s filesystem — NOT this client\'s. Only usable when gog runs on the same machine you do (local stdio); on a hosted deployment (e.g. mcp-host) these paths do not exist and the call fails with "no such file or directory" — use attachInline there. Read on the server, base64-encoded with a MIME type inferred from the extension.'),
   attachInline: attachInlineParam,
   from: z.string().optional().describe('Send from this email address (must be a verified send-as alias)'),
   autoFromAddressedAlias: z.boolean().optional().describe('When from is omitted, send from the verified send-as alias the original message was addressed TO, instead of the account\'s primary address — so a reply to mail sent to an alias goes back out from that alias. Ignored when from is set.'),
@@ -66,9 +66,9 @@ export function appendReplyFlags(args: GogArg[], f: ReplyFlags): void {
   if (f.noQuote) args.push('--no-quote');
   if (f.attach) for (const p of f.attach) args.push(`--attach=${p}`);
   // Same repeatable --attach flag, but the bytes travel with the call: the
-  // executor writes each one to a temp file beside gog and passes that path.
+  // runner writes each one to a temp file beside gog and passes that path.
   // This is the only attachment route that works when the caller and gog do not
-  // share a filesystem (hosted connector, GOG_RUNNER_URL backend). `args` is
+  // share a filesystem (a hosted deployment such as mcp-host). `args` is
   // passed so the size check sees the body too, which shares the same budget
   // once payloadArg has turned it into a file arg.
   args.push(...inlineAttachmentArgs('attach', f.attachInline, args));
@@ -78,8 +78,8 @@ export function appendReplyFlags(args: GogArg[], f: ReplyFlags): void {
   if (f.signatureFile) args.push(`--signature-file=${f.signatureFile}`);
   // PINNED, not conditional: GOG_GMAIL_AUTO_FROM_ADDRESSED_ALIAS in the host env
   // silently changes which address the mail goes out FROM, with nothing in the arg
-  // array to show for it — and the remote runner's backend env is not ours to set.
-  // An explicit flag is the only value authoritative on both transports.
+  // array to show for it — and a hosted deployment's env is not the caller's to set.
+  // An explicit flag is the only value authoritative everywhere.
   args.push(f.autoFromAddressedAlias ? '--auto-from-addressed-alias' : '--auto-from-addressed-alias=false');
 }
 
@@ -255,7 +255,7 @@ export function registerGmailTools(server: McpServer): void {
       replyToMessageId: z.string().optional().describe('Message ID to thread this message against — sets In-Reply-To/References only. It does NOT quote the original (pass quote for that), inherit its recipients, or prefix the subject with "Re:". For an actual reply use gog_gmail_reply.'),
       threadId: z.string().optional().describe('Thread ID to thread this message within. Same caveat as replyToMessageId: threading only, no quote and no inherited subject or recipients.'),
       quote: z.boolean().optional().describe('Include the original message quoted below the body. Requires replyToMessageId or threadId. gog quotes by DEFAULT on gmail reply but never on gmail send, so without this a threaded send arrives with the original nowhere in it.'),
-      attach: z.array(z.string()).optional().describe('File paths to attach (repeatable), resolved ON THE GOG SERVER\'s filesystem — NOT this client\'s. Only usable when gog runs on the same machine you do (local stdio); on the hosted connector or any GOG_RUNNER_URL backend these paths do not exist and the call fails with "no such file or directory" — use attachInline there. Each file is read on the server, base64-encoded with a MIME type inferred from its extension, and added as a multipart attachment.'),
+      attach: z.array(z.string()).optional().describe('File paths to attach (repeatable), resolved ON THE GOG SERVER\'s filesystem — NOT this client\'s. Only usable when gog runs on the same machine you do (local stdio); on a hosted deployment (e.g. mcp-host) these paths do not exist and the call fails with "no such file or directory" — use attachInline there. Each file is read on the server, base64-encoded with a MIME type inferred from its extension, and added as a multipart attachment.'),
       attachInline: attachInlineParam,
       account: accountParam,
     }),
@@ -265,9 +265,9 @@ export function registerGmailTools(server: McpServer): void {
     // skipped this would tell a caller "looks fine, send it" about an
     // attachment that was always going to fail.
     //
-    // A long body cannot ride in argv: the hosted runner caps a single arg and
-    // Linux caps MAX_ARG_STRLEN at 128 KiB. payloadArg swaps it for --body-file
-    // past the shared threshold; the executor materializes the temp file.
+    // A long body cannot ride in argv: Linux caps MAX_ARG_STRLEN at 128 KiB.
+    // payloadArg swaps it for --body-file past the shared threshold; the runner
+    // materializes the temp file.
     const args: GogArg[] = ['gmail', 'send', `--to=${to}`, `--subject=${subject}`, payloadArg('body', 'body-file', body)];
     if (cc) args.push(`--cc=${cc}`);
     if (bcc) args.push(`--bcc=${bcc}`);