gogcli-mcp 4.4.0 → 4.5.1

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "4.4.0",
+  "version": "4.5.1",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",
@@ -73,7 +73,7 @@
     },
     {
       "name": "gog_api_call",
-      "description": "Call any Discovery-described Google API method (escape hatch; write opt-in + dry-run)."
+      "description": "Call any Discovery-described Google API method (escape hatch; every write asks the user to confirm; dry-run available)."
     },
     {
       "name": "gog_auth_add",
@@ -149,7 +149,7 @@
     },
     {
       "name": "gog_calendar_delete",
-      "description": "Delete a calendar event"
+      "description": "Delete a calendar event (asks the user to confirm when it has guests or recurs)"
     },
     {
       "name": "gog_calendar_respond",
@@ -209,7 +209,7 @@
     },
     {
       "name": "gog_classroom_submissions_return",
-      "description": "Return a graded submission"
+      "description": "Return a graded submission (asks the user to confirm)"
     },
     {
       "name": "gog_classroom_submissions_turn_in",
@@ -293,7 +293,7 @@
     },
     {
       "name": "gog_drive_delete",
-      "description": "Move a file to trash"
+      "description": "Move a file to trash (a permanent delete asks the user to confirm)"
     },
     {
       "name": "gog_drive_share",
@@ -449,7 +449,7 @@
     },
     {
       "name": "gog_chat_spaces_create",
-      "description": "Create a named Chat space, optionally seeding its membership"
+      "description": "Create a named Chat space, optionally seeding its membership (with members, asks the user to confirm)"
     },
     {
       "name": "gog_chat_threads_list",
@@ -517,7 +517,7 @@
     },
     {
       "name": "gog_appscript_run_function",
-      "description": "Execute a function in a deployed Apps Script project"
+      "description": "Execute a function in a deployed Apps Script project (asks the user to confirm)"
     },
     {
       "name": "gog_appscript_run",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp",
-  "version": "4.4.0",
+  "version": "4.5.1",
   "mcpName": "io.github.chrischall/gogcli-mcp",
   "description": "MCP server wrapping gogcli for Google service access",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -41,12 +41,12 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.4.0",
+    "@chrischall/mcp-utils": "^2.6.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "zod": "^4.6.1"
   },
   "devDependencies": {
-    "@types/node": "^26.6.1",
+    "@types/node": "^26.6.2",
     "@vitest/coverage-v8": "^5.0.1",
     "esbuild": "^0.28.2",
     "typescript": "^7.0.2",

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp"
   },
-  "version": "4.4.0",
+  "version": "4.5.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp",
-      "version": "4.4.0",
+      "version": "4.5.1",
       "transport": {
         "type": "stdio"
       },

package/src/dispatch-confirmation.ts

@@ -1,17 +1,14 @@
 import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import type { CallToolResult, InputRequiredResult, ServerContext } from '@modelcontextprotocol/server';
-import { callerAcceptsFormElicitation, readEnvVar, requireConfirmation, textResult } from '@chrischall/mcp-utils';
-import { z } from 'zod';
 import {
-  confirmTokenTtlSeconds,
-  hashSendPayload,
-  issueConfirmToken,
-  sendConfirmFallbackEnabled,
-  verifyConfirmToken,
-  type ConfirmBinding,
-  type ConfirmTokenError,
-} from './send-confirm-token.js';
+  CONFIRM_TOKEN_INSTRUCTION,
+  confirmationFromEnv,
+  readEnvVar,
+  requireConfirmationWithFallback,
+  type ConfirmSubject,
+} from '@chrischall/mcp-utils';
+import { confirmSpentStore } from './send-confirm-token.js';
 
 // ============================================================================
 // THE DISPATCH RAIL, service-neutral: every tool that reaches another person
