gogcli-mcp 4.3.0 → 4.5.0

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "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,7 +41,7 @@
     "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"
   },

package/server.json

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

package/src/dispatch-confirmation.ts

@@ -0,0 +1,204 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import type { CallToolResult, InputRequiredResult, ServerContext } from '@modelcontextprotocol/server';
+import {
+  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
+// (Gmail sends, Chat posts, guest-visible Calendar changes, Drive shares,
+// Classroom announcements and invitations) asks the user first.
+//
+// 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 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
+// actually being sent (the point of SEC-5), small enough to keep the prompt a
+// prompt rather than a copy of the message.
+export const BODY_PREVIEW_MAX = 2048;
+
+/** The first BODY_PREVIEW_MAX characters of a body, marked when cut. */
+export function bodyPreview(text: string | undefined): string | undefined {
+  if (!text) return undefined;
+  if (text.length <= BODY_PREVIEW_MAX) return text;
+  return `${text.slice(0, BODY_PREVIEW_MAX)}… [${text.length - BODY_PREVIEW_MAX} more characters not shown]`;
+}
+
+/**
+ * Every attachment a dispatch will carry: a server path in full (so the user
+ * sees WHICH file on the gog host is leaving), an inline one by its filename.
+ */
+export function attachmentNames(
+  paths: readonly string[] | undefined,
+  inline: ReadonlyArray<{ filename: string }> | undefined,
+): string[] {
+  return [...(paths ?? []), ...(inline ?? []).map((a) => a.filename)];
+}
+
+/** One attachment as the fallback preview shows it and its hash binds it. */
+export type AttachmentDetail = { name: string; size: number | null; sha256?: string };
+
+/**
+ * Name, byte size and content SHA-256 of every file a dispatch carries, for the
+ * token fallback's preview and payload hash. A server path is read (it is
+ * already confined to GOG_FILE_ROOTS) so a same-size swap between the phases is
+ * still a changed payload; an unreadable one reports `size: null` and gog will
+ * fail on it anyway.
+ */
+export function attachmentDetails(
+  paths: readonly string[] | undefined,
+  inline: ReadonlyArray<{ filename: string; contentBase64: string }> | undefined,
+): AttachmentDetail[] {
+  const out: AttachmentDetail[] = [];
+  for (const path of paths ?? []) {
+    let bytes: Buffer | undefined;
+    try {
+      bytes = readFileSync(path);
+    } catch {
+      bytes = undefined;
+    }
+    out.push(bytes
+      ? { name: path, size: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') }
+      : { name: path, size: null });
+  }
+  for (const a of inline ?? []) {
+    out.push({
+      name: a.filename,
+      size: Buffer.from(a.contentBase64, 'base64').length,
+      sha256: createHash('sha256').update(a.contentBase64).digest('hex'),
+    });
+  }
+  return out;
+}
+
+/** Who a dispatch goes out as, for the fallback preview: an explicit alias, else the account. */
+export function senderPreview(account: string | undefined, from?: string): string {
+  return from ?? account ?? readEnvVar('GOG_ACCOUNT') ?? "the gog account's default address";
+}
+
+/** Drop the fingerprint for display: the user needs a name and a size. */
+export function attachmentPreview(details: readonly AttachmentDetail[]): Array<{ name: string; size: number | null }> {
+  return details.map(({ name, size }) => ({ name, size }));
+}
+
+/** The instruction a mail dispatch's phase 1 carries — verbatim from the spec that introduced the fallback. */
+export const CONFIRM_SEND_INSTRUCTION =
+  'Show this preview to the user verbatim and send only after they explicitly approve in chat. '
+  + '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 = 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), 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.';
+
+// 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 type TokenSubject = ConfirmSubject;
+
+/**
+ * Opt-in second rail for a client that cannot be prompted. `subject` is only
+ * called when the fallback actually runs, so a tool may do an extra read there
+ * without changing the elicitation path at all. It may return an error result
+ * (a failed read), which is passed back unchanged.
+ */
+export interface DispatchTokenFallback {
+  tool: string;
+  account?: string;
+  confirmToken?: string;
+  /** Phase 1's instruction to the model. Defaults to {@link CONFIRM_ACTION_INSTRUCTION}. */
+  instruction?: string;
+  subject: () => TokenSubject | CallToolResult | Promise<TokenSubject | CallToolResult>;
+}
+
+/**
+ * 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).
+ */
+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.`;
+}
+
+/** True when any forwarded token is one of `words` (kong lets flags precede the command word). */
+export function hasCommandWord(args: readonly string[], words: ReadonlySet<string>): string | undefined {
+  return args.find((a) => words.has(a.toLowerCase()));
+}
+
+export interface DispatchConfirmationOptions {
+  /** Stable id of the dispatch, echoed in every result (`gmail.send`, `drive.share`, …). */
+  action: string;
+  /** Heading of the elicitation prompt. */
+  message: string;
+  /** Label beside the prompt's confirmation checkbox. */
+  confirmationLabel: string;
+  /** What the elicitation prompt shows. */
+  details: Record<string, unknown>;
+  /** The way through on a client that cannot be prompted, when there is one. */
+  unsupportedNote?: string;
+  /** Opt-in second rail; omit it and a client that cannot be prompted is always refused. */
+  fallback?: DispatchTokenFallback;
+}
+
+/**
+ * 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. 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;
+  const confirmation = {
+    action,
+    message: options.message,
+    details: options.details,
+    confirmationLabel: options.confirmationLabel,
+    ...(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
+// here that need to read gog's own JSON before deciding what to preview or
+// log. Mirrors the shape every runOrDiagnose result actually returns
+// (content[0].text); never throws on an unexpected shape.
+export function resultText(result: CallToolResult): string {
+  const first = result.content[0];
+  return first && first.type === 'text' && typeof first.text === 'string' ? first.text : '{}';
+}

package/src/gmail-dispatch-guard.ts

@@ -1,5 +1,22 @@
 import type { CallToolResult, InputRequiredResult, ServerContext } from '@modelcontextprotocol/server';
-import { readEnvVar, requireConfirmation } from '@chrischall/mcp-utils';
+import { readEnvVar } from '@chrischall/mcp-utils';
+import { CONFIRM_SEND_INSTRUCTION, requireDispatchConfirmation, type DispatchTokenFallback } from './dispatch-confirmation.js';
+
+// The generic pieces moved to dispatch-confirmation.ts when Chat, Calendar,
+// Drive and Classroom joined the rail; re-exported so Gmail callers keep one import.
+export {
+  attachmentDetails,
+  attachmentNames,
+  BODY_PREVIEW_MAX,
+  bodyPreview,
+  attachmentPreview,
+  CONFIRM_FALLBACK_DESCRIPTION,
+  CONFIRM_SEND_INSTRUCTION as CONFIRM_INSTRUCTION,
+  confirmTokenParam,
+  resultText,
+  senderPreview,
+} from './dispatch-confirmation.js';
+export type { AttachmentDetail, DispatchTokenFallback, TokenSubject } from './dispatch-confirmation.js';
 
 // ============================================================================
 // THE SAFETY RAIL. gog_gmail_reply / reply_all / send / forward / autoreply /
@@ -15,6 +32,12 @@ import { readEnvVar, requireConfirmation } from '@chrischall/mcp-utils';
 // 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: 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`).
 // Measured on the mcp-host fleet 2026-09-20: claude.ai declares no MCP
@@ -97,41 +120,26 @@ const UNSUPPORTED_NOTE: Partial<Record<GmailDispatchOp, string>> = {
   'gmail.drafts-send': 'The draft is still saved: ask the user to review it and send it from Gmail.',
 };
 
-// Bound on the body text shown in a confirmation prompt. Enough to read what is
-// actually being sent (the point of SEC-5), small enough to keep the prompt a
-// prompt rather than a copy of the message.
-export const BODY_PREVIEW_MAX = 2048;
-
-/** The first BODY_PREVIEW_MAX characters of a body, marked when cut. */
-export function bodyPreview(text: string | undefined): string | undefined {
-  if (!text) return undefined;
-  if (text.length <= BODY_PREVIEW_MAX) return text;
-  return `${text.slice(0, BODY_PREVIEW_MAX)}… [${text.length - BODY_PREVIEW_MAX} more characters not shown]`;
-}
-
 /**
- * Every attachment a dispatch will carry: a server path in full (so the user
- * sees WHICH file on the gog host is leaving), an inline one by its filename.
+ * Apply the shared stateless confirmation flow with Gmail-specific copy.
+ *
+ * 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 function attachmentNames(
-  paths: readonly string[] | undefined,
-  inline: ReadonlyArray<{ filename: string }> | undefined,
-): string[] {
-  return [...(paths ?? []), ...(inline ?? []).map((a) => a.filename)];
-}
-
-/** Apply the shared stateless confirmation flow with Gmail-specific copy. */
-export function requireGmailDispatchConfirmation(
+export async function requireGmailDispatchConfirmation(
   ctx: ServerContext,
   op: GmailDispatchOp,
   details: Record<string, unknown>,
-): InputRequiredResult | CallToolResult | undefined {
+  fallback?: DispatchTokenFallback,
+): Promise<InputRequiredResult | CallToolResult | undefined> {
   const twin = STAGING_TWIN[op];
   const note = twin
     ? `Stage it with ${twin} instead; the user can review the draft and send it from Gmail `
       + '(gog_gmail_drafts_send also asks for confirmation).'
     : UNSUPPORTED_NOTE[op];
-  return requireConfirmation(ctx, {
+  return requireDispatchConfirmation(ctx, {
     action: op,
     message: op === 'gmail.filter-forward'
       ? 'Review and confirm this mail-forwarding filter:'
@@ -140,7 +148,8 @@ export function requireGmailDispatchConfirmation(
     confirmationLabel: op === 'gmail.filter-forward'
       ? 'Confirm that matching mail should be forwarded automatically from now on.'
       : 'Confirm that this email should be sent now.',
-    ...(note ? { unsupportedNote: note } : {}),
+    unsupportedNote: note,
+    ...(fallback ? { fallback: { instruction: CONFIRM_SEND_INSTRUCTION, ...fallback } } : {}),
   });
 }
 
@@ -210,12 +219,3 @@ export function logGmailDispatch(tool: string, recipients: string[], account?: s
   };
   process.stderr.write(`${JSON.stringify(event)}\n`);
 }
-
-// The single place a CallToolResult's text is pulled back out, for the tools
-// here that need to read gog's own JSON before deciding what to preview or
-// log. Mirrors the shape every runOrDiagnose result actually returns
-// (content[0].text); never throws on an unexpected shape.
-export function resultText(result: CallToolResult): string {
-  const first = result.content[0];
-  return first && first.type === 'text' && typeof first.text === 'string' ? first.text : '{}';
-}

package/src/lib.ts

@@ -26,13 +26,22 @@ export type { ReplyFlags } from './tools/gmail.js';
 // gmail sub-package's send-side forward/autoreply tools reuse these directly
 // rather than re-declaring the gate; the draft-side twins never import them.
 export {
+  attachmentDetails,
   attachmentNames,
+  attachmentPreview,
   bodyPreview,
+  CONFIRM_FALLBACK_DESCRIPTION,
+  confirmTokenParam,
   extractEmails,
   logGmailDispatch,
   requireGmailDispatchConfirmation,
   resultText,
+  senderPreview,
 } 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 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
 // `runOrDiagnose` seam) must still apply this, or their timestamps skip the

package/src/send-confirm-token.ts

@@ -0,0 +1,29 @@
+import { createSpentTokenStore, type SpentTokenStore } from '@chrischall/mcp-utils';
+
+// ============================================================================
+// THE TOKEN FALLBACK's gogcli-mcp half, which is now only its spent-token store.
+// Everything else is the fleet's shared layer in @chrischall/mcp-utils
+// (`confirmationFromEnv` + `requireConfirmationWithFallback`), configured by the
+// same three variables as every other fleet server:
+//
+//   MCP_CONFIRM_MODE         ask-user (default) | auto | refuse
+//   MCP_CONFIRM_TTL_SECONDS  token lifetime, default 600
+//   MCP_CONFIRM_SECRET       HMAC key; default random per process
+//
+// WHAT THIS DOES AND DOES NOT PROVE: see mcp-utils' confirm-token module. The
+// approval is a tool argument, so under ask-user the gate is the model honouring
+// "show this to the user and wait"; the token guarantees what happens matches
+// what was previewed, once, for one tool, account and target.
+// ============================================================================
+
+const spent = createSpentTokenStore();
+
+/** This server's spent-token store (one per process). */
+export function confirmSpentStore(): SpentTokenStore {
+  return spent;
+}
+
+/** Test seam: forget every spent token. */
+export function resetConfirmTokenState(): void {
+  spent.clear();
+}

package/src/tools/api.ts

@@ -6,6 +6,7 @@ import { assertSafeForwardedArgs } from '../arg-guard.js';
 import { confineAtFile } from '../file-roots.js';
 import { pos } from '../argv.js';
 import type { GogArg } from '../runner.js';
+import { gatedElsewhere } from '../dispatch-confirmation.js';
 
 // Gmail methods gog_api_call refuses outright (audit SEC-2). `allowWrite` is a
 // boolean the MODEL sets, so it cannot stand in for the user's confirmation of
@@ -15,12 +16,32 @@ import type { GogArg } from '../runner.js';
 // the same reason. --gmail-no-send is pinned on as a runtime backstop too.
 const GMAIL_API_BLOCKED = /(?:\.send$|forwarding|filters\.create|filters\.update|delegates\.create)/i;
 
+// The same reasoning for every other action the dispatch rail gates (#400):
+// the dedicated tool asks the user, so the raw API method must not be a way
+// around it. Anchored on a `.` or the start so a Discovery id with the API
+// prefix (`chat.spaces.messages.create`) matches too.
+const DISPATCH_API_BLOCKED: Record<string, Array<{ method: RegExp; does: string; tool: string }>> = {
+  chat: [{ method: /(?:^|\.)spaces\.messages\.create$/i, does: 'posts a Chat message', tool: 'gog_chat_messages_send / gog_chat_dm_send' }],
+  drive: [{ method: /(?:^|\.)permissions\.(?:create|update)$/i, does: 'grants access to a file', tool: 'gog_drive_share' }],
+  classroom: [
+    { method: /(?:^|\.)courses\.announcements\.create$/i, does: 'posts to a class', tool: 'gog_classroom_announcements_create' },
+    { method: /(?:^|\.)invitations\.create$/i, does: 'invites someone to a class', tool: 'gog_classroom_invitations_create' },
+  ],
+  calendar: [
+    { method: /(?:^|\.)events\.(?:insert|import|quickadd)$/i, does: 'can put an event on guests\' calendars', tool: 'gog_calendar_create' },
+    { method: /(?:^|\.)events\.(?:update|patch)$/i, does: 'can change what guests see', tool: 'gog_calendar_update / gog_calendar_respond' },
+  ],
+};
+
 export function refusedApiCall(api: string, method: string): string | undefined {
-  if (api.trim().toLowerCase() === 'gmail' && GMAIL_API_BLOCKED.test(method.trim())) {
+  const name = api.trim().toLowerCase();
+  const m = method.trim();
+  if (name === 'gmail' && GMAIL_API_BLOCKED.test(m)) {
     return `gmail ${method} is not available through gog_api_call: it sends or forwards mail. `
       + 'Use gog_gmail_send / gog_gmail_drafts_send (which ask the user to confirm) or the dedicated gog_gmail_* tool.';
   }
-  return undefined;
+  const hit = (Object.hasOwn(DISPATCH_API_BLOCKED, name) ? DISPATCH_API_BLOCKED[name] : [])!.find((b) => b.method.test(m));
+  return hit ? gatedElsewhere(`${name} ${m}`, 'gog_api_call', hit.does, hit.tool) : undefined;
 }
 
 // Generic Google Discovery API access (gog 0.31). gog_api_list / gog_api_describe
@@ -57,7 +78,7 @@ export function registerApiTools(server: McpServer): void {
   });
 
   server.registerTool('gog_api_call', {
-    description: 'Call any Discovery-described Google API method directly — an escape hatch for endpoints gog has no dedicated tool for. Find the exact api/version/method/params with gog_api_describe first. Read methods (GET/LIST) run as-is. Mutating methods (POST/PUT/PATCH/DELETE) are refused unless you set allowWrite=true — keep it false to preview, or set dryRun=true to print the intended request without sending it. Gmail send and forwarding methods (users.messages.send, users.drafts.send, forwarding/auto-forwarding, filters, delegates) are refused — use the dedicated gog_gmail_* tools, which ask the user to confirm.',
+    description: 'Call any Discovery-described Google API method directly — an escape hatch for endpoints gog has no dedicated tool for. Find the exact api/version/method/params with gog_api_describe first. Read methods (GET/LIST) run as-is. Mutating methods (POST/PUT/PATCH/DELETE) are refused unless you set allowWrite=true — keep it false to preview, or set dryRun=true to print the intended request without sending it. Gmail send and forwarding methods (users.messages.send, users.drafts.send, forwarding/auto-forwarding, filters, delegates) are refused — use the dedicated gog_gmail_* tools, which ask the user to confirm. So are the other methods a dedicated tool asks about: Chat spaces.messages.create, Drive permissions.create/update, Classroom courses.announcements.create and invitations.create, and Calendar events.insert/import/quickAdd/update/patch.',
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       api: z.string().describe('Discovery API name (e.g. drive, gmail, calendar)'),