gogcli-mcp 2.23.1 → 2.24.0

package/src/tools/classroom.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
+import { accountParam, runOrDiagnose, registerRunTool, pageTokenParam, pageAliasParam, resolvePageToken} from './utils.js';
 
 export function registerClassroomTools(server: McpServer): void {
   server.registerTool('gog_classroom_courses_list', {
@@ -11,17 +11,19 @@ export function registerClassroomTools(server: McpServer): void {
       teacher: z.string().optional().describe('Filter by teacher user ID'),
       student: z.string().optional().describe('Filter by student user ID'),
       max: z.number().optional().describe('Max results per page'),
-      page: z.string().optional().describe('Page token for pagination'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: z.boolean().optional().describe('Fetch all pages'),
       account: accountParam,
     },
-  }, async ({ state, teacher, student, max, page, all, account }) => {
+  }, async ({ state, teacher, student, max, pageToken, page, all, account }) => {
     const args = ['classroom', 'courses', 'list'];
     if (state) args.push(`--state=${state}`);
     if (teacher) args.push(`--teacher=${teacher}`);
     if (student) args.push(`--student=${student}`);
     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 });
   });
@@ -43,14 +45,16 @@ export function registerClassroomTools(server: McpServer): void {
     inputSchema: {
       courseId: z.string().describe('Course ID'),
       max: z.number().optional().describe('Max results per page'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: z.boolean().optional().describe('Fetch all pages'),
       account: accountParam,
     },
-  }, async ({ courseId, max, page, all, account }) => {
+  }, async ({ courseId, max, pageToken, page, all, account }) => {
     const args = ['classroom', 'students', 'list', courseId];
     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 });
   });
@@ -73,14 +77,16 @@ export function registerClassroomTools(server: McpServer): void {
     inputSchema: {
       courseId: z.string().describe('Course ID'),
       max: z.number().optional().describe('Max results per page'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: z.boolean().optional().describe('Fetch all pages'),
       account: accountParam,
     },
-  }, async ({ courseId, max, page, all, account }) => {
+  }, async ({ courseId, max, pageToken, page, all, account }) => {
     const args = ['classroom', 'teachers', 'list', courseId];
     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 });
   });
@@ -105,16 +111,18 @@ export function registerClassroomTools(server: McpServer): void {
       students: z.boolean().optional().describe('Include students only'),
       teachers: z.boolean().optional().describe('Include teachers only'),
       max: z.number().optional().describe('Max results per page'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: z.boolean().optional().describe('Fetch all pages'),
       account: accountParam,
     },
-  }, async ({ courseId, students, teachers, max, page, all, account }) => {
+  }, async ({ courseId, students, teachers, max, pageToken, page, all, account }) => {
     const args = ['classroom', 'roster', courseId];
     if (students) args.push('--students');
     if (teachers) args.push('--teachers');
     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 });
   });
@@ -128,18 +136,20 @@ export function registerClassroomTools(server: McpServer): void {
       topic: z.string().optional().describe('Filter by topic ID'),
       orderBy: z.string().optional().describe('Sort order (e.g. "updateTime desc")'),
       max: z.number().optional().describe('Max results per page'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: z.boolean().optional().describe('Fetch all pages'),
       scanPages: z.number().optional().describe('Max pages to scan when filtering'),
       account: accountParam,
     },
-  }, async ({ courseId, state, topic, orderBy, max, page, all, scanPages, account }) => {
+  }, async ({ courseId, state, topic, orderBy, max, pageToken, page, all, scanPages, account }) => {
     const args = ['classroom', 'coursework', 'list', courseId];
     if (state) args.push(`--state=${state}`);
     if (topic) args.push(`--topic=${topic}`);
     if (orderBy) args.push(`--order-by=${orderBy}`);
     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');
     if (scanPages !== undefined) args.push(`--scan-pages=${scanPages}`);
     return runOrDiagnose(args, { account });
@@ -167,17 +177,19 @@ export function registerClassroomTools(server: McpServer): void {
       late: z.enum(['late', 'not-late']).optional().describe('Filter by late status'),
       user: z.string().optional().describe('Filter by student user ID'),
       max: z.number().optional().describe('Max results per page'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: z.boolean().optional().describe('Fetch all pages'),
       account: accountParam,
     },
-  }, async ({ courseId, courseworkId, state, late, user, max, page, all, account }) => {
+  }, async ({ courseId, courseworkId, state, late, user, max, pageToken, page, all, account }) => {
     const args = ['classroom', 'submissions', 'list', courseId, courseworkId];
     if (state) args.push(`--state=${state}`);
     if (late) args.push(`--late=${late}`);
     if (user) args.push(`--user=${user}`);
     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 });
   });
