gogcli-mcp-docs 4.5.0 → 4.5.2

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-docs",
   "display_name": "gogcli (Docs)",
-  "version": "4.5.0",
+  "version": "4.5.2",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",
@@ -180,11 +180,11 @@
     },
     {
       "name": "gog_docs_comments_add",
-      "description": "Add a comment to a Google Doc. Optionally attach quoted text that appears as the highlighted passage in the Google Docs UI."
+      "description": "Add a comment to a Google Doc. Optionally attach quoted text that appears as the highlighted passage in the Google Docs UI. Asks the user to confirm."
     },
     {
       "name": "gog_docs_comments_reply",
-      "description": "Reply to an existing comment on a Google Doc."
+      "description": "Reply to an existing comment on a Google Doc. Asks the user to confirm."
     },
     {
       "name": "gog_docs_comments_resolve",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-docs",
-  "version": "4.5.0",
+  "version": "4.5.2",
   "mcpName": "io.github.chrischall/gogcli-mcp-docs",
   "description": "Extended Google Docs MCP server via gogcli — all base tools plus full Docs support",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@chrischall/mcp-utils": "^2.6.0",
-    "@modelcontextprotocol/server": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.1.0",
     "zod": "^4.6.1"
   },
   "license": "MIT",

package/server.json

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

package/src/tools/docs-extra.ts

@@ -1,8 +1,34 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose, paginationParams, pushPaginationFlags, payloadArg, pos, confinePath } from '../../../gogcli-mcp/src/lib.js';
+import {
+  accountParam,
+  runOrDiagnose,
+  paginationParams,
+  pushPaginationFlags,
+  payloadArg,
+  pos,
+  confinePath,
+  bodyPreview,
+  commentMentions,
+  commentSnapshot,
+  CONFIRM_FALLBACK_DESCRIPTION,
+  confirmTokenParam,
+  requireDispatchConfirmation,
+  resultText,
+} from '../../../gogcli-mcp/src/lib.js';
 import type { GogArg } from '../../../gogcli-mcp/src/lib.js';
 
