gogcli-mcp 2.23.0 → 2.23.2

package/src/gmail-results.ts

@@ -0,0 +1,228 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { rawTextResult } from '@chrischall/mcp-utils';
+import { run } from './runner.js';
+import { annotateTruncation, hasMorePages } from './pagination.js';
+import type { MatchCount } from './pagination.js';
+
+// Post-processing for Gmail search output, on the seam between gog's JSON and
+// the model client. Two guarantees live here, both of which exist because a
+// client read a search response and confidently reported that a message did not
+// exist when it did:
+//
+//   1. A capped result set SAYS SO, in prose. gog reports a nextPageToken and
+//      nothing else; a token is easy to skim past, and skipping it turns a
+//      partial answer into a false negative.
+//   2. Results are newest-first by internalDate. Gmail's own thread ordering
+//      keys on the thread, so a message that arrived today can rank below
+//      older ones and fall off the end of a capped page.
+
+type GmailListItem = Record<string, unknown> & {
+  date?: string;
+  internalDateIso?: string;
+};
+
+// Sort key for newest-first. internalDateIso is Gmail's own internalDate and is
+// what a parser should read; `date` parses the sender-written Date header and
+// can be skewed, malformed, or in another zone, so it is only a fallback.
+// Anything unparseable sorts LAST rather than being silently treated as the
+// epoch — which would rank it as the oldest result, the exact failure this
+// guarantee exists to remove.
+function sortKey(item: GmailListItem): number {
+  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;
+}
+
+// Array.prototype.sort is stable per spec, so equal keys — and the whole
+// undated tail, which shares NEGATIVE_INFINITY — keep their original order.
+function sortNewestFirst(items: GmailListItem[]): GmailListItem[] {
+  return [...items].sort((a, b) => {
+    const ka = sortKey(a);
+    const kb = sortKey(b);
+    // Compare before subtracting: (-Infinity) - (-Infinity) is NaN, which would
+    // make the comparator incoherent for every undated pair.
+    return ka === kb ? 0 : kb - ka;
+  });
+}
+
+export type GmailListMethod = 'users.threads.list' | 'users.messages.list';
+
+// The largest page Gmail's list endpoints will serve. One page at this size is
+// enough to count the whole match set for all but the broadest queries.
+const COUNT_PROBE_PAGE_SIZE = 500;
+
+// Count how many matches the query REALLY has.
+//
+// Deliberately NOT Gmail's own resultSizeEstimate, which is the obvious source
+// and is worthless: measured against a live mailbox on 2026-08-12 it returned
+// exactly 201 for every non-empty query tried — `from:freshbooks.com` (21 real
+// matches), `from:housecallpro.com` (6), `from:thumbtack.com newer_than:30d`
+// (3) — and 0 for a query with no matches. It saturates, so it is a
+// has-results boolean wearing a number's clothes. Reporting "3 of ~201" when
+// the truth is 3 of 6 would invent a figure, which is a worse failure than the
+// missing count this whole block exists to supply.
+//
+// So: ask for one maximal page of bare ids and count them. `fields` keeps the
+// response to ids alone, and the count is EXACT whenever the result set fits in
+// a page — which is the common case, and always the case for the narrow queries
+// a caller is most likely to draw a false negative from. A full page with more
+// behind it yields an honest lower bound instead.
+//
+// gog cannot supply this itself: `gmail search` and `gmail messages search`
+// build their JSON by hand from the items plus nextPageToken, so a direct
+// Discovery call is the only route. It is only ever spent on a result set
+// already known to be truncated.
+//
+// Best-effort by construction: any failure must degrade the warning, never the
+// search.
+async function countMatches(
+  method: GmailListMethod,
+  itemsKey: 'threads' | 'messages',
+  query: string,
+  account: string | undefined,
+): Promise<MatchCount> {
+  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) as Record<string, unknown>;
+    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 {};
+  }
+}
+
+export interface FinalizeOptions {
+  /** Which array in gog's payload holds the results. */
+  itemsKey: 'threads' | 'messages';
+  /** The Discovery method whose resultSizeEstimate matches that array. */
+  method: GmailListMethod;
+  /** The query as the caller wrote it. */
+  query: string;
+  account?: string;
+  /**
+   * False when gog rewrote the query server-side (--from-contact resolves a
+   * contact through the People API to addresses we cannot reproduce). An
+   * estimate for a DIFFERENT query is worse than none, so the field is skipped
+   * rather than guessed.
+   */
+  queryIsExact?: boolean;
+}
+
+// The single seam every Gmail search result passes through: guarantee the
+// ordering, and make a capped result set say so out loud. Any output that is
+// not the JSON shape this understands — an error, a plain "No results" — is
+// returned untouched.
+export async function finalizeGmailSearch(
+  result: CallToolResult,
+  options: FinalizeOptions,
+): Promise<CallToolResult> {
+  const { itemsKey, method, query, account, queryIsExact = true } = options;
+  const first = result.content[0];
+  if (result.isError || first?.type !== 'text') return result;
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(first.text) as Record<string, unknown>;
+  } catch {
+    return result;
+  }
+  const items = parsed[itemsKey];
+  if (!Array.isArray(items)) return result;
+
+  const sorted = sortNewestFirst(items as GmailListItem[]);
+  const out: Record<string, unknown> = { ...parsed, [itemsKey]: sorted };
+
+  // The presence of the block is itself the signal, so it is added ONLY for a
+  // genuinely capped set. gog leaves nextPageToken empty when --all exhausted
+  // the pages, which is why --all needs no special case here.
+  if (hasMorePages(parsed)) {
+    const count = queryIsExact ? await countMatches(method, itemsKey, query, account) : {};
+    annotateTruncation(out, sorted.length, count);
+  }
+
+  return rawTextResult(JSON.stringify(out));
+}
+
+// Walk up to `maxPages` pages and merge them into one payload.
+//
+// The point is the existence question — "is there any mail matching X?" — which
+// a single page cannot answer and which is exactly where a truncated response
+// gets misread as a negative. gog has `--all`, but that is unbounded: on a
+// broad query it walks the entire mailbox. This is the bounded form, so a
+// caller can say "look at up to 5 pages" and get either a real answer or an
+// honestly-still-truncated one.
+//
+// The merged payload keeps a nextPageToken only if pages remain when the cap is
+// hit, so finalizeGmailSearch still marks it truncated — running out of budget
+// is not the same as reaching the end, and must not read like it.
+export async function fetchGmailPages(
+  runPage: (token: string | undefined) => Promise<CallToolResult>,
+  itemsKey: 'threads' | 'messages',
+  maxPages: number,
+  startToken: string | undefined,
+): Promise<CallToolResult> {
+  const merged: unknown[] = [];
+  let base: Record<string, unknown> | undefined;
+  let token = startToken;
+
+  for (let pages = 0; pages < maxPages; pages++) {
+    const result = await runPage(token);
+    const parsed = parsePage(result, itemsKey);
+    // An error, or output this does not understand, part-way through the walk.
+    // Nothing collected yet means the caller should just see that result; once
+    // pages ARE collected, return them WITH the cursor that was about to be
+    // consumed, so the set still reads as truncated rather than complete.
+    if (parsed === undefined) {
+      return base === undefined ? result : finish(base, itemsKey, merged, token);
+    }
+    base = parsed;
+    merged.push(...(parsed[itemsKey] as unknown[]));
+    token = typeof parsed.nextPageToken === 'string' && parsed.nextPageToken !== ''
+      ? parsed.nextPageToken
+      : undefined;
+    if (token === undefined) break;
+  }
+
+  return finish(base as Record<string, unknown>, itemsKey, merged, token);
+}
+
+// A page's payload, or undefined if it is not a usable list response.
+function parsePage(
+  result: CallToolResult,
+  itemsKey: string,
+): Record<string, unknown> | undefined {
+  const first = result.content[0];
+  if (result.isError || first?.type !== 'text') return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(first.text);
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== 'object') return undefined;
+  const obj = parsed as Record<string, unknown>;
+  return Array.isArray(obj[itemsKey]) ? obj : undefined;
+}
+
+function finish(
+  base: Record<string, unknown>,
+  itemsKey: string,
+  merged: unknown[],
+  token: string | undefined,
+): CallToolResult {
+  const out: Record<string, unknown> = { ...base, [itemsKey]: merged };
+  if (token === undefined) delete out.nextPageToken;
+  else out.nextPageToken = token;
+  return rawTextResult(JSON.stringify(out));
+}