@@ -260,16 +272,18 @@ export function registerClassroomTools(server: McpServer): void {
       state: z.string().optional().describe('Filter by announcement state'),
       orderBy: z.string().optional().describe('Sort order'),
       max: z.number().optional().describe('Max results per page'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: z.boolean().optional().describe('Fetch all pages'),
       account: accountParam,
     },
-  }, async ({ courseId, state, orderBy, max, page, all, account }) => {
+  }, async ({ courseId, state, orderBy, max, pageToken, page, all, account }) => {
     const args = ['classroom', 'announcements', 'list', courseId];
     if (state) args.push(`--state=${state}`);
     if (orderBy) args.push(`--order-by=${orderBy}`);
     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 });
   });
@@ -308,14 +322,16 @@ export function registerClassroomTools(server: McpServer): void {
     inputSchema: {
       courseId: z.string().describe('Course ID'),
       max: z.number().optional().describe('Max results per page'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: z.boolean().optional().describe('Fetch all pages'),
       account: accountParam,
     },
-  }, async ({ courseId, max, page, all, account }) => {
+  }, async ({ courseId, max, pageToken, page, all, account }) => {
     const args = ['classroom', 'topics', 'list', courseId];
     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 });
   });
@@ -339,16 +355,18 @@ export function registerClassroomTools(server: McpServer): void {
       course: z.string().optional().describe('Filter by course ID'),
       user: z.string().optional().describe('Filter by user ID'),
       max: z.number().optional().describe('Max results per page'),
-      page: z.string().optional().describe('Page token'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       all: z.boolean().optional().describe('Fetch all pages'),
       account: accountParam,
     },
-  }, async ({ course, user, max, page, all, account }) => {
+  }, async ({ course, user, max, pageToken, page, all, account }) => {
     const args = ['classroom', 'invitations', 'list'];
     if (course) args.push(`--course=${course}`);
     if (user) args.push(`--user=${user}`);
     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 });
   });

package/src/tools/drive.ts

@@ -3,7 +3,7 @@ import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { rawTextResult } from '@chrischall/mcp-utils';
 import { run, runBinary } from '../runner.js';
-import { accountParam, diagnose, runOrDiagnose, registerRunTool } from './utils.js';
+import { accountParam, diagnose, runOrDiagnose, registerRunTool, pageTokenParam, pageAliasParam, resolvePageToken} from './utils.js';
 
 // A native Google Doc exports to text directly; anything else (PDF, image,
 // docx, …) is first copied WITH conversion to this type, which makes Drive run
@@ -25,16 +25,18 @@ export function registerDriveTools(server: McpServer): void {
     inputSchema: {
       folderId: z.string().optional().describe('Folder ID to list (default: root)'),
       max: z.number().optional().describe('Max results (default: 20)'),
-      page: z.string().optional().describe('Page token for pagination'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
       query: z.string().optional().describe('Drive query filter (e.g. "name contains \'budget\'")'),
       allDrives: z.boolean().optional().describe('Include shared drives (default: true). Set false for My Drive only.'),
       account: accountParam,
     },
-  }, async ({ folderId, max, page, query, allDrives, account }) => {
+  }, async ({ folderId, max, pageToken, page, query, allDrives, account }) => {
     const args = ['drive', 'ls'];
     if (folderId) args.push(`--parent=${folderId}`);
     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 (query) args.push(`--query=${query}`);
     if (allDrives === false) args.push('--no-all-drives');
     return runOrDiagnose(args, { account });

package/src/tools/gmail.ts

@@ -1,36 +1,67 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose, registerRunTool, payloadArg } from './utils.js';
+import { accountParam, runOrDiagnose, registerRunTool, payloadArg, pageTokenParam, pageAliasParam, resolvePageToken } from './utils.js';
+import { finalizeGmailSearch, fetchGmailPages } from '../gmail-results.js';
 import type { GogArg } from '../runner.js';
 
 export function registerGmailTools(server: McpServer): void {
   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 — 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 — 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 — 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: z.string().describe('Gmail search query'),
       max: z.number().int().optional().describe('Max results to return (default: 10)'),
+      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 every page instead of one. Removes truncation entirely, at the cost of one API round-trip per page — the reliable way to answer "does any message match?" for a query with few expected hits.'),
       fromContact: z.string().optional().describe('Resolve a Google Contact (name or email) to its addresses and AND a from:(addr OR addr) clause onto the query — 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 !== undefined) args.push(`--max=${max}`);
+    if (all) args.push('--all');
     if (fromContact) args.push(`--from-contact=${fromContact}`);
-    return runOrDiagnose(args, { account });
+    // The cursor is applied per page rather than baked into args, so the
+    // multi-page 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, '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: z.string().describe('Message ID'),
       format: z.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: z.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 — 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 });
   });
 