+/** A Doc's title from `gog docs info`, for a comment's prompt. Unreadable output names nothing. */
+export function docTitle(raw: string): string | undefined {
+  try {
+    const parsed = JSON.parse(raw) as { title?: unknown; document?: { title?: unknown } } | null;
+    const title = parsed?.document?.title ?? parsed?.title;
+    return typeof title === 'string' ? title : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function registerExtraDocsTools(server: McpServer): void {
   server.registerTool('gog_docs_copy', {
     description: 'Copy a Google Doc to a new document with the given title.',
@@ -419,30 +445,84 @@ export function registerExtraDocsTools(server: McpServer): void {
 
   server.registerTool('gog_docs_comments_add', {
     description:
-      'Add a comment to a Google Doc. Optionally attach quoted text that appears as the highlighted passage in the Google Docs UI.',
+      'Add a comment to a Google Doc. Optionally attach quoted text that appears as the highlighted passage in the Google Docs UI. '
+      + 'The Doc\'s owner and everyone the text +mentions are notified, so this reads the Doc and asks the MCP host to show '
+      + 'the user a confirmation prompt with the Doc, the text and who is mentioned first; nothing is posted unless they '
+      + 'accept.' + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: false },
     inputSchema: z.object({
       docId: z.string().describe('Doc ID (from the URL)'),
       content: z.string().describe('Comment text'),
       quoted: z.string().optional().describe('Quoted text to attach to the comment (shown in UIs when available)'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ docId, content, quoted, account }) => {
+  }, async ({ docId, content, quoted, account, confirmToken }, ctx) => {
     const args: GogArg[] = ['docs', 'comments', 'add', pos(docId), pos(content)];
     if (quoted) args.push(`--quoted=${quoted}`);
+    const got = await runOrDiagnose(['docs', 'info', pos(docId)], { account });
+    if (got.isError) return got;
+    const title = docTitle(resultText(got));
+    const doc = { id: docId, ...(title !== undefined ? { title } : {}) };
+    const mentions = commentMentions(content);
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: 'docs.comment-add',
+      message: 'Review and confirm this comment — the Doc\'s owner and anyone mentioned are notified:',
+      confirmationLabel: 'Confirm that this comment should be posted now.',
+      details: { doc, textPreview: bodyPreview(content), quoted, mentions },
+      unsupportedNote: 'Ask the user to comment from Google Docs.',
+      fallback: {
+        tool: 'gog_docs_comments_add',
+        account,
+        confirmToken,
+        subject: () => {
+          const view = { doc, text: content, quoted, mentions };
+          return { target: docId, payload: view, preview: view };
+        },
+      },
+    });
+    if (confirmation) return confirmation;
     return runOrDiagnose(args, { account });
   });
 
   server.registerTool('gog_docs_comments_reply', {
-    description: 'Reply to an existing comment on a Google Doc.',
+    description: 'Reply to an existing comment on a Google Doc. Everyone on the thread and anyone the reply +mentions is '
+      + 'notified, so this reads the Doc and the comment and asks the MCP host to show the user a confirmation prompt '
+      + 'with both and the reply first; nothing is posted unless they accept.' + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: false },
     inputSchema: z.object({
       docId: z.string().describe('Doc ID (from the URL)'),
       commentId: z.string().describe('Comment ID to reply to'),
       content: z.string().describe('Reply text'),
       account: accountParam,
-    }),
-  }, async ({ docId, commentId, content, account }) => {
+      confirmToken: confirmTokenParam,
+    }),
+  }, async ({ docId, commentId, content, account, confirmToken }, ctx) => {
+    const got = await runOrDiagnose(['docs', 'info', pos(docId)], { account });
+    if (got.isError) return got;
+    const thread = await runOrDiagnose(['docs', 'comments', 'get', pos(docId), pos(commentId)], { account });
+    if (thread.isError) return thread;
+    const title = docTitle(resultText(got));
+    const doc = { id: docId, ...(title !== undefined ? { title } : {}) };
+    const replyingTo = commentSnapshot(resultText(thread));
+    const mentions = commentMentions(content);
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: 'docs.comment-reply',
+      message: 'Review and confirm this reply — everyone on the thread and anyone mentioned is notified:',
+      confirmationLabel: 'Confirm that this reply should be posted now.',
+      details: { doc, replyingTo, textPreview: bodyPreview(content), mentions },
+      unsupportedNote: 'Ask the user to reply from Google Docs.',
+      fallback: {
+        tool: 'gog_docs_comments_reply',
+        account,
+        confirmToken,
+        subject: () => {
+          const view = { doc, replyingTo, text: content, mentions };
+          return { target: `${docId}/${commentId}`, payload: view, preview: view };
+        },
+      },
+    });
+    if (confirmation) return confirmation;
     return runOrDiagnose(['docs', 'comments', 'reply', pos(docId), pos(commentId), pos(content)], { account });
   });
 

