gogcli-mcp 2.23.0 → 2.23.2

package/src/tools/gmail.ts

@@ -1,23 +1,48 @@
 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', {

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.0'; // x-release-please-version
+const VERSION = '2.23.2'; // 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.

package/tests/gmail-results.test.ts

@@ -0,0 +1,285 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { rawTextResult, errorResult } from '@chrischall/mcp-utils';
+import * as runner from '../src/runner.js';
+import { finalizeGmailSearch, fetchGmailPages } from '../src/gmail-results.js';
+
+vi.mock('../src/runner.js');
+
+beforeEach(() => vi.clearAllMocks());
+
+const THREADS = (nextPageToken: string) => JSON.stringify({
+  threads: [
+    { id: 'a', internalDateIso: '2026-08-01T09:00:00-04:00' },
+    { id: 'b', internalDateIso: '2026-08-12T12:36:00-04:00' },
+    { id: 'c', internalDateIso: '2026-08-05T09:00:00-04:00' },
+  ],
+  nextPageToken,
+});
+
+const THREAD_OPTS = { itemsKey: 'threads', method: 'users.threads.list', query: 'x' } as const;
+
+const parse = (r: { content: { type: string; text?: string }[] }) =>
+  JSON.parse(r.content[0].text as string);
+
+describe('finalizeGmailSearch — ordering', () => {
+  it('sorts newest-first by internalDateIso', async () => {
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('')), THREAD_OPTS));
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['b', 'c', 'a']);
+  });
+
+  it('falls back to date when internalDateIso is absent', async () => {
+    const raw = JSON.stringify({
+      threads: [
+        { id: 'a', date: '2026-08-01T09:00:00-04:00' },
+        { id: 'b', date: '2026-08-09T09:00:00-04:00' },
+      ],
+      nextPageToken: '',
+    });
+    const out = parse(await finalizeGmailSearch(rawTextResult(raw), THREAD_OPTS));
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['b', 'a']);
+  });
+
+  it('puts undated and unparseable items last, in their original order', async () => {
+    const raw = JSON.stringify({
+      threads: [
+        { id: 'nodate' },
+        { id: 'empty', internalDateIso: '' },
+        { id: 'bad', internalDateIso: 'not-a-date' },
+        { id: 'dated', internalDateIso: '2026-08-05T09:00:00-04:00' },
+      ],
+      nextPageToken: '',
+    });
+    const out = parse(await finalizeGmailSearch(rawTextResult(raw), THREAD_OPTS));
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['dated', 'nodate', 'empty', 'bad']);
+  });
+
+  it('ignores a non-string date field', async () => {
+    const raw = JSON.stringify({
+      threads: [
+        { id: 'weird', internalDateIso: 12345 },
+        { id: 'dated', internalDateIso: '2026-08-05T09:00:00-04:00' },
+      ],
+      nextPageToken: '',
+    });
+    const out = parse(await finalizeGmailSearch(rawTextResult(raw), THREAD_OPTS));
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['dated', 'weird']);
+  });
+
+  it('keeps equal timestamps in their original relative order', async () => {
+    const raw = JSON.stringify({
+      threads: [
+        { id: 'first', internalDateIso: '2026-08-05T09:00:00-04:00' },
+        { id: 'second', internalDateIso: '2026-08-05T09:00:00-04:00' },
+      ],
+      nextPageToken: '',
+    });
+    const out = parse(await finalizeGmailSearch(rawTextResult(raw), THREAD_OPTS));
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['first', 'second']);
+  });
+
+  it('sorts the messages key too', async () => {
+    const raw = JSON.stringify({
+      messages: [
+        { id: 'a', internalDateIso: '2026-08-01T09:00:00-04:00' },
+        { id: 'b', internalDateIso: '2026-08-12T09:00:00-04:00' },
+      ],
+      nextPageToken: '',
+    });
+    const out = parse(await finalizeGmailSearch(rawTextResult(raw), {
+      itemsKey: 'messages', method: 'users.messages.list', query: 'x',
+    }));
+    expect(out.messages.map((t: { id: string }) => t.id)).toEqual(['b', 'a']);
+  });
+});
+
+describe('finalizeGmailSearch — truncation metadata', () => {
+  const countReply = (ids: number, more: boolean) => JSON.stringify({
+    threads: Array.from({ length: ids }, (_, i) => ({ id: `t${i}` })),
+    ...(more ? { nextPageToken: 'more' } : {}),
+  });
+
+  it('omits every truncation field when the result set is complete', async () => {
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('')), THREAD_OPTS));
+    expect(out).not.toHaveProperty('truncated');
+    expect(out).not.toHaveProperty('returned');
+    expect(out).not.toHaveProperty('totalMatches');
+    expect(out).not.toHaveProperty('warning');
+    expect(runner.run).not.toHaveBeenCalled();
+  });
+
+  it('omits them when gog reports no nextPageToken field at all', async () => {
+    const out = parse(await finalizeGmailSearch(rawTextResult('{"threads":[{"id":"a"}]}'), THREAD_OPTS));
+    expect(out).not.toHaveProperty('truncated');
+  });
+
+  it('reports an EXACT total when the count probe reaches the end', async () => {
+    vi.mocked(runner.run).mockResolvedValue(countReply(21, false));
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), {
+      itemsKey: 'threads', method: 'users.threads.list', query: 'invoice', account: 'me@x.com',
+    }));
+    expect(out.truncated).toBe(true);
+    expect(out.returned).toBe(3);
+    expect(out.totalMatches).toBe(21);
+    expect(out).not.toHaveProperty('totalMatchesAtLeast');
+    expect(out.warning).toBe(
+      'INCOMPLETE RESULT SET: returned 3 of 21 matches. Do not report an absence of results ' +
+      'based on this response. Page with nextPageToken or narrow the query.',
+    );
+  });
+
+  it('reports a LOWER BOUND when the count probe fills its page', async () => {
+    vi.mocked(runner.run).mockResolvedValue(countReply(500, true));
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), THREAD_OPTS));
+    expect(out.totalMatchesAtLeast).toBe(500);
+    expect(out).not.toHaveProperty('totalMatches');
+    expect(out.warning).toBe(
+      'INCOMPLETE RESULT SET: returned 3 of at least 500 matches. Do not report an absence of ' +
+      'results based on this response. Page with nextPageToken or narrow the query.',
+    );
+  });
+
+  it('counts bare ids for one maximal page, scoped to the matching items key', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"messages":[{"id":"a"}]}');
+    const raw = JSON.stringify({ messages: [{ id: 'a' }], nextPageToken: 'tok' });
+    await finalizeGmailSearch(rawTextResult(raw), {
+      itemsKey: 'messages', method: 'users.messages.list', query: 'invoice', account: 'me@x.com',
+    });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['api', 'call', 'gmail', 'v1', 'users.messages.list',
+        `--params=${JSON.stringify({ userId: 'me', q: 'invoice', maxResults: 500, fields: 'messages/id,nextPageToken' })}`],
+      { account: 'me@x.com' },
+    );
+  });
+
+  it('still warns, without a count, when the count probe fails', async () => {
+    vi.mocked(runner.run).mockRejectedValue(new Error('nope'));
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), THREAD_OPTS));
+    expect(out.truncated).toBe(true);
+    expect(out.returned).toBe(3);
+    expect(out).not.toHaveProperty('totalMatches');
+    expect(out).not.toHaveProperty('totalMatchesAtLeast');
+    expect(out.warning).toBe(
+      'INCOMPLETE RESULT SET: returned 3 matches and MORE EXIST beyond this page. Do not report ' +
+      'an absence of results based on this response. Page with nextPageToken or narrow the query.',
+    );
+  });
+
+  it('omits the count when the probe output is not JSON', async () => {
+    vi.mocked(runner.run).mockResolvedValue('not json');
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), THREAD_OPTS));
+    expect(out).not.toHaveProperty('totalMatches');
+  });
+
+  it('omits the count when the probe returns no items array', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"nextPageToken":"x"}');
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), THREAD_OPTS));
+    expect(out).not.toHaveProperty('totalMatches');
+    expect(out).not.toHaveProperty('totalMatchesAtLeast');
+  });
+
+  it('treats an empty nextPageToken on the probe as the end of the set', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"threads":[{"id":"a"}],"nextPageToken":""}');
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), THREAD_OPTS));
+    expect(out.totalMatches).toBe(1);
+  });
+
+  it('skips the count probe when the query gog ran cannot be reproduced', async () => {
+    const out = parse(await finalizeGmailSearch(rawTextResult(THREADS('tok')), {
+      ...THREAD_OPTS, queryIsExact: false,
+    }));
+    expect(runner.run).not.toHaveBeenCalled();
+    expect(out.truncated).toBe(true);
+    expect(out).not.toHaveProperty('totalMatches');
+  });
+});
+
+describe('finalizeGmailSearch — pass-through', () => {
+  it('passes an error result through untouched', async () => {
+    const err = errorResult('Error: boom');
+    expect(await finalizeGmailSearch(err, THREAD_OPTS)).toBe(err);
+  });
+
+  it('passes non-JSON output through untouched', async () => {
+    const text = rawTextResult('No results');
+    expect(await finalizeGmailSearch(text, THREAD_OPTS)).toBe(text);
+  });
+
+  it('passes JSON without the expected items array through untouched', async () => {
+    const text = rawTextResult('{"somethingElse":1}');
+    expect(await finalizeGmailSearch(text, THREAD_OPTS)).toBe(text);
+  });
+
+  it('passes a result with no text content through untouched', async () => {
+    const empty = { content: [] } as unknown as Parameters<typeof finalizeGmailSearch>[0];
+    expect(await finalizeGmailSearch(empty, THREAD_OPTS)).toBe(empty);
+  });
+
+  it('handles an empty result set without adding truncation fields', async () => {
+    const out = parse(await finalizeGmailSearch(rawTextResult('{"threads":[],"nextPageToken":""}'), THREAD_OPTS));
+    expect(out.threads).toEqual([]);
+    expect(out).not.toHaveProperty('truncated');
+  });
+});
+
+describe('fetchGmailPages', () => {
+  const page = (ids: string[], token?: string) => rawTextResult(JSON.stringify({
+    threads: ids.map((id) => ({ id })),
+    ...(token === undefined ? {} : { nextPageToken: token }),
+  }));
+
+  it('merges pages and drops the cursor when it reaches the end', async () => {
+    const runPage = vi.fn()
+      .mockResolvedValueOnce(page(['a'], 'T1'))
+      .mockResolvedValueOnce(page(['b'], 'T2'))
+      .mockResolvedValueOnce(page(['c']));
+    const out = JSON.parse((await fetchGmailPages(runPage, 'threads', 5, undefined)).content[0].text as string);
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['a', 'b', 'c']);
+    expect(out).not.toHaveProperty('nextPageToken');
+    expect(runPage.mock.calls.map((c) => c[0])).toEqual([undefined, 'T1', 'T2']);
+  });
+
+  it('treats an empty-string cursor as the end', async () => {
+    const runPage = vi.fn().mockResolvedValueOnce(page(['a'], ''));
+    const out = JSON.parse((await fetchGmailPages(runPage, 'threads', 5, undefined)).content[0].text as string);
+    expect(out).not.toHaveProperty('nextPageToken');
+    expect(runPage).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps the cursor when the page cap is reached first', async () => {
+    const runPage = vi.fn()
+      .mockResolvedValueOnce(page(['a'], 'T1'))
+      .mockResolvedValueOnce(page(['b'], 'T2'));
+    const out = JSON.parse((await fetchGmailPages(runPage, 'threads', 2, undefined)).content[0].text as string);
+    expect(out.threads).toHaveLength(2);
+    expect(out.nextPageToken).toBe('T2');
+    expect(runPage).toHaveBeenCalledTimes(2);
+  });
+
+  it('starts from a caller-supplied cursor', async () => {
+    const runPage = vi.fn().mockResolvedValue(page(['a']));
+    await fetchGmailPages(runPage, 'threads', 3, 'START');
+    expect(runPage).toHaveBeenCalledWith('START');
+  });
+
+  it('surfaces a failure on the FIRST page as-is', async () => {
+    const err = errorResult('Error: boom');
+    const runPage = vi.fn().mockResolvedValue(err);
+    expect(await fetchGmailPages(runPage, 'threads', 3, undefined)).toBe(err);
+  });
+
+  it('keeps pages already collected when a LATER page fails, still marked truncated', async () => {
+    const runPage = vi.fn()
+      .mockResolvedValueOnce(page(['a'], 'T1'))
+      .mockResolvedValueOnce(errorResult('Error: boom'));
+    const out = JSON.parse((await fetchGmailPages(runPage, 'threads', 3, undefined)).content[0].text as string);
+    expect(out.threads.map((t: { id: string }) => t.id)).toEqual(['a']);
+    expect(out.nextPageToken).toBe('T1');
+  });
+
+  it('bails on output it cannot parse or that has no items array', async () => {
+    for (const bad of [rawTextResult('not json'), rawTextResult('"scalar"'), rawTextResult('{"other":1}')]) {
+      const runPage = vi.fn().mockResolvedValue(bad);
+      expect(await fetchGmailPages(runPage, 'threads', 3, undefined)).toBe(bad);
+    }
+  });
+});

