gogcli-mcp-gmail 2.21.1 → 2.22.0

package/README.md

@@ -44,18 +44,19 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 claude mcp add gogcli-gmail -- gogcli-mcp-gmail
 ```
 
-## Extra Gmail Tools (23)
+## Extra Gmail Tools (45)
 
-Plus 5 auth tools and 4 base Gmail tools (search, get, send, run).
+Plus 8 auth tools and 4 base Gmail tools (search, get, send, run) — 57 in all.
 
 ### Read
 
 | Tool | Description |
 |------|-------------|
 | `gog_gmail_raw` | Dump the raw Gmail API JSON for a message (lossless, for scripting) |
-| `gog_gmail_attachment` | Download an attachment and deliver its contents — inline (base64 image/resource) when ≤3 MiB, otherwise uploaded to Google Drive with a shareable link (`deliver`: auto/inline/drive/off) |
+| `gog_gmail_attachment` | Download an attachment (by `attachmentIndex`, or the legacy opaque `attachmentId`) and deliver its contents — inline (base64 image/resource) when within the inline limit (3 MiB by default, `inlineMaxBytes`), otherwise uploaded to Google Drive with a shareable link (`deliver`: auto/inline/drive/off) |
 | `gog_gmail_url` | Print Gmail web URLs for one or more threads |
 | `gog_gmail_history` | List Gmail history events since a given historyId |
+| `gog_gmail_messages_search` | Search individual messages rather than threads — one result per matching message |
 
 ### Threads
 
@@ -75,6 +76,7 @@ Plus 5 auth tools and 4 base Gmail tools (search, get, send, run).
 | `gog_gmail_labels_rename` | Rename a label |
 | `gog_gmail_labels_delete` | Delete a label |
 | `gog_gmail_labels_modify` | Modify labels on one or more threads |
+| `gog_gmail_labels_style` | Change a user label's color or visibility |
 
 ### Bulk Operations
 
@@ -103,10 +105,30 @@ Plus 5 auth tools and 4 base Gmail tools (search, get, send, run).
 
 | Tool | Description |
 |------|-------------|
+| `gog_gmail_import` | Import an RFC822/EML message into the mailbox, keeping its original headers and date (does not send) |
 | `gog_gmail_forward` | Forward a message to new recipients (with optional note) |
+| `gog_gmail_reply` | Reply to a message (original sender only) |
+| `gog_gmail_reply_all` | Reply to every participant (sender plus all To/Cc recipients) |
 | `gog_gmail_autoreply` | Reply once to all messages matching a query (with dedupe label) |
 
-Track and admin settings (`track`, `settings filters`, `delegates`, `forwarding`, `sendas`, `vacation`, `watch`) are available via the base `gog_gmail_run` escape hatch.
+### Settings
+
+| Tool | Description |
+|------|-------------|
+| `gog_gmail_vacation_get` | Get the vacation responder (auto-reply) settings |
+| `gog_gmail_vacation_update` | Enable or disable the vacation responder, with optional start/end and audience limits |
+| `gog_gmail_filters_list` | List all Gmail filters |
+| `gog_gmail_filters_get` | Get a filter's criteria and actions by ID |
+| `gog_gmail_filters_create` | Create a filter from match criteria plus one or more actions |
+| `gog_gmail_filters_delete` | Delete a filter by ID |
+| `gog_gmail_sendas_list` | List all send-as aliases |
+| `gog_gmail_sendas_get` | Get one send-as alias by address |
+| `gog_gmail_sendas_create` | Create a send-as alias (usually needs verification before use) |
+| `gog_gmail_sendas_update` | Update an alias (display name, reply-to, signature, default) |
+| `gog_gmail_sendas_delete` | Delete a send-as alias |
+| `gog_gmail_sendas_verify` | Resend the verification email for a pending alias |
+
+Email tracking (`track`) and the remaining admin settings (`delegates`, `forwarding`, `watch`) have no dedicated tool — reach them through the base `gog_gmail_run` escape hatch.
 
 ## License
 

package/SKILL.md

@@ -5,7 +5,7 @@ description: Use when the user asks to read, organize, draft, forward, autoreply
 
 # gogcli-mcp-gmail
 
-Extended Gmail MCP server via [gogcli](https://github.com/openclaw/gogcli) — 32 tools: auth + 4 base Gmail + 23 extra dedicated Gmail tools.
+Extended Gmail MCP server via [gogcli](https://github.com/openclaw/gogcli) — 57 tools: 8 auth + 4 base Gmail + 45 extra dedicated Gmail tools.
 
 - **Source:** [github.com/chrischall/gogcli-mcp](https://github.com/chrischall/gogcli-mcp)
 
@@ -36,9 +36,10 @@ Extended Gmail MCP server via [gogcli](https://github.com/openclaw/gogcli) — 3
 | Tool | What it does |
 |------|-------------|
 | `gog_gmail_raw` | Raw Gmail API JSON for a message |
-| `gog_gmail_attachment` | Download an attachment and deliver its contents — inline when ≤3 MiB, else uploaded to Drive with a link (`deliver`: auto/inline/drive/off) |
+| `gog_gmail_attachment` | Download an attachment by `attachmentIndex` (or legacy `attachmentId`) and deliver its contents — inline when within `inlineMaxBytes` (3 MiB default), else uploaded to Drive with a link (`deliver`: auto/inline/drive/off) |
 | `gog_gmail_url` | Print web URLs for threads |
 | `gog_gmail_history` | List history events since a historyId |
+| `gog_gmail_messages_search` | Search individual messages, not threads — one row per message |
 
 ### Threads
 | Tool | What it does |
@@ -56,6 +57,7 @@ Extended Gmail MCP server via [gogcli](https://github.com/openclaw/gogcli) — 3
 | `gog_gmail_labels_rename` | Rename a label |
 | `gog_gmail_labels_delete` | Delete a label |
 | `gog_gmail_labels_modify` | Modify labels on one or more threads |
+| `gog_gmail_labels_style` | Change a label's color or visibility |
 
 ### Bulk operations
 | Tool | What it does |
@@ -81,7 +83,26 @@ Extended Gmail MCP server via [gogcli](https://github.com/openclaw/gogcli) — 3
 ### Write
 | Tool | What it does |
 |------|-------------|
+| `gog_gmail_import` | Import an RFC822/EML message into the mailbox (keeps its headers/date; does not send) |
 | `gog_gmail_forward` | Forward a message |
+| `gog_gmail_reply` | Reply to the original sender |
+| `gog_gmail_reply_all` | Reply to sender plus every To/Cc recipient |
 | `gog_gmail_autoreply` | Reply once to all messages matching a query |
 
-Plus 5 auth tools and 4 base Gmail tools (search, get, send, run). Use `gog_gmail_run` for advanced settings (`filters`, `delegates`, `forwarding`, `sendas`, `vacation`, `watch`) and email tracking (`track`).
+### Settings
+| Tool | What it does |
+|------|-------------|
+| `gog_gmail_vacation_get` | Get the vacation responder settings |
+| `gog_gmail_vacation_update` | Enable/disable the vacation responder |
+| `gog_gmail_filters_list` | List all filters |
+| `gog_gmail_filters_get` | Get a filter by ID |
+| `gog_gmail_filters_create` | Create a filter |
+| `gog_gmail_filters_delete` | Delete a filter |
+| `gog_gmail_sendas_list` | List send-as aliases |
+| `gog_gmail_sendas_get` | Get one send-as alias |
+| `gog_gmail_sendas_create` | Create a send-as alias |
+| `gog_gmail_sendas_update` | Update a send-as alias |
+| `gog_gmail_sendas_delete` | Delete a send-as alias |
+| `gog_gmail_sendas_verify` | Resend an alias verification email |
+
+Plus 8 auth tools and 4 base Gmail tools (search, get, send, run). Use `gog_gmail_run` for the settings with no dedicated tool (`delegates`, `forwarding`, `watch`) and email tracking (`track`).

package/dist/index.js

@@ -31435,6 +31435,13 @@ var TIMESTAMP_KEYS = /* @__PURE__ */ new Set([
   // Calendar event start/end
   "internalDate",
   // Gmail, epoch milliseconds (authoritative)
+  // gog >= 0.35.0 Gmail message AND thread listings. Already offset-bearing
+  // (RFC3339 from internalDate), so it needs no offset repair — it is
+  // allowlisted purely to gain a Display sibling, and to be re-rendered in
+  // DISPLAY_TZ like every other instant. Separately sourced from the sibling
+  // `date`, which is a naive re-format of the sender's Date header; the two may
+  // legitimately disagree. See docs/timestamps.md.
+  "internalDateIso",
   "modifiedTime",
   // Drive
   "createdTime",
@@ -31671,8 +31678,8 @@ function formatOneAccountHealth(a, now) {
   const age = ageInDays(a.created_at, now);
   const ageStr = age === null ? "" : ` Authorized ${age.toFixed(1)} day(s) ago.`;
   if (a.valid === false) {
-    const cause = INVALID_GRANT_PATTERN.test(a.error ?? "") ? 'refresh token expired or revoked \u2014 commonly the 7-day limit on OAuth consent screens still in "Testing" mode' : a.error?.trim() || "unknown error";
-    return `\u2717 ${email3}: NEEDS RE-AUTH \u2014 ${cause}.${ageStr} Re-authorize with gog_auth_add (browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless).`;
+    const cause2 = INVALID_GRANT_PATTERN.test(a.error ?? "") ? 'refresh token expired or revoked \u2014 commonly the 7-day limit on OAuth consent screens still in "Testing" mode' : a.error?.trim() || "unknown error";
+    return `\u2717 ${email3}: NEEDS RE-AUTH \u2014 ${cause2}.${ageStr} Re-authorize with gog_auth_add (browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless).`;
   }
   if (a.valid === true) {
     let line = `\u2713 ${email3}: token valid.${ageStr}`;
@@ -31714,7 +31721,7 @@ function registerAuthToolsWith(server, defaultServices) {
     }
   });
   server.registerTool("gog_auth_status", {
-    description: "Show gogcli auth configuration: keyring backend, credential files, and auth setup.",
+    description: "Show gogcli auth CONFIGURATION: keyring backend, credential files, and auth setup. Despite the name this is not a health check \u2014 it reads local setup and does not contact Google, so it says nothing about whether an account can still authenticate. Use gog_auth_health for that.",
     annotations: { readOnlyHint: true },
     inputSchema: {}
   }, async () => {
@@ -31725,7 +31732,7 @@ function registerAuthToolsWith(server, defaultServices) {
     }
   });
   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 \u2014 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.',
+    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 \u2014 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. On the hosted connector this is the ONLY check that measures Google: a connector showing "connected" or "refreshed" has verified the connector key that reaches the gog machine, and nothing else \u2014 the Google credential lives on that machine and can be dead while the connection looks perfectly healthy.',
     annotations: { readOnlyHint: true },
     inputSchema: {}
   }, async () => {
@@ -31889,14 +31896,29 @@ var failIfNotEmptyParam = external_exports.boolean().optional().describe(
 );
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.21.1" : "0.0.0";
+var VERSION = true ? "2.22.0" : "0.0.0";
 
 // ../gogcli-mcp/src/auth-log.ts
 var FAILURES = /* @__PURE__ */ new Set([
   "token.mint-failed",
   "grant.dead",
   "replay.failed",
-  "runner.auth-failed"
+  "runner.auth-failed",
+  "connect.key-rejected",
+  // An enrolment that could not proceed is a failure even though nobody is at
+  // fault: it is the only trace a half-enrolled connector leaves behind, and
+  // the absence of exactly this record is why DEFECT 4 could not be explained.
+  "connect.runner-unreachable",
+  "connect.google-unhealthy",
+  "refusal.google-unhealthy",
+  // The loudest record on this branch, and the only one that means "we cannot
+  // explain this". Google refused a real call while a live check of the same
+  // credential, taken seconds later, succeeded — so neither the 7-day cliff nor
+  // a revoked grant accounts for it. It is filed as a failure precisely because
+  // it is the record nobody may scroll past: it is the only evidence that could
+  // ever justify building something on the hosted path, and its absence over
+  // time is what retires that theory for good.
+  "refusal.google-ok"
 ]);
 var PREFIX = "gog-auth ";
 var TAG_CHARS = 12;
@@ -32043,10 +32065,39 @@ async function exchange(refreshToken, clientId, clientSecret) {
   return { accessToken: body.access_token, expiresAt: Date.now() + expiresInMs };
 }
 
+// ../gogcli-mcp/src/google-probe.ts
+var bool = (value) => typeof value === "boolean" ? value : void 0;
+var cause = (value) => typeof value === "string" && value.length > 0 ? value : void 0;
+function readGoogleProbe(body) {
+  const record2 = typeof body === "object" && body !== null ? body : {};
+  const measured = bool(record2.measured);
+  const reported = cause(record2.error);
+  if (measured === false) {
+    return {
+      kind: "unmeasured",
+      reason: reported ?? "the runner reported it could not measure the Google layer"
+    };
+  }
+  if (measured === true) {
+    if (bool(record2.ok) === true) return { kind: "ok" };
+    return {
+      kind: "unhealthy",
+      reason: reported ?? "the runner reported the Google layer unhealthy with no cause"
+    };
+  }
+  return {
+    kind: "unmeasured",
+    reason: reported ? `the runner did not report whether it measured the Google layer; it said: ${reported}` : "the runner did not report whether it measured the Google layer"
+  };
+}
+
 // ../gogcli-mcp/src/connector-runtime.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEADLINE_GRACE_MS = 5e3;
 var MIN_REPLAY_BUDGET_MS = 1e3;
+var REFUSAL_PROBE_TIMEOUT_MS = 4e3;
+var MIN_PROBE_BUDGET_MS = 1e3;
+var PROBE_INTERVAL_MS = 6e4;
 var RUNNER_GOG_FAILED = 422;
 var RUNNER_DRAINING = 503;
 var RUNNER_BAD_REQUEST = 400;
@@ -32093,7 +32144,7 @@ function gogTarget(args) {
   }
   return { service };
 }
-async function remintAfterGoogleRejection(err, used, args, readAccessToken, deadlineAt) {
+async function remintAfterGoogleRejection(err, used, args, readAccessToken, deadlineAt, probeGoogle) {
   if (!(err instanceof GogFailedError)) return void 0;
   const grantDead = REFRESH_TOKEN_DEAD_PATTERN.test(err.stderr);
   if (!grantDead && !GOOGLE_TOKEN_REJECTED_PATTERN.test(err.stderr)) return void 0;
@@ -32108,6 +32159,7 @@ async function remintAfterGoogleRejection(err, used, args, readAccessToken, dead
     return void 0;
   }
   if (!used) {
+    await probeGoogle(where);
     logAuthTransition("replay.declined", {
       ...where,
       reason: "no access token was supplied with the call, so gog acted as the backend volume\u2019s own identity"
@@ -32155,6 +32207,64 @@ async function remintAfterGoogleRejection(err, used, args, readAccessToken, dead
   return { token: fresh, budgetMs, invalidate: readAccessToken.invalidate, ...where };
 }
 function makeFlyExecutor(endpoint, key, readAccessToken) {
+  let lastProbeAt = Number.NEGATIVE_INFINITY;
+  const probeGoogleAfterRefusal = async (where, deadlineAt) => {
+    const record2 = { ...where, endpoint };
+    const now = Date.now();
+    const remainingMs = deadlineAt - now;
+    if (remainingMs < MIN_PROBE_BUDGET_MS) {
+      logAuthTransition("refusal.google-unmeasured", {
+        ...record2,
+        reason: `only ${remainingMs}ms of the call\u2019s deadline remained, so the Google layer was not measured rather than delay the caller\u2019s own error`
+      });
+      return;
+    }
+    if (now - lastProbeAt < PROBE_INTERVAL_MS) {
+      logAuthTransition("refusal.google-unmeasured", {
+        ...record2,
+        // "attempted", not "measured". `lastProbeAt` is stamped before the
+        // fetch and is deliberately NOT reset when the probe comes back with no
+        // verdict (a 404 from a runner too old to have the endpoint, a timeout,
+        // a dead socket) — the backend cost this throttle exists to bound was
+        // paid either way, and resetting it would let a retry loop storm a
+        // runner that is already unwell. So the timestamp stays and the sentence
+        // has to be the true one: on this branch a log line may not assert a
+        // measurement that never happened, and the previous probe may well have
+        // measured nothing at all.
+        reason: "a Google probe was attempted recently, so another was not sent: this probe spawns gog on the backend and takes the keyring\u2019s exclusive lock"
+      });
+      return;
+    }
+    lastProbeAt = now;
+    let event;
+    let reason;
+    try {
+      const res = await fetch(`${endpoint}/health/google`, {
+        headers: { Authorization: `Bearer ${key}` },
+        // Never more than the probe's own budget, never more than the call has
+        // left. `Math.min` rather than a plain constant because the second
+        // bound is the caller's, and it outranks ours.
+        signal: AbortSignal.timeout(Math.min(REFUSAL_PROBE_TIMEOUT_MS, remainingMs))
+      });
+      if (!res.ok) {
+        event = "refusal.google-unmeasured";
+        reason = `the runner did not answer the Google probe (HTTP ${res.status})`;
+      } else {
+        const verdict = readGoogleProbe(await res.json());
+        if (verdict.kind === "ok") {
+          event = "refusal.google-ok";
+          reason = "Google refused this call, yet a live token check on the same volume succeeded \u2014 so a dead or expired refresh token does not explain this refusal";
+        } else {
+          event = verdict.kind === "unhealthy" ? "refusal.google-unhealthy" : "refusal.google-unmeasured";
+          reason = verdict.reason;
+        }
+      }
+    } catch (err) {
+      event = "refusal.google-unmeasured";
+      reason = err instanceof Error ? err.message : String(err);
+    }
+    logAuthTransition(event, { ...record2, reason });
+  };
   return async (args, opts) => {
     const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
     const accessToken = await readAccessToken?.();
@@ -32167,7 +32277,8 @@ function makeFlyExecutor(endpoint, key, readAccessToken) {
         accessToken,
         args,
         readAccessToken,
-        deadlineAt
+        deadlineAt,
+        (where2) => probeGoogleAfterRefusal(where2, deadlineAt)
       );
       if (replay === void 0) throw err;
       const where = { credential: replay.credential, service: replay.service, endpoint };
@@ -32314,6 +32425,7 @@ function trimThread(result, latestN, snippetsOnly) {
     return result;
   }
 }
+var GOG_DEFAULT_INLINE_MAX_BYTES = 3145728;
 var MIME_BY_EXT = {
   pdf: "application/pdf",
   png: "image/png",
@@ -32375,13 +32487,29 @@ async function resolveBySize(messageId, sizeBytes, account) {
     return void 0;
   }
 }
+async function resolveByIndex(messageId, index, account) {
+  try {
+    const parsed = JSON.parse(
+      await run(["gmail", "get", messageId, "--use-indexed-attachment-ids"], { account })
+    );
+    const attachments = parsed.attachments;
+    if (!attachments) return void 0;
+    const declared = attachments.find((a) => a.attachmentIndex === index);
+    if (declared) return declared;
+    if (attachments.every((a) => a.attachmentIndex === void 0)) return attachments[index];
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
 function defaultOutPath(messageId, filename) {
   return `/tmp/gog-attachments/${messageId}/${filename}`;
 }
 function sanitizeAttachmentError(err, messageId, attachmentId) {
   let msg = err instanceof Error ? err.message : String(err);
   msg = msg.replace(/^Command failed:.*(\n|$)/, "");
-  msg = msg.split(attachmentId).join("<attachment>").split(messageId).join("<message>");
+  if (attachmentId) msg = msg.split(attachmentId).join("<attachment>");
+  msg = msg.split(messageId).join("<message>");
   return msg.trim() || "the download failed on the server";
 }
 function inlineImageResult(summary, base643, mimeType) {
@@ -32445,21 +32573,35 @@ function registerExtraGmailTools(server) {
     return runOrDiagnose(args, { account, lossless: true });
   });
   server.registerTool("gog_gmail_attachment", {
-    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 \u2014 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).`,
+    description: `Download a Gmail attachment and deliver its contents so you can actually read them. Identify the attachment by attachmentIndex (preferred: the 0-based position from a listing fetched with useIndexedAttachmentIds \u2014 stable, and it resolves the real name before the download) or by the legacy opaque attachmentId. 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 \u2014 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: external_exports.string().describe("Gmail message ID"),
-      attachmentId: external_exports.string().describe("Attachment ID (from the message payload)"),
+      attachmentId: external_exports.string().optional().describe("The opaque attachment ID from a listing. Legacy addressing: Gmail re-issues a DIFFERENT id for the same part on every API call, so an id copied from an older listing can be stale. Prefer attachmentIndex. Exactly one of attachmentId / attachmentIndex is required."),
+      attachmentIndex: external_exports.number().int().nonnegative().optional().describe("The attachment's 0-based position in its message \u2014 the `attachmentIndex` field of a listing fetched with useIndexedAttachmentIds. Stable (a message's MIME structure does not change), so this is the reliable way to name an attachment. Exactly one of attachmentId / attachmentIndex is required. NOTE: it is per-MESSAGE \u2014 in gog_gmail_thread_attachments the array is flattened across the whole thread, so use each row's messageId + attachmentIndex, never its position in that flat list."),
+      inlineMaxBytes: external_exports.number().int().nonnegative().optional().describe("Byte ceiling under which gog embeds the attachment bytes rather than only writing the file. Defaults to gog's own 3145728, which this server pins explicitly on every call so an ambient GOG_GMAIL_INLINE_MAX_BYTES cannot change the answer. Raise it to inline something larger, lower it to force the file/Drive path."),
       deliver: external_exports.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: external_exports.string().optional().describe("Server-side path where gog writes the file. NOTE: this resolves on the CONNECTOR/gog server's filesystem, not your machine \u2014 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: external_exports.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: external_exports.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, deliver = "auto", out, name, driveFolder, account }) => {
+  }, async ({ messageId, attachmentId, attachmentIndex, deliver = "auto", out, name, inlineMaxBytes, driveFolder, account }) => {
+    if (attachmentId === void 0 === (attachmentIndex === void 0)) {
+      return errorResult(
+        "Pass exactly one of attachmentId or attachmentIndex. Prefer attachmentIndex \u2014 the 0-based `attachmentIndex` from a listing fetched with useIndexedAttachmentIds \u2014 because Gmail's opaque attachmentId is not stable across API calls and a copied one may no longer resolve."
+      );
+    }
+    const indexed = attachmentIndex !== void 0;
+    const attachmentRef = indexed ? String(attachmentIndex) : attachmentId;
     const remote = runExecutor.getStore() !== void 0;
     try {
       let filename = name ? sanitizeFilename(name) : void 0;
       let mimeType = filename ? MIME_BY_EXT[extOf(filename)] : void 0;
+      if (indexed && !filename) {
+        const meta3 = await resolveByIndex(messageId, attachmentIndex, account);
+        if (meta3?.filename) filename = sanitizeFilename(meta3.filename);
+        if (meta3?.mimeType) mimeType = meta3.mimeType;
+      }
       const notes = [];
       let outPath = out;
       if (out && remote) {
@@ -32474,12 +32616,16 @@ function registerExtraGmailTools(server) {
       if (!mimeType && (deliver === "auto" || deliver === "inline")) {
         needInline = true;
       }
-      const args = ["gmail", "attachment", messageId, attachmentId];
+      const args = ["gmail", "attachment", messageId, attachmentRef];
+      args.push(indexed ? "--use-indexed-attachment-ids" : "--use-indexed-attachment-ids=false");
       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 path = info.path ?? outPath;
-      if (!filename) {
+      if (!filename && info.filename) filename = sanitizeFilename(info.filename);
+      if (!mimeType && info.mimeType) mimeType = info.mimeType;
+      if (!filename && !indexed) {
         const meta3 = await resolveBySize(messageId, info.bytes, account);
         if (meta3?.filename) filename = sanitizeFilename(meta3.filename);
         if (!mimeType && meta3?.mimeType) mimeType = meta3.mimeType;
@@ -32503,7 +32649,7 @@ function registerExtraGmailTools(server) {
           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.`