package/src/tools/utils.ts

@@ -5,6 +5,7 @@ import { errorResult, rawTextResult } from '@chrischall/mcp-utils';
 import { run, isRunnerTransportError } from '../runner.js';
 import type { GogArg, RunnerFailureKind } from '../runner.js';
 import { normalizeTimestamps } from '../timestamps.js';
+import { stripConsumedPageToken } from '../pagination.js';
 
 // Byte size at or below which a payload stays on the plain inline flag.
 //
@@ -77,10 +78,36 @@ export const ids = {
   person: z.string().describe('Person resource name (people/...) or email'),
 };
 
-// Pagination param triple — appears in 20+ tools across base + extras.
+// THE CURSOR IS NAMED AFTER THE FIELD THAT CARRIES IT. Every paginated response
+// reports its cursor as `nextPageToken`, so the request parameter is
+// `pageToken` — a caller reading a response can guess the input name and be
+// right. It used to be `page` (after gog's own `--page` flag), and that
+// mismatch was not cosmetic: MCP tool inputs are zod objects, which SILENTLY
+// STRIP unknown keys, so a client that inferred `pageToken` had it dropped
+// before the handler ran and got page 1 back forever — same items, same token,
+// no error. Two "that email doesn't exist" incidents came from exactly that.
+export const pageTokenParam = z.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.',
+);
+
+// Kept so anything already sending `page` keeps working. Prefer pageTokenParam.
+export const pageAliasParam = z.string().optional().describe(
+  'Deprecated alias for pageToken, accepted so existing callers keep working. Use pageToken — ' +
+  'it matches the nextPageToken field in the response.',
+);
+
+// The one place the alias collapses into a single value.
+export function resolvePageToken(p: { pageToken?: string; page?: string }): string | undefined {
+  return p.pageToken ?? p.page;
+}
+
+// Pagination params — appear in 30+ tools across base + extras.
 export const paginationParams = {
   max: z.number().int().optional().describe('Max results'),
-  page: z.string().optional().describe('Page token'),
+  pageToken: pageTokenParam,
+  page: pageAliasParam,
   all: z.boolean().optional().describe('Fetch all pages'),
 };
 
@@ -88,10 +115,11 @@ export const paginationParams = {
 // paginationParams above. Use together to keep call sites concise.
 export function pushPaginationFlags(
   args: string[],
-  p: { max?: number; page?: string; all?: boolean },
+  p: { max?: number; pageToken?: string; page?: string; all?: boolean },
 ): void {
   if (p.max !== undefined) args.push(`--max=${p.max}`);
-  if (p.page) args.push(`--page=${p.page}`);
+  const token = resolvePageToken(p);
+  if (token) args.push(`--page=${token}`);
   if (p.all) args.push('--all');
 }
 
@@ -330,7 +358,10 @@ export async function runOrDiagnose(
     // truth would stop telling it. Losslessness wins over presentation there —
     // the friendlier views of the same data are already normalized.
     const raw = await run(args, options);
-    return rawTextResult(options.lossless ? raw : normalizeTimestamps(raw));
+    // Same seam, same reason as normalizeTimestamps: doing this per call site
+    // would let one paginated tool forget and go on reporting a spent cursor as
+    // if it were a live one. `lossless` opts the raw dumps out of both.
+    return rawTextResult(options.lossless ? raw : stripConsumedPageToken(normalizeTimestamps(raw)));
   } catch (err) {
     return diagnose(err);
   }

package/src/worker.ts

@@ -38,7 +38,7 @@ import { gogAuth, CONNECTOR_INSTRUCTIONS, type GogProps } from './connector-auth
 // connector with all ~360 tools at once. Add whichever paths you want as separate
 // connectors in claude.ai (each authorizes with the same connector key).
 
-const VERSION = '2.23.1'; // x-release-please-version
+const VERSION = '2.24.0'; // x-release-please-version
 
 // Build an McpAgent subclass whose init() registers `registrars` onto its server,
 // each handler wrapped in the ALS scope carrying the per-session Fly executor.