gogcli-mcp-gmail 2.7.1 → 2.18.0

package/src/tools/gmail-extra.ts

@@ -1,6 +1,36 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose, toText, type ToolResult } from '../../../gogcli-mcp/src/lib.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { rawTextResult, textResult, errorResult } from '@chrischall/mcp-utils';
+import { accountParam, runOrDiagnose, run, diagnose, payloadArg, runExecutor } from '../../../gogcli-mcp/src/lib.js';
+import type { GogArg } from '../../../gogcli-mcp/src/lib.js';
+
+// gog rejects an inline flag together with its --*-file twin — `gmail drafts
+// create` errors with "use only one of --body-html or --body-html-file", and
+// `gmail forward` does the same for --note (misreporting it as --body). Catch
+// the conflict here so the caller gets a message naming the TOOL params it
+// actually passed, instead of a gog error naming flags it never saw.
+function assertNotBoth(
+  inlineParam: string,
+  fileParam: string,
+  inlineValue: string | undefined,
+  fileValue: string | undefined,
+): void {
+  if (inlineValue !== undefined && fileValue !== undefined) {
+    throw new Error(
+      `${inlineParam} and ${fileParam} are mutually exclusive — gog accepts only one of them. ` +
+      `Pass ${inlineParam} with the content itself (it is written to a temp file automatically when large), ` +
+      `or ${fileParam} with a path that already exists on the gog server.`,
+    );
+  }
+}
+
+// Pull the text out of a single-text-block tool result; undefined for any
+// other shape (an error result is still a text block, so it parses below).
+function resultText(result: CallToolResult): string | undefined {
+  const first = result.content[0];
+  return first?.type === 'text' ? first.text : undefined;
+}
 
 type GmailHeader = { name?: string; value?: string };
 type GmailMessage = {
@@ -41,23 +71,248 @@ function summarizeMessage(m: GmailMessage): Record<string, unknown> {
 // message-limit flag, so this is done by post-processing its output. Any
 // non-JSON output (an error, an unexpected shape) is passed through untouched.
 function trimThread(
-  result: ToolResult,
+  result: CallToolResult,
   latestN: number | undefined,
   snippetsOnly: boolean | undefined,
-): ToolResult {
+): CallToolResult {
   try {
-    const parsed = JSON.parse(result.content[0].text) as { thread?: { messages?: unknown[] } };
+    const parsed = JSON.parse(resultText(result) ?? '') as { thread?: { messages?: unknown[] } };
     const messages = parsed.thread?.messages;
     if (!Array.isArray(messages)) return result;
     let trimmed: unknown[] = messages;
     if (latestN !== undefined) trimmed = trimmed.slice(-latestN);
     if (snippetsOnly) trimmed = trimmed.map((m) => summarizeMessage(m as GmailMessage));
-    return toText(JSON.stringify({ ...parsed, thread: { ...parsed.thread, messages: trimmed } }));
+    return rawTextResult(JSON.stringify({ ...parsed, thread: { ...parsed.thread, messages: trimmed } }));
   } catch {
     return result;
   }
 }
 
+// `gog gmail attachment --inline --json` emits these fields (NO filename, NO MIME
+// type): base64 content when the attachment is within gog's 3 MiB inline cap,
+// otherwise just the on-disk path plus a `reason` explaining the size fallback.
+type InlineAttachment = {
+  path?: string;
+  bytes?: number;
+  cached?: boolean;
+  contentBase64?: string;
+  reason?: string;
+};
+
+// One entry from `gog gmail get --json` `.attachments[]`: the message part
+// metadata, which carries the TRUE filename and MIME type that the download
+// endpoint itself does not report. `size` is the stable key we match on —
+// Gmail's `attachmentId` is NOT stable across calls (see resolveBySize).
+type AttachmentMeta = { filename?: string; mimeType?: string; attachmentId?: string; size?: number };
+
+// MIME type by file extension — the download endpoint reports none, and the
+// client needs it to render an inline image or label an embedded resource. Part
+// metadata (authoritative) and a magic-byte sniff (below) backstop this.
+const MIME_BY_EXT: Record<string, string> = {
+  pdf: 'application/pdf',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  bmp: 'image/bmp',
+  tiff: 'image/tiff',
+  heic: 'image/heic',
+  txt: 'text/plain',
+  csv: 'text/csv',
+  md: 'text/markdown',
+  json: 'application/json',
+  xml: 'application/xml',
+  html: 'text/html',
+  htm: 'text/html',
+  ics: 'text/calendar',
+  zip: 'application/zip',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+};
+
+// Reverse map for naming a part that carried no filename: MIME type → a canonical
+// extension. Deliberate: a known type must never be saved as `*.bin`. Later
+// entries win, so image/jpeg resolves to `jpeg` and text/html to `htm` — both fine.
+const EXT_BY_MIME: Record<string, string> = Object.fromEntries(
+  Object.entries(MIME_BY_EXT).map(([ext, mime]) => [mime, ext]),
+);
+
+// Lowercased extension of a filename, or '' if it has none.
+function extOf(name: string): string {
+  const dot = name.lastIndexOf('.');
+  return dot >= 0 ? name.slice(dot + 1).toLowerCase() : '';
+}
+
+// Make a caller- or part-supplied name safe as a SINGLE path segment: no
+// directory separators or traversal (it is interpolated into an --out path gog
+// creates server-side), no control chars, bounded length.
+function sanitizeFilename(name: string): string {
+  const base = name
+    .replace(/[/\\]+/g, '_')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1f]/g, '')
+    .replace(/^\.+/, '')
+    .trim()
+    .slice(0, 200);
+  return base || 'attachment';
+}
+
+// Leading magic bytes → MIME type, for the common binary attachments.
+const MAGIC_SIGNATURES: ReadonlyArray<readonly [string, string]> = [
+  ['%PDF', 'application/pdf'],
+  ['\x89PNG', 'image/png'],
+  ['\xFF\xD8\xFF', 'image/jpeg'],
+  ['GIF8', 'image/gif'],
+];
+
+// Sniff a MIME type from the leading bytes of standard base64; returns undefined
+// for anything unrecognised. gog emits standard base64, and any 4-aligned prefix
+// of a valid base64 string is itself valid, so atob never throws here.
+function sniffMime(base64: string): string | undefined {
+  const head = atob(base64.slice(0, 16)); // 4-aligned slice; decodes to ~12 bytes
+  for (const [signature, mimeType] of MAGIC_SIGNATURES) {
+    if (head.startsWith(signature)) return mimeType;
+  }
+  return undefined;
+}
+
+// Resolve the real filename + MIME type from the message part metadata
+// (`gog gmail get` `.attachments[]`), which the download endpoint doesn't return.
+// A lightweight metadata read — no body bytes.
+//
+// The match is by SIZE, not attachmentId: Gmail's attachmentId is not stable
+// across API calls (a fresh `get` re-issues a different id for the same part, as
+// verified live), so the caller's id can't be matched against a fresh listing.
+// The downloaded byte count is stable and, in practice, unique per message — so
+// it identifies the part. An ambiguous (repeated) size yields undefined, and the
+// caller falls back to a magic-byte sniff + a MIME-derived name.
+async function resolveBySize(
+  messageId: string,
+  sizeBytes: number | undefined,
+  account: string | undefined,
+): Promise<AttachmentMeta | undefined> {
+  if (sizeBytes === undefined) return undefined;
+  try {
+    const parsed = JSON.parse(await run(['gmail', 'get', messageId], { account })) as {
+      attachments?: AttachmentMeta[];
+    };
+    const matches = (parsed.attachments ?? []).filter((a) => a.size === sizeBytes);
+    return matches.length === 1 ? matches[0] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// A writable, ephemeral server-side output path. gog MkdirAll's the tree, and
+// /tmp is writable on both the local host and the Fly backend AND is cleared when
+// the machine stops — unlike gog's default (the gogcli config dir), which on the
+// Fly volume would accumulate downloaded attachments indefinitely.
+function defaultOutPath(messageId: string, filename: string): string {
+  return `/tmp/gog-attachments/${messageId}/${filename}`;
+}
+
+// Strip the command echo and any message/attachment ids from a gog failure before
+// it reaches the caller. On the Fly backend gog runs under execFile, whose error
+// message is `Command failed: gog gmail attachment <msg> <token> ...\n<stderr>` —
+// leaking the full command line (opaque attachment token included) and a raw shell
+// error such as `mkdir /home/claude: permission denied`. Keep only the stderr
+// tail, with the ids redacted.
+function sanitizeAttachmentError(err: unknown, messageId: string, attachmentId: string): string {
+  let msg = err instanceof Error ? err.message : String(err);
+  msg = msg.replace(/^Command failed:.*(\n|$)/, ''); // drop the command echo line
+  msg = msg.split(attachmentId).join('<attachment>').split(messageId).join('<message>');
+  return msg.trim() || 'the download failed on the server';
+}
+
+// The attachment bytes as a native image block (so clients render them). A
+// leading text block summarises the attachment for the model.
+function inlineImageResult(summary: string, base64: string, mimeType: string): CallToolResult {
+  return { content: [{ type: 'text', text: summary }, { type: 'image', data: base64, mimeType }] };
+}
+
+// The attachment bytes as an MCP embedded-resource blob. Only some hosts render
+// or accept non-image resources (claude.ai currently rejects application/pdf),
+// so this is reserved for the explicit deliver="inline" escape hatch — deliver
+// "auto" never routes bytes the host would silently drop through here.
+function inlineResourceResult(
+  messageId: string,
+  filename: string,
+  summary: string,
+  base64: string,
+  mimeType: string,
+): CallToolResult {
+  return {
+    content: [
+      { type: 'text', text: summary },
+      {
+        type: 'resource',
+        resource: { uri: `gmail-attachment://${messageId}/${filename}`, mimeType, blob: base64 },
+      },
+    ],
+  };
+}
+
+// A file-path delivery: the bytes were written server-side and the caller reads
+// them from `path`. Used on the local (stdio) transport, where the caller shares
+// the filesystem — the remote connector uses Drive instead.
+function fileResult(
+  path: string,
+  fileName: string,
+  mimeType: string,
+  bytes: number | undefined,
+): CallToolResult {
+  return textResult({
+    delivery: 'file',
+    path,
+    fileName,
+    mimeType,
+    bytes,
+    note: 'Saved on the server filesystem — read it from `path`.',
+  });
+}
+
+// Prepend an advisory note (e.g. why a caller-supplied `out` was ignored) to a
+// result's content, or return it unchanged when there is nothing to say.
+function withNote(result: CallToolResult, notes: string[]): CallToolResult {
+  if (notes.length === 0) return result;
+  return { ...result, content: [{ type: 'text', text: notes.join(' ') }, ...result.content] };
+}
+
+// Upload the file gog wrote (server-side, on the same box that ran the download)
+// to Google Drive and return its metadata + shareable link. This is how a large
+// or non-renderable attachment — one the connector can't hand back inline —
+// reaches the caller.
+async function deliverViaDrive(
+  path: string,
+  name: string,
+  driveFolder: string | undefined,
+  account: string | undefined,
+): Promise<CallToolResult> {
+  const args = ['drive', 'upload', path, '--json'];
+  if (driveFolder) args.push(`--parent=${driveFolder}`);
+  args.push(`--name=${name}`); // callers always resolve a filename first
+  // `gog drive upload --json` wraps the created file under a `file` key.
+  const parsed = JSON.parse(await run(args, { account })) as {
+    file?: { id?: string; name?: string; mimeType?: string; size?: number | string; webViewLink?: string };
+  };
+  const file = parsed.file ?? {};
+  return textResult({
+    deliveredVia: 'drive',
+    note: 'Attachment delivered via Google Drive; open or download it at webViewLink.',
+    id: file.id,
+    name: file.name,
+    mimeType: file.mimeType,
+    size: file.size,
+    webViewLink: file.webViewLink,
+  });
+}
+
 export function registerExtraGmailTools(server: McpServer): void {
   server.registerTool('gog_gmail_raw', {
     description: 'Dump the raw Gmail API response as JSON (lossless; for scripting and LLM consumption).',
@@ -76,20 +331,126 @@ export function registerExtraGmailTools(server: McpServer): void {
   });
 
   server.registerTool('gog_gmail_attachment', {
-    description: 'Download a single attachment from a Gmail message.',
-    annotations: { readOnlyHint: true },
+    description:
+      'Download a Gmail attachment and deliver its contents so you can actually read them. The real filename ' +
+      'and MIME type are resolved from the message part metadata, so the saved file and response are named ' +
+      'correctly (e.g. Guest_Copy.pdf), never a generic *.bin. deliver="auto" (default) is transport-aware: ' +
+      'images always come back as a native image block; anything else is delivered by the channel that works ' +
+      'on your transport — a readable server-side file PATH on local (stdio) clients that share the filesystem, ' +
+      'or a Google Drive link on the remote connector (whose backend filesystem you can\'t read, and which ' +
+      'rejects inline PDF/binary blobs). deliver="inline" forces the bytes inline as an image or embedded ' +
+      'resource blob (use only if your client consumes resource blobs; errors if over gog\'s 3 MiB cap). ' +
+      'deliver="drive" always uploads to Drive; deliver="off" writes the file server-side and returns ' +
+      '{path, fileName, mimeType, bytes}. Drive delivery creates a file in your Drive (blocked when GOG_READONLY is set).',
     inputSchema: {
       messageId: z.string().describe('Gmail message ID'),
       attachmentId: z.string().describe('Attachment ID (from the message payload)'),
-      out: z.string().optional().describe('Output file path (default: gogcli config dir)'),
-      name: z.string().optional().describe('Filename (used when --out is empty or points to a directory)'),
+      deliver: z
+        .enum(['auto', 'inline', 'drive', 'off'])
+        .optional()
+        .describe('How to return the contents: auto (image inline; else a local file path or a Drive link, per transport), inline (force bytes as image/resource blob), drive (always a Drive link), or off (server-side download only). Default: auto.'),
+      out: z.string().optional().describe('Server-side path where gog writes the file. NOTE: this resolves on the CONNECTOR/gog server\'s filesystem, not your machine — on the remote connector it is ignored (you can\'t read it; you get a Drive link instead). Locally it is honored. Omit it to use an ephemeral temp path.'),
+      name: z.string().optional().describe('Filename override. Defaults to the attachment\'s real filename from the message metadata; pass this to skip that lookup or force a name.'),
+      driveFolder: z.string().optional().describe('Destination Google Drive folder ID for the uploaded copy (drive/auto delivery on the remote connector, or oversized attachments).'),
       account: accountParam,
     },
-  }, async ({ messageId, attachmentId, out, name, account }) => {
-    const args = ['gmail', 'attachment', messageId, attachmentId];
-    if (out) args.push(`--out=${out}`);
-    if (name) args.push(`--name=${name}`);
-    return runOrDiagnose(args, { account });
+  }, async ({ messageId, attachmentId, deliver = 'auto', out, name, driveFolder, account }) => {
+    // On the remote connector, `run` forwards to the Fly backend and this store
+    // is set; on local stdio it is unset. It is the one signal that tells apart
+    // "the caller shares my filesystem" (stdio → deliver a path) from "the caller
+    // can't read my disk and rejects binary blobs" (connector → deliver a Drive
+    // link). It also decides whether a caller-supplied `out` is meaningful.
+    const remote = runExecutor.getStore() !== undefined;
+    try {
+      // 1. Start from the caller's `name` (the recommended path — the caller got
+      //    the attachmentId from a listing that also carried the filename). The
+      //    download endpoint reports neither name nor MIME; when `name` is absent
+      //    we resolve them AFTER downloading, by matching the byte count against
+      //    the part metadata (attachmentIds aren't stable enough to match on).
+      let filename = name ? sanitizeFilename(name) : undefined;
+      let mimeType: string | undefined = filename ? MIME_BY_EXT[extOf(filename)] : undefined;
+
+      // 2. Choose the server-side output path. A caller `out` only makes sense on
+      //    the local transport; on the connector it resolves on the backend the
+      //    caller can't read, so ignore it (with a note) and use a temp path. The
+      //    on-disk basename is provisional when `name` is absent; the response
+      //    still reports the resolved filename.
+      const notes: string[] = [];
+      let outPath = out;
+      if (out && remote) {
+        notes.push("`out` was ignored: it resolves on the connector's server filesystem, which you can't read.");
+        outPath = undefined;
+      }
+      if (!outPath) outPath = defaultOutPath(messageId, filename ?? 'attachment');
+
+      // 3. Download. --inline returns the bytes for the image/resource cases; skip
+      //    it when we already know delivery is by path or Drive (don't ship base64
+      //    only to discard it). When the MIME type is still unknown we must
+      //    --inline to sniff it from the bytes.
+      let needInline = deliver === 'auto' || deliver === 'inline';
+      if (deliver === 'auto' && remote && mimeType && !mimeType.startsWith('image/')) {
+        needInline = false; // headed to Drive anyway
+      }
+      if (!mimeType && (deliver === 'auto' || deliver === 'inline')) {
+        needInline = true; // need the bytes to sniff the type
+      }
+      const args = ['gmail', 'attachment', messageId, attachmentId];
+      if (needInline) args.push('--inline');
+      args.push(`--out=${outPath}`, `--name=${filename ?? 'attachment'}`);
+      const info = JSON.parse(await run(args, { account })) as InlineAttachment;
+      const path = info.path ?? outPath;
+
+      // 4. Resolve the real filename/MIME when `name` wasn't supplied, by matching
+      //    the downloaded byte count against the part metadata.
+      if (!filename) {
+        const meta = await resolveBySize(messageId, info.bytes, account);
+        if (meta?.filename) filename = sanitizeFilename(meta.filename);
+        if (!mimeType && meta?.mimeType) mimeType = meta.mimeType;
+      }
+      if (!mimeType && info.contentBase64) mimeType = sniffMime(info.contentBase64);
+      mimeType = mimeType ?? 'application/octet-stream';
+      // Still no filename → derive one from the MIME type; never leave it *.bin.
+      if (!filename) {
+        const ext = EXT_BY_MIME[mimeType];
+        filename = ext ? `attachment.${ext}` : 'attachment';
+      }
+      const isImage = mimeType.startsWith('image/');
+      const summary = `${filename} — ${info.bytes ?? '?'} bytes, ${mimeType}, returned inline.`;
+
+      // 5. Deliver by the requested channel. Every delivery is wrapped with
+      //    `notes` so an ignored-`out` explanation is never silently dropped,
+      //    whatever the mode or type.
+      if (deliver === 'off') {
+        return withNote(textResult({ delivery: 'file', path, cached: info.cached, bytes: info.bytes, fileName: filename, mimeType }), notes);
+      }
+      if (deliver === 'drive') {
+        return withNote(await deliverViaDrive(path, filename, driveFolder, account), notes);
+      }
+      if (deliver === 'inline') {
+        if (info.contentBase64) {
+          return withNote(isImage
+            ? inlineImageResult(summary, info.contentBase64, mimeType)
+            : inlineResourceResult(messageId, filename, summary, info.contentBase64, mimeType), notes);
+        }
+        return errorResult(
+          `Attachment is too large to return inline (${info.reason ?? "exceeds gog's 3 MiB inline limit"}). ` +
+          'Use deliver="auto" or deliver="drive" to receive it as a Google Drive link.',
+        );
+      }
+      // deliver === 'auto': images render everywhere; everything else goes by the
+      // channel that works on this transport.
+      if (isImage && info.contentBase64) {
+        return withNote(inlineImageResult(summary, info.contentBase64, mimeType), notes);
+      }
+      if (remote) {
+        return withNote(await deliverViaDrive(path, filename, driveFolder, account), notes);
+      }
+      return withNote(fileResult(path, filename, mimeType, info.bytes), notes);
+    } catch (err) {
+      // Never surface gog's raw error (it echoes the full command line + attachment
+      // token on the backend); redact the ids and let diagnose classify the rest.
+      return diagnose(new Error(sanitizeAttachmentError(err, messageId, attachmentId)));
+    }
   });
 
   server.registerTool('gog_gmail_url', {
@@ -122,11 +483,12 @@ export function registerExtraGmailTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
-  const bulkActions: Array<{ tool: string; cmd: string; description: string }> = [
+  const bulkActions: Array<{ tool: string; cmd: string; description: string; supportsThread?: boolean }> = [
     {
       tool: 'gog_gmail_archive',
       cmd: 'archive',
-      description: 'Archive messages (remove from inbox). Pass either messageIds or a Gmail search query.',
+      description: 'Archive messages (remove from inbox). Pass either messageIds or a Gmail search query. Set thread=true to treat the ids as THREAD ids and archive every message in each thread (the right mode for ids that came from thread search).',
+      supportsThread: true,
     },
     {
       tool: 'gog_gmail_mark_read',
@@ -145,21 +507,29 @@ export function registerExtraGmailTools(server: McpServer): void {
     },
   ];
 
-  for (const { tool, cmd, description } of bulkActions) {
+  for (const { tool, cmd, description, supportsThread } of bulkActions) {
+    const inputSchema: Record<string, z.ZodTypeAny> = {
+      messageIds: z.array(z.string()).optional().describe('Specific message IDs to act on'),
+      query: z.string().optional().describe('Gmail search query (alternative to messageIds; acts on all matching)'),
+      max: z.number().optional().describe('Max messages when using --query (default: 100)'),
+      account: accountParam,
+    };
+    if (supportsThread) {
+      inputSchema.thread = z.boolean().optional().describe('Treat messageIds as THREAD ids and act on every message in each thread');
+    }
     server.registerTool(tool, {
       description,
       annotations: { destructiveHint: true },
-      inputSchema: {
-        messageIds: z.array(z.string()).optional().describe('Specific message IDs to act on'),
-        query: z.string().optional().describe('Gmail search query (alternative to messageIds; acts on all matching)'),
-        max: z.number().optional().describe('Max messages when using --query (default: 100)'),
-        account: accountParam,
-      },
-    }, async ({ messageIds, query, max, account }) => {
+      inputSchema,
+    }, async (rawArgs) => {
+      const { messageIds, query, max, thread, account } = rawArgs as {
+        messageIds?: string[]; query?: string; max?: number; thread?: boolean; account?: string;
+      };
       const args = ['gmail', cmd];
       if (messageIds) args.push(...messageIds);
       if (query) args.push(`--query=${query}`);
       if (max !== undefined) args.push(`--max=${max}`);
+      if (supportsThread && thread) args.push('--thread');
       return runOrDiagnose(args, { account });
     });
   }
@@ -181,14 +551,17 @@ export function registerExtraGmailTools(server: McpServer): void {
   });
 
   server.registerTool('gog_gmail_batch_delete', {
-    description: 'Permanently delete multiple messages (requires the broader Gmail scope). Use gog_gmail_trash for normal deletes.',
+    description: 'Permanently delete multiple messages (requires the broader Gmail scope; not reversible — messages bypass Trash). Requires force:true to delete non-interactively. Use gog_gmail_trash for normal deletes.',
     annotations: { destructiveHint: true },
     inputSchema: {
       messageIds: z.array(z.string()).min(1).describe('Message IDs to permanently delete'),
+      force: z.boolean().optional().describe('Required to delete in this non-interactive context — without it the delete is refused as a safety guard.'),
       account: accountParam,
     },
-  }, async ({ messageIds, account }) => {
-    return runOrDiagnose(['gmail', 'batch', 'delete', ...messageIds], { account });
+  }, async ({ messageIds, force, account }) => {
+    const args = ['gmail', 'batch', 'delete', ...messageIds];
+    if (force) args.push('--force');
+    return runOrDiagnose(args, { account });
   });
 
   server.registerTool('gog_gmail_batch_modify', {
@@ -248,12 +621,12 @@ export function registerExtraGmailTools(server: McpServer): void {
   });
 
   server.registerTool('gog_gmail_thread_attachments', {
-    description: 'List all attachments in a Gmail thread, optionally downloading them.',
+    description: 'List all attachments in a Gmail thread, optionally downloading them. NOTE: download/outDir write to the CONNECTOR/gog server\'s filesystem — on the remote connector you can\'t read those files, so use gog_gmail_attachment per attachment to receive bytes (image inline, or a Drive link). This tool is best used just to LIST attachments (filenames, ids, sizes) and then fetch the ones you want individually.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       threadId: z.string().describe('Gmail thread ID'),
-      download: z.boolean().optional().describe('Download all attachments'),
-      outDir: z.string().optional().describe('Directory to write attachments to (default: current directory)'),
+      download: z.boolean().optional().describe('Download all attachments to the SERVER filesystem (see the note above; on the remote connector the files aren\'t reachable — fetch individually with gog_gmail_attachment instead).'),
+      outDir: z.string().optional().describe('Directory to write attachments to, resolved on the gog SERVER\'s filesystem (default: current directory). Not your local machine on the remote connector.'),
       account: accountParam,
     },
   }, async ({ threadId, download, outDir, account }) => {
@@ -314,7 +687,7 @@ export function registerExtraGmailTools(server: McpServer): void {
       account: accountParam,
     },
   }, async ({ labelIdOrName, account }) => {
-    return runOrDiagnose(['gmail', 'labels', 'delete', labelIdOrName], { account });
+    return runOrDiagnose(['gmail', 'labels', 'delete', labelIdOrName, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_gmail_labels_modify', {
@@ -369,12 +742,14 @@ export function registerExtraGmailTools(server: McpServer): void {
     cc: z.string().optional().describe('CC recipients (comma-separated)'),
     bcc: z.string().optional().describe('BCC recipients (comma-separated)'),
     subject: z.string().describe('Subject'),
-    body: z.string().describe('Body (plain text)'),
-    bodyHtml: z.string().optional().describe('Body (HTML; optional)'),
+    body: z.string().describe('Body (plain text). Any size — a large body is written to a temp file on the gog server rather than inlined into the command line. Note gog strips trailing newlines from a file-delivered body.'),
+    bodyHtml: z.string().optional().describe('Body (HTML; optional). Pass the HTML itself at any size — a large body is written to a temp file on the gog server rather than inlined into the command line. Mutually exclusive with bodyHtmlFile.'),
+    bodyHtmlFile: z.string().optional().describe('Path to an HTML file that ALREADY EXISTS on the gog server to use as the HTML body, or "-" to read from stdin. Mutually exclusive with bodyHtml — supplying both is rejected. You rarely need this: bodyHtml handles large bodies on its own.'),
     replyToMessageId: z.string().optional().describe('Reply to a specific Gmail MESSAGE id — the short hex `id` field from gog_gmail_get / _search / _thread_get (e.g. 19e7593d77fd9636), NOT a thread id and NOT the RFC822 `<…@host>` Message-Id header. Anchors In-Reply-To/References to that exact message. To reply to a thread when you don\'t know the latest message, use replyToThreadId instead. If both are given, replyToMessageId wins.'),
     replyToThreadId: z.string().optional().describe('Reply to a Gmail THREAD id — passed to gog as --thread-id, which threads the draft using the thread\'s latest-message headers (In-Reply-To/References). This is what "reply to this thread" almost always means. Mutually exclusive with replyToMessageId (which wins if both are set). Thread ids and message ids are both 16-hex strings and easy to confuse — use this param, not replyToMessageId, when the id came from a thread.'),
     replyTo: z.string().optional().describe('Reply-To header address'),
     quote: z.boolean().optional().describe('Include quoted original message in reply (requires replyToMessageId or replyToThreadId)'),
+    replyAll: z.boolean().optional().describe('Auto-populate recipients from the original message (reply-all), inferring To/Cc from it. Requires replyToMessageId or replyToThreadId. Explicit to/cc/bcc still apply on top; omitRecipients still suppresses them.'),
     attach: z.array(z.string()).optional().describe('Local file paths to attach (repeatable). Read on the gog server, base64-encoded with a MIME type inferred from the extension. The JSON result echoes attached filenames and byte sizes — check it to confirm the files were found and embedded. On gog_gmail_drafts_update, supplying attach REPLACES the draft\'s existing attachments; omitting it preserves them (use clearAttachments to remove all).'),
     from: z.string().optional().describe('Send from this email address (must be a verified send-as alias)'),
     omitRecipients: z.boolean().optional().describe('Create the draft with no recipients even if to/cc/bcc are supplied — an accidental-send guard. Populate recipients in a later update before sending.'),
@@ -389,29 +764,37 @@ export function registerExtraGmailTools(server: McpServer): void {
     subject: string;
     body: string;
     bodyHtml?: string;
+    bodyHtmlFile?: string;
     replyToMessageId?: string;
     replyToThreadId?: string;
     replyTo?: string;
     quote?: boolean;
+    replyAll?: boolean;
     attach?: string[];
     from?: string;
     omitRecipients?: boolean;
   };
 
-  function appendDraftFlags(args: string[], f: DraftFlags): void {
+  function appendDraftFlags(args: GogArg[], f: DraftFlags): void {
+    assertNotBoth('bodyHtml', 'bodyHtmlFile', f.bodyHtml, f.bodyHtmlFile);
     if (!f.omitRecipients) {
       if (f.to) args.push(`--to=${f.to}`);
       if (f.cc) args.push(`--cc=${f.cc}`);
       if (f.bcc) args.push(`--bcc=${f.bcc}`);
     }
     args.push(`--subject=${f.subject}`);
-    args.push(`--body=${f.body}`);
-    if (f.bodyHtml) args.push(`--body-html=${f.bodyHtml}`);
+    // body is required, so this is an either/or swap rather than an extra push:
+    // --body and --body-file together are a hard error in gog.
+    args.push(payloadArg('body', 'body-file', f.body));
+    if (f.bodyHtml) args.push(payloadArg('body-html', 'body-html-file', f.bodyHtml, 'html'));
+    else if (f.bodyHtmlFile) args.push(`--body-html-file=${f.bodyHtmlFile}`);
     // A draft can reply to a specific message (--reply-to-message-id) or thread
     // off the latest message in a thread (--thread-id, which gog resolves
     // server-side). replyToMessageId wins when both are supplied.
     if (f.replyToMessageId) args.push(`--reply-to-message-id=${f.replyToMessageId}`);
     else if (f.replyToThreadId) args.push(`--thread-id=${f.replyToThreadId}`);
+    // --reply-all infers original recipients; gog requires a reply target above.
+    if (f.replyAll) args.push('--reply-all');
     if (f.replyTo) args.push(`--reply-to=${f.replyTo}`);
     if (f.quote) args.push('--quote');
     if (f.attach) for (const path of f.attach) args.push(`--attach=${path}`);
@@ -424,20 +807,20 @@ export function registerExtraGmailTools(server: McpServer): void {
   // front; for creates it's read from the write response's draftId. Degrades to
   // the raw write result if the id can't be determined.
   async function writeDraft(
-    args: string[],
+    args: GogArg[],
     account: string | undefined,
     returnFull: boolean | undefined,
     knownDraftId?: string,
-  ): Promise<ToolResult> {
+  ): Promise<CallToolResult> {
     const result = await runOrDiagnose(args, { account });
     if (!returnFull) return result;
     // The write must have returned a JSON acknowledgement before we re-fetch.
-    // A failed write (an error ToolResult, not JSON) is surfaced as-is rather
+    // A failed write (an error result, not JSON) is surfaced as-is rather
     // than masked by re-fetching the unchanged draft — this matters for the
     // update path, where a known draftId would otherwise re-fetch a stale draft.
     let parsed: { draftId?: string };
     try {
-      parsed = JSON.parse(result.content[0].text) as { draftId?: string };
+      parsed = JSON.parse(resultText(result) ?? '') as { draftId?: string };
     } catch {
       return result;
     }
@@ -450,7 +833,7 @@ export function registerExtraGmailTools(server: McpServer): void {
     description: 'Create a new Gmail draft. Recipients (to/cc/bcc) are optional; omit them (or set omitRecipients) to create a recipient-less draft as an accidental-send guard. For replies, prefer replyToThreadId (anchors to the thread\'s latest message) or replyToMessageId (a specific message) — don\'t pass a thread id into replyToMessageId, which mis-threads silently.',
     inputSchema: draftWriteSchema,
   }, async ({ account, returnFull, ...flags }) => {
-    const args = ['gmail', 'drafts', 'create'];
+    const args: GogArg[] = ['gmail', 'drafts', 'create'];
     appendDraftFlags(args, flags);
     return writeDraft(args, account, returnFull);
   });
@@ -464,7 +847,7 @@ export function registerExtraGmailTools(server: McpServer): void {
       clearAttachments: z.boolean().optional().describe('Remove all attachments from the draft. By default, omitting attach preserves the draft\'s existing attachments; this intentionally clears them. Ignored if attach is also supplied (attach replaces).'),
     },
   }, async ({ draftId, account, returnFull, clearAttachments, ...flags }) => {
-    const args = ['gmail', 'drafts', 'update', draftId];
+    const args: GogArg[] = ['gmail', 'drafts', 'update', draftId];
     appendDraftFlags(args, flags);
     if (clearAttachments) args.push('--clear-attachments');
     return writeDraft(args, account, returnFull, draftId);
@@ -509,15 +892,95 @@ export function registerExtraGmailTools(server: McpServer): void {
       account: accountParam,
     },
   }, async ({ messageId, to, cc, bcc, note, from, skipAttachments, account }) => {
-    const args = ['gmail', 'forward', messageId, `--to=${to}`];
+    const args: GogArg[] = ['gmail', 'forward', messageId, `--to=${to}`];
     if (cc) args.push(`--cc=${cc}`);
     if (bcc) args.push(`--bcc=${bcc}`);
-    if (note) args.push(`--note=${note}`);
+    if (note) args.push(payloadArg('note', 'note-file', note));
     if (from) args.push(`--from=${from}`);
     if (skipAttachments) args.push('--skip-attachments');
     return runOrDiagnose(args, { account });
   });
 
+  // gmail reply / reply-all share an identical flag set (gog 0.27+); they differ
+  // only in the subcommand and default recipient set (reply → sender; reply-all
+  // → every participant). Recipient flags are repeatable on the CLI, so they are
+  // arrays here. --to/--cc/--bcc ADD or MOVE recipients onto the inherited reply
+  // set; --remove drops them. Body/HTML follow the same inline-or-file shape as
+  // the draft tools.
+  const replySchema = {
+    messageId: z.string().describe('Gmail message ID to reply to — the short hex `id` from gog_gmail_get / _search / _messages_search (NOT the threadId, NOT the RFC822 `<…@host>` Message-Id header).'),
+    body: z.string().optional().describe('Reply body (plain text; required unless bodyHtml or bodyHtmlFile is set). Any size — a large body is written to a temp file on the gog server rather than inlined into the command line. Note gog strips trailing newlines from a file-delivered body.'),
+    bodyHtml: z.string().optional().describe('Reply body (HTML; optional). Pass the HTML itself at any size — a large body is written to a temp file on the gog server rather than inlined into the command line. Mutually exclusive with bodyHtmlFile.'),
+    bodyHtmlFile: z.string().optional().describe('Path to an HTML file that ALREADY EXISTS on the gog server for the reply body, or "-" for stdin. Mutually exclusive with bodyHtml — supplying both is rejected. You rarely need this: bodyHtml handles large bodies on its own.'),
+    to: z.array(z.string()).optional().describe('Add or move recipients to To (repeatable). Added on top of the recipients inherited from the original message.'),
+    cc: z.array(z.string()).optional().describe('Add or move recipients to Cc (repeatable)'),
+    bcc: z.array(z.string()).optional().describe('Add or move recipients to Bcc (repeatable)'),
+    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('Local file paths to attach (repeatable). Read on the gog server, base64-encoded with a MIME type inferred from the extension.'),
+    from: z.string().optional().describe('Send from this email address (must be a verified send-as alias)'),
+    signature: z.boolean().optional().describe('Append the Gmail signature from the active send-as address'),
+    signatureFrom: z.string().optional().describe('Append the Gmail signature from this send-as email address'),
+    signatureFile: z.string().optional().describe('Append a local signature file (plain text or HTML), read on the gog server'),
+    account: accountParam,
+  };
+
+  type ReplyFlags = {
+    body?: string;
+    bodyHtml?: string;
+    bodyHtmlFile?: string;
+    to?: string[];
+    cc?: string[];
+    bcc?: string[];
+    remove?: string[];
+    subject?: string;
+    noQuote?: boolean;
+    attach?: string[];
+    from?: string;
+    signature?: boolean;
+    signatureFrom?: string;
+    signatureFile?: string;
+  };
+
+  function appendReplyFlags(args: GogArg[], f: ReplyFlags): void {
+    assertNotBoth('bodyHtml', 'bodyHtmlFile', f.bodyHtml, f.bodyHtmlFile);
+    if (f.body) args.push(payloadArg('body', 'body-file', f.body));
+    if (f.bodyHtml) args.push(payloadArg('body-html', 'body-html-file', f.bodyHtml, 'html'));
+    else if (f.bodyHtmlFile) args.push(`--body-html-file=${f.bodyHtmlFile}`);
+    if (f.to) for (const r of f.to) args.push(`--to=${r}`);
+    if (f.cc) for (const r of f.cc) args.push(`--cc=${r}`);
+    if (f.bcc) for (const r of f.bcc) args.push(`--bcc=${r}`);
+    if (f.remove) for (const r of f.remove) args.push(`--remove=${r}`);
+    if (f.subject) args.push(`--subject=${f.subject}`);
+    if (f.noQuote) args.push('--no-quote');
+    if (f.attach) for (const p of f.attach) args.push(`--attach=${p}`);
+    if (f.from) args.push(`--from=${f.from}`);
+    if (f.signature) args.push('--signature');
+    if (f.signatureFrom) args.push(`--signature-from=${f.signatureFrom}`);
+    if (f.signatureFile) args.push(`--signature-file=${f.signatureFile}`);
+  }
+
+  server.registerTool('gog_gmail_reply', {
+    description: 'Reply to a Gmail message (sends to the original sender only). Threads off the message and inherits a "Re:" subject and the quoted original by default. For replying to every participant use gog_gmail_reply_all; to reply across many messages matching a query use gog_gmail_autoreply; to stage a reply without sending use gog_gmail_drafts_create.',
+    annotations: { destructiveHint: true },
+    inputSchema: replySchema,
+  }, async ({ messageId, account, ...flags }) => {
+    const args: GogArg[] = ['gmail', 'reply', messageId];
+    appendReplyFlags(args, flags);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_gmail_reply_all', {
+    description: 'Reply to all participants of a Gmail message (sender plus every To/Cc recipient). Same inherited "Re:" subject and quoting as gog_gmail_reply. Use the remove flag to drop specific recipients from the reply-all.',
+    annotations: { destructiveHint: true },
+    inputSchema: replySchema,
+  }, async ({ messageId, account, ...flags }) => {
+    const args: GogArg[] = ['gmail', 'reply-all', messageId];
+    appendReplyFlags(args, flags);
+    return runOrDiagnose(args, { account });
+  });
+
   server.registerTool('gog_gmail_autoreply', {
     description: 'Reply once to all messages matching a Gmail search query. Use the label flag to dedupe across runs.',
     annotations: { destructiveHint: true },
@@ -537,10 +1000,13 @@ export function registerExtraGmailTools(server: McpServer): void {
       account: accountParam,
     },
   }, async ({ query, max, subject, body, bodyHtml, from, replyTo, label, archive, markRead, skipBulk, allowSelf, account }) => {
-    const args = ['gmail', 'autoreply', query];
+    const args: GogArg[] = ['gmail', 'autoreply', query];
     if (max !== undefined) args.push(`--max=${max}`);
     if (subject) args.push(`--subject=${subject}`);
-    if (body) args.push(`--body=${body}`);
+    if (body) args.push(payloadArg('body', 'body-file', body));
+    // `gmail autoreply` has --body-file but NO --body-html-file (verified against
+    // gog 0.34.1), so an HTML autoreply body stays inline and is still bounded by
+    // the runner's per-arg cap. Route it through payloadArg if gog ever adds one.
     if (bodyHtml) args.push(`--body-html=${bodyHtml}`);
     if (from) args.push(`--from=${from}`);
     if (replyTo) args.push(`--reply-to=${replyTo}`);
@@ -624,6 +1090,8 @@ export function registerExtraGmailTools(server: McpServer): void {
     if (enable) args.push('--enable');
     if (disable) args.push('--disable');
     if (subject) args.push(`--subject=${subject}`);
+    // `gmail settings vacation update` exposes only --body — there is no
+    // --body-file variant (verified against gog 0.34.1), so this stays inline.
     if (body) args.push(`--body=${body}`);
     if (start) args.push(`--start=${start}`);
     if (end) args.push(`--end=${end}`);
@@ -687,7 +1155,7 @@ export function registerExtraGmailTools(server: McpServer): void {
     if (important) args.push('--important');
     if (trash) args.push('--trash');
     if (neverSpam) args.push('--never-spam');
-    if (forward) args.push(`--forward=${forward}`);
+    if (forward) args.push(`--forward=${forward}`, '--force'); // gog gates this op; without --force the runner's --no-input makes it refuse (forwarding filters only)
     return runOrDiagnose(args, { account });
   });
 
@@ -699,7 +1167,7 @@ export function registerExtraGmailTools(server: McpServer): void {
       account: accountParam,
     },
   }, async ({ filterId, account }) => {
-    return runOrDiagnose(['gmail', 'settings', 'filters', 'delete', filterId], { account });
+    return runOrDiagnose(['gmail', 'settings', 'filters', 'delete', filterId, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_gmail_sendas_list', {
@@ -772,7 +1240,7 @@ export function registerExtraGmailTools(server: McpServer): void {
       account: accountParam,
     },
   }, async ({ email, account }) => {
-    return runOrDiagnose(['gmail', 'settings', 'sendas', 'delete', email], { account });
+    return runOrDiagnose(['gmail', 'settings', 'sendas', 'delete', email, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_gmail_sendas_verify', {