package/tests/page-cursor-contract.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { createTestHarness } from '@chrischall/mcp-utils/test';
+import { BASE_TOOL_REGISTRARS } from '../src/server.js';
+
+// The bug this guards against was a NAME mismatch: the cursor was called `page`
+// while every response reports `nextPageToken`, and MCP inputs are zod objects
+// that silently strip unknown keys — so a client guessing the name from the
+// response got page 1 forever, with no error. Prose that steers a caller back
+// to the deprecated alias re-creates exactly that trap, one tool at a time.
+
+type ToolDef = { name: string; description?: string; inputSchema?: { properties?: Record<string, unknown> } };
+
+async function allTools(): Promise<ToolDef[]> {
+  const harness = await createTestHarness((server) => {
+    for (const register of BASE_TOOL_REGISTRARS) register(server);
+  });
+  const { tools } = await harness.client.listTools();
+  await harness.close();
+  return tools as ToolDef[];
+}
+
+describe('page-cursor contract across every base tool', () => {
+  it('never tells a caller to pass the cursor as the deprecated `page`', async () => {
+    // The alias as its own token: `page` closed immediately, which `pageToken`
+    // can never match. A looser pattern matches the correct name's prefix and
+    // fails on a description that is already right.
+    const offenders = (await allTools())
+      .filter((t) => /`page`|\bas page\b/i.test(t.description ?? ''))
+      .map((t) => t.name);
+    expect(offenders).toEqual([]);
+  });
+
+  it('always offers the `page` alias wherever `pageToken` is accepted', async () => {
+    const mismatched = (await allTools())
+      .filter((t) => {
+        const props = t.inputSchema?.properties ?? {};
+        return 'pageToken' in props && !('page' in props);
+      })
+      .map((t) => t.name);
+    expect(mismatched).toEqual([]);
+  });
+
+  it('names the cursor after the response field wherever one is paginated', async () => {
+    const tools = await allTools();
+    const withCursor = tools.filter((t) => 'pageToken' in (t.inputSchema?.properties ?? {}));
+    // Guards the audit itself: if this ever drops to zero the two tests above
+    // pass vacuously and the contract stops being checked at all.
+    expect(withCursor.length).toBeGreaterThan(0);
+  });
+});

