gogcli-mcp-gmail 2.24.0 → 2.25.0

package/dist/index.js

@@ -31182,10 +31182,11 @@ function sanitizedEnv() {
   }
   return result;
 }
+var TOKEN_LEFT_BOUNDARY = "(?<![A-Za-z0-9+/])";
 var GOOGLE_TOKEN_PATTERNS = [
-  /ya29\.[A-Za-z0-9._\-]+/g,
+  new RegExp(`${TOKEN_LEFT_BOUNDARY}ya29\\.[A-Za-z0-9._\\-]+`, "g"),
   // OAuth2 access tokens
-  /1\/\/[A-Za-z0-9._\-]+/g
+  new RegExp(`${TOKEN_LEFT_BOUNDARY}1//[A-Za-z0-9._\\-]+`, "g")
   // OAuth2 refresh tokens
 ];
 function redactGoogleTokens(text) {
@@ -31198,6 +31199,26 @@ function redactGoogleTokens(text) {
 function redactSecrets2(text) {
   return redactGoogleTokens(redactSecrets(text));
 }
+var OPAQUE_FIELD_VALUE = "[A-Za-z0-9+/_-]{16,}={0,2}";
+var opaquePlaceholder = (i) => `\0gogOpaque${i}\0`;
+function redactPreservingOpaqueFields(text, fields, redact) {
+  const lifted = [];
+  let staged = text;
+  for (const field of fields) {
+    const escaped = field.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(`("${escaped}"\\s*:\\s*")(${OPAQUE_FIELD_VALUE})(")`, "g");
+    staged = staged.replace(re, (_m, open, value, close) => {
+      lifted.push(value);
+      return `${open}${opaquePlaceholder(lifted.length - 1)}${close}`;
+    });
+  }
+  if (lifted.length === 0) return redact(text);
+  let redacted = redact(staged);
+  lifted.forEach((value, i) => {
+    redacted = redacted.split(opaquePlaceholder(i)).join(value);
+  });
+  return redacted;
+}
 function augmentedPath() {
   const home = process.env.HOME;
   const candidates = [
@@ -31228,19 +31249,24 @@ function formatTimeout(ms) {
   return `${ms}ms`;
 }
 async function spawnWithTempFiles(args, opts) {
-  const { mkdtemp, writeFile, rm } = await import("node:fs/promises");
+  const { mkdtemp, mkdir, writeFile, rm } = await import("node:fs/promises");
   const { tmpdir } = await import("node:os");
   const dir = await mkdtemp(join(tmpdir(), "gogcli-mcp-"));
   try {
     const argv = [];
+    let seq = 0;
     for (const arg of args) {
       if (!isGogFileArg(arg)) {
         argv.push(arg);
         continue;
       }
-      const path = join(dir, `${arg.flag}.${arg.ext ?? "txt"}`);
-      await writeFile(path, arg.contents, { encoding: "utf8", mode: 384 });
-      argv.push(`--${arg.flag}=${path}`);
+      const sub = join(dir, String(seq));
+      seq += 1;
+      await mkdir(sub, { recursive: true, mode: 448 });
+      const path = join(sub, arg.filename ?? `${arg.flag}.${arg.ext ?? "txt"}`);
+      const data = arg.encoding === "base64" ? Buffer.from(arg.contents, "base64") : Buffer.from(arg.contents, "utf8");
+      await writeFile(path, data, { mode: 384 });
+      argv.push(arg.positional ? path : `--${arg.flag}=${path}`);
     }
     return await spawnGog(argv, opts);
   } finally {
@@ -31325,8 +31351,9 @@ function assembleArgs(args, opts) {
   return fullArgs;
 }
 async function run(args, options = {}) {
-  const { account, spawner, interactive = false, timeout, readonly: readonly2 = false, redactMode = "full" } = options;
-  const redact = redactMode === "tokens" ? redactGoogleTokens : redactSecrets2;
+  const { account, spawner, interactive = false, timeout, readonly: readonly2 = false, redactMode = "full", opaqueFields } = options;
+  const base = redactMode === "tokens" ? redactGoogleTokens : redactSecrets2;
+  const redact = opaqueFields?.length ? (text) => redactPreservingOpaqueFields(text, opaqueFields, base) : base;
   const fullArgs = assembleArgs(args, { account, interactive, readonly: readonly2 });
   const store = activeExecutor();
   try {
@@ -31340,7 +31367,7 @@ async function run(args, options = {}) {
     }
     return redact(output);
   } catch (err) {
-    const message = redact(err instanceof Error ? err.message : String(err));
+    const message = base(err instanceof Error ? err.message : String(err));
     if (isRunnerTransportError(err)) {
       throw new RunnerTransportError(message, err.kind, err.status);
     }
@@ -31973,6 +32000,85 @@ function finish(base, itemsKey, merged, token) {
   return rawTextResult(JSON.stringify(out));
 }
 
+// ../gogcli-mcp/src/attachments.ts
+var MAX_INLINE_ATTACHMENT_BYTES = 8 * 1024 * 1024;
+var RUNNER_MAX_BODY_BYTES = 32 * 1024 * 1024;
+var RUNNER_BODY_JSON_RESERVE_BYTES = 256 * 1024;
+var MAX_REQUEST_PAYLOAD_WIRE_BYTES = RUNNER_MAX_BODY_BYTES - RUNNER_BODY_JSON_RESERVE_BYTES;
+var MAX_INLINE_ATTACHMENT_TOTAL_BYTES = Math.floor(MAX_REQUEST_PAYLOAD_WIRE_BYTES * 3 / 4);
+function wireBytesOf(arg) {
+  if (typeof arg === "string") return Buffer.byteLength(arg, "utf8");
+  return arg.encoding === "base64" ? arg.contents.length : Buffer.byteLength(arg.contents, "utf8");
+}
+var formatMiB = (bytes) => `${Math.floor(bytes / (1024 * 1024))} MiB`;
+var INLINE_ATTACHMENT_LIMITS_TEXT = `up to ${formatMiB(MAX_INLINE_ATTACHMENT_BYTES)} per file and ${formatMiB(MAX_INLINE_ATTACHMENT_TOTAL_BYTES)} in total`;
+var inlineAttachmentSchema = external_exports.object({
+  filename: external_exports.string().min(1).describe(
+    `Filename the recipient will see, e.g. "pendant-layouts.png". gog infers the attachment's MIME type from this extension, so give it the right one \u2014 a .png sent as "layouts" arrives as an untyped blob. Must be a single filename, not a path.`
+  ),
+  contentBase64: external_exports.string().min(1).describe(
+    "The file's bytes, base64-encoded (standard alphabet, with padding). This is the whole point of this parameter: the bytes travel with the request, so nothing needs to exist on the gog server's filesystem."
+  )
+});
+var attachInlineParam = external_exports.array(inlineAttachmentSchema).optional().describe(
+  `Attachments supplied as BYTES rather than as server-side paths \u2014 use this whenever you hold a file and the gog server does not, which is always the case on the hosted connector and on any remote deployment. Each entry is {filename, contentBase64} (${INLINE_ATTACHMENT_LIMITS_TEXT}). Can be combined with \`attach\`: the two name disjoint files (paths read on the server vs. bytes sent with the call), and both end up as ordinary attachments on the message.`
+);
+function validateFilename(filename, where) {
+  if (/[/\\]/.test(filename)) {
+    throw new Error(
+      `${where}: filename ${JSON.stringify(filename)} must be a bare filename, not a path. Pass just the name the recipient should see, e.g. "report.pdf".`
+    );
+  }
+  if (/[\x00-\x1f]/.test(filename) || /^\.+$/.test(filename) || filename.length > 200) {
+    throw new Error(
+      `${where}: filename ${JSON.stringify(filename)} is not a usable filename (no control characters, not "."/"..", 200 characters max).`
+    );
+  }
+}
+function decodedLength(contentBase64) {
+  const buf = Buffer.from(contentBase64, "base64");
+  return buf.toString("base64") === contentBase64 ? buf.length : null;
+}
+function inlineFileArg(flag, attachment, opts = {}) {
+  const { filename, contentBase64 } = attachment;
+  const where = opts.where ?? `attachInline entry ${JSON.stringify(filename)}`;
+  validateFilename(filename, where);
+  const bytes = decodedLength(contentBase64);
+  if (bytes === null) {
+    throw new Error(
+      `${where}: contents are not valid base64. Send the standard alphabet with padding and no line breaks \u2014 the value must survive a decode/re-encode round trip unchanged.`
+    );
+  }
+  if (bytes > MAX_INLINE_ATTACHMENT_BYTES) {
+    throw new Error(
+      `${where}: ${bytes} bytes exceeds the ${MAX_INLINE_ATTACHMENT_BYTES}-byte (${formatMiB(MAX_INLINE_ATTACHMENT_BYTES)}) per-file limit for inline content. Upload it to Drive and link to it instead, or send it from a local (stdio) deployment using a real server-side path.`
+    );
+  }
+  const arg = { kind: "file", flag, contents: contentBase64, encoding: "base64", filename };
+  if (opts.positional) arg.positional = true;
+  return { arg, bytes };
+}
+function inlineAttachmentArgs(flag, attachments, siblingArgs = []) {
+  if (!attachments?.length) return [];
+  const args = [];
+  const siblingWire = siblingArgs.reduce((sum, arg) => sum + wireBytesOf(arg), 0);
+  let attachmentWire = 0;
+  let decodedTotal = 0;
+  for (const attachment of attachments) {
+    const { arg, bytes } = inlineFileArg(flag, attachment);
+    attachmentWire += arg.contents.length;
+    decodedTotal += bytes;
+    if (siblingWire + attachmentWire > MAX_REQUEST_PAYLOAD_WIRE_BYTES) {
+      const blame = attachmentWire <= MAX_REQUEST_PAYLOAD_WIRE_BYTES ? ` These attachments would fit on their own; the rest of the message (its body, mostly) spends ${siblingWire} bytes of the same budget.` : "";
+      throw new Error(
+        `This message is too large to send: ${decodedTotal} bytes of attachments (${attachmentWire} bytes once base64-encoded for transit) exceed the ${MAX_REQUEST_PAYLOAD_WIRE_BYTES}-byte request limit.${blame} The ceiling for attachments alone is ${MAX_INLINE_ATTACHMENT_TOTAL_BYTES} bytes (${formatMiB(MAX_INLINE_ATTACHMENT_TOTAL_BYTES)}); a long body lowers it. Send fewer or smaller files per message, shorten the body, or upload the large files to Drive and link them.`
+      );
+    }
+    args.push(arg);
+  }
+  return args;
+}
+
 // ../gogcli-mcp/src/tools/gmail.ts
 function registerGmailTools(server) {
   server.registerTool("gog_gmail_search", {
@@ -32026,7 +32132,7 @@ function registerGmailTools(server) {
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_gmail_send", {
-    description: "Send an email. When attach is used, the JSON result echoes the attached filenames and byte sizes \u2014 check it to confirm the files were found and embedded.",
+    description: 'Send an email. Two ways to attach a file: `attach` takes paths READ ON THE GOG SERVER, and `attachInline` takes the bytes themselves. Use attachInline unless you know the file exists on the same machine gog runs on \u2014 on the hosted connector and any remote deployment there is no shared filesystem, so no path you can name resolves there and `attach` will fail with "no such file or directory". When either is used, the JSON result echoes the attached filenames and byte sizes \u2014 check it to confirm the files were embedded.',
     annotations: { destructiveHint: true },
     inputSchema: {
       to: external_exports.string().describe("Recipient(s), comma-separated"),
@@ -32036,16 +32142,19 @@ function registerGmailTools(server) {
       bcc: external_exports.string().optional().describe("BCC recipients, comma-separated"),
       replyToMessageId: external_exports.string().optional().describe("Message ID to reply to"),
       threadId: external_exports.string().optional().describe("Thread ID to reply within"),
-      attach: external_exports.array(external_exports.string()).optional().describe("Local file paths to attach (repeatable). Each file is read on the gog server (not this client), base64-encoded with a MIME type inferred from its extension, and added as a multipart attachment. Keep the total under Gmail's ~35 MB inline-upload limit."),
+      attach: external_exports.array(external_exports.string()).optional().describe(`File paths to attach (repeatable), resolved ON THE GOG SERVER's filesystem \u2014 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" \u2014 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
     }
-  }, async ({ to, subject, body, cc, bcc, replyToMessageId, threadId, attach, account }) => {
+  }, async ({ to, subject, body, cc, bcc, replyToMessageId, threadId, attach, attachInline, account }) => {
     const args = ["gmail", "send", `--to=${to}`, `--subject=${subject}`, payloadArg("body", "body-file", body)];
     if (cc) args.push(`--cc=${cc}`);
     if (bcc) args.push(`--bcc=${bcc}`);
     if (replyToMessageId) args.push(`--reply-to-message-id=${replyToMessageId}`);
     if (threadId) args.push(`--thread-id=${threadId}`);
     if (attach) for (const path of attach) args.push(`--attach=${path}`);
+    const inline = inlineAttachmentArgs("attach", attachInline, args);
+    args.push(...inline);
     return runOrDiagnose(args, { account });
   });
   registerRunTool(server, { service: "gmail", examples: '"archive", "mark-read", "labels"' });
@@ -32061,7 +32170,7 @@ var failIfNotEmptyParam = external_exports.boolean().optional().describe(
 );
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.24.0" : "0.0.0";
+var VERSION = true ? "2.25.0" : "0.0.0";
 
 // ../gogcli-mcp/src/auth-log.ts
 var FAILURES = /* @__PURE__ */ new Set([
@@ -32635,6 +32744,9 @@ var MAGIC_SIGNATURES = [
   ["\xFF\xD8\xFF", "image/jpeg"],
   ["GIF8", "image/gif"]
 ];
+function isValidBase642(value) {
+  return Buffer.from(value, "base64").toString("base64") === value;
+}
 function sniffMime(base643) {
   const head = atob(base643.slice(0, 16));
   for (const [signature, mimeType] of MAGIC_SIGNATURES) {
@@ -33571,8 +33683,15 @@ function registerExtraGmailTools(server) {
       if (needInline) args.push("--inline");
       args.push(`--inline-max-bytes=${inlineMaxBytes ?? GOG_DEFAULT_INLINE_MAX_BYTES}`);
       args.push(`--out=${outPath}`, `--name=${filename ?? "attachment"}`);
-      const info = JSON.parse(await run(args, { account }));
+      const info = JSON.parse(await run(args, { account, opaqueFields: ["contentBase64"] }));
       const path = info.path ?? outPath;
+      const inlineUnusable = info.contentBase64 !== void 0 && !isValidBase642(info.contentBase64);
+      if (inlineUnusable) {
+        delete info.contentBase64;
+        notes.push(
+          "The inline copy of this attachment was dropped: the bytes returned by the server were not valid base64, so returning them would have failed as a protocol error. The file itself was downloaded successfully and is delivered below."
+        );
+      }
       if (!filename && info.filename) filename = sanitizeFilename(info.filename);
       if (!mimeType && info.mimeType) mimeType = info.mimeType;
       if (!filename && !indexed) {
@@ -33598,6 +33717,11 @@ function registerExtraGmailTools(server) {
         if (info.contentBase64) {
           return withNote(isImage ? inlineImageResult(summary, info.contentBase64, mimeType) : inlineResourceResult(messageId, filename, summary, info.contentBase64, mimeType), notes);
         }
+        if (inlineUnusable) {
+          return errorResult(
+            `The bytes returned for ${filename} were not valid base64, so they cannot be delivered inline (the MCP transport would reject them as a protocol error). The file WAS downloaded and is readable server-side at ${path}. Use deliver="auto" or deliver="drive" to receive it.`
+          );
+        }
         return errorResult(
           `Attachment is too large to return inline (${info.reason ?? "exceeds gog's inline size limit, 3 MiB by default \u2014 raise inlineMaxBytes"}). Use deliver="auto" or deliver="drive" to receive it as a Google Drive link.`
         );
@@ -34017,7 +34141,8 @@ function registerExtraGmailTools(server) {
     replyTo: external_exports.string().optional().describe("Reply-To header address"),
     quote: external_exports.boolean().optional().describe("Include quoted original message in reply (requires replyToMessageId or replyToThreadId)"),
     replyAll: external_exports.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: external_exports.array(external_exports.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 \u2014 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)."),
+    attach: external_exports.array(external_exports.string()).optional().describe(`File paths to attach (repeatable), resolved ON THE GOG SERVER's filesystem \u2014 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" \u2014 use attachInline there. Read on the server, base64-encoded with a MIME type inferred from the extension. The JSON result echoes attached filenames and byte sizes \u2014 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).`),
+    attachInline: attachInlineParam,
     from: external_exports.string().optional().describe("Send from this email address (must be a verified send-as alias)"),
     autoFromAddressedAlias: external_exports.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 \u2014 so a reply to mail sent to an alias goes back out from that alias. Ignored when from is set."),
     omitRecipients: external_exports.boolean().optional().describe("Create the draft with no recipients even if to/cc/bcc are supplied \u2014 an accidental-send guard. Populate recipients in a later update before sending."),
@@ -34041,6 +34166,7 @@ function registerExtraGmailTools(server) {
     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}`);
+    args.push(...inlineAttachmentArgs("attach", f.attachInline, args));
     if (f.from) args.push(`--from=${f.from}`);
     args.push(f.autoFromAddressedAlias ? "--auto-from-addressed-alias" : "--auto-from-addressed-alias=false");
   }
@@ -34212,7 +34338,8 @@ function registerExtraGmailTools(server) {
     remove: external_exports.array(external_exports.string()).optional().describe("Remove these recipients from all fields (repeatable) \u2014 e.g. to drop someone from a reply-all."),
     subject: external_exports.string().optional().describe('Override reply subject (default: "Re: <original>"). A changed subject starts a NEW Gmail thread.'),
     noQuote: external_exports.boolean().optional().describe("Do not include the original message quoted below the reply (default: the original is quoted)"),
-    attach: external_exports.array(external_exports.string()).optional().describe("Local file paths to attach (repeatable). Read on the gog server, base64-encoded with a MIME type inferred from the extension."),
+    attach: external_exports.array(external_exports.string()).optional().describe(`File paths to attach (repeatable), resolved ON THE GOG SERVER's filesystem \u2014 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" \u2014 use attachInline there. Read on the server, base64-encoded with a MIME type inferred from the extension.`),
+    attachInline: attachInlineParam,
     from: external_exports.string().optional().describe("Send from this email address (must be a verified send-as alias)"),
     autoFromAddressedAlias: external_exports.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 \u2014 so a reply to mail sent to an alias goes back out from that alias. Ignored when from is set."),
     signature: external_exports.boolean().optional().describe("Append the Gmail signature from the active send-as address"),
@@ -34232,6 +34359,7 @@ function registerExtraGmailTools(server) {
     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}`);
+    args.push(...inlineAttachmentArgs("attach", f.attachInline, args));
     if (f.from) args.push(`--from=${f.from}`);
     if (f.signature) args.push("--signature");
     if (f.signatureFrom) args.push(`--signature-from=${f.signatureFrom}`);

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-gmail",
   "display_name": "gogcli (Gmail)",
-  "version": "2.24.0",
+  "version": "2.25.0",
   "description": "Extended Gmail for Claude via gogcli — auth + full Gmail support (threads, labels, drafts, attachments, forward, autoreply, bulk operations)",
   "author": {
     "name": "Chris Hall",
@@ -99,7 +99,7 @@
     },
     {
       "name": "gog_gmail_send",
-      "description": "Send an email"
+      "description": "Send an email, with attachments from server-side paths (attach) or from base64 bytes sent with the call (attachInline, for remote deployments with no shared filesystem)"
     },
     {
       "name": "gog_gmail_run",
@@ -195,11 +195,11 @@
     },
     {
       "name": "gog_gmail_drafts_create",
-      "description": "Create a new Gmail draft"
+      "description": "Create a new Gmail draft, with attachments from server-side paths (attach) or from base64 bytes sent with the call (attachInline, for remote deployments with no shared filesystem)"
     },
     {
       "name": "gog_gmail_drafts_update",
-      "description": "Update an existing Gmail draft; re-thread it in place with replyToThreadId (same draft id) and verify the result via threadingVerification; forkSiblingDraftId refuses the write when the new body would drop text the named sibling copy still holds; a 404 is attributed to the draft id or to the reply target before it is reported"
+      "description": "Update an existing Gmail draft; re-thread it in place with replyToThreadId (same draft id) and verify the result via threadingVerification; forkSiblingDraftId refuses the write when the new body would drop text the named sibling copy still holds; a 404 is attributed to the draft id or to the reply target before it is reported Attachments come from server-side paths (attach) or from base64 bytes sent with the call (attachInline, for remote deployments with no shared filesystem)."
     },
     {
       "name": "gog_gmail_drafts_delete",
@@ -215,11 +215,11 @@
     },
     {
       "name": "gog_gmail_drafts_reply",
-      "description": "Save a reply to a Gmail message as a draft (inherited recipients, subject and quote; never sends)"
+      "description": "Save a reply to a Gmail message as a draft (inherited recipients, subject and quote; never sends) Attachments come from server-side paths (attach) or from base64 bytes sent with the call (attachInline, for remote deployments with no shared filesystem)."
     },
     {
       "name": "gog_gmail_drafts_reply_all",
-      "description": "Save a reply-all to a Gmail message as a draft (never sends)"
+      "description": "Save a reply-all to a Gmail message as a draft (never sends) Attachments come from server-side paths (attach) or from base64 bytes sent with the call (attachInline, for remote deployments with no shared filesystem)."
     },
     {
       "name": "gog_gmail_drafts_forward",
@@ -235,11 +235,11 @@
     },
     {
       "name": "gog_gmail_reply",
-      "description": "Reply to a Gmail message (sender only)"
+      "description": "Reply to a Gmail message (sender only) Attachments come from server-side paths (attach) or from base64 bytes sent with the call (attachInline, for remote deployments with no shared filesystem)."
     },
     {
       "name": "gog_gmail_reply_all",
-      "description": "Reply to all participants of a Gmail message"
+      "description": "Reply to all participants of a Gmail message Attachments come from server-side paths (attach) or from base64 bytes sent with the call (attachInline, for remote deployments with no shared filesystem)."
     },
     {
       "name": "gog_gmail_autoreply",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-gmail",
-  "version": "2.24.0",
+  "version": "2.25.0",
   "mcpName": "io.github.chrischall/gogcli-mcp-gmail",
   "description": "Extended Gmail MCP server via gogcli — auth + full Gmail support (threads, labels, drafts, attachments, forward, autoreply, bulk operations)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/src/tools/gmail-extra.ts

@@ -2,8 +2,8 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { rawTextResult, textResult, errorResult } from '@chrischall/mcp-utils';
-import { accountParam, runOrDiagnose, run, diagnose, payloadArg, runExecutor, normalizeTimestamps, finalizeGmailSearch, fetchGmailPages, pageTokenParam, pageAliasParam, resolvePageToken} from '../../../gogcli-mcp/src/lib.js';
-import type { GogArg } from '../../../gogcli-mcp/src/lib.js';
+import { accountParam, runOrDiagnose, run, diagnose, payloadArg, runExecutor, normalizeTimestamps, finalizeGmailSearch, fetchGmailPages, pageTokenParam, pageAliasParam, resolvePageToken, attachInlineParam, inlineAttachmentArgs} from '../../../gogcli-mcp/src/lib.js';
+import type { GogArg, InlineAttachmentInput } 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
@@ -191,9 +191,29 @@ const MAGIC_SIGNATURES: ReadonlyArray<readonly [string, string]> = [
   ['GIF8', 'image/gif'],
 ];
 
+// Does this string survive a base64 decode/re-encode round trip unchanged?
+//
+// The MCP SDK validates an image block's `data` and a resource block's `blob`
+// against its own base64 schema, and a failure there is a PROTOCOL error
+// (-32602 "Invalid Base64 string") — thrown past this tool's try/catch, so the
+// caller gets a wire-level fault with no clue which attachment caused it and no
+// suggestion of what to do instead. Checking here converts that into an ordinary
+// tool result that can name the file and offer a working alternative.
+//
+// No try/catch: `Buffer.from(…, 'base64')` is total — it SKIPS characters it
+// does not recognise rather than throwing, which is precisely why a bare decode
+// cannot be used as the check and the re-encode comparison is required.
+function isValidBase64(value: string): boolean {
+  return Buffer.from(value, 'base64').toString('base64') === value;
+}
+
 // 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.
+// for anything unrecognised.
+//
+// `atob` cannot throw here, and that is now ENFORCED rather than assumed: the
+// caller drops `contentBase64` outright when isValidBase64 rejects it, so this
+// only ever runs on a payload that round-trips — and any 4-aligned prefix of
+// valid base64 is itself valid.
 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) {
@@ -2288,9 +2308,29 @@ export function registerExtraGmailTools(server: McpServer): void {
       // default keeps the arg array the single authority on both transports.
       args.push(`--inline-max-bytes=${inlineMaxBytes ?? GOG_DEFAULT_INLINE_MAX_BYTES}`);
       args.push(`--out=${outPath}`, `--name=${filename ?? 'attachment'}`);
-      const info = JSON.parse(await run(args, { account })) as InlineAttachment;
+      // `contentBase64` is exempt from redaction: it is the attachment's own
+      // bytes, and a base64 blob large enough will eventually spell a token
+      // shape by chance — which used to delete a slab out of the middle of it
+      // and hand the client an "Invalid Base64 string" protocol error. See
+      // RunOptions.opaqueFields.
+      const info = JSON.parse(await run(args, { account, opaqueFields: ['contentBase64'] })) as InlineAttachment;
       const path = info.path ?? outPath;
 
+      // BACKSTOP, not the fix — the redaction exemption above is. Bytes that
+      // cannot round-trip as base64 must never be handed to the SDK, which
+      // rejects them as a -32602 protocol error the caller cannot act on. The
+      // file itself was still written server-side, so dropping the inline copy
+      // degrades to the path/Drive channel rather than losing the attachment.
+      const inlineUnusable = info.contentBase64 !== undefined && !isValidBase64(info.contentBase64);
+      if (inlineUnusable) {
+        delete info.contentBase64;
+        notes.push(
+          'The inline copy of this attachment was dropped: the bytes returned by the server were not ' +
+          'valid base64, so returning them would have failed as a protocol error. The file itself was ' +
+          'downloaded successfully and is delivered below.',
+        );
+      }
+
       // 4. Resolve the real filename/MIME when it is still unknown. gog's own
       //    --inline response carries the part metadata whenever its lookup hit, so
       //    prefer that; the size heuristic is the last resort and applies only to
@@ -2327,6 +2367,13 @@ export function registerExtraGmailTools(server: McpServer): void {
             ? inlineImageResult(summary, info.contentBase64, mimeType)
             : inlineResourceResult(messageId, filename, summary, info.contentBase64, mimeType), notes);
         }
+        if (inlineUnusable) {
+          return errorResult(
+            `The bytes returned for ${filename} were not valid base64, so they cannot be delivered inline ` +
+            '(the MCP transport would reject them as a protocol error). The file WAS downloaded and is ' +
+            `readable server-side at ${path}. Use deliver="auto" or deliver="drive" to receive it.`,
+          );
+        }
         return errorResult(
           `Attachment is too large to return inline (${info.reason ?? "exceeds gog's inline size limit, 3 MiB by default — raise inlineMaxBytes"}). ` +
           'Use deliver="auto" or deliver="drive" to receive it as a Google Drive link.',
@@ -2844,7 +2891,8 @@ export function registerExtraGmailTools(server: McpServer): void {
     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).'),
+    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. 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).'),
+    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.'),
     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.'),
@@ -2866,6 +2914,7 @@ export function registerExtraGmailTools(server: McpServer): void {
     quote?: boolean;
     replyAll?: boolean;
     attach?: string[];
+    attachInline?: InlineAttachmentInput[];
     from?: string;
     autoFromAddressedAlias?: boolean;
     omitRecipients?: boolean;
@@ -2894,6 +2943,12 @@ export function registerExtraGmailTools(server: McpServer): void {
     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}`);
+    // 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.
+    // 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 passed so the size check sees the body, which shares the budget.
+    args.push(...inlineAttachmentArgs('attach', f.attachInline, args));
     if (f.from) args.push(`--from=${f.from}`);
     // 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
@@ -3178,7 +3233,8 @@ export function registerExtraGmailTools(server: McpServer): void {
     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.'),
+    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.'),
+    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.'),
     signature: z.boolean().optional().describe('Append the Gmail signature from the active send-as address'),
@@ -3198,6 +3254,7 @@ export function registerExtraGmailTools(server: McpServer): void {
     subject?: string;
     noQuote?: boolean;
     attach?: string[];
+    attachInline?: InlineAttachmentInput[];
     from?: string;
     autoFromAddressedAlias?: boolean;
     signature?: boolean;
@@ -3217,6 +3274,7 @@ export function registerExtraGmailTools(server: McpServer): void {
     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}`);
+    args.push(...inlineAttachmentArgs('attach', f.attachInline, args)); // see appendDraftFlags
     if (f.from) args.push(`--from=${f.from}`);
     if (f.signature) args.push('--signature');
     if (f.signatureFrom) args.push(`--signature-from=${f.signatureFrom}`);

package/tests/tools/gmail-extra.test.ts

@@ -322,6 +322,106 @@ describe('gog_gmail_attachment', () => {
     await call({});
     expect((vi.mocked(lib.diagnose).mock.calls[0][0] as Error).message).toBe('the download failed on the server');
   });
+
+  // ==========================================================================
+  // FILENAME INDEPENDENCE — the defect reported as "inline delivery fails on
+  // filenames containing spaces".
+  //
+  // It was never the filename. The runner spawns an argv ARRAY (never a shell),
+  // so a space has nothing to split; the real variable was the base64 content
+  // colliding with a redaction pattern. These lock in that names with spaces,
+  // non-ASCII and punctuation all deliver inline, and that the download args
+  // carry each name as ONE element.
+  // ==========================================================================
+  describe('filename independence', () => {
+    const NAMES = [
+      'image.png',
+      'Screenshot 2026-06-13 152500.png',
+      'Reçu — étude, final (v2).png',
+      "quote'and\"double.png",
+      'ファイル 名前.png',
+    ];
+
+    for (const filename of NAMES) {
+      it(`delivers ${JSON.stringify(filename)} inline as an image`, async () => {
+        // Indexed mode resolves the real name BEFORE the download, so the name
+        // is what gets handed to gog — the strongest form of this assertion.
+        stubGog({
+          meta: { attachments: [{ filename, mimeType: 'image/png', size: 24, attachmentIndex: 0 }] },
+          download: { path: `/tmp/gog-attachments/m1/${filename}`, bytes: 24, contentBase64: PNG_B64, filename, mimeType: 'image/png' },
+        });
+        const res = await harness.callTool('gog_gmail_attachment', { messageId: 'm1', attachmentIndex: 0 });
+        const image = res.content.find((c) => c.type === 'image') as { data: string; mimeType: string };
+        expect(image).toBeDefined();
+        expect(image.data).toBe(PNG_B64);
+        // The name reaches gog as a SINGLE argv element, spaces and all.
+        expect(dlArgs()).toContain(`--name=${filename}`);
+        expect(dlArgs()).toContain(`--out=/tmp/gog-attachments/m1/${filename}`);
+        expect((res.content[0] as { text: string }).text).toContain(filename);
+      });
+    }
+
+    it('passes a spaced --out path as one argv element, never split on whitespace', async () => {
+      const filename = 'Screenshot 2026-06-13 152500.png';
+      stubGog({ download: { bytes: 24, contentBase64: PNG_B64, filename, mimeType: 'image/png' } });
+      await call({ name: filename });
+      const args = dlArgs();
+      expect(args).toContain(`--out=/tmp/gog-attachments/m1/${filename}`);
+      // If anything had split on spaces these would appear as separate elements.
+      expect(args).not.toContain('2026-06-13');
+      expect(args).not.toContain('152500.png');
+    });
+  });
+
+  // The bytes are exempted from redaction at the runner seam; this asserts the
+  // tool actually asks for that exemption, which is the thing that keeps a
+  // `1//`-containing PNG from arriving corrupt.
+  it('requests the contentBase64 redaction exemption on the download', async () => {
+    stubGog({ download: { bytes: 24, contentBase64: PNG_B64, filename: 'a.png', mimeType: 'image/png' } });
+    await call({});
+    const call0 = vi.mocked(lib.run).mock.calls.find((c) => (c[0] as string[])[1] === 'attachment')!;
+    expect(call0[1]).toMatchObject({ opaqueFields: ['contentBase64'] });
+  });
+
+  // Belt-and-braces: if bytes ever do arrive unusable, the caller must get a
+  // readable tool result, not an MCP -32602 protocol fault they cannot act on.
+  it('degrades to the file path when the returned bytes are not valid base64', async () => {
+    stubGog({
+      meta: PNG_LIST,
+      download: { path: '/tmp/gog-attachments/m1/photo.png', bytes: 24, contentBase64: 'not!valid!base64!', filename: 'photo.png', mimeType: 'image/png' },
+    });
+    const res = await call({});
+    expect(res.content.some((c) => c.type === 'image')).toBe(false);
+    expect(textOf(res)).toContain('not valid base64');
+    expect(JSON.stringify(res)).toContain('/tmp/gog-attachments/m1/photo.png');
+  });
+
+  // The MIME sniff decodes the leading bytes. On an unusable payload that decode
+  // is the FIRST thing to fail, and it must not be what surfaces — the caller's
+  // problem is the payload, not the sniff.
+  it('survives a MIME sniff of unusable bytes instead of throwing out of the sniff', async () => {
+    stubGog({
+      meta: { attachments: [] }, // nothing to resolve a MIME type from
+      download: { path: '/tmp/gog-attachments/m1/attachment', bytes: 4, contentBase64: '!!!!' },
+    });
+    const res = await call({});
+    expect(res.isError).toBeUndefined();
+    // content[0] is the dropped-inline note; the delivery payload follows it.
+    const payload = JSON.parse((res.content.at(-1) as { text: string }).text);
+    expect(payload.mimeType).toBe('application/octet-stream');
+    expect(payload.fileName).toBe('attachment');
+  });
+
+  it('explains itself rather than throwing when deliver=inline gets unusable bytes', async () => {
+    stubGog({
+      meta: PNG_LIST,
+      download: { path: '/tmp/gog-attachments/m1/photo.png', bytes: 24, contentBase64: '!!!!', filename: 'photo.png', mimeType: 'image/png' },
+    });
+    const res = await call({ deliver: 'inline' });
+    expect(res.isError).toBe(true);
+    expect(textOf(res)).toContain('not valid base64');
+    expect(textOf(res)).toContain('/tmp/gog-attachments/m1/photo.png');
+  });
 });
 
 describe('gog_gmail_url', () => {
@@ -1290,6 +1390,69 @@ describe('gog_gmail_drafts_create', () => {
     );
   });
 
+  // ==========================================================================
+  // INLINE ATTACHMENT BYTES on drafts — the outbound half of the "no shared
+  // filesystem" defect. `attach` paths resolve on the gog server and are
+  // unreachable from a remote caller; attachInline carries the bytes instead.
+  // ==========================================================================
+  it('turns attachInline into repeatable --attach file args on drafts_create', async () => {
+    const png = Buffer.from([0x89, 0x50, 0x4e, 0x47]).toString('base64');
+    await harness.callTool('gog_gmail_drafts_create', {
+      subject: 'Layouts',
+      body: 'See attached',
+      attachInline: [{ filename: 'pendant-layouts.png', contentBase64: png }],
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      [
+        'gmail', 'drafts', 'create', '--subject=Layouts', '--body=See attached',
+        { kind: 'file', flag: 'attach', contents: png, encoding: 'base64', filename: 'pendant-layouts.png' },
+        '--auto-from-addressed-alias=false',
+      ],
+      { account: undefined },
+    );
+  });
+
+  it('keeps attach paths and attachInline bytes side by side, in that order', async () => {
+    const bytes = Buffer.from('hello').toString('base64');
+    await harness.callTool('gog_gmail_drafts_create', {
+      subject: 'S', body: 'B',
+      attach: ['/tmp/on-server.pdf'],
+      attachInline: [{ filename: 'from-client.txt', contentBase64: bytes }],
+    });
+    const args = vi.mocked(lib.runOrDiagnose).mock.calls[0][0];
+    expect(args).toContain('--attach=/tmp/on-server.pdf');
+    expect(args).toContainEqual({ kind: 'file', flag: 'attach', contents: bytes, encoding: 'base64', filename: 'from-client.txt' });
+  });
+
+  it('supports attachInline on drafts_update too', async () => {
+    const bytes = Buffer.from('v2').toString('base64');
+    await harness.callTool('gog_gmail_drafts_update', {
+      draftId: 'd1', subject: 'S', body: 'B',
+      attachInline: [{ filename: 'revised.pdf', contentBase64: bytes }],
+    });
+    const args = vi.mocked(lib.runOrDiagnose).mock.calls[0][0];
+    expect(args).toContainEqual({ kind: 'file', flag: 'attach', contents: bytes, encoding: 'base64', filename: 'revised.pdf' });
+  });
+
+  it('preserves a filename with spaces on the way to gog', async () => {
+    await harness.callTool('gog_gmail_drafts_create', {
+      subject: 'S', body: 'B',
+      attachInline: [{ filename: 'Screenshot 2026-06-13 152500.png', contentBase64: Buffer.from('x').toString('base64') }],
+    });
+    const args = vi.mocked(lib.runOrDiagnose).mock.calls[0][0];
+    expect(args.find((a) => typeof a !== 'string')).toMatchObject({ filename: 'Screenshot 2026-06-13 152500.png' });
+  });
+
+  it('rejects an invalid inline attachment without writing a draft', async () => {
+    const res = await harness.callTool('gog_gmail_drafts_create', {
+      subject: 'S', body: 'B',
+      attachInline: [{ filename: '../escape.png', contentBase64: Buffer.from('x').toString('base64') }],
+    });
+    expect(res.isError).toBe(true);
+    expect((res.content[0] as { text: string }).text).toMatch(/must be a bare filename, not a path/);
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+
   it('passes --body-html-file when bodyHtmlFile is supplied', async () => {
     await harness.callTool('gog_gmail_drafts_create', {
       subject: 'Hi',