package/src/lib.ts

@@ -19,6 +19,12 @@ export { run, runBinary, runExecutor, isGogFileArg, MIN_GOG_VERSION } from './ru
 // `runOrDiagnose` seam) must still apply this, or their timestamps skip the
 // offset repair and the `<field>Display` sibling every other tool returns.
 export { normalizeTimestamps } from './timestamps.js';
+export { annotateTruncatedList, stripConsumedPageToken } from './pagination.js';
+// Search-result finalization (newest-first ordering + loud truncation metadata).
+// Sub-package search tools must route their output through this or they lose both
+// guarantees the base gog_gmail_search makes.
+export { finalizeGmailSearch, fetchGmailPages } from './gmail-results.js';
+export type { FinalizeOptions, GmailListMethod } from './gmail-results.js';
 export { useRemoteGogRunner } from './remote-runner.js';
 export type { RunOptions, Spawner, GogExecutor, GogArg, GogFileArg } from './runner.js';
 export {
@@ -31,5 +37,8 @@ export {
   ids,
   paginationParams,
   pushPaginationFlags,
+  pageTokenParam,
+  pageAliasParam,
+  resolvePageToken,
   registerRunTool,
 } from './tools/utils.js';

package/src/pagination.ts

@@ -0,0 +1,108 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { rawTextResult } from '@chrischall/mcp-utils';
+
+// gog reports an exhausted cursor as `"nextPageToken": ""` rather than omitting
+// the field. That empty string is worse than nothing: the natural reading of a
+// paginated response is "the cursor key is there, so there is another page",
+// and a caller acting on the key's PRESENCE pages forever or, worse, concludes
+// the opposite of the truth. Strip it so the field means exactly one thing —
+// present iff another page exists.
+//
+// Deliberately top-level only. A nested `nextPageToken` belongs to some
+// embedded resource whose paging semantics are not ours to reinterpret.
+
+// Byte-identical passthrough is the contract when nothing was removed — see
+// normalizeTimestamps, which this sits beside on the same seam and whose
+// indent-preserving discipline it copies.
+function detectIndent(text: string): number {
+  const match = /\n(\s+)\S/.exec(text);
+  return match ? match[1].replace(/\t/g, '  ').length : 0;
+}
+
+export function stripConsumedPageToken(text: string): string {
+  const trimmed = text.trim();
+  if (trimmed === '' || !trimmed.startsWith('{')) return text;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return text;
+  }
+  // The `{` guard above means anything that parses here is a plain object —
+  // never null, an array, or a scalar — so no further shape check is needed.
+  const obj = parsed as Record<string, unknown>;
+  if (obj.nextPageToken !== '') return text;
+  delete obj.nextPageToken;
+  return JSON.stringify(obj, null, detectIndent(text));
+}
+
+// ---------------------------------------------------------------------------
+// Truncation metadata
+// ---------------------------------------------------------------------------
+
+// How many items the query really has, when we were able to find out.
+export interface MatchCount {
+  /** Exact total — the probe reached the end of the result set. */
+  total?: number;
+  /** Lower bound — the probe filled its page and more remain. */
+  atLeast?: number;
+}
+
+// The prose matters more than the boolean. A bare `truncated: true` is exactly
+// the kind of structured field a model client skims past — which is how a
+// non-empty nextPageToken produced a confident "no such email exists". This
+// says, in words, the one conclusion the caller must not draw.
+export function truncationWarning(returned: number, count: MatchCount): string {
+  const scope = count.total !== undefined
+    ? `returned ${returned} of ${count.total} matches`
+    : count.atLeast !== undefined
+      ? `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.';
+}
+
+// Add the truncation block to a parsed payload, in place.
+//
+// Only ever called for a genuinely capped set, so the block's PRESENCE is
+// itself the signal and a complete response stays clean. By the time this runs
+// an exhausted cursor has already been stripped by stripConsumedPageToken, so
+// "has a nextPageToken" and "has another page" are the same question.
+export function annotateTruncation(
+  out: Record<string, unknown>,
+  returned: number,
+  count: MatchCount,
+): void {
+  out.truncated = true;
+  out.returned = returned;
+  if (count.total !== undefined) out.totalMatches = count.total;
+  if (count.atLeast !== undefined) out.totalMatchesAtLeast = count.atLeast;
+  out.warning = truncationWarning(returned, count);
+}
+
+// True when the payload still carries a live cursor.
+export function hasMorePages(parsed: Record<string, unknown>): boolean {
+  return typeof parsed.nextPageToken === 'string' && parsed.nextPageToken !== '';
+}
+
+// Attach the truncation block to a tool result whose payload we cannot cheaply
+// count — the fact of truncation without a fabricated total. Anything that is
+// not the JSON shape this understands passes through untouched.
+export function annotateTruncatedList(
+  result: CallToolResult,
+  itemsKey: string,
+): CallToolResult {
+  const first = result.content[0];
+  if (result.isError || first?.type !== 'text') return result;
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(first.text) as Record<string, unknown>;
+  } catch {
+    return result;
+  }
+  const items = parsed[itemsKey];
+  if (!Array.isArray(items) || !hasMorePages(parsed)) return result;
+  const out: Record<string, unknown> = { ...parsed };
+  annotateTruncation(out, items.length, {});
+  return rawTextResult(JSON.stringify(out));
+}

package/src/tools/calendar.ts

@@ -1,10 +1,13 @@
 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';
+import { annotateTruncatedList } from '../pagination.js';
 
 export function registerCalendarTools(server: McpServer): void {
   server.registerTool('gog_calendar_events', {
-    description: 'List calendar events. Filters can be combined (e.g. --from + --to for a range, or --today for just today).',
+    description: 'List calendar events. Filters can be combined (e.g. --from + --to for a range, or --today for just today). '
+      + 'gog returns only 10 events by default, so a wide date range is USUALLY INCOMPLETE: raise max, or page with pageToken until the response carries no nextPageToken. '
+      + 'A response carrying "truncated": true is an incomplete view — never conclude an event does not exist from one.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       calendarId: z.string().optional().describe('Calendar ID (default: primary calendar)'),
@@ -12,22 +15,32 @@ export function registerCalendarTools(server: McpServer): void {
       to: z.string().optional().describe('End time filter (RFC3339, date, or natural language)'),
       today: z.boolean().optional().describe('Only show today\'s events'),
       query: z.string().optional().describe('Free text search within events'),
-      all: z.boolean().optional().describe('Fetch events from all calendars'),
+      max: z.number().int().optional().describe('Max events to return. gog defaults to 10, which silently hides the rest — raise it, or page with pageToken.'),
+      pageToken: pageTokenParam,
+      page: pageAliasParam,
+      all: z.boolean().optional().describe('Fetch events from ALL CALENDARS. NOTE: unlike the gmail search tools, this does NOT mean "all pages" — it widens the calendar set, not the page window. Use pageToken to reach later pages.'),
       eventTypes: z.array(z.enum(['default', 'birthday', 'focus-time', 'from-gmail', 'out-of-office', 'working-location'])).optional().describe('Filter to specific event types (repeatable)'),
       timezone: z.string().optional().describe('Display timezone for event times (IANA name, e.g. America/New_York, or "local" for the system timezone). Default: each event\'s timezone, then its calendar\'s timezone.'),
       account: accountParam,
     },
-  }, async ({ calendarId, from, to, today, query, all, eventTypes, timezone, account }) => {
+  }, async ({ calendarId, from, to, today, query, max, pageToken, page, all, eventTypes, timezone, account }) => {
     const args = ['calendar', 'events'];
     if (calendarId) args.push(calendarId);
     if (from) args.push(`--from=${from}`);
     if (to) args.push(`--to=${to}`);
     if (today) args.push('--today');
     if (query) args.push(`--query=${query}`);
+    if (max !== undefined) args.push(`--max=${max}`);
+    const token = resolvePageToken({ pageToken, page });
+    if (token) args.push(`--page=${token}`);
     if (all) args.push('--all');
     if (eventTypes) for (const t of eventTypes) args.push(`--event-types=${t}`);
     if (timezone) args.push(`--timezone=${timezone}`);
-    return runOrDiagnose(args, { account });
+    const result = await runOrDiagnose(args, { account });
+    // No count probe here: unlike Gmail's list endpoints, the Calendar API has
+    // no cheap way to count a range exactly, so the warning carries the fact of
+    // truncation without inventing a total.
+    return annotateTruncatedList(result, 'events');
   });
 
   server.registerTool('gog_calendar_get', {

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 });