gogcli-mcp 2.24.0 → 2.26.0

package/src/runner.ts

@@ -18,12 +18,43 @@ export type Spawner = (
 export interface GogFileArg {
   /** Discriminant separating this from a plain argv string. */
   kind: 'file';
-  /** Flag NAME without leading dashes, e.g. 'body-html-file'. */
+  /**
+   * Flag NAME without leading dashes, e.g. 'body-html-file'. The materialized
+   * path is passed as `--<flag>=<path>`, EXCEPT when `positional` is set, where
+   * this names the temp file's parent directory and nothing else.
+   */
   flag: string;
-  /** The large payload, verbatim. */
+  /**
+   * The payload. Text verbatim when `encoding` is 'utf8' (the default); the
+   * base64 spelling of the bytes when it is 'base64'.
+   */
   contents: string;
   /** Temp-file extension without the dot, e.g. 'html'. Defaults to 'txt'. */
   ext?: string;
+  /**
+   * How to interpret `contents` when writing it. 'utf8' (default) preserves the
+   * existing text-payload behaviour exactly; 'base64' decodes first, which is
+   * what lets a caller hand over a PNG or a PDF without a shared filesystem.
+   */
+  encoding?: 'utf8' | 'base64';
+  /**
+   * Exact basename for the temp file, overriding the `<flag>.<ext>` default.
+   *
+   * Load-bearing for attachments: gog reads the MIME part's filename off the
+   * path it is given, so a file materialized as `attach.txt` would arrive in the
+   * recipient's mailbox named `attach.txt` no matter what the caller called it.
+   * Callers MUST pass an already-sanitized single path segment.
+   */
+  filename?: string;
+  /**
+   * Emit the materialized path as a BARE argv element instead of `--flag=path`.
+   *
+   * For subcommands taking the file as a positional argument — `gog drive
+   * upload <localPath>` is the only one today. Argument ORDER is preserved by
+   * every executor, so a positional file arg lands exactly where it sat in the
+   * caller's array.
+   */
+  positional?: boolean;
 }
 
 export type GogArg = string | GogFileArg;
@@ -157,6 +188,25 @@ export interface RunOptions {
   // carries no token, so stripping only real token shapes keeps it intact while
   // still catching any token that unexpectedly appears.
   redactMode?: 'full' | 'tokens';
+  // JSON string fields whose values are OPAQUE binary payloads this wrapper
+  // asked for by name — `contentBase64` from `gog gmail attachment --inline`
+  // being the only one today. Their values are lifted out before redaction runs
+  // and put back verbatim afterwards.
+  //
+  // Redaction exists to catch a credential that leaked into PROSE. A base64
+  // blob is not prose: it is uniformly-distributed bytes over a 64-character
+  // alphabet, so given enough of them it will eventually contain the literal
+  // spelling of any short secret shape by chance alone — `1//` at ~30% per
+  // attachment (see TOKEN_LEFT_BOUNDARY), and `AIza…` at ~0.2% even after that
+  // anchor lands. Boundary-anchoring the patterns fixes the common case;
+  // exempting the field fixes the CLASS, and keeps a future pattern added to
+  // mcp-utils from silently re-breaking attachments.
+  //
+  // Deliberately narrow in three ways: it is opt-in per call, only the named
+  // key is exempt, and only a value that is ENTIRELY base64 alphabet qualifies
+  // (see OPAQUE_FIELD_VALUE) — so a field carrying real prose, which is where a
+  // real leaked token would live, still gets redacted normally.
+  opaqueFields?: readonly string[];
 }
 
 const TIMEOUT_MS = 30_000;
@@ -167,7 +217,7 @@ const TIMEOUT_MS = 30_000;
 // so the requirement change is surfaced in the release notes (see
 // .github/release.yml). This is the single source of truth for the required
 // version; keep the README/CLAUDE.md mention in sync.
-export const MIN_GOG_VERSION = '0.37.0';
+export const MIN_GOG_VERSION = '0.38.1';
 
 // Interpret the GOG_READONLY kill-switch. `readEnvVar` already treats blank
 // values, 'undefined'/'null' sentinels, and unresolved .mcpb placeholders
@@ -197,6 +247,43 @@ function sanitizedEnv(): NodeJS.ProcessEnv {
   return result;
 }
 
+// The LEFT boundary every Google token shape below is anchored on, and the
+// reason this file has a regression test named after a PNG.
+//
+// `1//` is three characters drawn entirely from the standard base64 alphabet,
+// so the unanchored pattern `1\/\/[A-Za-z0-9._-]+` matches inside ANY base64
+// blob that happens to contain that run — and then eats forward to the next
+// `+` or `/`, deleting a slab out of the middle of the payload. `gog gmail
+// attachment --inline` returns the attachment bytes as base64 in its JSON, that
+// JSON goes through `run()`, and `run()` redacts. The result was a mangled
+// `contentBase64` and an MCP protocol error at the client ("Invalid Base64
+// string") on roughly a THIRD of all attachments — measured, not estimated: a
+// 72 KiB file is ~97k base64 chars and the expected number of `1//` runs is
+// n/64³ ≈ 0.37, i.e. P(corrupt) ≈ 30%.
+//
+// That coin-flip is what made the bug look like it was about FILENAMES: it
+// correlates with nothing a reader can see, so two attachments in one thread
+// differing only in name would land on opposite sides of it. It is content, not
+// name — the runner has always spawned with an argv array and never a shell, so
+// spaces in a filename were never able to split anything.
+//
+// A real token never appears WELDED to base64 text: it is delimited by a quote,
+// whitespace, `=`, `:`, `&`, a bracket, or the start of the string. So requiring
+// a non-base64 character (or nothing) to its left keeps every genuine detection
+// and drops the mid-blob false positives, which by construction are always
+// preceded by another base64 character.
+//
+// The class is EXACTLY the standard base64 alphabet, and no wider. Every
+// character omitted from it is a delimiter a real token is found after, so each
+// one added would silently cost a detection: `=` in particular would stop
+// `refresh_token=1//0e…` and `access_token=ya29.…` — the form-encoded spelling,
+// which the shared redactor's query-param rule does not catch without a
+// preceding `?`/`&` — from being redacted at all. `=` is also unnecessary here,
+// since base64 padding is terminal and can never precede a mid-blob `1//`.
+// Likewise `.`, `_` and `-`: none occurs in standard base64, and `1//` cannot
+// occur in base64url (which has no `/`), so neither alphabet needs them.
+const TOKEN_LEFT_BOUNDARY = '(?<![A-Za-z0-9+/])';
+
 // Redact bearer/refresh-token patterns from error text before surfacing
 // it back to the MCP client. If gog ever emits a token in stderr (e.g.
 // from a verbose log mode), this prevents it from leaking to the model.
@@ -204,8 +291,8 @@ function sanitizedEnv(): NodeJS.ProcessEnv {
 // cookies, well-known key shapes (incl. Google AIza… API keys), and secret
 // query params — but not Google's OAuth2 token shapes, so those stay here.
 const GOOGLE_TOKEN_PATTERNS: RegExp[] = [
-  /ya29\.[A-Za-z0-9._\-]+/g,           // OAuth2 access tokens
-  /1\/\/[A-Za-z0-9._\-]+/g,            // OAuth2 refresh tokens
+  new RegExp(`${TOKEN_LEFT_BOUNDARY}ya29\\.[A-Za-z0-9._\\-]+`, 'g'),  // OAuth2 access tokens
+  new RegExp(`${TOKEN_LEFT_BOUNDARY}1//[A-Za-z0-9._\\-]+`, 'g'),      // OAuth2 refresh tokens
 ];
 // Strip only Google's OAuth2 token shapes. Precise enough to leave an OAuth
 // consent URL (client_id, scope names, state, code_challenge) untouched.
@@ -220,6 +307,55 @@ export function redactSecrets(text: string): string {
   return redactGoogleTokens(redactSharedSecrets(text));
 }
 
+// A JSON string value that is ENTIRELY standard/URL-safe base64 (plus padding),
+// and long enough to be a payload rather than a flag. Anything else — a path, a
+// MIME type, a sentence, an OAuth token sitting in prose — fails this and is
+// redacted normally, which is what keeps the exemption from becoming a hole.
+const OPAQUE_FIELD_VALUE = '[A-Za-z0-9+/_-]{16,}={0,2}';
+
+// Placeholder standing in for a lifted value while redaction runs.
+//
+// NUL-delimited because NUL cannot occur in gog's output: stdout is decoded as
+// UTF-8 text and JSON escapes it as a backslash-u escape, so the placeholder can never
+// collide with real content the way a printable sentinel could. The body
+// contains no character any redaction pattern keys on, and the index keeps each
+// one unique so two blobs can never be swapped on restore.
+const opaquePlaceholder = (i: number): string => `\u0000gogOpaque${i}\u0000`;
+
+/**
+ * Redact `text` while leaving the values of `fields` untouched.
+ *
+ * Lift each `"field":"<base64>"` value out to a placeholder, redact what
+ * remains, then put the values back. Splicing rather than parsing keeps this on
+ * the raw string: `run()` returns text, gog's output is not always JSON, and a
+ * parse/re-serialize round trip would rewrite key order and number formatting
+ * in output the caller may be matching on.
+ */
+export function redactPreservingOpaqueFields(
+  text: string,
+  fields: readonly string[],
+  redact: (input: string) => string,
+): string {
+  const lifted: string[] = [];
+  let staged = text;
+  for (const field of fields) {
+    // The key is escaped because it reaches a RegExp; the value class is fixed
+    // above, so a base64 payload can never terminate its own string early.
+    const escaped = field.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`("${escaped}"\\s*:\\s*")(${OPAQUE_FIELD_VALUE})(")`, 'g');
+    staged = staged.replace(re, (_m, open: string, value: string, close: string) => {
+      lifted.push(value);
+      return `${open}${opaquePlaceholder(lifted.length - 1)}${close}`;
+    });
+  }
+  if (lifted.length === 0) return redact(text);
+  let redacted = redact(staged);
+  lifted.forEach((value, i) => {
+    redacted = redacted.split(opaquePlaceholder(i)).join(value);
+  });
+  return redacted;
+}
+
 // MCP desktop clients often spawn servers with a stripped PATH that excludes
 // Homebrew, user-local, and Go's default install dirs — so even when gog is
 // installed, the spawned server can't find it. Augment the child's PATH with
@@ -266,7 +402,7 @@ async function spawnWithTempFiles(
   args: GogArg[],
   opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean },
 ): Promise<string> {
-  const { mkdtemp, writeFile, rm } = await import('node:fs/promises');
+  const { mkdtemp, mkdir, writeFile, rm } = await import('node:fs/promises');
   const { tmpdir } = await import('node:os');
 
   // mkdtemp creates the directory with mode 0700 (owner-only) on POSIX, so the
@@ -275,17 +411,30 @@ async function spawnWithTempFiles(
   const dir = await mkdtemp(join(tmpdir(), 'gogcli-mcp-'));
   try {
     const argv: string[] = [];
+    let seq = 0;
     for (const arg of args) {
       if (!isGogFileArg(arg)) {
         argv.push(arg);
         continue;
       }
-      // Name the file after the flag: one command can carry two payloads
-      // (e.g. --body-file and --signature-file, both .txt), and a fixed
-      // basename would have the second silently clobber the first.
-      const path = join(dir, `${arg.flag}.${arg.ext ?? 'txt'}`);
-      await writeFile(path, arg.contents, { encoding: 'utf8', mode: 0o600 });
-      argv.push(`--${arg.flag}=${path}`);
+      // Each payload gets its own numbered SUBDIRECTORY, so the basename is free
+      // to be whatever the caller needs without any risk of one payload
+      // clobbering another. That matters twice over now: `--attach` is
+      // repeatable, so a single send can carry several files whose real names
+      // are chosen by the caller and may well collide (two `chart.png`s from
+      // different folders), and an attachment's basename is what the recipient
+      // sees, so it cannot be uniquified by mangling it.
+      const sub = join(dir, String(seq));
+      seq += 1;
+      await mkdir(sub, { recursive: true, mode: 0o700 });
+      const path = join(sub, arg.filename ?? `${arg.flag}.${arg.ext ?? 'txt'}`);
+      // 'base64' decodes to the real bytes; 'utf8' writes the string as-is,
+      // which is the pre-existing behaviour for every text payload.
+      const data = arg.encoding === 'base64'
+        ? Buffer.from(arg.contents, 'base64')
+        : Buffer.from(arg.contents, 'utf8');
+      await writeFile(path, data, { mode: 0o600 });
+      argv.push(arg.positional ? path : `--${arg.flag}=${path}`);
     }
     return await spawnGog(argv, opts);
   } finally {
@@ -406,8 +555,14 @@ function assembleArgs(
 }
 
 export async function run(args: GogArg[], options: RunOptions = {}): Promise<string> {
-  const { account, spawner, interactive = false, timeout, readonly = false, redactMode = 'full' } = options;
-  const redact = redactMode === 'tokens' ? redactGoogleTokens : redactSecrets;
+  const { account, spawner, interactive = false, timeout, readonly = false, redactMode = 'full', opaqueFields } = options;
+  const base = redactMode === 'tokens' ? redactGoogleTokens : redactSecrets;
+  // Only OUTPUT carries opaque payloads. An error message is prose by
+  // definition, so it always takes the plain redactor — exempting a field there
+  // would be exempting exactly the text a leaked token would appear in.
+  const redact = opaqueFields?.length
+    ? (text: string): string => redactPreservingOpaqueFields(text, opaqueFields, base)
+    : base;
 
   const fullArgs = assembleArgs(args, { account, interactive, readonly });
 
@@ -433,7 +588,7 @@ export async function run(args: GogArg[], options: RunOptions = {}): Promise<str
     // A thrown non-Error would make `.message` undefined and redact() blow up
     // with a TypeError, masking the real failure. Same instanceof guard the
     // codebase already uses in errorText() (tools/utils.ts).
-    const message = redact(err instanceof Error ? err.message : String(err));
+    const message = base(err instanceof Error ? err.message : String(err));
     // Redaction must not cost the error its TYPE. `RunnerTransportError` is the
     // structural claim "this failure was ours, not Google's"; flattening it to a
     // bare Error here would put diagnose() straight back to guessing from prose,

package/src/server.ts

@@ -1,7 +1,9 @@
 import type { ToolRegistrar } from '@chrischall/mcp-utils';
 import { registerApiTools } from './tools/api.js';
+import { registerAppScriptTools } from './tools/appscript.js';
 import { registerAuthTools, authToolsFor } from './tools/auth.js';
 import { registerCalendarTools } from './tools/calendar.js';
+import { registerChatTools } from './tools/chat.js';
 import { registerClassroomTools } from './tools/classroom.js';
 import { registerContactsTools } from './tools/contacts.js';
 import { registerDocsTools } from './tools/docs.js';
@@ -23,8 +25,10 @@ export const VERSION = typeof GOGCLI_VERSION !== 'undefined' ? GOGCLI_VERSION :
 // re-exported below.
 export const BASE_TOOL_REGISTRARS: ToolRegistrar[] = [
   registerApiTools,
+  registerAppScriptTools,
   registerAuthTools,
   registerCalendarTools,
+  registerChatTools,
   registerClassroomTools,
   registerContactsTools,
   registerDocsTools,
@@ -37,9 +41,11 @@ export const BASE_TOOL_REGISTRARS: ToolRegistrar[] = [
 
 export {
   registerApiTools,
+  registerAppScriptTools,
   registerAuthTools,
   authToolsFor,
   registerCalendarTools,
+  registerChatTools,
   registerClassroomTools,
   registerContactsTools,
   registerDocsTools,

package/src/tools/appscript.ts

@@ -0,0 +1,173 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import {
+  accountParam,
+  runOrDiagnose,
+  registerRunTool,
+  paginationParams,
+  pushPaginationFlags,
+} from './utils.js';
+
+// Google Apps Script (gog >= 0.38.0 for pull/deployments/versions).
+//
+// This wraps the READ and RUN halves of the Apps Script API. gog has no push,
+// so nothing here can change a project's code: `create` makes an empty project
+// and `pull`/`content` only copy code outwards. The one tool with real reach is
+// gog_appscript_run_function, which executes somebody's script under this
+// account's authority — see its description.
+//
+// The Apps Script API is OFF by default on a Google Cloud project, so the first
+// call on a fresh OAuth client fails with "Apps Script API is not enabled for
+// this OAuth project" and a console URL. That error is gog's, it names the
+// exact project, and it is not a scope failure — do not answer it with a
+// re-auth.
+export function registerAppScriptTools(server: McpServer): void {
+  const scriptIdParam = z.string().describe(
+    'Apps Script project ID — the long ID in script.google.com/…/projects/<scriptId>/…, NOT the Drive file ID of a '
+    + 'container document',
+  );
+  const apiEnableNote =
+    ' Needs the Apps Script API enabled on the OAuth client\'s Google Cloud project; if it is not, gog says so and prints '
+    + 'the console URL to enable it. That is a project setting, not a missing scope — re-authorizing will not fix it.';
+
+  server.registerTool('gog_appscript_get', {
+    description:
+      'Get an Apps Script project\'s metadata: title, creator, create/update times, and the parent Drive file when the '
+      + 'project is bound to a Sheet, Doc or Form. Use gog_appscript_content to read the actual code.' + apiEnableNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      scriptId: scriptIdParam,
+      account: accountParam,
+    },
+  }, async ({ scriptId, account }) => {
+    return runOrDiagnose(['appscript', 'get', scriptId], { account });
+  });
+
+  server.registerTool('gog_appscript_content', {
+    description:
+      'Read a project\'s source — every .gs file and its appsscript.json manifest — INLINE in the response. This is the '
+      + 'tool to reach for when the question is "what does this script do"; it needs no filesystem, so it works the same '
+      + 'on a hosted deployment as it does locally, unlike gog_appscript_pull.' + apiEnableNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      scriptId: scriptIdParam,
+      account: accountParam,
+    },
+  }, async ({ scriptId, account }) => {
+    return runOrDiagnose(['appscript', 'content', scriptId], { account });
+  });
+
+  server.registerTool('gog_appscript_pull', {
+    description:
+      'Write a project\'s files into a local directory, for editing a script as ordinary files. '
+      + 'THE DIRECTORY IS RESOLVED WHERE GOG RUNS, which is the caller\'s own machine only on a local (stdio) deployment: '
+      + 'on the hosted connector, or any GOG_RUNNER_URL backend, the files land on that server where the caller cannot '
+      + 'reach them. Use gog_appscript_content there instead — it returns the same source in the response. Existing files '
+      + 'are left alone unless overwrite is set. Read-only as far as Google is concerned: nothing is pushed back.'
+      + apiEnableNote,
+    inputSchema: {
+      scriptId: scriptIdParam,
+      dir: z.string().describe('Destination directory, resolved on the machine where gog runs'),
+      overwrite: z.boolean().optional().describe('Overwrite files that already exist in dir'),
+      account: accountParam,
+    },
+  }, async ({ scriptId, dir, overwrite, account }) => {
+    const args = ['appscript', 'pull', scriptId, dir];
+    if (overwrite) args.push('--overwrite');
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_appscript_create', {
+    description:
+      'Create a new, empty Apps Script project. Pass parentId to bind it to a Drive file (a Sheet, Doc or Form), which is '
+      + 'what makes the script a container-bound script with access to that document; omit it for a standalone project. '
+      + 'gog cannot upload code, so the project starts empty either way.' + apiEnableNote,
+    inputSchema: {
+      title: z.string().describe('Project title'),
+      parentId: z.string().optional().describe('Drive file ID to bind the project to (Sheet, Doc or Form). Omit for a standalone project.'),
+      account: accountParam,
+    },
+  }, async ({ title, parentId, account }) => {
+    const args = ['appscript', 'create', `--title=${title}`];
+    if (parentId) args.push(`--parent-id=${parentId}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_appscript_deployments', {
+    description:
+      'List a project\'s deployments — the published web apps, add-ons and API executables, each pinned to a version. A '
+      + 'deployment ID from here is what gog_appscript_run_function needs when a script is not running in dev mode.'
+      + apiEnableNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      scriptId: scriptIdParam,
+      ...paginationParams,
+      account: accountParam,
+    },
+  }, async ({ scriptId, max, pageToken, page, all, account }) => {
+    const args = ['appscript', 'deployments', scriptId];
+    pushPaginationFlags(args, { max, pageToken, page, all });
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_appscript_versions', {
+    description:
+      'List a project\'s saved versions — the immutable snapshots deployments point at, with their numbers and '
+      + 'descriptions. Useful for answering "what is actually deployed" next to gog_appscript_deployments.' + apiEnableNote,
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      scriptId: scriptIdParam,
+      ...paginationParams,
+      account: accountParam,
+    },
+  }, async ({ scriptId, max, pageToken, page, all, account }) => {
+    const args = ['appscript', 'versions', scriptId];
+    pushPaginationFlags(args, { max, pageToken, page, all });
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_appscript_run_function', {
+    description:
+      'Execute a function in a deployed Apps Script project. TREAT THIS AS ARBITRARY CODE EXECUTION: the script runs with '
+      + 'this Google account\'s authority and can send mail, edit Drive files or call external services, and the wrapper '
+      + 'cannot tell a read from a write — read the code with gog_appscript_content first if you did not write it. '
+      + 'Requires the project to be deployed as an API executable and to share the OAuth client with the calling '
+      + 'credentials, otherwise Google refuses regardless of scopes. devMode runs the latest saved code instead of the '
+      + 'deployed version, and only works if the account owns the script. '
+      + 'This is NOT the escape hatch — gog_appscript_run is that.' + apiEnableNote,
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      scriptId: scriptIdParam,
+      functionName: z.string().describe('Name of the function to call, e.g. "doWork"'),
+      params: z.string().optional().describe('Function parameters as a JSON ARRAY of positional arguments, e.g. \'["a", 1]\' — not an object'),
+      devMode: z.boolean().optional().describe('Run the latest saved code rather than the deployed version (owner only)'),
+      account: accountParam,
+    },
+  }, async ({ scriptId, functionName, params, devMode, account }) => {
+    // gog passes --params through to the API as-is, so a malformed value comes
+    // back as a Google error about the request body rather than about the
+    // argument the caller actually got wrong. Checking the shape here is what
+    // turns "invalid argument" into "params must be a JSON array".
+    if (params !== undefined) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(params);
+      } catch {
+        throw new Error(`params must be a JSON array of positional arguments, e.g. '["a", 1]'. Received: ${params}`);
+      }
+      if (!Array.isArray(parsed)) {
+        throw new Error(`params must be a JSON ARRAY of positional arguments, e.g. '["a", 1]' — Apps Script takes positional arguments, not named ones. Received: ${params}`);
+      }
+    }
+    const args = ['appscript', 'run', scriptId, functionName];
+    if (params !== undefined) args.push(`--params=${params}`);
+    if (devMode) args.push('--dev-mode');
+    return runOrDiagnose(args, { account });
+  });
+
+  registerRunTool(server, {
+    service: 'appscript',
+    examples: '"get", "content", "deployments"',
+    note: 'To execute a function, use gog_appscript_run_function — this tool is the generic escape hatch.',
+  });
+}

package/src/tools/calendar.ts

@@ -3,6 +3,56 @@ import { z } from 'zod';
 import { accountParam, runOrDiagnose, registerRunTool, pageTokenParam, pageAliasParam, resolvePageToken } from './utils.js';
 import { annotateTruncatedList } from '../pagination.js';
 
+// Reminder params, shared by create and update (gog >= 0.38.0 for
+// --no-reminders). An event's reminders are one of THREE states, and the two
+// params below have to spell all three because gog does:
+//
+//   reminders: ['popup:30m']  →  --reminder=popup:30m   custom overrides
+//   noReminders: true         →  --no-reminders         no reminder at all
+//   reminders: []             →  --reminder=            back to the calendar's defaults
+//
+// That last one is the subtle one and it only means anything on update: gog
+// reads an EMPTY --reminder as "clear the overrides and use the calendar
+// default" (openclaw/gogcli#1016), which is a different outcome from omitting
+// the flag (leave whatever the event already has) and from --no-reminders
+// (override the calendar with silence). An empty array is how a JSON caller
+// says it, since there is no way to send a bare flag with no value.
+const reminderParams = {
+  reminders: z.array(z.string()).max(5).optional().describe(
+    'Reminders as method:duration, e.g. ["popup:30m", "email:1d"]. Method is popup or email; duration accepts m/h/d '
+    + '(max 40320 minutes = 4 weeks). Google allows at most 5. These REPLACE the event\'s reminders — on update, pass an '
+    + 'EMPTY array to drop custom reminders and go back to the calendar\'s defaults. Cannot be combined with noReminders.',
+  ),
+  noReminders: z.boolean().optional().describe(
+    'Give the event no reminders at all, overriding the calendar\'s defaults. Different from an empty reminders array, '
+    + 'which RESTORES those defaults. Cannot be combined with reminders.',
+  ),
+};
+
+// The one place the three states become argv. Kept together so create and
+// update cannot drift apart on the empty-array case.
+function pushReminderFlags(
+  args: string[],
+  p: { reminders?: string[]; noReminders?: boolean },
+): void {
+  if (p.noReminders) {
+    // gog's own flags are `xor:"reminders"`, so it would reject this too — but
+    // only after a spawn, and with kong's wording rather than the tool's.
+    if (p.reminders !== undefined) {
+      throw new Error('reminders and noReminders are mutually exclusive: pass reminders to set custom ones, noReminders for none, or an empty reminders array to restore the calendar defaults.');
+    }
+    args.push('--no-reminders');
+    return;
+  }
+  if (p.reminders === undefined) return;
+  // Empty array → one empty --reminder, which is gog's "restore defaults".
+  if (p.reminders.length === 0) {
+    args.push('--reminder=');
+    return;
+  }
+  for (const reminder of p.reminders) args.push(`--reminder=${reminder}`);
+}
+
 export function registerCalendarTools(server: McpServer): void {
   server.registerTool('gog_calendar_events', {
     description: 'List calendar events. Describe the window ONE way and one way only (gog >= 0.36.0 rejects the rest as ambiguous rather than silently discarding a flag): '
@@ -80,9 +130,10 @@ export function registerCalendarTools(server: McpServer): void {
       allDay: z.boolean().optional().describe('All-day event (use date-only in from/to)'),
       timezone: z.string().optional().describe('IANA timezone metadata applied to from/to (e.g. America/New_York). Sets both start and end timezone unless start/end timezone are overridden.'),
       withZoom: z.boolean().optional().describe('Create a Zoom video conference for this event (requires Zoom S2S OAuth setup)'),
+      ...reminderParams,
       account: accountParam,
     },
-  }, async ({ calendarId, summary, from, to, description, location, attendees, allDay, timezone, withZoom, account }) => {
+  }, async ({ calendarId, summary, from, to, description, location, attendees, allDay, timezone, withZoom, reminders, noReminders, account }) => {
     const args = ['calendar', 'create', calendarId, `--summary=${summary}`, `--from=${from}`, `--to=${to}`];
     if (description) args.push(`--description=${description}`);
     if (location) args.push(`--location=${location}`);
@@ -90,6 +141,7 @@ export function registerCalendarTools(server: McpServer): void {
     if (allDay) args.push('--all-day');
     if (timezone) args.push(`--timezone=${timezone}`);
     if (withZoom) args.push('--with-zoom');
+    pushReminderFlags(args, { reminders, noReminders });
     return runOrDiagnose(args, { account });
   });
 
@@ -111,9 +163,10 @@ export function registerCalendarTools(server: McpServer): void {
       regenerateZoom: z.boolean().optional().describe('Replace the event\'s existing Zoom video conference'),
       removeZoom: z.boolean().optional().describe('Remove the event\'s Zoom video conference'),
       removeMeet: z.boolean().optional().describe('Remove the event\'s Google Meet video conference (clears conference data only)'),
+      ...reminderParams,
       account: accountParam,
     },
-  }, async ({ calendarId, eventId, summary, from, to, description, location, attendees, addAttendees, attachments, withZoom, regenerateZoom, removeZoom, removeMeet, account }) => {
+  }, async ({ calendarId, eventId, summary, from, to, description, location, attendees, addAttendees, attachments, withZoom, regenerateZoom, removeZoom, removeMeet, reminders, noReminders, account }) => {
     const args = ['calendar', 'update', calendarId, eventId];
     if (summary !== undefined) args.push(`--summary=${summary}`);
     if (from !== undefined) args.push(`--from=${from}`);
@@ -127,6 +180,7 @@ export function registerCalendarTools(server: McpServer): void {
     if (regenerateZoom) args.push('--regenerate-zoom');
     if (removeZoom) args.push('--remove-zoom');
     if (removeMeet) args.push('--remove-meet');
+    pushReminderFlags(args, { reminders, noReminders });
     return runOrDiagnose(args, { account });
   });