gogcli-mcp-sheets 4.5.0 → 4.5.2

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-sheets",
   "display_name": "gogcli (Sheets)",
-  "version": "4.5.0",
+  "version": "4.5.2",
   "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
   "author": {
     "name": "Chris Hall",
@@ -349,15 +349,15 @@
     },
     {
       "name": "gog_sheets_datasource_add",
-      "description": "Add a BigQuery Connected Sheets data source (custom SQL or a native table)"
+      "description": "Add a BigQuery Connected Sheets data source (custom SQL or a native table) (billed; asks the user to confirm)"
     },
     {
       "name": "gog_sheets_datasource_update",
-      "description": "Repoint a Connected Sheets data source's SQL, table or billing project"
+      "description": "Repoint a Connected Sheets data source's SQL, table or billing project (billed; asks the user to confirm)"
     },
     {
       "name": "gog_sheets_datasource_refresh",
-      "description": "Re-run a Connected Sheets data source against current BigQuery data"
+      "description": "Re-run a Connected Sheets data source against current BigQuery data (billed; asks the user to confirm)"
     },
     {
       "name": "gog_sheets_datasource_delete",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-sheets",
-  "version": "4.5.0",
+  "version": "4.5.2",
   "mcpName": "io.github.chrischall/gogcli-mcp-sheets",
   "description": "Extended Google Sheets MCP server via gogcli — all base tools plus full Sheets 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-sheets"
   },
-  "version": "4.5.0",
+  "version": "4.5.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp-sheets",
-      "version": "4.5.0",
+      "version": "4.5.2",
       "transport": {
         "type": "stdio"
       },

package/src/tools/sheets-extra.ts

@@ -2,7 +2,20 @@ import { McpServer } from '@modelcontextprotocol/server';
 import type { CallToolResult } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { rawTextResult } from '@chrischall/mcp-utils';
-import { accountParam, runOrDiagnose, run, diagnose, errorText, payloadArg, pos, confinePath, confineAtFile } from '../../../gogcli-mcp/src/lib.js';
+import {
+  accountParam,
+  runOrDiagnose,
+  run,
+  diagnose,
+  errorText,
+  payloadArg,
+  pos,
+  confinePath,
+  confineAtFile,
+  CONFIRM_FALLBACK_DESCRIPTION,
+  confirmTokenParam,
+  requireDispatchConfirmation,
+} from '../../../gogcli-mcp/src/lib.js';
 import type { GogArg } from '../../../gogcli-mcp/src/lib.js';
 
 // Pull the text out of a single-text-block tool result; undefined for any
@@ -12,6 +25,44 @@ function resultText(result: CallToolResult): string | undefined {
   return first?.type === 'text' ? first.text : undefined;
 }
 
