gogcli-mcp 2.7.1 → 2.18.0

package/src/runner.ts

@@ -1,6 +1,7 @@
-import { spawn } from 'node:child_process';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import type { ChildProcess } from 'node:child_process';
-import { delimiter } from 'node:path';
+import { delimiter, join } from 'node:path';
+import { parseBoolEnv, readEnvVar, redactSecrets as redactSharedSecrets } from '@chrischall/mcp-utils';
 
 export type Spawner = (
   command: string,
@@ -8,11 +9,64 @@ 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.
+export interface GogFileArg {
+  /** Discriminant separating this from a plain argv string. */
+  kind: 'file';
+  /** Flag NAME without leading dashes, e.g. 'body-html-file'. */
+  flag: string;
+  /** The large payload, verbatim. */
+  contents: string;
+  /** Temp-file extension without the dot, e.g. 'html'. Defaults to 'txt'. */
+  ext?: string;
+}
+
+export type GogArg = string | GogFileArg;
+
+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>;
+
+// 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 }>();
+
 export interface RunOptions {
   account?: string;
   spawner?: Spawner;
   interactive?: boolean;
   timeout?: number;
+  // Inject gog's global --readonly flag, which blocks mutating API requests at
+  // runtime. Independent of (and OR-ed with) the GOG_READONLY env var.
+  readonly?: boolean;
+  // How aggressively to redact the output/error before it reaches the client.
+  // 'full' (default) runs the shared mcp-utils redactor plus the Google token
+  // shapes. 'tokens' runs ONLY the Google token shapes (ya29.…/1//…) — use it
+  // for output that is known-safe but that the broad shared redactor mangles,
+  // most notably an OAuth consent URL whose `classroom.coursework.students`-style
+  // scope names the shared redactor mistakes for secrets. A step-1 auth URL
+  // carries no token, so stripping only real token shapes keeps it intact while
+  // still catching any token that unexpectedly appears.
+  redactMode?: 'full' | 'tokens';
 }
 
 const TIMEOUT_MS = 30_000;
@@ -23,16 +77,17 @@ const TIMEOUT_MS = 30_000;
 // so the requirement change is surfaced in the release notes (see
 // .github/release.yml). This is the single source of truth for the required
 // version; keep the README/CLAUDE.md mention in sync.
-export const MIN_GOG_VERSION = '0.24.0';
-
-// Treat unresolved .mcpb placeholders ("${user_config.gog_path}") and empty
-// strings the same as an unset env var. When an optional .mcpb user_config
-// field is left blank, some clients pass the literal placeholder text through
-// to the spawned server instead of substituting "" or omitting the key.
-function envOrUndefined(key: string): string | undefined {
-  const value = process.env[key];
-  if (!value || value.startsWith('${')) return undefined;
-  return value;
+export const MIN_GOG_VERSION = '0.34.1';
+
+// Interpret the GOG_READONLY kill-switch. `readEnvVar` already treats blank
+// values, 'undefined'/'null' sentinels, and unresolved .mcpb placeholders
+// ("${user_config.gog_readonly}") as unset. On top of that, GOG_READONLY is
+// deliberately fail-safe: any *set* value that isn't an explicit off value
+// (0/false/no/off) enables readonly — parseBoolEnv's `default: true` covers
+// unrecognised values (e.g. "enable"), so a typo blocks writes instead of
+// silently allowing them.
+function readonlyEnvEnabled(): boolean {
+  return readEnvVar('GOG_READONLY') !== undefined && parseBoolEnv('GOG_READONLY', { default: true });
 }
 
 // Strip ambient secrets from the child env so gogcli only sees its own
@@ -55,19 +110,25 @@ function sanitizedEnv(): NodeJS.ProcessEnv {
 // Redact bearer/refresh-token patterns from error text before surfacing
 // it back to the MCP client. If gog ever emits a token in stderr (e.g.
 // from a verbose log mode), this prevents it from leaking to the model.
-const TOKEN_PATTERNS: RegExp[] = [
-  /Bearer\s+[A-Za-z0-9._\-+/=]+/gi,
+// The shared mcp-utils redactSecrets covers Bearer/Basic headers, JWTs,
+// cookies, well-known key shapes (incl. Google AIza… API keys), and secret
+// query params — but not Google's OAuth2 token shapes, so those stay here.
+const GOOGLE_TOKEN_PATTERNS: RegExp[] = [
   /ya29\.[A-Za-z0-9._\-]+/g,           // OAuth2 access tokens
   /1\/\/[A-Za-z0-9._\-]+/g,            // OAuth2 refresh tokens
-  /AIza[A-Za-z0-9_\-]{35}/g,           // Google API keys
 ];
-export function redactSecrets(text: string): string {
+// Strip only Google's OAuth2 token shapes. Precise enough to leave an OAuth
+// consent URL (client_id, scope names, state, code_challenge) untouched.
+export function redactGoogleTokens(text: string): string {
   let redacted = text;
-  for (const re of TOKEN_PATTERNS) {
+  for (const re of GOOGLE_TOKEN_PATTERNS) {
     redacted = redacted.replace(re, '[REDACTED]');
   }
   return redacted;
 }
+export function redactSecrets(text: string): string {
+  return redactGoogleTokens(redactSharedSecrets(text));
+}
 
 // MCP desktop clients often spawn servers with a stripped PATH that excludes
 // Homebrew, user-local, and Go's default install dirs — so even when gog is
@@ -104,25 +165,78 @@ function formatTimeout(ms: number): string {
   return `${ms}ms`;
 }
 
-export async function run(args: string[], options: RunOptions = {}): Promise<string> {
-  const { account, spawner = spawn as unknown as Spawner, interactive = false, timeout } = options;
+// 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 },
+): Promise<string> {
+  const { mkdtemp, writeFile, rm } = await import('node:fs/promises');
+  const { tmpdir } = await import('node:os');
 
-  const effectiveAccount = account ?? envOrUndefined('GOG_ACCOUNT');
-
-  const fullArgs = ['--json', '--color=never'];
-  if (!interactive) {
-    fullArgs.push('--no-input');
+  // mkdtemp creates the directory with mode 0700 (owner-only) on POSIX, so the
+  // payload is never world-readable, not even for the instant between the
+  // directory appearing and writeFile's own 0600 mode landing.
+  const dir = await mkdtemp(join(tmpdir(), 'gogcli-mcp-'));
+  try {
+    const argv: string[] = [];
+    for (const arg of args) {
+      if (!isGogFileArg(arg)) {
+        argv.push(arg);
+        continue;
+      }
+      // Name the file after the flag: one command can carry two payloads
+      // (e.g. --body-file and --signature-file, both .txt), and a fixed
+      // basename would have the second silently clobber the first.
+      const path = join(dir, `${arg.flag}.${arg.ext ?? 'txt'}`);
+      await writeFile(path, arg.contents, { encoding: 'utf8', mode: 0o600 });
+      argv.push(`--${arg.flag}=${path}`);
+    }
+    return await spawnGog(argv, opts);
+  } finally {
+    // Never let a cleanup failure mask the real gog error (or a real result).
+    await rm(dir, { recursive: true, force: true }).catch(() => {});
   }
-  if (effectiveAccount) {
-    fullArgs.push('--account', effectiveAccount);
+}
+
+// Spawn-based executor. 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
+// in tests/runner.test.ts depend on.
+function spawnExecutor(
+  args: GogArg[],
+  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean },
+): Promise<string> {
+  if (args.some(isGogFileArg)) {
+    return spawnWithTempFiles(args, opts);
   }
-  fullArgs.push(...args);
+  return spawnGog(args as string[], opts);
+}
 
+// 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.
+
+async function spawnGog(
+  fullArgs: string[],
+  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean },
+): Promise<string> {
+  const { timeout, interactive = false, spawner, binary = false } = opts;
+  const spawn = spawner ?? (await import('node:child_process')).spawn as unknown as Spawner;
   const effectiveTimeout = timeout ?? TIMEOUT_MS;
 
   return new Promise((resolve, reject) => {
     const childEnv = { ...sanitizedEnv(), PATH: augmentedPath() };
-    const child = spawner(envOrUndefined('GOG_PATH') ?? 'gog', fullArgs, { env: childEnv });
+    const child = spawn(readEnvVar('GOG_PATH') ?? 'gog', fullArgs, { env: childEnv });
     const stdoutChunks: Buffer[] = [];
     const stderrChunks: Buffer[] = [];
     let settled = false;
@@ -140,16 +254,22 @@ export async function run(args: string[], options: RunOptions = {}): Promise<str
       clearTimeout(timer);
       if (settled) return;
       settled = true;
-      const stdout = Buffer.concat(stdoutChunks).toString();
       const stderr = Buffer.concat(stderrChunks).toString().trim();
       if (code === 0) {
+        // Binary mode: return the raw stdout bytes base64-encoded, never a utf8
+        // string (which would corrupt a PDF/image). No stderr append.
+        if (binary) {
+          resolve(Buffer.concat(stdoutChunks).toString('base64'));
+          return;
+        }
+        const stdout = Buffer.concat(stdoutChunks).toString();
         if (interactive && stderr) {
           resolve(stdout + '\n' + stderr);
         } else {
           resolve(stdout);
         }
       } else {
-        reject(new Error(redactSecrets(stderr || `gog exited with code ${code}`)));
+        reject(new Error(stderr || `gog exited with code ${code}`));
       }
     });
 
@@ -169,3 +289,78 @@ export async function run(args: string[], options: RunOptions = {}): Promise<str
     });
   });
 }
+
+// Assemble the full gog argv: the always-injected flags (--json/--color=never,
+// --no-input unless interactive, --readonly when opted in), --account, then the
+// caller's args. Shared by run() and runBinary() so both get identical flags.
+function assembleArgs(
+  args: GogArg[],
+  opts: { account?: string; interactive: boolean; readonly: boolean },
+): GogArg[] {
+  const effectiveAccount = opts.account ?? readEnvVar('GOG_ACCOUNT');
+  const fullArgs: GogArg[] = ['--json', '--color=never'];
+  if (!opts.interactive) {
+    fullArgs.push('--no-input');
+  }
+  // Block all mutating gog API requests at runtime when either the caller opts
+  // in or GOG_READONLY is set in the environment. gog has no native env binding
+  // for --readonly, so the wrapper translates GOG_READONLY into the flag.
+  if (opts.readonly || readonlyEnvEnabled()) {
+    fullArgs.push('--readonly');
+  }
+  if (effectiveAccount) {
+    fullArgs.push('--account', effectiveAccount);
+  }
+  fullArgs.push(...args);
+  return fullArgs;
+}
+
+export async function run(args: GogArg[], options: RunOptions = {}): Promise<string> {
+  const { account, spawner, interactive = false, timeout, readonly = false, redactMode = 'full' } = options;
+  const redact = redactMode === 'tokens' ? redactGoogleTokens : redactSecrets;
+
+  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 = runExecutor.getStore();
+  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);
+  } catch (err) {
+    throw new Error(redact((err as Error).message));
+  }
+}
+
+// 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.
+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 && runExecutor.getStore()) {
+    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/server.ts

@@ -1,5 +1,6 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { registerAuthTools } from './tools/auth.js';
+import type { ToolRegistrar } from '@chrischall/mcp-utils';
+import { registerApiTools } from './tools/api.js';
+import { registerAuthTools, authToolsFor } from './tools/auth.js';
 import { registerCalendarTools } from './tools/calendar.js';
 import { registerClassroomTools } from './tools/classroom.js';
 import { registerContactsTools } from './tools/contacts.js';
@@ -17,32 +18,27 @@ declare const GOGCLI_VERSION: string;
 /* v8 ignore next */
 export const VERSION = typeof GOGCLI_VERSION !== 'undefined' ? GOGCLI_VERSION : '0.0.0';
 
-export function createServer(options?: { name?: string; version?: string }): McpServer {
-  return new McpServer({
-    name: options?.name ?? 'gogcli',
-    version: options?.version ?? VERSION,
-  });
-}
-
-export function createBaseServer(options?: { name?: string; version?: string }): McpServer {
-  const server = createServer(options);
-
-  registerAuthTools(server);
-  registerCalendarTools(server);
-  registerClassroomTools(server);
-  registerContactsTools(server);
-  registerDocsTools(server);
-  registerDriveTools(server);
-  registerGmailTools(server);
-  registerSheetsTools(server);
-  registerSlidesTools(server);
-  registerTasksTools(server);
-
-  return server;
-}
+// Registrar list for the base (all-services) server, in runMcp's `tools`
+// shape. Sub-packages assemble their own list from the individual registrars
+// re-exported below.
+export const BASE_TOOL_REGISTRARS: ToolRegistrar[] = [
+  registerApiTools,
+  registerAuthTools,
+  registerCalendarTools,
+  registerClassroomTools,
+  registerContactsTools,
+  registerDocsTools,
+  registerDriveTools,
+  registerGmailTools,
+  registerSheetsTools,
+  registerSlidesTools,
+  registerTasksTools,
+];
 
 export {
+  registerApiTools,
   registerAuthTools,
+  authToolsFor,
   registerCalendarTools,
   registerClassroomTools,
   registerContactsTools,

package/src/tools/api.ts

@@ -0,0 +1,65 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { accountParam, runOrDiagnose } from './utils.js';
+
+// Generic Google Discovery API access (gog 0.31). gog_api_list / gog_api_describe
+// are read-only Discovery lookups; gog_api_call is a Discovery-backed escape
+// hatch for any method gog has no dedicated subcommand for — guarded by an
+// explicit write opt-in and a dry-run preview.
+export function registerApiTools(server: McpServer): void {
+  server.registerTool('gog_api_list', {
+    description: 'List the Google Discovery APIs available for gog_api_call / gog_api_describe (name + version + title).',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      all: z.boolean().optional().describe('Include every Discovery API (including preview/less-common ones) instead of the curated default set'),
+      account: accountParam,
+    },
+  }, async ({ all, account }) => {
+    const args = ['api', 'list'];
+    if (all) args.push('--all');
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_api_describe', {
+    description: 'Describe a Google Discovery API, or a single method within it — its parameters, request/response schema, and required OAuth scopes. Use this to discover the exact api/version/method and params before calling gog_api_call.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      api: z.string().describe('Discovery API name (e.g. drive, gmail, calendar)'),
+      version: z.string().describe('API version (e.g. v3, v1)'),
+      method: z.string().optional().describe('Optional method id to describe a single method (e.g. files.list); omit to describe the whole API'),
+      account: accountParam,
+    },
+  }, async ({ api, version, method, account }) => {
+    const args = ['api', 'describe', api, version];
+    if (method) args.push(method);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_api_call', {
+    description: 'Call any Discovery-described Google API method directly — an escape hatch for endpoints gog has no dedicated tool for. Find the exact api/version/method/params with gog_api_describe first. Read methods (GET/LIST) run as-is. Mutating methods (POST/PUT/PATCH/DELETE) are refused unless you set allowWrite=true — keep it false to preview, or set dryRun=true to print the intended request without sending it.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      api: z.string().describe('Discovery API name (e.g. drive, gmail, calendar)'),
+      version: z.string().describe('API version (e.g. v3, v1)'),
+      method: z.string().describe('Method id to call (e.g. files.list, files.create)'),
+      params: z.string().optional().describe('Query/path parameters as a JSON object string (e.g. {"fileId":"abc","fields":"name"})'),
+      body: z.string().optional().describe('Request body as a JSON string (for write methods)'),
+      scope: z.string().optional().describe('Override the OAuth scope used for the call'),
+      allowWrite: z.boolean().optional().describe('Required to invoke a mutating method (POST/PUT/PATCH/DELETE). Without it, gog refuses write methods. Leave unset for read-only calls.'),
+      dryRun: z.boolean().optional().describe('Print the intended request and exit without sending it (no changes made)'),
+      account: accountParam,
+    },
+  }, async ({ api, version, method, params, body, scope, allowWrite, dryRun, account }) => {
+    const args = ['api', 'call', api, version, method];
+    if (params) args.push(`--params=${params}`);
+    if (body) args.push(`--body=${body}`);
+    if (scope) args.push(`--scope=${scope}`);
+    // gog additionally gates mutating Discovery calls behind a confirmation;
+    // the runner injects --no-input, so --allow-write alone still refuses.
+    if (allowWrite) args.push('--allow-write');
+    if (dryRun) args.push('--dry-run');
+    // Fleet convention: --force is appended LAST (after --dry-run when both are set).
+    if (allowWrite) args.push('--force');
+    return runOrDiagnose(args, { account });
+  });
+}