package/tests/pagination.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest';
+import { rawTextResult, errorResult } from '@chrischall/mcp-utils';
+import {
+  stripConsumedPageToken,
+  annotateTruncatedList,
+  truncationWarning,
+  hasMorePages,
+} from '../src/pagination.js';
+
+describe('stripConsumedPageToken', () => {
+  it('removes an exhausted cursor so the key means "another page exists"', () => {
+    expect(stripConsumedPageToken('{"threads":[{"id":"a"}],"nextPageToken":""}'))
+      .toBe('{"threads":[{"id":"a"}]}');
+  });
+
+  it('keeps a live cursor untouched, byte for byte', () => {
+    const live = '{"threads":[{"id":"a"}],"nextPageToken":"tok"}';
+    expect(stripConsumedPageToken(live)).toBe(live);
+  });
+
+  it('preserves --pretty indentation when it has to re-serialize', () => {
+    const pretty = '{\n  "threads": [],\n  "nextPageToken": ""\n}';
+    expect(stripConsumedPageToken(pretty)).toBe('{\n  "threads": []\n}');
+  });
+
+  it('treats a tab indent as two spaces, matching the timestamp seam', () => {
+    expect(stripConsumedPageToken('{\n\t"a": 1,\n\t"nextPageToken": ""\n}'))
+      .toBe('{\n  "a": 1\n}');
+  });
+
+  it('leaves a payload with no cursor field alone', () => {
+    const plain = '{"threads":[]}';
+    expect(stripConsumedPageToken(plain)).toBe(plain);
+  });
+
+  it('only touches the top level — a nested cursor is another resource\'s', () => {
+    const nested = '{"thread":{"nextPageToken":""}}';
+    expect(stripConsumedPageToken(nested)).toBe(nested);
+  });
+
+  it('passes through non-JSON, empty, array and scalar output untouched', () => {
+    for (const text of ['No results', '', '   ', '[{"nextPageToken":""}]', '"a string"', '{not json']) {
+      expect(stripConsumedPageToken(text)).toBe(text);
+    }
+  });
+
+  it('passes through a JSON null without dereferencing it', () => {
+    expect(stripConsumedPageToken('null')).toBe('null');
+  });
+});
+
+describe('truncationWarning', () => {
+  it('names an exact total when one is known', () => {
+    expect(truncationWarning(3, { total: 21 })).toContain('returned 3 of 21 matches');
+  });
+
+  it('says "at least" for a lower bound', () => {
+    expect(truncationWarning(3, { atLeast: 500 })).toContain('returned 3 of at least 500 matches');
+  });
+
+  it('still forbids a negative conclusion when no count is available', () => {
+    const w = truncationWarning(3, {});
+    expect(w).toContain('returned 3 matches and MORE EXIST beyond this page');
+    expect(w).toContain('Do not report an absence of results');
+  });
+});
+
+describe('hasMorePages', () => {
+  it('is true only for a live cursor', () => {
+    expect(hasMorePages({ nextPageToken: 'tok' })).toBe(true);
+    expect(hasMorePages({ nextPageToken: '' })).toBe(false);
+    expect(hasMorePages({})).toBe(false);
+    expect(hasMorePages({ nextPageToken: 7 })).toBe(false);
+  });
+});
+
+describe('annotateTruncatedList', () => {
+  it('adds the block when a live cursor remains', () => {
+    const out = JSON.parse(annotateTruncatedList(
+      rawTextResult('{"events":[{"id":"a"},{"id":"b"}],"nextPageToken":"tok"}'), 'events',
+    ).content[0].text as string);
+    expect(out.truncated).toBe(true);
+    expect(out.returned).toBe(2);
+    expect(out.warning).toContain('INCOMPLETE RESULT SET');
+  });
+
+  it('returns the result untouched when the set is complete', () => {
+    const complete = rawTextResult('{"events":[{"id":"a"}]}');
+    expect(annotateTruncatedList(complete, 'events')).toBe(complete);
+  });
+
+  it('passes errors, non-JSON, missing arrays and empty content through untouched', () => {
+    const err = errorResult('boom');
+    expect(annotateTruncatedList(err, 'events')).toBe(err);
+    const text = rawTextResult('No results');
+    expect(annotateTruncatedList(text, 'events')).toBe(text);
+    const other = rawTextResult('{"somethingElse":1,"nextPageToken":"tok"}');
+    expect(annotateTruncatedList(other, 'events')).toBe(other);
+    const empty = { content: [] } as unknown as Parameters<typeof annotateTruncatedList>[0];
+    expect(annotateTruncatedList(empty, 'events')).toBe(empty);
+  });
+});