+/** A spreadsheet's title from `gog sheets metadata --select=properties.title`. Unreadable output names nothing. */
+export function spreadsheetTitle(raw: string | undefined): string | undefined {
+  try {
+    const parsed = JSON.parse(String(raw)) as { properties?: { title?: unknown }; spreadsheet?: { properties?: { title?: unknown } } } | null;
+    const title = parsed?.spreadsheet?.properties?.title ?? parsed?.properties?.title;
+    return typeof title === 'string' ? title : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * What a data source queries and who pays, from `gog sheets datasource describe`,
+ * for a refresh's prompt. Best effort: only the fields found are named.
+ */
+export function dataSourceSnapshot(raw: string | undefined): { billingProject?: string; query?: string; table?: string } {
+  type BigQuerySpec = {
+    projectId?: unknown;
+    querySpec?: { rawQuery?: unknown };
+    tableSpec?: { tableProjectId?: unknown; datasetId?: unknown; tableId?: unknown };
+  };
+  let bq: BigQuerySpec | undefined;
+  try {
+    const parsed = JSON.parse(String(raw)) as ({ dataSource?: { spec?: { bigQuery?: BigQuerySpec } }; spec?: { bigQuery?: BigQuerySpec } }) | null;
+    bq = (parsed?.dataSource ?? parsed)?.spec?.bigQuery;
+  } catch {
+    bq = undefined;
+  }
+  const str = (v: unknown) => (typeof v === 'string' ? v : undefined);
+  const t = bq?.tableSpec;
+  const table = [t?.tableProjectId, t?.datasetId, t?.tableId].map(str).filter(Boolean).join('.');
+  return {
+    ...(str(bq?.projectId) ? { billingProject: str(bq?.projectId) } : {}),
+    ...(str(bq?.querySpec?.rawQuery) ? { query: str(bq?.querySpec?.rawQuery) } : {}),
+    ...(table ? { table } : {}),
+  };
+}
+
 // Convert a CSS-style hex color ("#FFF5D9", "#FD9", "FFF5D9") to the
 // {red, green, blue} 0-1 float triple that Sheets API CellFormat expects.
 // Returns null on unparseable input — caller decides whether to fall back
@@ -77,6 +128,42 @@ async function checkDateFormatTarget(
   );
 }
 
+/**
+ * Fleet audit 2026-09-24 SEC-6: every datasource add / update / refresh starts
+ * a BigQuery job billed to a project, so each asks first — naming the
+ * spreadsheet by title, what will be queried and who pays.
+ */
+async function confirmBilledExecution(
+  ctx: Parameters<typeof requireDispatchConfirmation>[0],
+  o: {
+    tool: string;
+    action: string;
+    account: string | undefined;
+    confirmToken: string | undefined;
+    spreadsheetId: string;
+    target: string;
+    view: Record<string, unknown>;
+  },
+) {
+  const got = await runOrDiagnose(['sheets', 'metadata', pos(o.spreadsheetId), '--select=properties.title'], { account: o.account });
+  if (got.isError) return got;
+  const title = spreadsheetTitle(resultText(got));
+  const view = { spreadsheet: { id: o.spreadsheetId, ...(title !== undefined ? { title } : {}) }, ...o.view };
+  return requireDispatchConfirmation(ctx, {
+    action: o.action,
+    message: 'Review and confirm starting a BigQuery execution — it is billed to the billing project:',
+    confirmationLabel: 'Confirm that this billed BigQuery query should run now.',
+    details: view,
+    unsupportedNote: 'Ask the user to run it from Google Sheets (Data > Data connectors).',
+    fallback: {
+      tool: o.tool,
+      account: o.account,
+      confirmToken: o.confirmToken,
+      subject: () => ({ target: o.target, payload: view, preview: view }),
+    },
+  });
+}
+
 export function registerExtraSheetsTools(server: McpServer): void {
 
   server.registerTool('gog_sheets_list_tabs', {
@@ -1144,7 +1231,9 @@ export function registerExtraSheetsTools(server: McpServer): void {
   const bigQueryChargeNote =
     ' COSTS MONEY AND RUNS ASYNCHRONOUSLY: this starts a BigQuery execution billed to the billing project, and returns ' +
     'once the execution has been REQUESTED — not once it has finished. Poll gog_sheets_datasource_describe until its ' +
-    'dataExecutionStatus state is SUCCEEDED or FAILED before treating the data as current.';
+    'dataExecutionStatus state is SUCCEEDED or FAILED before treating the data as current. Because it bills, it first asks ' +
+    'the MCP host to show the user a confirmation prompt naming the spreadsheet, the query or table and the billing ' +
+    'project; nothing runs unless they accept.' + CONFIRM_FALLBACK_DESCRIPTION;
 
   server.registerTool('gog_sheets_datasource_add', {
     description:
@@ -1162,8 +1251,9 @@ export function registerExtraSheetsTools(server: McpServer): void {
       table: z.string().optional().describe('BigQuery table ID. Requires dataset; mutually exclusive with query.'),
       tableProject: z.string().optional().describe('BigQuery project that owns the table (default: the billing project). Only valid with dataset/table.'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ spreadsheetId, billingProject, query, dataset, table, tableProject, account }) => {
+  }, async ({ spreadsheetId, billingProject, query, dataset, table, tableProject, account, confirmToken }, ctx) => {
     const tableFlags = tableProject !== undefined || dataset !== undefined || table !== undefined;
     if (query !== undefined && tableFlags) {
       throw new Error('query and the table fields (dataset, table, tableProject) are mutually exclusive — a data source is backed by one or the other.');
@@ -1176,6 +1266,12 @@ export function registerExtraSheetsTools(server: McpServer): void {
     if (tableProject) args.push(`--table-project=${tableProject}`);
     if (dataset) args.push(`--dataset=${dataset}`);
     if (table) args.push(`--table=${table}`);
+    const source = query !== undefined ? { query } : { table: [tableProject ?? billingProject, dataset, table].join('.') };
+    const confirmation = await confirmBilledExecution(ctx, {
+      tool: 'gog_sheets_datasource_add', action: 'sheets.datasource-add', account, confirmToken, spreadsheetId,
+      target: spreadsheetId, view: { billingProject, ...source },
+    });
+    if (confirmation) return confirmation;
     return runOrDiagnose(args, { account });
   });
 
@@ -1196,8 +1292,9 @@ export function registerExtraSheetsTools(server: McpServer): void {
       table: z.string().optional().describe('Replacement table ID. Only valid on a table-backed source.'),
       tableProject: z.string().optional().describe('Replacement project owning the table. Only valid on a table-backed source.'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ spreadsheetId, dataSourceId, billingProject, query, dataset, table, tableProject, account }) => {
+  }, async ({ spreadsheetId, dataSourceId, billingProject, query, dataset, table, tableProject, account, confirmToken }, ctx) => {
     const tableFlags = tableProject !== undefined || dataset !== undefined || table !== undefined;
     if (query !== undefined && tableFlags) {
       throw new Error('query and the table fields (dataset, table, tableProject) are mutually exclusive — a data source is backed by one or the other.');
@@ -1211,6 +1308,12 @@ export function registerExtraSheetsTools(server: McpServer): void {
     if (tableProject !== undefined) args.push(`--table-project=${tableProject}`);
     if (dataset !== undefined) args.push(`--dataset=${dataset}`);
     if (table !== undefined) args.push(`--table=${table}`);
+    const changes = Object.fromEntries(Object.entries({ billingProject, query, tableProject, dataset, table }).filter(([, v]) => v !== undefined));
+    const confirmation = await confirmBilledExecution(ctx, {
+      tool: 'gog_sheets_datasource_update', action: 'sheets.datasource-update', account, confirmToken, spreadsheetId,
+      target: `${spreadsheetId}/${dataSourceId}`, view: { dataSourceId, changes },
+    });
+    if (confirmation) return confirmation;
     return runOrDiagnose(args, { account });
   });
 
@@ -1240,10 +1343,19 @@ export function registerExtraSheetsTools(server: McpServer): void {
       dataSourceId: z.string().describe('Data source ID, as reported by gog_sheets_datasource_list'),
       forceRefresh: z.boolean().optional().describe('Refresh even when the previous execution failed'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ spreadsheetId, dataSourceId, forceRefresh, account }) => {
+  }, async ({ spreadsheetId, dataSourceId, forceRefresh, account, confirmToken }, ctx) => {
     const args: GogArg[] = ['sheets', 'datasource', 'refresh', pos(spreadsheetId), pos(dataSourceId)];
     if (forceRefresh) args.push('--force-refresh');
+    const described = await runOrDiagnose(['sheets', 'datasource', 'describe', pos(spreadsheetId), pos(dataSourceId)], { account });
+    if (described.isError) return described;
+    const confirmation = await confirmBilledExecution(ctx, {
+      tool: 'gog_sheets_datasource_refresh', action: 'sheets.datasource-refresh', account, confirmToken, spreadsheetId,
+      target: `${spreadsheetId}/${dataSourceId}`,
+      view: { dataSourceId, ...dataSourceSnapshot(resultText(described)), forceRefresh: Boolean(forceRefresh) },
+    });
+    if (confirmation) return confirmation;
     return runOrDiagnose(args, { account });
   });
 

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

@@ -0,0 +1,158 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { registerExtraSheetsTools, dataSourceSnapshot, spreadsheetTitle } from '../../src/tools/sheets-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: datasource add / update / refresh each start a
+// BigQuery job billed to a project, so each asks first — naming the spreadsheet,
+// what is queried and who pays.
+
+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(registerExtraSheetsTools, { 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(registerExtraSheetsTools);
+
+const META = JSON.stringify({ properties: { title: 'Sales dashboard' } });
+const DESCRIBE = JSON.stringify({ dataSource: { dataSourceId: 'ds1', spec: { bigQuery: { projectId: 'billing-1', querySpec: { rawQuery: 'SELECT 1' } } } } });
+function stub(failing?: string) {
+  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 === 'sheets metadata') return rawTextResult(META);
+    if (key === 'sheets datasource describe') return rawTextResult(DESCRIBE);
+    return rawTextResult('{"ok":true}');
+  });
+}
+const callsTo = (...words: string[]) => vi.mocked(lib.runOrDiagnose).mock.calls.filter(([args]) =>
+  words.every((w, i) => args[i] === w));
+
+const SHEET = { id: 'sid', title: 'Sales dashboard' };
+const CASES = [
+  {
+    tool: 'gog_sheets_datasource_add',
+    args: { spreadsheetId: 'sid', billingProject: 'billing-1', dataset: 'sales', table: 'orders' },
+    action: 'sheets.datasource-add',
+    details: { spreadsheet: SHEET, billingProject: 'billing-1', table: 'billing-1.sales.orders' },
+    write: 'add',
+    reads: ['sheets metadata'],
+    changed: { table: 'refunds' },
+  },
+  {
+    tool: 'gog_sheets_datasource_update',
+    args: { spreadsheetId: 'sid', dataSourceId: 'ds1', query: 'SELECT 2', billingProject: 'billing-2' },
+    action: 'sheets.datasource-update',
+    details: { spreadsheet: SHEET, dataSourceId: 'ds1', changes: { billingProject: 'billing-2', query: 'SELECT 2' } },
+    write: 'update',
+    reads: ['sheets metadata'],
+    changed: { query: 'SELECT 3' },
+  },
+  {
+    tool: 'gog_sheets_datasource_refresh',
+    args: { spreadsheetId: 'sid', dataSourceId: 'ds1', forceRefresh: true },
+    action: 'sheets.datasource-refresh',
+    details: { spreadsheet: SHEET, dataSourceId: 'ds1', billingProject: 'billing-1', query: 'SELECT 1', forceRefresh: true },
+    write: 'refresh',
+    reads: ['sheets datasource describe', 'sheets metadata'],
+    changed: { forceRefresh: false },
+  },
+];
+
+describe.each(CASES)('$tool', (c) => {
+  it('asks naming the spreadsheet, the source and who pays; runs once accepted', async () => {
+    stub();
+    const { harness, details, seen } = await prompted();
+    await harness.callTool(c.tool, c.args);
+    expect(seen[0]!.params.message).toMatch(/billed/);
+    expect(details()).toEqual(c.details);
+    expect(callsTo('sheets', 'metadata')[0]![0]).toEqual(['sheets', 'metadata', pos('sid'), '--select=properties.title']);
+    expect(callsTo('sheets', 'datasource', c.write)).toHaveLength(1);
+  });
+
+  it('runs nothing when the user declines', async () => {
+    stub();
+    expect(json(await (await prompted({ action: 'decline' })).harness.callTool(c.tool, c.args)))
+      .toMatchObject({ cancelled: true, action: c.action });
+    expect(callsTo('sheets', 'datasource', c.write)).toHaveLength(0);
+  });
+
+  it.each(c.reads)('returns a failed read (%s) without asking or running', async (failing) => {
+    stub(failing);
+    const { harness, seen } = await prompted();
+    expect((await harness.callTool(c.tool, c.args)).isError).toBe(true);
+    expect(seen).toHaveLength(0);
+    expect(callsTo('sheets', 'datasource', c.write)).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(c.tool, c.args));
+    expect(r).toMatchObject({ reason: 'confirmation-unsupported', action: c.action });
+    expect(r.note).toMatch(/Data connectors/);
+  });
+
+  it('token fallback: changed arguments are refused, the same call runs', async () => {
+    process.env.MCP_CONFIRM_MODE = 'ask-user';
+    stub();
+    const harness = await unprompted();
+    const p1 = json(await harness.callTool(c.tool, c.args));
+    expect(p1.preview).toEqual(c.details);
+    expect(json(await harness.callTool(c.tool, { ...c.args, ...c.changed, confirmToken: p1.confirmToken })))
+      .toMatchObject({ error: 'DRAFT_CHANGED' });
+    await harness.callTool(c.tool, { ...c.args, confirmToken: p1.confirmToken });
+    expect(callsTo('sheets', 'datasource', c.write)).toHaveLength(1);
+  });
+});
+
+it('a query-backed add previews the SQL', async () => {
+  stub();
+  const { harness, details } = await prompted({ action: 'decline' });
+  await harness.callTool('gog_sheets_datasource_add', { spreadsheetId: 'sid', billingProject: 'b', query: 'SELECT 9', });
+  expect(details()).toEqual({ spreadsheet: SHEET, billingProject: 'b', query: 'SELECT 9' });
+});
+
+it('a table in another project names that project', async () => {
+  stub();
+  const { harness, details } = await prompted({ action: 'decline' });
+  await harness.callTool('gog_sheets_datasource_add', { spreadsheetId: 'sid', billingProject: 'b', tableProject: 'p', dataset: 'd', table: 't' });
+  expect(details().table).toBe('p.d.t');
+});
+
+describe('parsers', () => {
+  it('spreadsheetTitle reads either shape and tolerates unreadable output', () => {
+    expect(spreadsheetTitle(JSON.stringify({ spreadsheet: { properties: { title: 'A' } } }))).toBe('A');
+    expect(spreadsheetTitle(JSON.stringify({ properties: { title: 7 } }))).toBeUndefined();
+    expect(spreadsheetTitle('null')).toBeUndefined();
+    expect(spreadsheetTitle(undefined)).toBeUndefined();
+  });
+
+  it('dataSourceSnapshot names a table source, a bare spec, and nothing for unreadable output', () => {
+    expect(dataSourceSnapshot(JSON.stringify({ spec: { bigQuery: { tableSpec: { tableProjectId: 'p', datasetId: 'd', tableId: 't' } } } })))
+      .toEqual({ table: 'p.d.t' });
+    expect(dataSourceSnapshot(JSON.stringify({ dataSource: { spec: { bigQuery: { projectId: 7 } } } }))).toEqual({});
+    expect(dataSourceSnapshot('null')).toEqual({});
+    expect(dataSourceSnapshot('nope')).toEqual({});
+  });
+});

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

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