package/src/tools/auth.ts

@@ -1,18 +1,27 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { run } from '../runner.js';
-import { toText, toError, runOrDiagnose, registerRunTool } from './utils.js';
+import { errorResult, rawTextResult } from '@chrischall/mcp-utils';
+import { errorText, formatAuthHealth, registerRunTool } from './utils.js';
 
-export function registerAuthTools(server: McpServer): void {
+// Register the auth tools with a specific least-privilege default `services`.
+// Kept internal so the exported `registerAuthTools` stays a bare
+// `(server) => void` ToolRegistrar; `authToolsFor` binds a narrower default.
+function registerAuthToolsWith(server: McpServer, defaultServices: string): void {
+  const servicesDescribe =
+    `Services to authorize: "all" or comma-separated list (e.g. "sheets,gmail,calendar"). ` +
+    `Default: "${defaultServices}". Prefer the narrowest set you need — requesting a service whose ` +
+    `Google API is not enabled on the OAuth client's project makes Google reject the WHOLE request ` +
+    `with invalid_scope.`;
   server.registerTool('gog_auth_list', {
     description: 'List all Google accounts stored in gogcli. Use this to check which accounts are configured and available.',
     annotations: { readOnlyHint: true },
     inputSchema: {},
   }, async () => {
     try {
-      return toText(await run(['auth', 'list']));
+      return rawTextResult(await run(['auth', 'list']));
     } catch (err) {
-      return toError(err);
+      return errorResult(errorText(err));
     }
   });
 
@@ -22,9 +31,29 @@ export function registerAuthTools(server: McpServer): void {
     inputSchema: {},
   }, async () => {
     try {
-      return toText(await run(['auth', 'status']));
+      return rawTextResult(await run(['auth', 'status']));
+    } catch (err) {
+      return errorResult(errorText(err));
+    }
+  });
+
+  server.registerTool('gog_auth_health', {
+    description:
+      'Check the LIVE health of each stored Google account. Unlike gog_auth_status (which only ' +
+      'reports keyring/config setup), this performs a real token refresh against Google, so it detects ' +
+      'expired or revoked (invalid_grant) refresh tokens — the account-wide sign-out that blocks every ' +
+      '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.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {},
+  }, async () => {
+    try {
+      // `run` injects --json; --check makes gog probe each token live.
+      return rawTextResult(formatAuthHealth(await run(['auth', 'list', '--check']), Date.now()));
     } catch (err) {
-      return toError(err);
+      return errorResult(errorText(err));
     }
   });
 
@@ -34,9 +63,9 @@ export function registerAuthTools(server: McpServer): void {
     inputSchema: {},
   }, async () => {
     try {
-      return toText(await run(['auth', 'services']));
+      return rawTextResult(await run(['auth', 'services']));
     } catch (err) {
-      return toError(err);
+      return errorResult(errorText(err));
     }
   });
 
