gogcli-mcp-gmail 2.0.12 → 2.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [2.1.0](https://github.com/chrischall/gogcli-mcp/compare/v2.0.13...v2.1.0) (2026-05-25)
+
+
+### Features
+
+* **gmail:** add gogcli-mcp-gmail sub-package ([fac0f51](https://github.com/chrischall/gogcli-mcp/commit/fac0f515fd2ea587c570d7ac70c080cb8dc486ac))
+
+
+### Refactor
+
+* aggressive cleanup pass (audit findings) ([e635b39](https://github.com/chrischall/gogcli-mcp/commit/e635b391cf611e9c102a422ffbce5ebe28687b80))
+* review-pass cleanup (enums, shared schemas, test harness) ([ea851de](https://github.com/chrischall/gogcli-mcp/commit/ea851deb30b9cfef3f07ed506a011fc363b34018))
+
+
+### Documentation
+
+* update gogcli repo URLs to openclaw/gogcli (was steipete/gogcli) ([951a181](https://github.com/chrischall/gogcli-mcp/commit/951a1818ebc269f203aee723ccbea32c13817d8b))

package/dist/index.js

@@ -31074,7 +31074,7 @@ async function run(args, options = {}) {
 
 // ../gogcli-mcp/src/tools/utils.ts
 var accountParam = external_exports.string().optional().describe(
-  "Google account email to use (overrides GOG_ACCOUNT env var)"
+  "Google account email to use, e.g. you@gmail.com \u2014 must be the full address, not a bare username. Overrides the GOG_ACCOUNT env var. Omit to use the single configured account."
 );
 var ids = {
   course: external_exports.string().describe("Course ID"),
@@ -31133,26 +31133,41 @@ function toError(err) {
 }
 var AUTH_ERROR_PATTERN = /\b(401|unauthorized|token.*(expired|revoked)|invalid_grant)\b/i;
 var TRANSIENT_ERROR_PATTERN = /\b429\b|\b5\d\d\b|\bquota\b|rateLimit|\bDEADLINE_EXCEEDED\b/i;
+var GRID_LIMIT_ERROR_PATTERN = /exceeds grid limits/i;
 var AUTH_HINT = "\n\nAuthentication may have expired. Use gog_auth_add to re-authorize the account. Ask the user if they would like to re-authenticate.";
 var TRANSIENT_HINT = "\n\nThis error is often transient. Retry the same call before trying a different approach (do not fall back to smaller writes or row-by-row operations).";
+var GRID_LIMIT_HINT = "\n\nThe target range is outside the sheet's current grid. Add the missing rows or columns first with gog_sheets_insert (dimension: rows or cols), then retry the write.";
+function formatAccountList(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed?.accounts)) {
+      return parsed.accounts.map((a) => a?.email).filter(Boolean).join("\n");
+    }
+  } catch {
+  }
+  return raw.trim();
+}
+async function diagnose(err) {
+  const errText = toError(err).content[0].text;
+  const isAuthError = AUTH_ERROR_PATTERN.test(errText);
+  const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
+  const isGridLimitError = GRID_LIMIT_ERROR_PATTERN.test(errText);
+  const hint = isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : isGridLimitError ? GRID_LIMIT_HINT : "";
+  try {
+    const accounts = formatAccountList(await run(["auth", "list"]));
+    return toText(`${errText}
+
+Configured accounts:
+${accounts || "(none)"}${hint}`);
+  } catch {
+    return toText(`${errText}${hint}`);
+  }
+}
 async function runOrDiagnose(args, options) {
   try {
     return toText(await run(args, options));
   } catch (err) {
-    const base = toError(err);
-    const errText = base.content[0].text;
-    const isAuthError = AUTH_ERROR_PATTERN.test(errText);
-    const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
-    const hint = isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : "";
-    try {
-      const accounts = await run(["auth", "list"]);
-      return toText(`${errText}
-
-Configured accounts:
-${accounts}${hint}`);
-    } catch {
-      return toText(`${errText}${hint}`);
-    }
+    return diagnose(err);
   }
 }
 
@@ -31221,7 +31236,7 @@ function registerAuthTools(server2) {
 // ../gogcli-mcp/src/tools/gmail.ts
 function registerGmailTools(server2) {
   server2.registerTool("gog_gmail_search", {
-    description: 'Search Gmail threads using Gmail query syntax (e.g. "from:alice subject:invoice is:unread").',
+    description: `Search Gmail threads using Gmail query syntax (e.g. "from:alice subject:invoice is:unread"). The query is passed verbatim to Gmail; a bare name token (from:alison) matches per Gmail's own heuristics, a full address (from:alison@example.com) is exact. To match a contact across several addresses, OR them: from:(a@x.com OR b@y.com).`,
     annotations: { readOnlyHint: true },
     inputSchema: {
       query: external_exports.string().describe("Gmail search query"),
@@ -31272,9 +31287,15 @@ function registerGmailTools(server2) {
 
 // ../gogcli-mcp/src/tools/sheets.ts
 var cellValueParam = external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean(), external_exports.null()]);
+var dryRunParam = external_exports.boolean().optional().describe(
+  "Preview the operation without modifying the sheet (gog --dry-run): reports the intended actions and exits without writing."
+);
+var failIfNotEmptyParam = external_exports.boolean().optional().describe(
+  'Safety guard against silent overwrites: before writing, read the target range and refuse the write if any target cell already holds data. Costs one extra read. Anchor ranges (e.g. "Sheet1!A1") are expanded to the full area your values will cover; explicit and named ranges are checked as-is.'
+);
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.0.12" : "0.0.0";
+var VERSION = true ? "2.2.0" : "0.0.0";
 function createServer(options) {
   return new McpServer({
     name: options?.name ?? "gogcli",
@@ -31283,6 +31304,37 @@ function createServer(options) {
 }
 
 // src/tools/gmail-extra.ts
+var SNIPPET_HEADERS = ["From", "To", "Cc", "Subject", "Date"];
+function summarizeMessage(m) {
+  const rawHeaders = m.payload?.headers;
+  const headers = {};
+  if (Array.isArray(rawHeaders)) {
+    for (const h of rawHeaders) {
+      if (h.name && SNIPPET_HEADERS.includes(h.name)) headers[h.name] = h.value;
+    }
+  }
+  return {
+    id: m.id,
+    threadId: m.threadId,
+    internalDate: m.internalDate,
+    labelIds: m.labelIds,
+    snippet: m.snippet,
+    headers
+  };
+}
+function trimThread(result, latestN, snippetsOnly) {
+  try {
+    const parsed = JSON.parse(result.content[0].text);
+    const messages = parsed.thread?.messages;
+    if (!Array.isArray(messages)) return result;
+    let trimmed = messages;
+    if (latestN !== void 0) trimmed = trimmed.slice(-latestN);
+    if (snippetsOnly) trimmed = trimmed.map((m) => summarizeMessage(m));
+    return toText(JSON.stringify({ ...parsed, thread: { ...parsed.thread, messages: trimmed } }));
+  } catch {
+    return result;
+  }
+}
 function registerExtraGmailTools(server2) {
   server2.registerTool("gog_gmail_raw", {
     description: "Dump the raw Gmail API response as JSON (lossless; for scripting and LLM consumption).",
@@ -31424,23 +31476,27 @@ function registerExtraGmailTools(server2) {
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_gmail_thread_get", {
-    description: "Get a Gmail thread with all messages, optionally downloading attachments and sanitizing content for agent consumption.",
+    description: "Get a Gmail thread with all messages. For long threads that overflow context, use latestN to fetch only the most recent messages and/or snippetsOnly for a lightweight per-message headers+snippet view; sanitizeContent strips raw payloads/HTML and is the biggest size reducer when you do need bodies.",
     annotations: { readOnlyHint: true },
     inputSchema: {
       threadId: external_exports.string().describe("Gmail thread ID"),
       download: external_exports.boolean().optional().describe("Download all attachments"),
       full: external_exports.boolean().optional().describe("Show full message bodies"),
-      sanitizeContent: external_exports.boolean().optional().describe("Strip HTML, remove URLs, omit raw payloads from JSON"),
+      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"),
       outDir: external_exports.string().optional().describe("Directory to write attachments to (default: current directory)"),
       account: accountParam
     }
-  }, async ({ threadId, download, full, sanitizeContent, outDir, account }) => {
+  }, async ({ threadId, download, full, sanitizeContent, latestN, snippetsOnly, 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}`);
-    return runOrDiagnose(args, { account });
+    const result = await runOrDiagnose(args, { account });
+    if (latestN === void 0 && !snippetsOnly) return result;
+    return trimThread(result, latestN, snippetsOnly);
   });
   server2.registerTool("gog_gmail_thread_modify", {
     description: "Modify labels on all messages in a thread (add and/or remove labels).",
@@ -31577,12 +31633,16 @@ function registerExtraGmailTools(server2) {
     quote: external_exports.boolean().optional().describe("Include quoted original message in reply (requires replyToMessageId)"),
     attach: external_exports.array(external_exports.string()).optional().describe("Attachment file paths (repeatable)"),
     from: external_exports.string().optional().describe("Send from this email address (must be a verified send-as alias)"),
+    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
   };
   function appendDraftFlags(args, f) {
-    if (f.to) args.push(`--to=${f.to}`);
-    if (f.cc) args.push(`--cc=${f.cc}`);
-    if (f.bcc) args.push(`--bcc=${f.bcc}`);
+    if (!f.omitRecipients) {
+      if (f.to) args.push(`--to=${f.to}`);
+      if (f.cc) args.push(`--cc=${f.cc}`);
+      if (f.bcc) args.push(`--bcc=${f.bcc}`);
+    }
     args.push(`--subject=${f.subject}`);
     args.push(`--body=${f.body}`);
     if (f.bodyHtml) args.push(`--body-html=${f.bodyHtml}`);
@@ -31592,13 +31652,26 @@ function registerExtraGmailTools(server2) {
     if (f.attach) for (const path of f.attach) args.push(`--attach=${path}`);
     if (f.from) args.push(`--from=${f.from}`);
   }
+  async function writeDraft(args, account, returnFull, knownDraftId) {
+    const result = await runOrDiagnose(args, { account });
+    if (!returnFull) return result;
+    let parsed;
+    try {
+      parsed = JSON.parse(result.content[0].text);
+    } catch {
+      return result;
+    }
+    const draftId = knownDraftId ?? parsed.draftId;
+    if (!draftId) return result;
+    return runOrDiagnose(["gmail", "drafts", "get", draftId], { account });
+  }
   server2.registerTool("gog_gmail_drafts_create", {
-    description: "Create a new Gmail draft.",
+    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.",
     inputSchema: draftWriteSchema
-  }, async ({ account, ...flags }) => {
+  }, async ({ account, returnFull, ...flags }) => {
     const args = ["gmail", "drafts", "create"];
     appendDraftFlags(args, flags);
-    return runOrDiagnose(args, { account });
+    return writeDraft(args, account, returnFull);
   });
   server2.registerTool("gog_gmail_drafts_update", {
     description: "Update an existing Gmail draft.",
@@ -31607,20 +31680,23 @@ function registerExtraGmailTools(server2) {
       draftId: external_exports.string().describe("Draft ID"),
       ...draftWriteSchema
     }
-  }, async ({ draftId, account, ...flags }) => {
+  }, async ({ draftId, account, returnFull, ...flags }) => {
     const args = ["gmail", "drafts", "update", draftId];
     appendDraftFlags(args, flags);
-    return runOrDiagnose(args, { account });
+    return writeDraft(args, account, returnFull, draftId);
   });
   server2.registerTool("gog_gmail_drafts_delete", {
-    description: "Delete a Gmail draft.",
+    description: "Permanently delete a Gmail draft (not reversible \u2014 drafts do not go to Trash). Requires force:true to delete non-interactively.",
     annotations: { destructiveHint: true },
     inputSchema: {
       draftId: external_exports.string().describe("Draft ID"),
+      force: external_exports.boolean().optional().describe("Required to delete in this non-interactive context \u2014 without it the delete is refused as a safety guard."),
       account: accountParam
     }
-  }, async ({ draftId, account }) => {
-    return runOrDiagnose(["gmail", "drafts", "delete", draftId], { account });
+  }, async ({ draftId, account, force }) => {
+    const args = ["gmail", "drafts", "delete", draftId];
+    if (force) args.push("--force");
+    return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_gmail_drafts_send", {
     description: "Send an existing Gmail draft.",

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-gmail",
   "display_name": "gogcli (Gmail)",
-  "version": "2.0.12",
+  "version": "2.2.0",
   "description": "Extended Gmail for Claude via gogcli — auth + full Gmail support (threads, labels, drafts, attachments, forward, autoreply, bulk operations)",
   "author": {
     "name": "Chris Hall",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-gmail",
-  "version": "2.0.12",
+  "version": "2.2.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

@@ -1,6 +1,62 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose } from '../../../gogcli-mcp/src/lib.js';
+import { accountParam, runOrDiagnose, toText, type ToolResult } from '../../../gogcli-mcp/src/lib.js';
+
+type GmailHeader = { name?: string; value?: string };
+type GmailMessage = {
+  id?: string;
+  threadId?: string;
+  internalDate?: string;
+  labelIds?: string[];
+  snippet?: string;
+  payload?: { headers?: GmailHeader[] };
+};
+
+// Headers worth keeping in a snippets-only thread view.
+const SNIPPET_HEADERS = ['From', 'To', 'Cc', 'Subject', 'Date'];
+
+// Reduce a full Gmail message to a lightweight overview: id/labels/snippet plus
+// the key envelope headers, dropping the raw MIME payload that dominates the
+// size of a thread fetch.
+function summarizeMessage(m: GmailMessage): Record<string, unknown> {
+  const rawHeaders = m.payload?.headers;
+  const headers: Record<string, string | undefined> = {};
+  if (Array.isArray(rawHeaders)) {
+    for (const h of rawHeaders) {
+      if (h.name && SNIPPET_HEADERS.includes(h.name)) headers[h.name] = h.value;
+    }
+  }
+  return {
+    id: m.id,
+    threadId: m.threadId,
+    internalDate: m.internalDate,
+    labelIds: m.labelIds,
+    snippet: m.snippet,
+    headers,
+  };
+}
+
+// Wrapper-side trim of a `gog gmail thread get` JSON result: keep only the last
+// `latestN` messages and/or reduce each to a snippet view. gog has no native
+// message-limit flag, so this is done by post-processing its output. Any
+// non-JSON output (an error, an unexpected shape) is passed through untouched.
+function trimThread(
+  result: ToolResult,
+  latestN: number | undefined,
+  snippetsOnly: boolean | undefined,
+): ToolResult {
+  try {
+    const parsed = JSON.parse(result.content[0].text) as { thread?: { messages?: unknown[] } };
+    const messages = parsed.thread?.messages;
+    if (!Array.isArray(messages)) return result;
+    let trimmed: unknown[] = messages;
+    if (latestN !== undefined) trimmed = trimmed.slice(-latestN);
+    if (snippetsOnly) trimmed = trimmed.map((m) => summarizeMessage(m as GmailMessage));
+    return toText(JSON.stringify({ ...parsed, thread: { ...parsed.thread, messages: trimmed } }));
+  } catch {
+    return result;
+  }
+}
 
 export function registerExtraGmailTools(server: McpServer): void {
   server.registerTool('gog_gmail_raw', {
@@ -152,23 +208,27 @@ export function registerExtraGmailTools(server: McpServer): void {
   });
 
   server.registerTool('gog_gmail_thread_get', {
-    description: 'Get a Gmail thread with all messages, optionally downloading attachments and sanitizing content for agent consumption.',
+    description: 'Get a Gmail thread with all messages. For long threads that overflow context, use latestN to fetch only the most recent messages and/or snippetsOnly for a lightweight per-message headers+snippet view; sanitizeContent strips raw payloads/HTML and is the biggest size reducer when you do need bodies.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       threadId: z.string().describe('Gmail thread ID'),
       download: z.boolean().optional().describe('Download all attachments'),
       full: z.boolean().optional().describe('Show full message bodies'),
-      sanitizeContent: z.boolean().optional().describe('Strip HTML, remove URLs, omit raw payloads from JSON'),
+      sanitizeContent: z.boolean().optional().describe('Strip HTML, remove URLs, omit raw payloads from JSON (largest payload-size reduction)'),
+      latestN: z.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: z.boolean().optional().describe('Reduce each message to its id, labels, snippet, and key headers (From/To/Cc/Subject/Date), dropping full bodies'),
       outDir: z.string().optional().describe('Directory to write attachments to (default: current directory)'),
       account: accountParam,
     },
-  }, async ({ threadId, download, full, sanitizeContent, outDir, account }) => {
+  }, async ({ threadId, download, full, sanitizeContent, latestN, snippetsOnly, 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}`);
-    return runOrDiagnose(args, { account });
+    const result = await runOrDiagnose(args, { account });
+    if (latestN === undefined && !snippetsOnly) return result;
+    return trimThread(result, latestN, snippetsOnly);
   });
 
   server.registerTool('gog_gmail_thread_modify', {
@@ -316,6 +376,8 @@ export function registerExtraGmailTools(server: McpServer): void {
     quote: z.boolean().optional().describe('Include quoted original message in reply (requires replyToMessageId)'),
     attach: z.array(z.string()).optional().describe('Attachment file paths (repeatable)'),
     from: z.string().optional().describe('Send from this email address (must be a verified send-as alias)'),
+    omitRecipients: z.boolean().optional().describe('Create the draft with no recipients even if to/cc/bcc are supplied — an accidental-send guard. Populate recipients in a later update before sending.'),
+    returnFull: z.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,
   };
 
@@ -331,12 +393,15 @@ export function registerExtraGmailTools(server: McpServer): void {
     quote?: boolean;
     attach?: string[];
     from?: string;
+    omitRecipients?: boolean;
   };
 
   function appendDraftFlags(args: string[], f: DraftFlags): void {
-    if (f.to) args.push(`--to=${f.to}`);
-    if (f.cc) args.push(`--cc=${f.cc}`);
-    if (f.bcc) args.push(`--bcc=${f.bcc}`);
+    if (!f.omitRecipients) {
+      if (f.to) args.push(`--to=${f.to}`);
+      if (f.cc) args.push(`--cc=${f.cc}`);
+      if (f.bcc) args.push(`--bcc=${f.bcc}`);
+    }
     args.push(`--subject=${f.subject}`);
     args.push(`--body=${f.body}`);
     if (f.bodyHtml) args.push(`--body-html=${f.bodyHtml}`);
@@ -347,13 +412,41 @@ export function registerExtraGmailTools(server: McpServer): void {
     if (f.from) args.push(`--from=${f.from}`);
   }
 
+  // Run a draft write, then — when returnFull is set — re-fetch the stored
+  // draft so the caller can verify subject/body/recipients persisted without a
+  // separate gog_gmail_drafts_get round trip. For updates the id is known up
+  // front; for creates it's read from the write response's draftId. Degrades to
+  // the raw write result if the id can't be determined.
+  async function writeDraft(
+    args: string[],
+    account: string | undefined,
+    returnFull: boolean | undefined,
+    knownDraftId?: string,
+  ): Promise<ToolResult> {
+    const result = await runOrDiagnose(args, { account });
+    if (!returnFull) return result;
+    // The write must have returned a JSON acknowledgement before we re-fetch.
+    // A failed write (an error ToolResult, not JSON) is surfaced as-is rather
+    // than masked by re-fetching the unchanged draft — this matters for the
+    // update path, where a known draftId would otherwise re-fetch a stale draft.
+    let parsed: { draftId?: string };
+    try {
+      parsed = JSON.parse(result.content[0].text) as { draftId?: string };
+    } catch {
+      return result;
+    }
+    const draftId = knownDraftId ?? parsed.draftId;
+    if (!draftId) return result;
+    return runOrDiagnose(['gmail', 'drafts', 'get', draftId], { account });
+  }
+
   server.registerTool('gog_gmail_drafts_create', {
-    description: 'Create a new Gmail draft.',
+    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.',
     inputSchema: draftWriteSchema,
-  }, async ({ account, ...flags }) => {
+  }, async ({ account, returnFull, ...flags }) => {
     const args = ['gmail', 'drafts', 'create'];
     appendDraftFlags(args, flags);
-    return runOrDiagnose(args, { account });
+    return writeDraft(args, account, returnFull);
   });
 
   server.registerTool('gog_gmail_drafts_update', {
@@ -363,21 +456,24 @@ export function registerExtraGmailTools(server: McpServer): void {
       draftId: z.string().describe('Draft ID'),
       ...draftWriteSchema,
     },
-  }, async ({ draftId, account, ...flags }) => {
+  }, async ({ draftId, account, returnFull, ...flags }) => {
     const args = ['gmail', 'drafts', 'update', draftId];
     appendDraftFlags(args, flags);
-    return runOrDiagnose(args, { account });
+    return writeDraft(args, account, returnFull, draftId);
   });
 
   server.registerTool('gog_gmail_drafts_delete', {
-    description: 'Delete a Gmail draft.',
+    description: 'Permanently delete a Gmail draft (not reversible — drafts do not go to Trash). Requires force:true to delete non-interactively.',
     annotations: { destructiveHint: true },
     inputSchema: {
       draftId: z.string().describe('Draft ID'),
+      force: z.boolean().optional().describe('Required to delete in this non-interactive context — without it the delete is refused as a safety guard.'),
       account: accountParam,
     },
-  }, async ({ draftId, account }) => {
-    return runOrDiagnose(['gmail', 'drafts', 'delete', draftId], { account });
+  }, async ({ draftId, account, force }) => {
+    const args = ['gmail', 'drafts', 'delete', draftId];
+    if (force) args.push('--force');
+    return runOrDiagnose(args, { account });
   });
 
   server.registerTool('gog_gmail_drafts_send', {

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

@@ -223,6 +223,72 @@ describe('gog_gmail_thread_get', () => {
       { account: undefined },
     );
   });
+
+  const THREAD = JSON.stringify({
+    downloaded: false,
+    thread: {
+      id: 't1',
+      messages: [
+        { id: 'm1', threadId: 't1', internalDate: '1', labelIds: ['INBOX'], snippet: 'first', payload: { headers: [{ name: 'From', value: 'a@x.com' }, { name: 'Subject', value: 'Hi' }, { name: 'X-Spam', value: 'no' }, { value: 'orphan-no-name' }], body: { data: 'AAAA' } } },
+        { id: 'm2', threadId: 't1', internalDate: '2', labelIds: ['INBOX'], snippet: 'second', payload: { headers: [{ name: 'From', value: 'b@x.com' }] } },
+        { id: 'm3', threadId: 't1', internalDate: '3', labelIds: ['SENT'], snippet: 'third' },
+      ],
+    },
+  });
+
+  it('does not transform the output when no paging params are given', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValueOnce(toText(THREAD));
+    const result = await handlers.get('gog_gmail_thread_get')!({ threadId: 't1' });
+    expect(result.content[0].text).toBe(THREAD);
+  });
+
+  it('latestN returns only the last N messages', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValueOnce(toText(THREAD));
+    const result = await handlers.get('gog_gmail_thread_get')!({ threadId: 't1', latestN: 2 });
+    // latestN is wrapper-side; no CLI flag is added
+    expect(vi.mocked(lib.runOrDiagnose).mock.calls[0]![0]).toEqual(['gmail', 'thread', 'get', 't1']);
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.thread.messages.map((m: { id: string }) => m.id)).toEqual(['m2', 'm3']);
+  });
+
+  it('snippetsOnly returns per-message headers and snippet without bodies', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValueOnce(toText(THREAD));
+    const result = await handlers.get('gog_gmail_thread_get')!({ threadId: 't1', snippetsOnly: true });
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.thread.messages).toHaveLength(3);
+    const m1 = parsed.thread.messages[0];
+    expect(m1.snippet).toBe('first');
+    expect(m1.headers).toEqual({ From: 'a@x.com', Subject: 'Hi' }); // X-Spam dropped
+    expect(m1.payload).toBeUndefined();
+    // a message with no payload yields empty headers without throwing
+    expect(parsed.thread.messages[2].headers).toEqual({});
+  });
+
+  it('combines latestN and snippetsOnly', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValueOnce(toText(THREAD));
+    const result = await handlers.get('gog_gmail_thread_get')!({ threadId: 't1', latestN: 1, snippetsOnly: true });
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.thread.messages).toHaveLength(1);
+    expect(parsed.thread.messages[0].id).toBe('m3');
+  });
+
+  it('returns the raw result when the payload is not JSON', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValueOnce(toText('not json'));
+    const result = await handlers.get('gog_gmail_thread_get')!({ threadId: 't1', latestN: 2 });
+    expect(result.content[0].text).toBe('not json');
+  });
+
+  it('returns the raw result when there is no messages array', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValueOnce(toText('{"thread":{}}'));
+    const result = await handlers.get('gog_gmail_thread_get')!({ threadId: 't1', snippetsOnly: true });
+    expect(result.content[0].text).toBe('{"thread":{}}');
+  });
+
+  it('returns the raw result when there is no thread object', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValueOnce(toText('{}'));
+    const result = await handlers.get('gog_gmail_thread_get')!({ threadId: 't1', latestN: 1 });
+    expect(result.content[0].text).toBe('{}');
+  });
 });
 
 describe('gog_gmail_thread_modify', () => {
@@ -430,6 +496,53 @@ describe('gog_gmail_drafts_create', () => {
       { account: undefined },
     );
   });
+
+  it('skips recipient flags when omitRecipients is true, even if to/cc/bcc are supplied', async () => {
+    await handlers.get('gog_gmail_drafts_create')!({
+      to: 'a@b.com', cc: 'cc@x.com', bcc: 'bcc@x.com',
+      subject: 'Hi', body: 'Hello', omitRecipients: true,
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['gmail', 'drafts', 'create', '--subject=Hi', '--body=Hello'],
+      { account: undefined },
+    );
+  });
+
+  it('returnFull re-fetches and returns the full stored draft', async () => {
+    vi.mocked(lib.runOrDiagnose)
+      .mockResolvedValueOnce(toText('{"draftId":"d9","message":{"id":"m9"}}'))
+      .mockResolvedValueOnce(toText('{"id":"d9","message":{"subject":"Hi","body":"Hello"}}'));
+    const result = await handlers.get('gog_gmail_drafts_create')!({
+      subject: 'Hi', body: 'Hello', returnFull: true,
+    });
+    expect(lib.runOrDiagnose).toHaveBeenNthCalledWith(1,
+      ['gmail', 'drafts', 'create', '--subject=Hi', '--body=Hello'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenNthCalledWith(2,
+      ['gmail', 'drafts', 'get', 'd9'], { account: undefined });
+    expect(result.content[0].text).toContain('"subject":"Hi"');
+  });
+
+  it('returnFull does not push --return-full to the CLI', async () => {
+    vi.mocked(lib.runOrDiagnose)
+      .mockResolvedValueOnce(toText('{"draftId":"d9"}'))
+      .mockResolvedValueOnce(toText('{}'));
+    await handlers.get('gog_gmail_drafts_create')!({ subject: 'Hi', body: 'Hello', returnFull: true });
+    expect(vi.mocked(lib.runOrDiagnose).mock.calls[0]![0]).not.toContain('--return-full');
+  });
+
+  it('returnFull returns the write result when output is not parseable JSON', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValueOnce(toText('not json'));
+    const result = await handlers.get('gog_gmail_drafts_create')!({ subject: 'Hi', body: 'Hello', returnFull: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledTimes(1);
+    expect(result.content[0].text).toBe('not json');
+  });
+
+  it('returnFull returns the write result when no draftId is present', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValueOnce(toText('{"message":{"id":"m9"}}'));
+    const result = await handlers.get('gog_gmail_drafts_create')!({ subject: 'Hi', body: 'Hello', returnFull: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledTimes(1);
+    expect(result.content[0].text).toBe('{"message":{"id":"m9"}}');
+  });
 });
 
 describe('gog_gmail_drafts_update', () => {
@@ -457,6 +570,38 @@ describe('gog_gmail_drafts_update', () => {
       { account: undefined },
     );
   });
+
+  it('skips recipient flags when omitRecipients is true', async () => {
+    await handlers.get('gog_gmail_drafts_update')!({
+      draftId: 'd1', to: 'a@b.com', subject: 'S', body: 'B', omitRecipients: true,
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['gmail', 'drafts', 'update', 'd1', '--subject=S', '--body=B'],
+      { account: undefined },
+    );
+  });
+
+  it('returnFull re-fetches the draft by its known id', async () => {
+    vi.mocked(lib.runOrDiagnose)
+      .mockResolvedValueOnce(toText('{"draftId":"d1"}'))
+      .mockResolvedValueOnce(toText('{"id":"d1","message":{"subject":"S"}}'));
+    const result = await handlers.get('gog_gmail_drafts_update')!({
+      draftId: 'd1', subject: 'S', body: 'B', returnFull: true,
+    });
+    expect(lib.runOrDiagnose).toHaveBeenNthCalledWith(2,
+      ['gmail', 'drafts', 'get', 'd1'], { account: undefined });
+    expect(result.content[0].text).toContain('"subject":"S"');
+  });
+
+  it('returnFull surfaces a failed update instead of re-fetching a stale draft', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValueOnce(toText('Error: update failed'));
+    const result = await handlers.get('gog_gmail_drafts_update')!({
+      draftId: 'd1', subject: 'S', body: 'B', returnFull: true,
+    });
+    // write failed (non-JSON) → no re-fetch; the error is surfaced
+    expect(lib.runOrDiagnose).toHaveBeenCalledTimes(1);
+    expect(result.content[0].text).toBe('Error: update failed');
+  });
 });
 
 describe('gog_gmail_drafts_delete', () => {
@@ -467,6 +612,22 @@ describe('gog_gmail_drafts_delete', () => {
       { account: undefined },
     );
   });
+
+  it('appends --force when force is true', async () => {
+    await handlers.get('gog_gmail_drafts_delete')!({ draftId: 'd1', force: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['gmail', 'drafts', 'delete', 'd1', '--force'],
+      { account: undefined },
+    );
+  });
+
+  it('omits --force when force is false', async () => {
+    await handlers.get('gog_gmail_drafts_delete')!({ draftId: 'd1', force: false });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['gmail', 'drafts', 'delete', 'd1'],
+      { account: undefined },
+    );
+  });
 });
 
 describe('gog_gmail_drafts_send', () => {