+          `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.`
         );
       }
       if (isImage && info.contentBase64) {
@@ -32645,15 +32791,17 @@ function registerExtraGmailTools(server) {
       sanitizeContent: external_exports.boolean().optional().describe("Strip HTML, remove URLs, omit raw payloads from JSON (largest payload-size reduction)"),
       latestN: external_exports.number().int().positive().optional().describe("Return only the most recent N messages in the thread (wrapper-side trim; avoids overflowing context on long threads)"),
       snippetsOnly: external_exports.boolean().optional().describe("Reduce each message to its id, labels, snippet, and key headers (From/To/Cc/Subject/Date), dropping full bodies"),
+      useIndexedAttachmentIds: external_exports.boolean().optional().describe("Report each attachment as a 0-based `attachmentIndex` within its message instead of an opaque `attachmentId`. The index is stable across calls (a message's MIME structure does not change) while the id is not, so this is what you want before calling gog_gmail_attachment."),
       outDir: external_exports.string().optional().describe("Directory to write attachments to (default: current directory)"),
       account: accountParam
     }
-  }, async ({ threadId, download, full, sanitizeContent, latestN, snippetsOnly, outDir, account }) => {
+  }, async ({ threadId, download, full, sanitizeContent, latestN, snippetsOnly, useIndexedAttachmentIds, outDir, account }) => {
     const args = ["gmail", "thread", "get", threadId];
     if (download) args.push("--download");
     if (full) args.push("--full");
     if (sanitizeContent) args.push("--sanitize-content");
     if (outDir) args.push(`--out-dir=${outDir}`);
+    args.push(useIndexedAttachmentIds ? "--use-indexed-attachment-ids" : "--use-indexed-attachment-ids=false");
     const result = await runOrDiagnose(args, { account });
     if (latestN === void 0 && !snippetsOnly) return result;
     return trimThread(result, latestN, snippetsOnly);
@@ -32679,13 +32827,15 @@ function registerExtraGmailTools(server) {
     inputSchema: {
       threadId: external_exports.string().describe("Gmail thread ID"),
       download: external_exports.boolean().optional().describe("Download all attachments to the SERVER filesystem (see the note above; on the remote connector the files aren't reachable \u2014 fetch individually with gog_gmail_attachment instead)."),
+      useIndexedAttachmentIds: external_exports.boolean().optional().describe("Report each attachment as a 0-based `attachmentIndex` instead of an opaque `attachmentId`. Set this before calling gog_gmail_attachment: the index is stable across calls, the id is not. The index counts WITHIN each message, and this listing flattens every message's attachments into one array \u2014 so pair each row's `messageId` with its own `attachmentIndex`; a row's position in the flat array is NOT the index."),
       outDir: external_exports.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 }) => {
+  }, async ({ threadId, download, useIndexedAttachmentIds, outDir, account }) => {
     const args = ["gmail", "thread", "attachments", threadId];
     if (download) args.push("--download");
     if (outDir) args.push(`--out-dir=${outDir}`);
+    args.push(useIndexedAttachmentIds ? "--use-indexed-attachment-ids" : "--use-indexed-attachment-ids=false");
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_gmail_labels_list", {
@@ -32774,11 +32924,13 @@ function registerExtraGmailTools(server) {
     inputSchema: {
       draftId: external_exports.string().describe("Draft ID"),
       download: external_exports.boolean().optional().describe("Download draft attachments"),
+      useIndexedAttachmentIds: external_exports.boolean().optional().describe("Report each attachment as a 0-based `attachmentIndex` instead of an opaque `attachmentId` (stable across calls, unlike the id)."),
       account: accountParam
     }
-  }, async ({ draftId, download, account }) => {
+  }, async ({ draftId, download, useIndexedAttachmentIds, account }) => {
     const args = ["gmail", "drafts", "get", draftId];
     if (download) args.push("--download");
+    args.push(useIndexedAttachmentIds ? "--use-indexed-attachment-ids" : "--use-indexed-attachment-ids=false");
     return runOrDiagnose(args, { account });
   });
   const draftWriteSchema = {
@@ -32788,7 +32940,7 @@ function registerExtraGmailTools(server) {
     subject: external_exports.string().describe("Subject"),
     body: external_exports.string().describe("Body (plain text). Any size \u2014 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: external_exports.string().optional().describe("Body (HTML; optional). Pass the HTML itself at any size \u2014 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: external_exports.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 \u2014 supplying both is rejected. You rarely need this: bodyHtml handles large bodies on its own.'),
+    bodyHtmlFile: external_exports.string().optional().describe(`Path to an HTML file that ALREADY EXISTS on the gog server to use as the HTML body. gog also accepts "-" for stdin, but this server never writes to gog's stdin, so "-" would hang until the call times out. Mutually exclusive with bodyHtml \u2014 supplying both is rejected. You rarely need this: bodyHtml handles large bodies on its own.`),
     replyToMessageId: external_exports.string().optional().describe("Reply to a specific Gmail MESSAGE id \u2014 the short hex `id` field from gog_gmail_get / _search / _thread_get (e.g. 19e7593d77fd9636), NOT a thread id and NOT the RFC822 `<\u2026@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: external_exports.string().optional().describe(`Reply to a Gmail THREAD id \u2014 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 \u2014 use this param, not replyToMessageId, when the id came from a thread.`),
     replyTo: external_exports.string().optional().describe("Reply-To header address"),
@@ -32796,6 +32948,7 @@ function registerExtraGmailTools(server) {
     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)."),
     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."),
     returnFull: external_exports.boolean().optional().describe("After writing, re-fetch and return the full stored draft (subject, body, recipients) instead of just the write acknowledgement. Costs one extra read."),
     account: accountParam
@@ -32818,6 +32971,7 @@ function registerExtraGmailTools(server) {
     if (f.quote) args.push("--quote");
     if (f.attach) for (const path of f.attach) args.push(`--attach=${path}`);
     if (f.from) args.push(`--from=${f.from}`);
+    args.push(f.autoFromAddressedAlias ? "--auto-from-addressed-alias" : "--auto-from-addressed-alias=false");
   }
   async function writeDraft(args, account, returnFull, knownDraftId) {
     const result = await runOrDiagnose(args, { account });
@@ -32830,7 +32984,7 @@ function registerExtraGmailTools(server) {
     }
     const draftId = knownDraftId ?? parsed.draftId;
     if (!draftId) return result;
-    return runOrDiagnose(["gmail", "drafts", "get", draftId], { account });
+    return runOrDiagnose(["gmail", "drafts", "get", draftId, "--use-indexed-attachment-ids=false"], { account });
   }
   server.registerTool("gog_gmail_drafts_create", {
     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) \u2014 don't pass a thread id into replyToMessageId, which mis-threads silently.",
@@ -32879,6 +33033,24 @@ function registerExtraGmailTools(server) {
   }, async ({ draftId, account }) => {
     return runOrDiagnose(["gmail", "drafts", "send", draftId], { account });
   });
+  server.registerTool("gog_gmail_import", {
+    description: "Import an existing RFC822/EML message INTO the mailbox. This is Gmail's import path, not a send: nothing leaves the account, and the message keeps its own From/Date/Message-Id headers so it files where it belongs chronologically. Use it to restore an exported message or to file a .eml under a label; to actually send mail use gog_gmail_send, and to stage one use gog_gmail_drafts_create. The file is read on the gog SERVER, not your machine.",
+    inputSchema: {
+      file: external_exports.string().describe(`Path to an RFC822/EML file that ALREADY EXISTS on the gog server. gog also accepts "-" for stdin, but this server never writes to gog's stdin, so "-" would hang until the call times out.`),
+      labels: external_exports.array(external_exports.string()).optional().describe(`Labels to apply to the imported message (repeatable). Each may be a label ID or a label name \u2014 names are resolved server-side. A name containing a COMMA cannot be passed here: gog declares --label as a Kong slice with no separator override, so Kong splits each value on commas and "Clients, Inc" is looked up as two labels ("Clients" and "Inc") and fails. Use that label's ID instead \u2014 ids never contain a comma; gog_gmail_labels_list gives you one.`),
+      internalDateSource: external_exports.enum(["dateHeader", "receivedTime"]).optional().describe("Which clock sets Gmail's internal date: dateHeader (gog default \u2014 the message's own Date header, so it sorts into the mailbox at its original time) or receivedTime (now)."),
+      neverMarkSpam: external_exports.boolean().optional().describe("Never classify the imported message as spam."),
+      processForCalendar: external_exports.boolean().optional().describe("Process calendar invitations inside the imported message \u2014 this can ADD EVENTS to your calendar."),
+      account: accountParam
+    }
+  }, async ({ file: file2, labels, internalDateSource, neverMarkSpam, processForCalendar, account }) => {
+    const args = ["gmail", "import", file2];
+    if (labels) for (const label of labels) args.push(`--label=${label}`);
+    if (internalDateSource) args.push(`--internal-date-source=${internalDateSource}`);
+    if (neverMarkSpam) args.push("--never-mark-spam");
+    if (processForCalendar) args.push("--process-for-calendar");
+    return runOrDiagnose(args, { account });
+  });
   server.registerTool("gog_gmail_forward", {
     description: "Forward an existing Gmail message to new recipients.",
     annotations: { destructiveHint: true },
@@ -32905,7 +33077,7 @@ function registerExtraGmailTools(server) {
     messageId: external_exports.string().describe("Gmail message ID to reply to \u2014 the short hex `id` from gog_gmail_get / _search / _messages_search (NOT the threadId, NOT the RFC822 `<\u2026@host>` Message-Id header)."),
     body: external_exports.string().optional().describe("Reply body (plain text; required unless bodyHtml or bodyHtmlFile is set). Any size \u2014 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: external_exports.string().optional().describe("Reply body (HTML; optional). Pass the HTML itself at any size \u2014 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: external_exports.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 \u2014 supplying both is rejected. You rarely need this: bodyHtml handles large bodies on its own.'),
+    bodyHtmlFile: external_exports.string().optional().describe(`Path to an HTML file that ALREADY EXISTS on the gog server for the reply body. gog also accepts "-" for stdin, but this server never writes to gog's stdin, so "-" would hang until the call times out. Mutually exclusive with bodyHtml \u2014 supplying both is rejected. You rarely need this: bodyHtml handles large bodies on its own.`),
     to: external_exports.array(external_exports.string()).optional().describe("Add or move recipients to To (repeatable). Added on top of the recipients inherited from the original message."),
     cc: external_exports.array(external_exports.string()).optional().describe("Add or move recipients to Cc (repeatable)"),
     bcc: external_exports.array(external_exports.string()).optional().describe("Add or move recipients to Bcc (repeatable)"),
@@ -32914,6 +33086,7 @@ function registerExtraGmailTools(server) {
     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."),
     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"),
     signatureFrom: external_exports.string().optional().describe("Append the Gmail signature from this send-as email address"),
     signatureFile: external_exports.string().optional().describe("Append a local signature file (plain text or HTML), read on the gog server"),
@@ -32935,6 +33108,7 @@ function registerExtraGmailTools(server) {
     if (f.signature) args.push("--signature");
     if (f.signatureFrom) args.push(`--signature-from=${f.signatureFrom}`);
     if (f.signatureFile) args.push(`--signature-file=${f.signatureFile}`);
+    args.push(f.autoFromAddressedAlias ? "--auto-from-addressed-alias" : "--auto-from-addressed-alias=false");
   }
   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.',
@@ -32998,9 +33172,11 @@ function registerExtraGmailTools(server) {
       includeBody: external_exports.boolean().optional().describe("Include the decoded message body in each result"),
       full: external_exports.boolean().optional().describe("Show full message bodies without truncation (implies includeBody)"),
       bodyFormat: external_exports.enum(["text", "html"]).optional().describe("Body format preference when includeBody is set"),
+      includeAttachments: external_exports.boolean().optional().describe("Include each message's attachment metadata (filename, size, mimeType, id or index). NOT a cheap add-on: like includeBody it makes gog fetch every matching message at format=full, so it costs a full per-message read \u2014 narrow the query or lower max before turning it on."),
+      useIndexedAttachmentIds: external_exports.boolean().optional().describe("Report each attachment as a 0-based `attachmentIndex` within its message instead of an opaque `attachmentId` (stable across calls, unlike the id). Only has an effect alongside includeAttachments or includeBody."),
       account: accountParam
     }
-  }, async ({ query, max, page, all, includeBody, full, bodyFormat, account }) => {
+  }, async ({ query, max, page, all, includeBody, full, bodyFormat, includeAttachments, useIndexedAttachmentIds, account }) => {
     const args = ["gmail", "messages", "search", query];
     if (max !== void 0) args.push(`--max=${max}`);
     if (page) args.push(`--page=${page}`);
@@ -33008,6 +33184,8 @@ function registerExtraGmailTools(server) {
     if (includeBody) args.push("--include-body");
     if (full) args.push("--full");
     if (bodyFormat) args.push(`--body-format=${bodyFormat}`);
+    args.push(includeAttachments ? "--include-attachments" : "--include-attachments=false");
+    args.push(useIndexedAttachmentIds ? "--use-indexed-attachment-ids" : "--use-indexed-attachment-ids=false");
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_gmail_labels_style", {

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-gmail",
   "display_name": "gogcli (Gmail)",
-  "version": "2.21.1",
+  "version": "2.22.0",
   "description": "Extended Gmail for Claude via gogcli — auth + full Gmail support (threads, labels, drafts, attachments, forward, autoreply, bulk operations)",
   "author": {
     "name": "Chris Hall",
@@ -111,7 +111,7 @@
     },
     {
       "name": "gog_gmail_attachment",
-      "description": "Download a Gmail attachment and deliver its contents: inline (base64 image/resource) when within the 3 MiB limit, otherwise uploaded to Google Drive with a shareable link"
+      "description": "Download a Gmail attachment by 0-based attachmentIndex (or legacy attachmentId) and deliver its contents: inline (base64 image/resource) when within the inline limit, otherwise uploaded to Google Drive with a shareable link"
     },
     {
       "name": "gog_gmail_url",
@@ -209,6 +209,10 @@
       "name": "gog_gmail_drafts_send",
       "description": "Send an existing Gmail draft"
     },
+    {
+      "name": "gog_gmail_import",
+      "description": "Import an RFC822/EML message into the mailbox (keeps its original headers and date; does not send)"
+    },
     {
       "name": "gog_gmail_forward",
       "description": "Forward a Gmail message to new recipients"