@@ -50,25 +79,93 @@ export function registerAuthTools(server: McpServer): void {
     annotations: { destructiveHint: true },
     inputSchema: {
       email: z.string().describe('Google account email to authorize'),
-      services: z.string().optional().default('all').describe(
-        'Services to authorize: "all" or comma-separated list (e.g. "sheets,gmail,calendar"). Default: "all"',
-      ),
+      services: z.string().optional().default(defaultServices).describe(servicesDescribe),
     },
-  }, async ({ email, services = 'all' }) => {
+  }, async ({ email, services = defaultServices }) => {
     try {
-      return toText(await run(['auth', 'add', email, '--services', services], {
+      return rawTextResult(await run(['auth', 'add', email, '--services', services], {
         interactive: true,
         timeout: 300_000,
       }));
     } catch (err) {
-      return toError(err);
+      return errorResult(errorText(err));
+    }
+  });
+
+  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, ' +
+      '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 ' +
+      'gog_auth_add_complete or the second step will not match this one.',
+    inputSchema: {
+      email: z.string().describe('Google account email to authorize'),
+      services: z.string().optional().default(defaultServices).describe(servicesDescribe),
+    },
+  }, async ({ email, services = defaultServices }) => {
+    try {
+      // --force-consent guarantees a refresh token even if a prior grant exists
+      // (the whole point when recovering from a dead one). redactMode 'tokens'
+      // keeps the consent URL's scope names intact (the shared redactor mangles
+      // them) while still stripping any real token — a step-1 URL carries none.
+      return rawTextResult(await run(
+        ['auth', 'add', email, '--remote', '--step', '1', '--services', services, '--force-consent'],
+        { redactMode: 'tokens' },
+      ));
+    } catch (err) {
+      return errorResult(errorText(err));
+    }
+  });
+
+  server.registerTool('gog_auth_add_complete', {
+    description:
+      'Complete REMOTE/headless Google authorization (step 2 of 2). Takes the full redirected localhost ' +
+      'URL the user copied after finishing gog_auth_add_url, exchanges it for a refresh token, and stores ' +
+      'it. Use the SAME `services` value you passed to gog_auth_add_url. Must run within 10 minutes of ' +
+      'step 1 and against the same gogcli host.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      email: z.string().describe('Google account email being authorized (same as step 1)'),
+      redirectUrl: z.string().describe(
+        'The full localhost redirect URL the user copied from the browser address bar after signing in ' +
+        '(contains code and state; the page itself fails to load, which is expected).',
+      ),
+      services: z.string().optional().default(defaultServices).describe(
+        `Services authorized — MUST match the value passed to gog_auth_add_url. Default: "${defaultServices}".`,
+      ),
+    },
+  }, async ({ email, redirectUrl, services = defaultServices }) => {
+    try {
+      return rawTextResult(await run(
+        ['auth', 'add', email, '--remote', '--step', '2', '--auth-url', redirectUrl,
+          '--services', services, '--force-consent'],
+      ));
+    } catch (err) {
+      return errorResult(errorText(err));
     }
   });
 
   registerRunTool(server, {
     service: 'auth',
-    examples: '"remove", "alias", "tokens"',
+    examples: '"remove", "alias", "list"',
     omitAccount: true,
     note: 'For browser-based authorization, use gog_auth_add instead.',
   });
 }
+
+// The base all-services registrar: bare `(server) => void` so it drops straight
+// into BASE_TOOL_REGISTRARS / ToolRegistrar[]. Requests every service ('all').
+export function registerAuthTools(server: McpServer): void {
+  registerAuthToolsWith(server, 'all');
+}
+
+// A `registerAuthTools` bound to a least-privilege default `services`. A
+// single-service package/agent registers `authToolsFor('gmail')` instead of the
+// bare `registerAuthTools` so its re-auth requests only that service's scopes.
+// The base all-services package keeps the bare registrar (default 'all').
+export function authToolsFor(defaultServices: string): (server: McpServer) => void {
+  return (server) => registerAuthToolsWith(server, defaultServices);
+}