@@ -20,9 +17,11 @@ import {
 //
 // Elicitation is primary: the host shows the preview and the model never holds
 // the approval. On a client that declares no elicitation (claude.ai, measured),
-// the call is refused — unless the call site supplies a `DispatchTokenFallback`
-// and the server opted in with GOG_SEND_CONFIRM_FALLBACK=token, in which case
-// the two-phase preview + confirmToken flow (send-confirm-token.ts) runs instead.
+// the call site's `DispatchTokenFallback` runs the two-phase preview +
+// confirmToken flow instead (mcp-utils' confirmationFromEnv +
+// requireConfirmationWithFallback), as the fleet's MCP_CONFIRM_MODE says:
+// ask-user (default), auto, or refuse. A call site with no fallback (the
+// forwarding filter) is always refused on such a client.
 // ============================================================================
 
 // Bound on the body text shown in a confirmation prompt. Enough to read what is
@@ -100,39 +99,23 @@ export const CONFIRM_SEND_INSTRUCTION =
   + 'Then call again with confirmToken.';
 
 /** The same instruction for a dispatch that is not mail (a share, an invitation, a post). */
-export const CONFIRM_ACTION_INSTRUCTION =
-  'Show this preview to the user verbatim and proceed only after they explicitly approve in chat. '
-  + 'Then call again with confirmToken.';
-
-const FALLBACK_HINT = 'Or set GOG_SEND_CONFIRM_FALLBACK=token to enable two-step confirmation.';
+export const CONFIRM_ACTION_INSTRUCTION = CONFIRM_TOKEN_INSTRUCTION;
 
 /** Appended to each gated tool's description. */
 export const CONFIRM_FALLBACK_DESCRIPTION =
-  ' If the client cannot show that prompt (no MCP elicitation, e.g. claude.ai) and the server sets '
-  + 'GOG_SEND_CONFIRM_FALLBACK=token, a two-step flow applies instead: call WITHOUT confirmToken and nothing is '
-  + 'sent or changed — the result has status "confirmation-required", the full preview and a confirmToken. Show that preview '
-  + 'to the user verbatim; only after they explicitly approve it in chat, call again with the SAME arguments plus '
-  + 'confirmToken. The tool re-reads what it would act on and refuses (DRAFT_CHANGED, with a fresh preview and token) '
-  + 'if it changed; TOKEN_EXPIRED / TOKEN_REUSED / TOKEN_INVALID also do nothing.';
+  ' If the client cannot show that prompt (no MCP elicitation, e.g. claude.ai), a two-step flow applies instead: call '
+  + 'WITHOUT confirmToken and nothing is sent or changed — the result has status "confirmation-required", the full '
+  + 'preview and a confirmToken. Follow its instruction (by default: show the preview to the user verbatim and only '
+  + 'after they explicitly approve it in chat, call again with the SAME arguments plus confirmToken). The tool re-reads '
+  + 'what it would act on and refuses (DRAFT_CHANGED, with a fresh preview and token) if it changed; TOKEN_EXPIRED / '
+  + 'TOKEN_REUSED / TOKEN_INVALID also do nothing. A server set to MCP_CONFIRM_MODE=refuse refuses instead.';
 
-export const confirmTokenParam = z.string().optional().describe(
-  'ONLY for the two-step fallback (client without MCP elicitation, server with GOG_SEND_CONFIRM_FALLBACK=token). '
-  + 'The confirmToken from this same tool\'s phase-1 "confirmation-required" response, passed back ONLY after the user '
-  + 'has seen that preview and explicitly approved it in chat — never on the first call, never invented, never '
-  + 'reused. Call again with the same arguments. Ignored when the client supports elicitation.',
-);
+// The schema input every gated tool adds: mcp-utils' own, so its wording and
+// the helper that reads it cannot drift apart.
+export { confirmTokenParam } from '@chrischall/mcp-utils';
 
 /** What the fallback binds a token to — recomputed from a fresh read on every call. */
-export interface TokenSubject {
-  /** The draftId / messageId / fileId / eventId / query the dispatch acts on. */
-  target: string;
-  /** A version that rotates on edit: a draft's messageId, an event's etag. */
-  revision?: string;
-  /** Canonical send payload; its SHA-256 is bound into the token. */
-  payload: unknown;
-  /** The complete preview shown to the user. */
-  preview: Record<string, unknown>;
-}
+export type TokenSubject = ConfirmSubject;
 
 /**
  * Opt-in second rail for a client that cannot be prompted. `subject` is only
@@ -149,73 +132,23 @@ export interface DispatchTokenFallback {
   subject: () => TokenSubject | CallToolResult | Promise<TokenSubject | CallToolResult>;
 }
 
-const TOKEN_ERROR_NOTE: Record<Exclude<ConfirmTokenError, 'DRAFT_CHANGED'>, string> = {
-  TOKEN_EXPIRED: 'Nothing was sent or changed: the confirmToken expired. Call again WITHOUT confirmToken for a fresh preview, '
-    + 'and ask the user to approve it again.',
-  TOKEN_REUSED: 'Nothing was sent or changed by this call: this confirmToken was already used, and one approval acts once. '
-    + 'If doing it again is really intended, call again WITHOUT confirmToken and get a new approval.',
-  TOKEN_INVALID: 'Nothing was sent or changed: this confirmToken was not issued by this server for this tool, account and '
-    + 'target (or the server has restarted since). Call again WITHOUT confirmToken for a fresh preview and approval.',
-};
-
-const DRAFT_CHANGED_NOTE = {
-  'message-id-rotated': 'Nothing was sent or changed: the target was edited since the user approved it (a draft\'s '
-    + 'messageId or an event\'s version rotated), so what would happen is not what they saw.',
-  'payload-changed': 'Nothing was sent or changed: what would happen no longer matches what the user approved.',
-} as const;
-
-function isToolResult(value: TokenSubject | CallToolResult): value is CallToolResult {
-  return Array.isArray((value as CallToolResult).content);
-}
-
-function rejection(data: Record<string, unknown>): CallToolResult {
-  return { ...textResult({ status: 'confirmation-rejected', confirmed: false, dispatched: false, ...data }), isError: true };
-}
-
-async function tokenConfirmation(op: string, fallback: DispatchTokenFallback): Promise<CallToolResult | undefined> {
-  const subject = await fallback.subject();
-  if (isToolResult(subject)) return subject;
-  const binding: ConfirmBinding = {
-    tool: fallback.tool,
-    account: fallback.account ?? readEnvVar('GOG_ACCOUNT') ?? '',
-    target: subject.target,
-    ...(subject.revision === undefined ? {} : { revision: subject.revision }),
-    payloadHash: hashSendPayload(subject.payload),
-  };
-  const phaseOne = () => {
-    const { token, expiresAt } = issueConfirmToken(binding);
-    return {
-      action: op,
-      preview: subject.preview,
-      confirmToken: token,
-      expiresAt,
-      ttlSeconds: confirmTokenTtlSeconds(),
-      instruction: fallback.instruction ?? CONFIRM_ACTION_INSTRUCTION,
-    };
-  };
-  if (!fallback.confirmToken) {
-    return textResult({ status: 'confirmation-required', confirmed: false, dispatched: false, ...phaseOne() });
-  }
-  const verdict = verifyConfirmToken(fallback.confirmToken, binding);
-  if (verdict.ok) return undefined;
-  if (verdict.error === 'DRAFT_CHANGED') {
-    return rejection({
-      error: 'DRAFT_CHANGED',
-      reason: verdict.reason,
-      note: `${DRAFT_CHANGED_NOTE[verdict.reason!]} The current preview and a fresh confirmToken are below.`,
-      ...phaseOne(),
-    });
-  }
-  return rejection({ error: verdict.error, action: op, note: TOKEN_ERROR_NOTE[verdict.error] });
+/**
+ * The refusal an escape hatch (`gog_<service>_run`, `gog_api_call`) gives for an
+ * action it must not perform: the run tool cannot see the guests, the class or
+ * the folder tree a change reaches, so it cannot preview it. `instead` names
+ * the way through — the dedicated tool, or the user doing it in the product.
+ */
+export function refusedInRun(what: string, via: string, does: string, instead: string): string {
+  return `${what} ${does} and is not available through ${via}. ${instead}`;
 }
 
 /**
- * The refusal an escape hatch (`gog_<service>_run`, `gog_api_call`) gives for an
- * action a dedicated tool gates. Without it, the run tool is a way around the
- * rail: the model forwards the same subcommand and nobody is asked (#400).
+ * {@link refusedInRun} for an action a dedicated tool gates. Without it, the
+ * run tool is a way around the rail: the model forwards the same subcommand
+ * and nobody is asked (#400).
  */
 export function gatedElsewhere(what: string, via: string, does: string, tool: string): string {
-  return `${what} ${does} and is not available through ${via}. Use ${tool}, which asks the user to confirm.`;
+  return refusedInRun(what, via, does, `Use ${tool}, which asks the user to confirm.`);
 }
 
 /** True when any forwarded token is one of `words` (kong lets flags precede the command word). */
@@ -223,6 +156,56 @@ export function hasCommandWord(args: readonly string[], words: ReadonlySet<strin
   return args.find((a) => words.has(a.toLowerCase()));
 }
 
+/**
+ * The value of `--name=value` or `--name value` among forwarded args, `''` for
+ * a bare `--name`, undefined when the flag is absent. Kong accepts both
+ * spellings, so a vet that read only one of them would be a way around itself.
+ * Over-inclusive on a bare flag followed by another flag (it reads that flag
+ * as the value): a vet only ever asks whether the flag is present or names a
+ * specific value, and refusing is the safe direction of error.
+ */
+export function flagValue(args: readonly string[], name: string): string | undefined {
+  const flag = `--${name}`;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === flag) return args[i + 1] ?? '';
+    if (a.startsWith(`${flag}=`)) return a.slice(flag.length + 1);
+  }
+  return undefined;
+}
+
+// gog's spellings of `comments create|reply` under drive and docs (`gog schema` 0.41.0).
+const COMMENT_ADD_WORDS = new Set(['create', 'add', 'new']);
+const COMMENT_REPLY_WORDS = new Set(['reply', 'respond']);
+
+/** True when a forwarded flag list asks for `--<flag>` (bare, or =anything but false). */
+export function hasTrueFlag(args: readonly string[], flag: string): boolean {
+  const name = `--${flag}`;
+  return args.some((a) => {
+    const lower = a.toLowerCase();
+    if (lower === name) return true;
+    return lower.startsWith(`${name}=`) && lower.slice(name.length + 1) !== 'false';
+  });
+}
+
+/**
+ * gog_{drive,docs}_run must not post the comments gog_*_comments_add / _reply
+ * would ask about: a comment notifies the file's owner and everyone it +mentions.
+ */
+export function vetCommentsRun(service: 'drive' | 'docs', subcommand: string, args: readonly string[]): string | undefined {
+  if (subcommand.toLowerCase() !== 'comments') return undefined;
+  const reply = hasCommandWord(args, COMMENT_REPLY_WORDS);
+  if (reply) {
+    return gatedElsewhere(`gog ${service} comments ${reply.toLowerCase()}`, `gog_${service}_run`,
+      'notifies the comment thread', `gog_${service}_comments_reply`);
+  }
+  const add = hasCommandWord(args, COMMENT_ADD_WORDS);
+  return add
+    ? gatedElsewhere(`gog ${service} comments ${add.toLowerCase()}`, `gog_${service}_run`,
+      'notifies the file\'s owner and anyone it mentions', `gog_${service}_comments_add`)
+    : undefined;
+}
+
 export interface DispatchConfirmationOptions {
   /** Stable id of the dispatch, echoed in every result (`gmail.send`, `drive.share`, …). */
   action: string;
@@ -242,29 +225,33 @@ export interface DispatchConfirmationOptions {
  * Ask the user before a dispatch. `undefined` means proceed; anything else is
  * the result to return unchanged.
  *
- * Elicitation stays the primary path and is untouched. Only when the caller
- * declares it cannot be prompted AND a `fallback` is supplied AND
- * GOG_SEND_CONFIRM_FALLBACK=token does the two-phase token flow run instead of
- * the refusal; with the env unset, the refusal names that switch.
+ * Elicitation stays the primary path and is untouched. When the caller
+ * declares it cannot be prompted AND a `fallback` is supplied, MCP_CONFIRM_MODE
+ * decides: ask-user (default) or auto run the two-phase token flow; refuse
+ * refuses and names the switch. Without a fallback it is always refused.
  */
 export async function requireDispatchConfirmation(
   ctx: ServerContext,
   options: DispatchConfirmationOptions,
 ): Promise<InputRequiredResult | CallToolResult | undefined> {
   const { action, fallback } = options;
-  if (fallback && callerAcceptsFormElicitation(ctx) === false && sendConfirmFallbackEnabled()) {
-    return tokenConfirmation(action, fallback);
-  }
-  const note = fallback
-    ? [options.unsupportedNote, FALLBACK_HINT].filter(Boolean).join(' ')
-    : options.unsupportedNote;
-  return requireConfirmation(ctx, {
+  const confirmation = {
     action,
     message: options.message,
     details: options.details,
     confirmationLabel: options.confirmationLabel,
-    ...(note ? { unsupportedNote: note } : {}),
-  });
+    ...(options.unsupportedNote ? { unsupportedNote: options.unsupportedNote } : {}),
+  };
+  if (!fallback) return requireConfirmationWithFallback(ctx, confirmation);
+  return requireConfirmationWithFallback(ctx, confirmationFromEnv({
+    ...confirmation,
+    tool: fallback.tool,
+    account: fallback.account ?? readEnvVar('GOG_ACCOUNT') ?? '',
+    confirmToken: fallback.confirmToken,
+    subject: fallback.subject,
+    instruction: fallback.instruction ?? CONFIRM_ACTION_INSTRUCTION,
+    spent: confirmSpentStore(),
+  }));
 }
 
 // The single place a CallToolResult's text is pulled back out, for the tools

package/src/gmail-dispatch-guard.ts

@@ -32,11 +32,11 @@ export type { AttachmentDetail, DispatchTokenFallback, TokenSubject } from './di
 // user's accepted confirmation dispatches. The confirmation is never a tool
 // argument, so a model cannot bypass the user by setting a boolean itself.
 //
-// The one exception is OPT-IN: with GOG_SEND_CONFIRM_FALLBACK=token, a client
-// that cannot be prompted gets a two-phase preview + confirmToken instead of a
-// refusal (`DispatchTokenFallback`, send-confirm-token.ts). There the approval
-// IS a tool argument; see that file for exactly what the token does and does
-// not guarantee.
+// The one exception: a client that cannot be prompted gets a two-phase preview
+// + confirmToken instead of a refusal (`DispatchTokenFallback`; mcp-utils'
+// confirmationFromEnv), unless the server sets MCP_CONFIRM_MODE=refuse. There
+// the approval IS a tool argument; see mcp-utils' confirm-token module for
+// exactly what the token does and does not guarantee.
 //
 // A CLIENT THAT CANNOT SHOW THAT PROMPT gets a sentence rather than a prompt
 // it will refuse to deliver (`unsupportedNote`, mcp-utils `requireConfirmation`).
@@ -123,10 +123,10 @@ const UNSUPPORTED_NOTE: Partial<Record<GmailDispatchOp, string>> = {
 /**
  * Apply the shared stateless confirmation flow with Gmail-specific copy.
  *
- * Elicitation stays the primary path and is untouched. Only when the caller
- * declares it cannot be prompted AND a `fallback` is supplied AND
- * GOG_SEND_CONFIRM_FALLBACK=token does the two-phase token flow run instead of
- * the refusal; with the env unset, the refusal names that switch.
+ * Elicitation stays the primary path and is untouched. When the caller
+ * declares it cannot be prompted AND a `fallback` is supplied, MCP_CONFIRM_MODE
+ * decides: ask-user (default) or auto run the two-phase token flow; refuse
+ * refuses and names the switch.
  */
 export async function requireGmailDispatchConfirmation(
   ctx: ServerContext,
@@ -196,25 +196,32 @@ function trustedDomains(account: string | undefined): Set<string> {
 }
 
 // A distinguishable, greppable event for every mail dispatch — recipient
-// count plus whichever recipients fall outside the trusted-domain list — so an
-// unexpected external send (outside counsel, a wrong-number alias) can be
-// caught after the fact even if the confirmation step above is somehow
-// bypassed by a future caller. stdout is the JSON-RPC channel, so this goes to
-// stderr like every other diagnostic in this repo.
+// count plus the DOMAINS of whichever recipients fall outside the trusted list
+// — so an unexpected external send (outside counsel, a wrong-number alias) can
+// be caught after the fact even if the confirmation step above is somehow
+// bypassed by a future caller. Never the addresses (PRIV-1, fleet-audit
+// #1012): on mcp-host this line is host log data the user never sees or
+// controls, and a third party's address is their identity where their domain
+// is the audit signal. stdout is the JSON-RPC channel, so this goes to stderr
+// like every other diagnostic in this repo.
 export function logGmailDispatch(tool: string, recipients: string[], account?: string): void {
   const domains = trustedDomains(account);
-  const externalRecipients = recipients.filter((recipient) => {
+  const externalDomains = new Set<string>();
+  let externalRecipientCount = 0;
+  for (const recipient of recipients) {
     const at = recipient.indexOf('@');
-    const domain = at > -1 ? recipient.slice(at + 1) : '';
-    return !domain || !domains.has(domain);
-  });
+    const domain = at > -1 ? recipient.slice(at + 1).toLowerCase() : '';
+    if (domain && domains.has(domain)) continue;
+    externalRecipientCount += 1;
+    externalDomains.add(domain || '(no domain)');
+  }
   const event = {
     event: 'gmail_dispatch',
     tool,
     recipientCount: recipients.length,
-    externalRecipientCount: externalRecipients.length,
-    hasExternalRecipients: externalRecipients.length > 0,
-    externalRecipients,
+    externalRecipientCount,
+    hasExternalRecipients: externalRecipientCount > 0,
+    externalDomains: [...externalDomains].sort(),
     timestamp: new Date().toISOString(),
   };
   process.stderr.write(`${JSON.stringify(event)}\n`);

package/src/lib.ts

@@ -19,7 +19,7 @@ export {
 // The reply/reply-all schema and flag builder live in the base package so the
 // gmail sub-package's draft-side twins reuse ONE definition — registering the
 // same tool name from both registrar lists would be a duplicate-name error.
-export { replySchema, appendReplyFlags } from './tools/gmail.js';
+export { replySchema, appendReplyFlags, parseMetadataHeaders } from './tools/gmail.js';
 export type { ReplyFlags } from './tools/gmail.js';
 // The gmail confirmation gate — gog_gmail_reply/send/forward/autoreply are
 // the only tools that dispatch mail irreversibly on the first call. The
@@ -40,7 +40,11 @@ export {
 } from './gmail-dispatch-guard.js';
 // The service-neutral rail for every other tool that reaches another person.
 export { requireDispatchConfirmation } from './dispatch-confirmation.js';
-export { readCourse } from './tools/classroom.js';
+export { readCourse, readCoursework, readClassroomWork, studentLabel } from './tools/classroom.js';
+export type { ClassroomWork, ClassroomWorkKind } from './tools/classroom.js';
+// Pure parsers a sub-package's confirmation prompt reuses on its own reads.
+export { eventSnapshot } from './tools/calendar.js';
+export { commentMentions, commentSnapshot, shareTargetMeta } from './tools/drive.js';
 export type { AttachmentDetail, DispatchTokenFallback, TokenSubject } from './gmail-dispatch-guard.js';
 export { run, runBinary, isGogFileArg, MIN_GOG_VERSION } from './runner.js';
 // Sub-package tools that read gog JSON through bare `run()` (rather than the