gogcli-mcp-gmail 2.23.1 → 2.24.0

package/README.md

@@ -3,7 +3,7 @@
 > [!WARNING]
 > **AI-developed project.** This codebase was built and is actively maintained by [Claude Code](https://www.anthropic.com/claude). Review all code and tool permissions before use.
 
-Extended Gmail [MCP](https://modelcontextprotocol.io) server via [gogcli](https://github.com/openclaw/gogcli). Includes auth tools plus 46 additional dedicated Gmail tools for threads, labels, drafts, attachments, forwarding, autoreply, and bulk operations.
+Extended Gmail [MCP](https://modelcontextprotocol.io) server via [gogcli](https://github.com/openclaw/gogcli). Includes auth tools plus 49 additional dedicated Gmail tools for threads, labels, drafts, attachments, forwarding, autoreply, and bulk operations.
 
 ## Requirements
 
@@ -44,9 +44,9 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 claude mcp add gogcli-gmail -- gogcli-mcp-gmail
 ```
 
-## Extra Gmail Tools (46)
+## Extra Gmail Tools (49)
 
-Plus 8 auth tools and 4 base Gmail tools (search, get, send, run) — 58 in all.
+Plus 8 auth tools and 4 base Gmail tools (search, get, send, run) — 61 in all.
 
 ### Read
 
@@ -101,6 +101,9 @@ Plus 8 auth tools and 4 base Gmail tools (search, get, send, run) — 58 in all.
 | `gog_gmail_drafts_delete` | Delete a draft |
 | `gog_gmail_drafts_send` | Send an existing draft (a 404 comes back diagnosed — `DRAFT_FORKED`, or `GOOGLE_404_NOT_THE_DRAFT` when the draft is still listed) |
 | `gog_gmail_drafts_diff` | Diff two named drafts — divergent body lines (with untruncated `onlyInACount`/`onlyInBCount`), threading loss, and a conservative fork verdict (2 gog calls) |
+| `gog_gmail_drafts_reply` | Save a reply as a draft — inherited recipients, subject and quote; never sends |
+| `gog_gmail_drafts_reply_all` | Save a reply-all as a draft; never sends |
+| `gog_gmail_drafts_forward` | Save a forward as a draft; recipients optional, so it can be staged without any |
 
 #### When a draft you created stops resolving
 

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) — 58 tools: 8 auth + 4 base Gmail + 46 extra dedicated Gmail tools.
+Extended Gmail MCP server via [gogcli](https://github.com/openclaw/gogcli) — 61 tools: 8 auth + 4 base Gmail + 49 extra dedicated Gmail tools.
 
 - **Source:** [github.com/chrischall/gogcli-mcp](https://github.com/chrischall/gogcli-mcp)
 
@@ -80,6 +80,9 @@ Extended Gmail MCP server via [gogcli](https://github.com/openclaw/gogcli) — 5
 | `gog_gmail_drafts_delete` | Delete a draft |
 | `gog_gmail_drafts_send` | Send a draft (404 → `DRAFT_FORKED`, or `GOOGLE_404_NOT_THE_DRAFT` if the draft is still listed) |
 | `gog_gmail_drafts_diff` | Diff two drafts (body divergence, threading loss, fork verdict) |
+| `gog_gmail_drafts_reply` | Save a reply as a draft — inherited recipients, subject and quote; never sends |
+| `gog_gmail_drafts_reply_all` | Save a reply-all as a draft; never sends |
+| `gog_gmail_drafts_forward` | Save a forward as a draft; recipients optional, so it can be staged without any |
 
 A draft edited in a mail client is replaced, not updated: the old id 404s. `drafts_update` / `drafts_send` answer that
 404 with a `DRAFT_FORKED` report (what happened, the drafts that exist, what to do) instead of a bare `notFound`, at a

package/dist/index.js

@@ -31547,6 +31547,40 @@ function normalizeTimestamps(text, tz = displayTimeZone(), naiveTz = naiveSource
   return JSON.stringify(parsed, null, detectIndent(text));
 }
 
+// ../gogcli-mcp/src/pagination.ts
+function detectIndent2(text) {
+  const match = /\n(\s+)\S/.exec(text);
+  return match ? match[1].replace(/\t/g, "  ").length : 0;
+}
+function stripConsumedPageToken(text) {
+  const trimmed = text.trim();
+  if (trimmed === "" || !trimmed.startsWith("{")) return text;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return text;
+  }
+  const obj = parsed;
+  if (obj.nextPageToken !== "") return text;
+  delete obj.nextPageToken;
+  return JSON.stringify(obj, null, detectIndent2(text));
+}
+function truncationWarning(returned, count) {
+  const scope = count.total !== void 0 ? `returned ${returned} of ${count.total} matches` : count.atLeast !== void 0 ? `returned ${returned} of at least ${count.atLeast} matches` : `returned ${returned} matches and MORE EXIST beyond this page`;
+  return `INCOMPLETE RESULT SET: ${scope}. Do not report an absence of results based on this response. Page with nextPageToken or narrow the query.`;
+}
+function annotateTruncation(out, returned, count) {
+  out.truncated = true;
+  out.returned = returned;
+  if (count.total !== void 0) out.totalMatches = count.total;
+  if (count.atLeast !== void 0) out.totalMatchesAtLeast = count.atLeast;
+  out.warning = truncationWarning(returned, count);
+}
+function hasMorePages(parsed) {
+  return typeof parsed.nextPageToken === "string" && parsed.nextPageToken !== "";
+}
+
 // ../gogcli-mcp/src/tools/utils.ts
 var PAYLOAD_INLINE_MAX = 4096;
 function payloadArg(inlineFlag, fileFlag, value, ext) {
@@ -31582,9 +31616,19 @@ var ids = {
   // People API uses fully-qualified resource names ("people/c123") not bare IDs.
   person: external_exports.string().describe("Person resource name (people/...) or email")
 };
+var pageTokenParam = external_exports.string().optional().describe(
+  "Cursor for the NEXT page. Pass back the nextPageToken from a previous response verbatim, keeping the query and max identical: call once, then call again with pageToken=<that value>. A response with NO nextPageToken is the last page."
+);
+var pageAliasParam = external_exports.string().optional().describe(
+  "Deprecated alias for pageToken, accepted so existing callers keep working. Use pageToken \u2014 it matches the nextPageToken field in the response."
+);
+function resolvePageToken(p) {
+  return p.pageToken ?? p.page;
+}
 var paginationParams = {
   max: external_exports.number().int().optional().describe("Max results"),
-  page: external_exports.string().optional().describe("Page token"),
+  pageToken: pageTokenParam,
+  page: pageAliasParam,
   all: external_exports.boolean().optional().describe("Fetch all pages")
 };
 function registerRunTool(server, options) {
@@ -31659,7 +31703,7 @@ ${accounts || "(none)"}${hint}`);
 async function runOrDiagnose(args, options) {
   try {
     const raw = await run(args, options);
-    return rawTextResult(options.lossless ? raw : normalizeTimestamps(raw));
+    return rawTextResult(options.lossless ? raw : stripConsumedPageToken(normalizeTimestamps(raw)));
   } catch (err) {
     return diagnose(err);
   }
@@ -31709,6 +31753,7 @@ function formatAuthHealth(raw, now) {
 // ../gogcli-mcp/src/tools/auth.ts
 function registerAuthToolsWith(server, defaultServices) {
   const servicesDescribe = `Services to authorize: "all" or comma-separated list (e.g. "sheets,gmail,calendar"). Default: "${defaultServices}". Prefer the narrowest set you need \u2014 requesting a service whose Google API is not enabled on the OAuth client's project makes Google reject the WHOLE request with invalid_scope.`;
+  const extraScopesDescribe = "Additional raw OAuth scope URIs to request, comma-separated, on top of the ones `services` implies. Use for scopes no service covers \u2014 e.g. https://www.googleapis.com/auth/bigquery.readonly, required before gog_sheets_datasource_* can read BigQuery-backed Connected Sheets. Leave unset otherwise: an extra scope whose API is not enabled on the OAuth client project makes Google reject the WHOLE authorization with invalid_scope.";
   server.registerTool("gog_auth_list", {
     description: "List the Google accounts stored in gogcli, with their scopes. This reads local configuration only \u2014 it does not contact Google and does NOT tell you whether an account still works: a signed-out account whose refresh token expired or was revoked is listed here exactly like a healthy one, scopes and all. Use gog_auth_health to check whether an account can actually authenticate.",
     annotations: { readOnlyHint: true },
@@ -31758,11 +31803,14 @@ function registerAuthToolsWith(server, defaultServices) {
     annotations: { destructiveHint: true },
     inputSchema: {
       email: external_exports.string().describe("Google account email to authorize"),
-      services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe)
+      services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe),
+      extraScopes: external_exports.string().optional().describe(extraScopesDescribe)
     }
-  }, async ({ email: email3, services = defaultServices }) => {
+  }, async ({ email: email3, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(["auth", "add", email3, "--services", services], {
+      const args = ["auth", "add", email3, "--services", services];
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`, "--force-consent");
+      return rawTextResult(await run(args, {
         interactive: true,
         timeout: 3e5
       }));
@@ -31774,14 +31822,14 @@ function registerAuthToolsWith(server, defaultServices) {
     description: "Begin REMOTE/headless Google authorization (step 1 of 2). Returns a sign-in URL to open in any browser \u2014 no local server or terminal on the gogcli host is needed, so this works over the hosted connector where the interactive gog_auth_add cannot. Hand the URL to the user; after they sign in, the browser is redirected to a localhost URL that fails to load \u2014 that is expected. They copy that full redirected URL (from the address bar) and you pass it to gog_auth_add_complete. The link is valid for 10 minutes. If you pass a custom `services` here, pass the SAME value to gog_auth_add_complete or the second step will not match this one.",
     inputSchema: {
       email: external_exports.string().describe("Google account email to authorize"),
-      services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe)
+      services: external_exports.string().optional().default(defaultServices).describe(servicesDescribe),
+      extraScopes: external_exports.string().optional().describe(`${extraScopesDescribe} Pass the SAME value to gog_auth_add_complete.`)
     }
-  }, async ({ email: email3, services = defaultServices }) => {
+  }, async ({ email: email3, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(
-        ["auth", "add", email3, "--remote", "--step", "1", "--services", services, "--force-consent"],
-        { redactMode: "tokens" }
-      ));
+      const args = ["auth", "add", email3, "--remote", "--step", "1", "--services", services, "--force-consent"];
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`);
+      return rawTextResult(await run(args, { redactMode: "tokens" }));
     } catch (err) {
       return errorResult(errorText(err));
     }
@@ -31796,25 +31844,28 @@ function registerAuthToolsWith(server, defaultServices) {
       ),
       services: external_exports.string().optional().default(defaultServices).describe(
         `Services authorized \u2014 MUST match the value passed to gog_auth_add_url. Default: "${defaultServices}".`
+      ),
+      extraScopes: external_exports.string().optional().describe(
+        "Extra OAuth scope URIs \u2014 MUST match the value passed to gog_auth_add_url, for the same reason `services` must: the two steps have to describe the same grant."
       )
     }
-  }, async ({ email: email3, redirectUrl, services = defaultServices }) => {
+  }, async ({ email: email3, redirectUrl, services = defaultServices, extraScopes }) => {
     try {
-      return rawTextResult(await run(
-        [
-          "auth",
-          "add",
-          email3,
-          "--remote",
-          "--step",
-          "2",
-          "--auth-url",
-          redirectUrl,
-          "--services",
-          services,
-          "--force-consent"
-        ]
-      ));
+      const args = [
+        "auth",
+        "add",
+        email3,
+        "--remote",
+        "--step",
+        "2",
+        "--auth-url",
+        redirectUrl,
+        "--services",
+        services,
+        "--force-consent"
+      ];
+      if (extraScopes) args.push(`--extra-scopes=${extraScopes}`);
+      return rawTextResult(await run(args));
     } catch (err) {
       return errorResult(errorText(err));
     }
@@ -31830,34 +31881,148 @@ function authToolsFor(defaultServices) {
   return (server) => registerAuthToolsWith(server, defaultServices);
 }
 
+// ../gogcli-mcp/src/gmail-results.ts
+function sortKey(item) {
+  for (const raw of [item.internalDateIso, item.date]) {
+    if (typeof raw !== "string" || !raw) continue;
+    const t = Date.parse(raw);
+    if (!Number.isNaN(t)) return t;
+  }
+  return Number.NEGATIVE_INFINITY;
+}
+function sortNewestFirst(items) {
+  return [...items].sort((a, b) => {
+    const ka = sortKey(a);
+    const kb = sortKey(b);
+    return ka === kb ? 0 : kb - ka;
+  });
+}
+var COUNT_PROBE_PAGE_SIZE = 500;
+async function countMatches(method, itemsKey, query, account) {
+  try {
+    const params = JSON.stringify({
+      userId: "me",
+      q: query,
+      maxResults: COUNT_PROBE_PAGE_SIZE,
+      fields: `${itemsKey}/id,nextPageToken`
+    });
+    const raw = await run(["api", "call", "gmail", "v1", method, `--params=${params}`], { account });
+    const parsed = JSON.parse(raw);
+    const items = parsed[itemsKey];
+    if (!Array.isArray(items)) return {};
+    const more = typeof parsed.nextPageToken === "string" && parsed.nextPageToken !== "";
+    return more ? { atLeast: items.length } : { total: items.length };
+  } catch {
+    return {};
+  }
+}
+async function finalizeGmailSearch(result, options) {
+  const { itemsKey, method, query, account, queryIsExact = true } = options;
+  const first = result.content[0];
+  if (result.isError || first?.type !== "text") return result;
+  let parsed;
+  try {
+    parsed = JSON.parse(first.text);
+  } catch {
+    return result;
+  }
+  const items = parsed[itemsKey];
+  if (!Array.isArray(items)) return result;
+  const sorted = sortNewestFirst(items);
+  const out = { ...parsed, [itemsKey]: sorted };
+  if (hasMorePages(parsed)) {
+    const count = queryIsExact ? await countMatches(method, itemsKey, query, account) : {};
+    annotateTruncation(out, sorted.length, count);
+  }
+  return rawTextResult(JSON.stringify(out));
+}
+async function fetchGmailPages(runPage, itemsKey, maxPages, startToken) {
+  const merged = [];
+  let base;
+  let token = startToken;
+  for (let pages = 0; pages < maxPages; pages++) {
+    const result = await runPage(token);
+    const parsed = parsePage(result, itemsKey);
+    if (parsed === void 0) {
+      return base === void 0 ? result : finish(base, itemsKey, merged, token);
+    }
+    base = parsed;
+    merged.push(...parsed[itemsKey]);
+    token = typeof parsed.nextPageToken === "string" && parsed.nextPageToken !== "" ? parsed.nextPageToken : void 0;
+    if (token === void 0) break;
+  }
+  return finish(base, itemsKey, merged, token);
+}
+function parsePage(result, itemsKey) {
+  const first = result.content[0];
+  if (result.isError || first?.type !== "text") return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(first.text);
+  } catch {
+    return void 0;
+  }
+  if (parsed === null || typeof parsed !== "object") return void 0;
+  const obj = parsed;
+  return Array.isArray(obj[itemsKey]) ? obj : void 0;
+}
+function finish(base, itemsKey, merged, token) {
+  const out = { ...base, [itemsKey]: merged };
+  if (token === void 0) delete out.nextPageToken;
+  else out.nextPageToken = token;
+  return rawTextResult(JSON.stringify(out));
+}
+
 // ../gogcli-mcp/src/tools/gmail.ts
 function registerGmailTools(server) {
   server.registerTool("gog_gmail_search", {
-    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).`,
+    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). Results are ALWAYS newest-first by Gmail\'s internalDate \u2014 the wrapper sorts them, so the first result is the most recent match and a recent message can never be buried below older ones. IMPORTANT \u2014 a response carrying "truncated": true is an INCOMPLETE view of the matches: NEVER report that a message does not exist, or that there is no such mail, on the strength of one. Page through it (pass nextPageToken back as `pageToken`), set maxPages to walk several pages in one call, or narrow the query, and only then draw a conclusion. If you already know the thread, do not search for it at all \u2014 read it directly with gog_gmail_thread_get, which returns the whole thread and cannot be truncated or mis-ranked.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       query: external_exports.string().describe("Gmail search query"),
       max: external_exports.number().int().optional().describe("Max results to return (default: 10)"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
+      maxPages: external_exports.number().int().positive().max(20).optional().describe('Walk up to this many pages in ONE call and merge the results, instead of returning a single page. Use it for existence questions ("is there any mail matching X?"), which a single page cannot answer. Stops early at the last page; if pages remain when the cap is hit the response is still marked truncated. Prefer this over all=true, which is unbounded.'),
+      all: external_exports.boolean().optional().describe('Fetch every page instead of one. Removes truncation entirely, at the cost of one API round-trip per page \u2014 the reliable way to answer "does any message match?" for a query with few expected hits.'),
       fromContact: external_exports.string().optional().describe("Resolve a Google Contact (name or email) to its addresses and AND a from:(addr OR addr) clause onto the query \u2014 saves looking the contact up first when you only know who, not which address."),
       account: accountParam
     }
-  }, async ({ query, max, fromContact, account }) => {
+  }, async ({ query, max, pageToken, page, maxPages, all, fromContact, account }) => {
     const args = ["gmail", "search", query];
     if (max !== void 0) args.push(`--max=${max}`);
+    if (all) args.push("--all");
     if (fromContact) args.push(`--from-contact=${fromContact}`);
-    return runOrDiagnose(args, { account });
+    const runPage = (tok) => runOrDiagnose(tok ? [...args, `--page=${tok}`] : args, { account });
+    const token = resolvePageToken({ pageToken, page });
+    const result = maxPages !== void 0 ? await fetchGmailPages(runPage, "threads", maxPages, token) : await runPage(token);
+    return finalizeGmailSearch(result, {
+      itemsKey: "threads",
+      method: "users.threads.list",
+      query,
+      account,
+      // --from-contact is expanded INSIDE gog, against the People API, so the
+      // query Gmail actually saw is not the one we hold here.
+      queryIsExact: !fromContact
+    });
   });
   server.registerTool("gog_gmail_get", {
-    description: "Get a Gmail message by ID.",
+    description: "Get a Gmail message by ID. For a long message, sanitizeContent is the cheapest way to keep it in context: it drops the raw MIME payload and the HTML part, which are usually the bulk of the response.",
     annotations: { readOnlyHint: true },
     inputSchema: {
       messageId: external_exports.string().describe("Message ID"),
       format: external_exports.enum(["full", "metadata", "raw"]).optional().describe("Message format (default: full)"),
+      // Requires gog >= 0.37.0. Before that (openclaw/gogcli#992) the JSON
+      // carried the headers and body TWICE — once inside `message`, once
+      // copied to the top level — so the flag meant to shrink the payload
+      // enlarged it. MIN_GOG_VERSION is the guard; there is no runtime check.
+      sanitizeContent: external_exports.boolean().optional().describe("Return agent-oriented sanitized content: HTML stripped, HTTP(S) URLs removed, raw Gmail payloads omitted from the JSON. The largest payload-size reduction available here. Note the URL removal is lossy \u2014 omit this when you need to follow a link out of the message."),
       account: accountParam
     }
-  }, async ({ messageId, format, account }) => {
+  }, async ({ messageId, format, sanitizeContent, account }) => {
     const args = ["gmail", "get", messageId];
     if (format) args.push(`--format=${format}`);
+    if (sanitizeContent) args.push("--sanitize-content");
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_gmail_send", {
@@ -31896,7 +32061,7 @@ var failIfNotEmptyParam = external_exports.boolean().optional().describe(
 );
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.23.1" : "0.0.0";
+var VERSION = true ? "2.24.0" : "0.0.0";
 
 // ../gogcli-mcp/src/auth-log.ts
 var FAILURES = /* @__PURE__ */ new Set([
@@ -33464,15 +33629,17 @@ function registerExtraGmailTools(server) {
     inputSchema: {
       since: external_exports.string().optional().describe("Start history ID"),
       max: external_exports.number().optional().describe("Max results (default: 100)"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       account: accountParam
     }
-  }, async ({ since, max, page, all, account }) => {
+  }, async ({ since, max, pageToken, page, all, account }) => {
     const args = ["gmail", "history"];
     if (since) args.push(`--since=${since}`);
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     return runOrDiagnose(args, { account });
   });
@@ -33567,7 +33734,7 @@ function registerExtraGmailTools(server) {
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_gmail_thread_get", {
-    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. Note each message carries two distinct id concepts: the top-level `id` (the Gmail short hex message id \u2014 pass THIS as replyToMessageId to reply) and the `Message-Id` header (the RFC822 `<\u2026@host>` value used in In-Reply-To/References) \u2014 don't confuse either with the `threadId`. To reply to the thread itself, pass the thread's id as replyToThreadId on gog_gmail_drafts_create.",
+    description: "Get a Gmail thread with all messages. THIS IS THE CORRECT TOOL WHEN YOU ALREADY KNOW THE threadId \u2014 it returns the thread in full, so unlike a search it can never be truncated, mis-ranked, or come back empty because the query missed. Never re-discover a known thread with gog_gmail_search; read it here. 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. Note each message carries two distinct id concepts: the top-level `id` (the Gmail short hex message id \u2014 pass THIS as replyToMessageId to reply) and the `Message-Id` header (the RFC822 `<\u2026@host>` value used in In-Reply-To/References) \u2014 don't confuse either with the `threadId`. To reply to the thread itself, pass the thread's id as replyToThreadId on gog_gmail_drafts_create.",
     annotations: { readOnlyHint: true },
     inputSchema: {
       threadId: external_exports.string().describe("Gmail thread ID"),
@@ -33692,17 +33859,19 @@ function registerExtraGmailTools(server) {
     annotations: { readOnlyHint: true },
     inputSchema: {
       max: external_exports.number().optional().describe("Max results (default: 20)"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       enrich: external_exports.boolean().optional().describe(
         "Add subject, from and internalDateIso to each draft. Costs ONE extra gog invocation (`gmail messages search in:drafts`) regardless of how many drafts there are \u2014 but that single command makes gog fetch every matching draft server-side at concurrency 10, so Google reads and wall-clock are linear in the result count even though gog spawns are not. Narrow `max` before enabling it. If the search fails the listing silently degrades to the free fields rather than erroring."
       ),
       account: accountParam
     }
-  }, async ({ max, page, all, enrich, account }) => {
+  }, async ({ max, pageToken, page, all, enrich, account }) => {
     const args = ["gmail", "drafts", "list"];
     if (max !== void 0) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push("--all");
     const result = await runOrDiagnose(args, { account });
     let parsed;
@@ -33720,7 +33889,7 @@ function registerExtraGmailTools(server) {
     if (enrich) {
       const searchArgs = ["gmail", "messages", "search", "in:drafts", `--max=${max ?? GOG_DRAFTS_LIST_DEFAULT_MAX}`];
       if (all) searchArgs.push("--all");
-      if (page) searchArgs.push(`--page=${page}`);
+      if (token) searchArgs.push(`--page=${token}`);
       searchArgs.push("--include-attachments=false", "--use-indexed-attachment-ids=false");
       try {
         const messages = JSON.parse(await runNormalized(searchArgs, { account })).messages;
@@ -34070,7 +34239,7 @@ function registerExtraGmailTools(server) {
     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.',
+    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 this same reply without sending it use gog_gmail_drafts_reply, which composes exactly what this tool would send.',
     annotations: { destructiveHint: true },
     inputSchema: replySchema
   }, async ({ messageId, account, ...flags }) => {
@@ -34079,7 +34248,7 @@ function registerExtraGmailTools(server) {
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_gmail_reply_all", {
-    description: 'Reply to all participants of a Gmail message (sender plus every To/Cc recipient). Same inherited "Re:" subject and quoting as gog_gmail_reply. Use the remove flag to drop specific recipients from the reply-all.',
+    description: 'Reply to all participants of a Gmail message (sender plus every To/Cc recipient). Same inherited "Re:" subject and quoting as gog_gmail_reply. Use the remove flag to drop specific recipients from the reply-all. To stage it without sending use gog_gmail_drafts_reply_all.',
     annotations: { destructiveHint: true },
     inputSchema: replySchema
   }, async ({ messageId, account, ...flags }) => {
@@ -34087,6 +34256,46 @@ function registerExtraGmailTools(server) {
     appendReplyFlags(args, flags);
     return runOrDiagnose(args, { account });
   });
+  const draftReplyNote = ' Composes exactly what gog_gmail_reply%s would send \u2014 inherited recipients, "Re:" subject and quoted original \u2014 but SAVES IT AS A DRAFT instead of sending. Nothing leaves the mailbox; send it later with gog_gmail_drafts_send, or edit it first with gog_gmail_drafts_update (which overwrites the whole body, quote included \u2014 read the draft back before editing).';
+  server.registerTool("gog_gmail_drafts_reply", {
+    description: "Save a reply to a Gmail message as a draft (to the original sender only)." + draftReplyNote.replace("%s", "") + " Prefer this over gog_gmail_drafts_create + replyToMessageId when the draft is a real reply: that route threads the draft but leaves recipients and quoting for you to reconstruct.",
+    inputSchema: { ...replySchema, returnFull: draftWriteSchema.returnFull }
+  }, async ({ messageId, account, returnFull, ...flags }) => {
+    const args = ["gmail", "drafts", "reply", messageId];
+    appendReplyFlags(args, flags);
+    return writeDraft(args, account, returnFull);
+  });
+  server.registerTool("gog_gmail_drafts_reply_all", {
+    description: "Save a reply-all to a Gmail message as a draft (sender plus every To/Cc recipient)." + draftReplyNote.replace("%s", "_all") + " Use the remove flag to drop recipients BEFORE the draft exists, rather than editing them out afterwards.",
+    inputSchema: { ...replySchema, returnFull: draftWriteSchema.returnFull }
+  }, async ({ messageId, account, returnFull, ...flags }) => {
+    const args = ["gmail", "drafts", "reply-all", messageId];
+    appendReplyFlags(args, flags);
+    return writeDraft(args, account, returnFull);
+  });
+  server.registerTool("gog_gmail_drafts_forward", {
+    description: "Save a forward of a Gmail message as a draft. Same composition as gog_gmail_forward \u2014 the original message quoted below an optional note, with its attachments carried over \u2014 but nothing is sent. Unlike gog_gmail_forward, `to` is OPTIONAL here: omit it to stage a recipient-less forward as an accidental-send guard, then add recipients with gog_gmail_drafts_update before gog_gmail_drafts_send.",
+    inputSchema: {
+      messageId: external_exports.string().describe("Gmail message ID to forward"),
+      to: external_exports.string().optional().describe("Recipients (comma-separated). Optional for a draft \u2014 omit to stage the forward without recipients."),
+      cc: external_exports.string().optional().describe("CC recipients (comma-separated)"),
+      bcc: external_exports.string().optional().describe("BCC recipients (comma-separated)"),
+      note: external_exports.string().optional().describe("Introductory text above the forwarded message"),
+      from: external_exports.string().optional().describe("Send from this email address (must be a verified send-as alias)"),
+      skipAttachments: external_exports.boolean().optional().describe("Do not include original attachments"),
+      returnFull: draftWriteSchema.returnFull,
+      account: accountParam
+    }
+  }, async ({ messageId, to, cc, bcc, note, from, skipAttachments, returnFull, account }) => {
+    const args = ["gmail", "drafts", "forward", messageId];
+    if (to) args.push(`--to=${to}`);
+    if (cc) args.push(`--cc=${cc}`);
+    if (bcc) args.push(`--bcc=${bcc}`);
+    if (note) args.push(payloadArg("note", "note-file", note));
+    if (from) args.push(`--from=${from}`);
+    if (skipAttachments) args.push("--skip-attachments");
+    return writeDraft(args, account, returnFull);
+  });
   server.registerTool("gog_gmail_autoreply", {
     description: "Reply once to all messages matching a Gmail search query. Use the label flag to dedupe across runs.",
     annotations: { destructiveHint: true },
@@ -34121,12 +34330,14 @@ function registerExtraGmailTools(server) {
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_gmail_messages_search", {
-    description: "Search individual messages (not threads) using Gmail query syntax. Returns one result per matching message.",
+    description: 'Search individual messages (not threads) using Gmail query syntax. Returns one result per matching message. Results are ALWAYS newest-first by Gmail\'s internalDate \u2014 the wrapper sorts them, so the first result is the most recent match. IMPORTANT \u2014 a response carrying "truncated": true is an INCOMPLETE view of the matches: NEVER report that a message does not exist on the strength of one. Page through it (pass nextPageToken back as `pageToken`), set maxPages to walk several pages in one call, or narrow the query first. If you already know the thread, read it with gog_gmail_thread_get instead of searching for it.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       query: external_exports.string().describe('Gmail search query (e.g. "from:alice is:unread has:attachment")'),
       max: external_exports.number().optional().describe("Max results"),
-      page: external_exports.string().optional().describe("Page token"),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
+      maxPages: external_exports.number().int().positive().max(20).optional().describe('Walk up to this many pages in ONE call and merge the results, instead of returning a single page. Use it for existence questions ("is there any mail matching X?"), which a single page cannot answer. Stops early at the last page; if pages remain when the cap is hit the response is still marked truncated. Prefer this over all=true, which is unbounded.'),
       all: external_exports.boolean().optional().describe("Fetch all pages"),
       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)"),
@@ -34135,17 +34346,24 @@ function registerExtraGmailTools(server) {
       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, includeAttachments, useIndexedAttachmentIds, account }) => {
+  }, async ({ query, max, pageToken, page, maxPages, 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}`);
     if (all) args.push("--all");
     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 });
+    const runPage = (tok) => runOrDiagnose(tok ? [...args, `--page=${tok}`] : args, { account });
+    const token = resolvePageToken({ pageToken, page });
+    const result = maxPages !== void 0 ? await fetchGmailPages(runPage, "messages", maxPages, token) : await runPage(token);
+    return finalizeGmailSearch(result, {
+      itemsKey: "messages",
+      method: "users.messages.list",
+      query,
+      account
+    });
   });
   server.registerTool("gog_gmail_labels_style", {
     description: "Change a user label's color or visibility (background/text color from Gmail's palette, label-list and message-list visibility).",

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-gmail",
   "display_name": "gogcli (Gmail)",
-  "version": "2.23.1",
+  "version": "2.24.0",
   "description": "Extended Gmail for Claude via gogcli — auth + full Gmail support (threads, labels, drafts, attachments, forward, autoreply, bulk operations)",
   "author": {
     "name": "Chris Hall",
@@ -91,7 +91,7 @@
     },
     {
       "name": "gog_gmail_search",
-      "description": "Search Gmail threads using Gmail query syntax"
+      "description": "Search Gmail threads using Gmail query syntax; newest-first, and flags a truncated result set"
     },
     {
       "name": "gog_gmail_get",
@@ -151,7 +151,7 @@
     },
     {
       "name": "gog_gmail_thread_get",
-      "description": "Get a thread with all messages"
+      "description": "Get a Gmail thread with all messages — the right tool when the threadId is already known"
     },
     {
       "name": "gog_gmail_thread_modify",
@@ -213,6 +213,18 @@
       "name": "gog_gmail_drafts_diff",
       "description": "Diff two named drafts: what each body has that the other lost, how their threading differs, and (only on a link back to the original or on agreement over unquoted text, with evidence) whether one replaced the other"
     },
+    {
+      "name": "gog_gmail_drafts_reply",
+      "description": "Save a reply to a Gmail message as a draft (inherited recipients, subject and quote; never sends)"
+    },
+    {
+      "name": "gog_gmail_drafts_reply_all",
+      "description": "Save a reply-all to a Gmail message as a draft (never sends)"
+    },
+    {
+      "name": "gog_gmail_drafts_forward",
+      "description": "Save a forward of a Gmail message as a draft; recipients are optional (never sends)"
+    },
     {
       "name": "gog_gmail_import",
       "description": "Import an RFC822/EML message into the mailbox (keeps its original headers and date; does not send)"
@@ -235,7 +247,7 @@
     },
     {
       "name": "gog_gmail_messages_search",
-      "description": "Search individual messages (not threads) using Gmail query syntax"
+      "description": "Search individual messages; newest-first, and flags a truncated result set"
     },
     {
       "name": "gog_gmail_labels_style",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-gmail",
-  "version": "2.23.1",
+  "version": "2.24.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,7 +2,7 @@ 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 } from '../../../gogcli-mcp/src/lib.js';
+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';
 
 // gog rejects an inline flag together with its --*-file twin — `gmail drafts
@@ -2365,15 +2365,17 @@ export function registerExtraGmailTools(server: McpServer): void {
     inputSchema: {
       since: z.string().optional().describe('Start history ID'),
       max: z.number().optional().describe('Max results (default: 100)'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: z.boolean().optional().describe('Fetch all pages'),
       account: accountParam,
     },
-  }, async ({ since, max, page, all, account }) => {
+  }, async ({ since, max, pageToken, page, all, account }) => {
     const args = ['gmail', 'history'];
     if (since) args.push(`--since=${since}`);
     if (max !== undefined) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push('--all');
     return runOrDiagnose(args, { account });
   });
@@ -2476,7 +2478,7 @@ export function registerExtraGmailTools(server: McpServer): void {
   });
 
   server.registerTool('gog_gmail_thread_get', {
-    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. Note each message carries two distinct id concepts: the top-level `id` (the Gmail short hex message id — pass THIS as replyToMessageId to reply) and the `Message-Id` header (the RFC822 `<…@host>` value used in In-Reply-To/References) — don\'t confuse either with the `threadId`. To reply to the thread itself, pass the thread\'s id as replyToThreadId on gog_gmail_drafts_create.',
+    description: 'Get a Gmail thread with all messages. THIS IS THE CORRECT TOOL WHEN YOU ALREADY KNOW THE threadId — it returns the thread in full, so unlike a search it can never be truncated, mis-ranked, or come back empty because the query missed. Never re-discover a known thread with gog_gmail_search; read it here. 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. Note each message carries two distinct id concepts: the top-level `id` (the Gmail short hex message id — pass THIS as replyToMessageId to reply) and the `Message-Id` header (the RFC822 `<…@host>` value used in In-Reply-To/References) — don\'t confuse either with the `threadId`. To reply to the thread itself, pass the thread\'s id as replyToThreadId on gog_gmail_drafts_create.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       threadId: z.string().describe('Gmail thread ID'),
@@ -2624,7 +2626,8 @@ export function registerExtraGmailTools(server: McpServer): void {
     annotations: { readOnlyHint: true },
     inputSchema: {
       max: z.number().optional().describe('Max results (default: 20)'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: z.boolean().optional().describe('Fetch all pages'),
       enrich: z.boolean().optional().describe(
         'Add subject, from and internalDateIso to each draft. Costs ONE extra gog invocation (`gmail messages search in:drafts`) ' +
@@ -2634,10 +2637,11 @@ export function registerExtraGmailTools(server: McpServer): void {
       ),
       account: accountParam,
     },
-  }, async ({ max, page, all, enrich, account }) => {
+  }, async ({ max, pageToken, page, all, enrich, account }) => {
     const args = ['gmail', 'drafts', 'list'];
     if (max !== undefined) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push('--all');
     const result = await runOrDiagnose(args, { account });
 
@@ -2668,7 +2672,7 @@ export function registerExtraGmailTools(server: McpServer): void {
       // list is on page N: an extra gog spawn that joins ZERO rows and still
       // reported applied:true. The token is a drafts-list cursor, so it is only
       // meaningful to the paged search.
-      if (page) searchArgs.push(`--page=${page}`);
+      if (token) searchArgs.push(`--page=${token}`);
       // Both PINNED for the same reason as gog_gmail_messages_search: the env
       // vars behind them change the result shape (and the per-message cost).
       searchArgs.push('--include-attachments=false', '--use-indexed-attachment-ids=false');
@@ -3221,7 +3225,7 @@ export function registerExtraGmailTools(server: McpServer): void {
   }
 
   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.',
+    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 this same reply without sending it use gog_gmail_drafts_reply, which composes exactly what this tool would send.',
     annotations: { destructiveHint: true },
     inputSchema: replySchema,
   }, async ({ messageId, account, ...flags }) => {
@@ -3231,7 +3235,7 @@ export function registerExtraGmailTools(server: McpServer): void {
   });
 
   server.registerTool('gog_gmail_reply_all', {
-    description: 'Reply to all participants of a Gmail message (sender plus every To/Cc recipient). Same inherited "Re:" subject and quoting as gog_gmail_reply. Use the remove flag to drop specific recipients from the reply-all.',
+    description: 'Reply to all participants of a Gmail message (sender plus every To/Cc recipient). Same inherited "Re:" subject and quoting as gog_gmail_reply. Use the remove flag to drop specific recipients from the reply-all. To stage it without sending use gog_gmail_drafts_reply_all.',
     annotations: { destructiveHint: true },
     inputSchema: replySchema,
   }, async ({ messageId, account, ...flags }) => {
@@ -3240,6 +3244,76 @@ export function registerExtraGmailTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
+  // gog >= 0.36.0: the draft-side twins of reply / reply-all / forward. They
+  // take the SAME flag set as the send-side commands and share the composition
+  // path with them, so the schemas above are reused verbatim rather than
+  // re-declared — the only difference is the subcommand and that NOTHING IS
+  // SENT.
+  //
+  // These exist because staging a reply used to mean gog_gmail_drafts_create
+  // with replyToMessageId/replyToThreadId, which threads the draft but does NOT
+  // inherit the original's recipients or quote its body — the caller had to
+  // rebuild both by hand, and a missed Cc is invisible until the draft goes
+  // out. Here the inheritance is gog's, identical to what the send path would
+  // have produced.
+  const draftReplyNote =
+    ' Composes exactly what gog_gmail_reply%s would send — inherited recipients, "Re:" subject and quoted ' +
+    'original — but SAVES IT AS A DRAFT instead of sending. Nothing leaves the mailbox; send it later with ' +
+    'gog_gmail_drafts_send, or edit it first with gog_gmail_drafts_update (which overwrites the whole body, ' +
+    'quote included — read the draft back before editing).';
+
+  server.registerTool('gog_gmail_drafts_reply', {
+    description:
+      'Save a reply to a Gmail message as a draft (to the original sender only).' + draftReplyNote.replace('%s', '') +
+      ' Prefer this over gog_gmail_drafts_create + replyToMessageId when the draft is a real reply: that route threads ' +
+      'the draft but leaves recipients and quoting for you to reconstruct.',
+    inputSchema: { ...replySchema, returnFull: draftWriteSchema.returnFull },
+  }, async ({ messageId, account, returnFull, ...flags }) => {
+    const args: GogArg[] = ['gmail', 'drafts', 'reply', messageId];
+    appendReplyFlags(args, flags);
+    return writeDraft(args, account, returnFull);
+  });
+
+  server.registerTool('gog_gmail_drafts_reply_all', {
+    description:
+      'Save a reply-all to a Gmail message as a draft (sender plus every To/Cc recipient).' +
+      draftReplyNote.replace('%s', '_all') +
+      ' Use the remove flag to drop recipients BEFORE the draft exists, rather than editing them out afterwards.',
+    inputSchema: { ...replySchema, returnFull: draftWriteSchema.returnFull },
+  }, async ({ messageId, account, returnFull, ...flags }) => {
+    const args: GogArg[] = ['gmail', 'drafts', 'reply-all', messageId];
+    appendReplyFlags(args, flags);
+    return writeDraft(args, account, returnFull);
+  });
+
+  server.registerTool('gog_gmail_drafts_forward', {
+    description:
+      'Save a forward of a Gmail message as a draft. Same composition as gog_gmail_forward — the original ' +
+      'message quoted below an optional note, with its attachments carried over — but nothing is sent. ' +
+      'Unlike gog_gmail_forward, `to` is OPTIONAL here: omit it to stage a recipient-less forward as an ' +
+      'accidental-send guard, then add recipients with gog_gmail_drafts_update before gog_gmail_drafts_send.',
+    inputSchema: {
+      messageId: z.string().describe('Gmail message ID to forward'),
+      to: z.string().optional().describe('Recipients (comma-separated). Optional for a draft — omit to stage the forward without recipients.'),
+      cc: z.string().optional().describe('CC recipients (comma-separated)'),
+      bcc: z.string().optional().describe('BCC recipients (comma-separated)'),
+      note: z.string().optional().describe('Introductory text above the forwarded message'),
+      from: z.string().optional().describe('Send from this email address (must be a verified send-as alias)'),
+      skipAttachments: z.boolean().optional().describe('Do not include original attachments'),
+      returnFull: draftWriteSchema.returnFull,
+      account: accountParam,
+    },
+  }, async ({ messageId, to, cc, bcc, note, from, skipAttachments, returnFull, account }) => {
+    const args: GogArg[] = ['gmail', 'drafts', 'forward', messageId];
+    if (to) args.push(`--to=${to}`);
+    if (cc) args.push(`--cc=${cc}`);
+    if (bcc) args.push(`--bcc=${bcc}`);
+    if (note) args.push(payloadArg('note', 'note-file', note));
+    if (from) args.push(`--from=${from}`);
+    if (skipAttachments) args.push('--skip-attachments');
+    return writeDraft(args, account, returnFull);
+  });
+
   server.registerTool('gog_gmail_autoreply', {
     description: 'Reply once to all messages matching a Gmail search query. Use the label flag to dedupe across runs.',
     annotations: { destructiveHint: true },
@@ -3278,12 +3352,17 @@ export function registerExtraGmailTools(server: McpServer): void {
   });
 
   server.registerTool('gog_gmail_messages_search', {
-    description: 'Search individual messages (not threads) using Gmail query syntax. Returns one result per matching message.',
+    description: 'Search individual messages (not threads) using Gmail query syntax. Returns one result per matching message. '
+      + 'Results are ALWAYS newest-first by Gmail\'s internalDate — the wrapper sorts them, so the first result is the most recent match. '
+      + 'IMPORTANT — a response carrying "truncated": true is an INCOMPLETE view of the matches: NEVER report that a message does not exist on the strength of one. Page through it (pass nextPageToken back as `pageToken`), set maxPages to walk several pages in one call, or narrow the query first. '
+      + 'If you already know the thread, read it with gog_gmail_thread_get instead of searching for it.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       query: z.string().describe('Gmail search query (e.g. "from:alice is:unread has:attachment")'),
       max: z.number().optional().describe('Max results'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
+      maxPages: z.number().int().positive().max(20).optional().describe('Walk up to this many pages in ONE call and merge the results, instead of returning a single page. Use it for existence questions (\"is there any mail matching X?\"), which a single page cannot answer. Stops early at the last page; if pages remain when the cap is hit the response is still marked truncated. Prefer this over all=true, which is unbounded.'),
       all: z.boolean().optional().describe('Fetch all pages'),
       includeBody: z.boolean().optional().describe('Include the decoded message body in each result'),
       full: z.boolean().optional().describe('Show full message bodies without truncation (implies includeBody)'),
@@ -3292,10 +3371,9 @@ export function registerExtraGmailTools(server: McpServer): void {
       useIndexedAttachmentIds: z.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, includeAttachments, useIndexedAttachmentIds, account }) => {
+  }, async ({ query, max, pageToken, page, maxPages, all, includeBody, full, bodyFormat, includeAttachments, useIndexedAttachmentIds, account }) => {
     const args = ['gmail', 'messages', 'search', query];
     if (max !== undefined) args.push(`--max=${max}`);
-    if (page) args.push(`--page=${page}`);
     if (all) args.push('--all');
     if (includeBody) args.push('--include-body');
     if (full) args.push('--full');
@@ -3305,7 +3383,19 @@ export function registerExtraGmailTools(server: McpServer): void {
     // nothing in the arg array to show for it. See gog_gmail_thread_get.
     args.push(includeAttachments ? '--include-attachments' : '--include-attachments=false');
     args.push(useIndexedAttachmentIds ? '--use-indexed-attachment-ids' : '--use-indexed-attachment-ids=false');
-    return runOrDiagnose(args, { account });
+    // See gog_gmail_search: the cursor rides per page so the walk can advance it.
+    const runPage = (tok: string | undefined) =>
+      runOrDiagnose(tok ? [...args, `--page=${tok}`] : args, { account });
+    const token = resolvePageToken({ pageToken, page });
+    const result = maxPages !== undefined
+      ? await fetchGmailPages(runPage, 'messages', maxPages, token)
+      : await runPage(token);
+    return finalizeGmailSearch(result, {
+      itemsKey: 'messages',
+      method: 'users.messages.list',
+      query,
+      account,
+    });
   });
 
   server.registerTool('gog_gmail_labels_style', {

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

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { registerExtraGmailTools } from '../../src/tools/gmail-extra.js';
 import * as lib from '../../../gogcli-mcp/src/lib.js';
+import * as runner from '../../../gogcli-mcp/src/runner.js';
 import { createTestHarness, type TestHarness } from '@chrischall/mcp-utils/test';
 import { rawTextResult, errorResult } from '@chrischall/mcp-utils';
 
@@ -14,6 +15,16 @@ vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
   };
 });
 
+// finalizeGmailSearch reaches for runner.run DIRECTLY (not the lib re-export
+// the mock above replaces) to count matches behind a truncated result set.
+// Without this the probe would spawn the real `gog` and hit the live Gmail API
+// from a unit test. Only `run` is replaced — runExecutor is a real
+// AsyncLocalStorage the connector-shape tests depend on.
+vi.mock('../../../gogcli-mcp/src/runner.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof runner>();
+  return { ...actual, run: vi.fn() };
+});
+
 let harness: TestHarness;
 
 beforeEach(async () => {
@@ -21,6 +32,9 @@ beforeEach(async () => {
   vi.mocked(lib.run).mockResolvedValue('{}');
   vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
   vi.mocked(lib.diagnose).mockResolvedValue(errorResult('diagnosed'));
+  // Default: the match-count probe finds nothing to report, so no test depends
+  // on a live call. Tests that care stub it explicitly.
+  vi.mocked(runner.run).mockRejectedValue(new Error('no count probe stubbed'));
   harness = await createTestHarness(registerExtraGmailTools);
 });
 
@@ -1655,6 +1669,139 @@ describe('gog_gmail_reply_all', () => {
   });
 });
 
+// gog 0.36.0 (openclaw/gogcli#977) added the draft-side twins of reply /
+// reply-all / forward. The point of these tests is the SUBCOMMAND: the flag
+// handling is the send path's, shared verbatim, and a copy of it here would
+// only re-assert what the reply tests above already pin. What is new — and what
+// a regression would silently break — is that these route to `drafts <verb>`
+// and therefore never send.
+describe('gog_gmail_drafts_reply', () => {
+  it('routes to gmail drafts reply, not the sending reply', async () => {
+    await harness.callTool('gog_gmail_drafts_reply', { messageId: 'm1', body: 'Thanks' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['gmail', 'drafts', 'reply', 'm1', '--body=Thanks', '--auto-from-addressed-alias=false'],
+      { account: undefined },
+    );
+  });
+
+  it('passes the shared reply flag set through unchanged', async () => {
+    await harness.callTool('gog_gmail_drafts_reply', {
+      messageId: 'm1',
+      body: 'Hi',
+      to: ['a@b.com'],
+      cc: ['cc@x.com'],
+      remove: ['old@x.com'],
+      subject: 'New subject',
+      noQuote: true,
+      attach: ['/tmp/a.pdf'],
+      from: 'me@x.com',
+      signature: true,
+      account: 'me@gmail.com',
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      [
+        'gmail', 'drafts', 'reply', 'm1',
+        '--body=Hi',
+        '--to=a@b.com',
+        '--cc=cc@x.com',
+        '--remove=old@x.com',
+        '--subject=New subject',
+        '--no-quote',
+        '--attach=/tmp/a.pdf',
+        '--from=me@x.com',
+        '--signature',
+        '--auto-from-addressed-alias=false',
+      ],
+      { account: 'me@gmail.com' },
+    );
+  });
+
+  it('returnFull re-fetches the saved draft and never reaches the CLI as a flag', async () => {
+    vi.mocked(lib.runOrDiagnose)
+      .mockResolvedValueOnce(rawTextResult('{"draftId":"d9"}'))
+      .mockResolvedValueOnce(rawTextResult('{"id":"d9","message":{"subject":"Re: Hi"}}'));
+    const result = await harness.callTool('gog_gmail_drafts_reply', {
+      messageId: 'm1', body: 'Hi', returnFull: true,
+    });
+    expect(lib.runOrDiagnose).toHaveBeenNthCalledWith(1,
+      ['gmail', 'drafts', 'reply', 'm1', '--body=Hi', '--auto-from-addressed-alias=false'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenNthCalledWith(2,
+      ['gmail', 'drafts', 'get', 'd9', '--use-indexed-attachment-ids=false'], { account: undefined });
+    expect(result.content[0].text).toContain('"subject":"Re: Hi"');
+  });
+});
+
+describe('gog_gmail_drafts_reply_all', () => {
+  it('routes to gmail drafts reply-all', async () => {
+    await harness.callTool('gog_gmail_drafts_reply_all', { messageId: 'm1', body: 'Thanks all' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['gmail', 'drafts', 'reply-all', 'm1', '--body=Thanks all', '--auto-from-addressed-alias=false'],
+      { account: undefined },
+    );
+  });
+
+  it('carries repeatable recipient removals onto the draft', async () => {
+    await harness.callTool('gog_gmail_drafts_reply_all', {
+      messageId: 'm1', body: 'Hi', remove: ['drop@y.com', 'also@y.com'],
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      [
+        'gmail', 'drafts', 'reply-all', 'm1',
+        '--body=Hi',
+        '--remove=drop@y.com',
+        '--remove=also@y.com',
+        '--auto-from-addressed-alias=false',
+      ],
+      { account: undefined },
+    );
+  });
+});
+
+describe('gog_gmail_drafts_forward', () => {
+  it('omits --to entirely when no recipients are given', async () => {
+    await harness.callTool('gog_gmail_drafts_forward', { messageId: 'm1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['gmail', 'drafts', 'forward', 'm1'],
+      { account: undefined },
+    );
+  });
+
+  it('passes every forward flag', async () => {
+    await harness.callTool('gog_gmail_drafts_forward', {
+      messageId: 'm1',
+      to: 'a@b.com,c@d.com',
+      cc: 'cc@x.com',
+      bcc: 'bcc@x.com',
+      note: 'FYI',
+      from: 'me@x.com',
+      skipAttachments: true,
+      account: 'me@gmail.com',
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      [
+        'gmail', 'drafts', 'forward', 'm1',
+        '--to=a@b.com,c@d.com',
+        '--cc=cc@x.com',
+        '--bcc=bcc@x.com',
+        '--note=FYI',
+        '--from=me@x.com',
+        '--skip-attachments',
+      ],
+      { account: 'me@gmail.com' },
+    );
+  });
+
+  it('returnFull re-fetches the saved forward draft', async () => {
+    vi.mocked(lib.runOrDiagnose)
+      .mockResolvedValueOnce(rawTextResult('{"draftId":"d7"}'))
+      .mockResolvedValueOnce(rawTextResult('{"id":"d7","message":{"subject":"Fwd: Hi"}}'));
+    const result = await harness.callTool('gog_gmail_drafts_forward', { messageId: 'm1', returnFull: true });
+    expect(lib.runOrDiagnose).toHaveBeenNthCalledWith(2,
+      ['gmail', 'drafts', 'get', 'd7', '--use-indexed-attachment-ids=false'], { account: undefined });
+    expect(result.content[0].text).toContain('"subject":"Fwd: Hi"');
+  });
+});
+
 describe('gog_gmail_autoreply', () => {
   it('calls runOrDiagnose with query and --body', async () => {
     await harness.callTool('gog_gmail_autoreply', { query: 'is:unread', body: 'Thanks' });
@@ -1735,7 +1882,7 @@ describe('gog_gmail_messages_search', () => {
     await harness.callTool('gog_gmail_messages_search', {
       query: 'is:unread',
       max: 10,
-      page: 'tok',
+      pageToken: 'tok',
       all: true,
       includeBody: true,
       full: true,
@@ -1743,7 +1890,7 @@ describe('gog_gmail_messages_search', () => {
       account: 'me@x.com',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['gmail', 'messages', 'search', 'is:unread', '--max=10', '--page=tok', '--all', '--include-body', '--full', '--body-format=html', '--include-attachments=false', '--use-indexed-attachment-ids=false'],
+      ['gmail', 'messages', 'search', 'is:unread', '--max=10', '--all', '--include-body', '--full', '--body-format=html', '--include-attachments=false', '--use-indexed-attachment-ids=false', '--page=tok'],
       { account: 'me@x.com' },
     );
   });
@@ -1757,6 +1904,98 @@ describe('gog_gmail_messages_search', () => {
   });
 });
 
+describe('page-cursor contract', () => {
+  it('never steers a caller to the deprecated `page` alias', async () => {
+    const { tools } = await harness.client.listTools();
+    const offenders = (tools as { name: string; description?: string }[])
+      .filter((t) => /`page`|\bas page\b/i.test(t.description ?? ''))
+      .map((t) => t.name);
+    expect(offenders).toEqual([]);
+  });
+
+  it('offers the alias wherever pageToken is accepted', async () => {
+    const { tools } = await harness.client.listTools();
+    const withCursor = (tools as { name: string; inputSchema?: { properties?: Record<string, unknown> } }[])
+      .filter((t) => 'pageToken' in (t.inputSchema?.properties ?? {}));
+    expect(withCursor.length).toBeGreaterThan(0);
+    expect(withCursor.filter((t) => !('page' in (t.inputSchema?.properties ?? {}))).map((t) => t.name)).toEqual([]);
+  });
+});
+
+describe('gog_gmail_messages_search — the page cursor reaches the API', () => {
+  it('threads a pageToken through to the gog invocation', async () => {
+    await harness.callTool('gog_gmail_messages_search', { query: 'x', pageToken: 'CURSOR' });
+    const args = vi.mocked(lib.runOrDiagnose).mock.calls[0][0] as string[];
+    expect(args).toContain('--page=CURSOR');
+  });
+
+  it('still accepts the deprecated page alias, and pageToken wins over it', async () => {
+    await harness.callTool('gog_gmail_messages_search', { query: 'x', page: 'OLD' });
+    expect(vi.mocked(lib.runOrDiagnose).mock.calls[0][0]).toContain('--page=OLD');
+    vi.mocked(lib.runOrDiagnose).mockClear();
+    await harness.callTool('gog_gmail_messages_search', { query: 'x', pageToken: 'NEW', page: 'OLD' });
+    expect(vi.mocked(lib.runOrDiagnose).mock.calls[0][0]).toContain('--page=NEW');
+  });
+
+  it('walks and merges pages under maxPages', async () => {
+    vi.mocked(lib.runOrDiagnose)
+      .mockResolvedValueOnce(rawTextResult(JSON.stringify({ messages: [{ id: 'a' }], nextPageToken: 'T1' })))
+      .mockResolvedValueOnce(rawTextResult(JSON.stringify({ messages: [{ id: 'b' }] })));
+    const result = await harness.callTool('gog_gmail_messages_search', { query: 'x', maxPages: 4 });
+    const out = JSON.parse(result.content[0].text as string);
+    expect(out.messages.map((m: { id: string }) => m.id)).toEqual(['a', 'b']);
+    expect(out).not.toHaveProperty('nextPageToken');
+    expect(vi.mocked(lib.runOrDiagnose).mock.calls[1][0]).toContain('--page=T1');
+  });
+});
+
+describe('gog_gmail_messages_search — result finalization', () => {
+  it('sorts results newest-first', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult(JSON.stringify({
+      messages: [
+        { id: 'old', internalDateIso: '2026-08-01T09:00:00-04:00' },
+        { id: 'new', internalDateIso: '2026-08-12T12:36:00-04:00' },
+        { id: 'mid', internalDateIso: '2026-08-05T09:00:00-04:00' },
+      ],
+      nextPageToken: '',
+    })));
+    const result = await harness.callTool('gog_gmail_messages_search', { query: 'x' });
+    const out = JSON.parse(result.content[0].text as string);
+    expect(out.messages.map((m: { id: string }) => m.id)).toEqual(['new', 'mid', 'old']);
+    expect(out).not.toHaveProperty('truncated');
+  });
+
+  it('marks a capped result set truncated and counts the real total', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult(JSON.stringify({
+      messages: [{ id: 'a' }, { id: 'b' }],
+      nextPageToken: 'tok',
+    })));
+    vi.mocked(runner.run).mockResolvedValue(JSON.stringify({
+      messages: [{ id: 'a' }, { id: 'b' }, { id: 'c' }, { id: 'd' }, { id: 'e' }],
+    }));
+    const result = await harness.callTool('gog_gmail_messages_search', { query: 'x', max: 2 });
+    const out = JSON.parse(result.content[0].text as string);
+    expect(out.truncated).toBe(true);
+    expect(out.returned).toBe(2);
+    expect(out.totalMatches).toBe(5);
+    expect(out.warning).toBe(
+      'INCOMPLETE RESULT SET: returned 2 of 5 matches. Do not report an absence of results ' +
+      'based on this response. Page with nextPageToken or narrow the query.',
+    );
+    expect(runner.run).toHaveBeenCalledWith(
+      ['api', 'call', 'gmail', 'v1', 'users.messages.list',
+        '--params={"userId":"me","q":"x","maxResults":500,"fields":"messages/id,nextPageToken"}'],
+      { account: undefined },
+    );
+  });
+
+  it('leaves output it does not recognise untouched', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('No results'));
+    const result = await harness.callTool('gog_gmail_messages_search', { query: 'x' });
+    expect(result.content[0].text).toBe('No results');
+  });
+});
+
 describe('gog_gmail_labels_style', () => {
   it('calls runOrDiagnose with just the label', async () => {
     await harness.callTool('gog_gmail_labels_style', { labelIdOrName: 'Work' });