package/tests/tools/calendar.test.ts

@@ -379,3 +379,54 @@ describe('gog_calendar_run', () => {
   });
 });
 
+
+describe('gog_calendar_events — pagination (previously absent entirely)', () => {
+  // gog defaults this command to --max=10 and the tool exposed NEITHER max nor
+  // a cursor, so a wide date range silently returned 10 events with a live
+  // token the caller could not use. Measured live: 2025-01-01..2026-08-01 gave
+  // 10 of 12.
+  it('passes --max and --page through to gog', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"events":[]}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_calendar_events', { max: 100, pageToken: 'CURSOR' });
+    const args = vi.mocked(runner.run).mock.calls[0][0] as string[];
+    expect(args).toContain('--max=100');
+    expect(args).toContain('--page=CURSOR');
+  });
+
+  it('accepts the deprecated page alias', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"events":[]}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_calendar_events', { page: 'CURSOR' });
+    expect(vi.mocked(runner.run).mock.calls[0][0]).toContain('--page=CURSOR');
+  });
+
+  it('keeps --all meaning ALL CALENDARS, not all pages', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"events":[]}');
+    const harness = await setupHandlers();
+    await harness.callTool('gog_calendar_events', { all: true });
+    expect(vi.mocked(runner.run).mock.calls[0][0]).toContain('--all');
+  });
+
+  it('marks a capped range truncated, with no fabricated total', async () => {
+    vi.mocked(runner.run).mockResolvedValue(JSON.stringify({
+      events: [{ id: 'e1' }, { id: 'e2' }],
+      nextPageToken: 'MORE',
+    }));
+    const harness = await setupHandlers();
+    const out = JSON.parse((await harness.callTool('gog_calendar_events',
+      { from: '2025-01-01', to: '2026-08-01' })).content[0].text as string);
+    expect(out.truncated).toBe(true);
+    expect(out.returned).toBe(2);
+    expect(out).not.toHaveProperty('totalMatches');
+    expect(out.warning).toContain('INCOMPLETE RESULT SET: returned 2 matches and MORE EXIST');
+  });
+
+  it('leaves a complete range unannotated', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"events":[{"id":"e1"}],"nextPageToken":""}');
+    const harness = await setupHandlers();
+    const out = JSON.parse((await harness.callTool('gog_calendar_events', {})).content[0].text as string);
+    expect(out).not.toHaveProperty('truncated');
+    expect(out).not.toHaveProperty('nextPageToken');
+  });
+});