package/tests/tools/docs-extra-gates.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { registerExtraDocsTools, docTitle } from '../../src/tools/docs-extra.js';
+import * as lib from '../../../gogcli-mcp/src/lib.js';
+import { createTestHarness } from '@chrischall/mcp-utils/test';
+import { rawTextResult } from '@chrischall/mcp-utils';
+import type { ElicitRequest, ElicitResult } from '@modelcontextprotocol/server';
+import { pos } from '../../../gogcli-mcp/src/argv.js';
+import { resetConfirmTokenState } from '../../../gogcli-mcp/src/send-confirm-token.js';
+
+vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof lib>();
+  return { ...actual, runOrDiagnose: vi.fn() };
+});
+
+// Fleet audit 2026-09-24 SEC-6: a Doc comment or reply notifies the owner, the
+// thread and everyone it +mentions, so both ask first — naming the Doc.
+
+const ORIGINAL_ENV = { ...process.env };
+beforeEach(() => {
+  vi.clearAllMocks();
+  process.env = { ...ORIGINAL_ENV };
+  delete process.env.MCP_CONFIRM_MODE;
+  resetConfirmTokenState();
+});
+afterEach(() => { process.env = ORIGINAL_ENV; });
+
+const json = (r: { content: Array<{ text?: string }> }) => JSON.parse(r.content[0]!.text as string);
+async function prompted(answer: ElicitResult = { action: 'accept', content: { confirmed: true } }) {
+  const seen: ElicitRequest[] = [];
+  const harness = await createTestHarness(registerExtraDocsTools, { elicitation: async (r) => { seen.push(r); return answer; } });
+  const details = () => JSON.parse(seen[0]!.params.message.split('\n').slice(1).join('\n')).details;
+  return { harness, seen, details };
+}
+const unprompted = () => createTestHarness(registerExtraDocsTools);
+
+const INFO = JSON.stringify({ document: { documentId: 'd1', title: 'Q3 plan' } });
+const COMMENT = JSON.stringify({ comment: { id: 'k1', content: 'Is this final?', author: { displayName: 'Alice' } } });
+function stub(failing?: string, info = INFO) {
+  vi.mocked(lib.runOrDiagnose).mockImplementation(async (args) => {
+    const key = args.filter((a): a is string => typeof a === 'string' && !a.startsWith('--')).join(' ');
+    if (failing && key.startsWith(failing)) return { content: [{ type: 'text', text: 'Error: not found' }], isError: true };
+    if (key === 'docs info') return rawTextResult(info);
+    if (key === 'docs comments get') return rawTextResult(COMMENT);
+    return rawTextResult('{"ok":true}');
+  });
+}
+const callsTo = (...words: string[]) => vi.mocked(lib.runOrDiagnose).mock.calls.filter(([args]) =>
+  words.every((w, i) => args[i] === w));
+
+describe('gog_docs_comments_add', () => {
+  const ARGS = { docId: 'd1', content: 'Check with @bob@example.com', quoted: 'Revenue' };
+
+  it('reads the Doc and asks with its title, the text, the quote and who is mentioned', async () => {
+    stub();
+    const { harness, details } = await prompted();
+    await harness.callTool('gog_docs_comments_add', ARGS);
+    expect(details()).toEqual({ doc: { id: 'd1', title: 'Q3 plan' }, textPreview: ARGS.content, quoted: 'Revenue', mentions: ['bob@example.com'] });
+    expect(callsTo('docs', 'comments', 'add')[0]![0]).toEqual(['docs', 'comments', 'add', pos('d1'), pos(ARGS.content), '--quoted=Revenue']);
+  });
+
+  it('posts nothing when the user declines or the read fails', async () => {
+    stub();
+    expect(json(await (await prompted({ action: 'decline' })).harness.callTool('gog_docs_comments_add', ARGS)))
+      .toMatchObject({ cancelled: true, action: 'docs.comment-add' });
+    stub('docs info');
+    expect((await (await prompted()).harness.callTool('gog_docs_comments_add', ARGS)).isError).toBe(true);
+    expect(callsTo('docs', 'comments', 'add')).toHaveLength(0);
+  });
+
+  it('refuses a client that cannot be prompted', async () => {
+    process.env.MCP_CONFIRM_MODE = 'refuse';
+    stub();
+    const r = json(await (await unprompted()).callTool('gog_docs_comments_add', ARGS));
+    expect(r).toMatchObject({ reason: 'confirmation-unsupported', action: 'docs.comment-add' });
+    expect(r.note).toMatch(/Google Docs/);
+  });
+
+  it('token fallback: changed text is DRAFT_CHANGED; the same call posts', async () => {
+    process.env.MCP_CONFIRM_MODE = 'ask-user';
+    stub(undefined, '{}');
+    const harness = await unprompted();
+    const args = { docId: 'd1', content: 'Nice' };
+    const p1 = json(await harness.callTool('gog_docs_comments_add', args));
+    expect(p1.preview).toEqual({ doc: { id: 'd1' }, text: 'Nice', mentions: [] });
+    expect(json(await harness.callTool('gog_docs_comments_add', { ...args, content: 'Nicer', confirmToken: p1.confirmToken })))
+      .toMatchObject({ error: 'DRAFT_CHANGED' });
+    await harness.callTool('gog_docs_comments_add', { ...args, confirmToken: p1.confirmToken });
+    expect(callsTo('docs', 'comments', 'add')).toHaveLength(1);
+  });
+});
+
+describe('gog_docs_comments_reply', () => {
+  const ARGS = { docId: 'd1', commentId: 'k1', content: 'Yes.' };
+
+  it('reads the Doc and the comment and asks with both and the reply', async () => {
+    stub();
+    const { harness, details } = await prompted();
+    await harness.callTool('gog_docs_comments_reply', ARGS);
+    expect(details()).toEqual({ doc: { id: 'd1', title: 'Q3 plan' }, replyingTo: { author: 'Alice', content: 'Is this final?' }, textPreview: 'Yes.', mentions: [] });
+    expect(callsTo('docs', 'comments', 'reply')[0]![0]).toEqual(['docs', 'comments', 'reply', pos('d1'), pos('k1'), pos('Yes.')]);
+  });
+
+  it.each(['docs info', 'docs comments get'])('returns a failed read (%s) without asking or replying', async (failing) => {
+    stub(failing);
+    const { harness, seen } = await prompted();
+    expect((await harness.callTool('gog_docs_comments_reply', ARGS)).isError).toBe(true);
+    expect(seen).toHaveLength(0);
+    expect(callsTo('docs', 'comments', 'reply')).toHaveLength(0);
+  });
+
+  it('refuses a client that cannot be prompted', async () => {
+    process.env.MCP_CONFIRM_MODE = 'refuse';
+    stub();
+    const r = json(await (await unprompted()).callTool('gog_docs_comments_reply', ARGS));
+    expect(r).toMatchObject({ reason: 'confirmation-unsupported', action: 'docs.comment-reply' });
+  });
+
+  it('token fallback: previews the thread and posts on phase 2', async () => {
+    process.env.MCP_CONFIRM_MODE = 'ask-user';
+    stub();
+    const harness = await unprompted();
+    const p1 = json(await harness.callTool('gog_docs_comments_reply', ARGS));
+    expect(p1.preview).toEqual({ doc: { id: 'd1', title: 'Q3 plan' }, replyingTo: { author: 'Alice', content: 'Is this final?' }, text: 'Yes.', mentions: [] });
+    await harness.callTool('gog_docs_comments_reply', { ...ARGS, confirmToken: p1.confirmToken });
+    expect(callsTo('docs', 'comments', 'reply')).toHaveLength(1);
+  });
+});
+
+describe('docTitle', () => {
+  it('reads a nested or top-level title and tolerates unreadable output', () => {
+    expect(docTitle(JSON.stringify({ document: { title: 'A' } }))).toBe('A');
+    expect(docTitle(JSON.stringify({ title: 'B' }))).toBe('B');
+    expect(docTitle(JSON.stringify({ title: 7 }))).toBeUndefined();
+    expect(docTitle('null')).toBeUndefined();
+    expect(docTitle('nope')).toBeUndefined();
+  });
+});

package/tests/tools/docs-extra.test.ts

@@ -13,7 +13,10 @@ vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
   };
 });
 
-const setupHandlers = () => createTestHarness(registerExtraDocsTools);
+// The comment tools ask first (docs-extra-gates.test.ts covers the prompts); here the user accepts.
+const setupHandlers = () => createTestHarness(registerExtraDocsTools, {
+  elicitation: async () => ({ action: 'accept', content: { confirmed: true } }),
+});
 
 beforeEach(() => vi.clearAllMocks());