gogcli-mcp-sheets 4.5.2 → 4.6.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
-    "version": "4.5.2"
+    "version": "4.6.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli (Sheets)",
       "source": "./",
       "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
-      "version": "4.5.2",
+      "version": "4.6.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp-sheets",
   "displayName": "gogcli (Sheets)",
-  "version": "4.5.2",
+  "version": "4.6.0",
   "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
   "author": {
     "name": "Chris Hall",

package/dist/index.js

@@ -36369,6 +36369,9 @@ function countNonEmptyCells(getOutput) {
 var DATASOURCE_ALIASES = /* @__PURE__ */ new Set(["datasource", "data-source", "data-sources", "connected-sheets"]);
 var DATASOURCE_BILLED = /* @__PURE__ */ new Set(["add", "update", "refresh"]);
 function vetSheetsRun(subcommand, args) {
+  if (subcommand.toLowerCase() === "batch-request") {
+    return gatedElsewhere("gog sheets batch-request", "gog_sheets_run", "applies structural changes to a spreadsheet", "gog_sheets_batch_request");
+  }
   if (!DATASOURCE_ALIASES.has(subcommand.toLowerCase())) return void 0;
   const word = hasCommandWord(args, DATASOURCE_BILLED)?.toLowerCase();
   return word ? gatedElsewhere(`gog sheets datasource ${word}`, "gog_sheets_run", "runs a billed BigQuery job", `gog_sheets_datasource_${word}`) : void 0;
@@ -36492,7 +36495,7 @@ function registerSheetsTools(server) {
 }
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "4.5.2" : "0.0.0";
+var VERSION = true ? "4.6.0" : "0.0.0";
 
 // ../gogcli-mcp/src/bootstrap-auth.ts
 import { join as join5 } from "node:path";
@@ -36655,6 +36658,35 @@ async function confirmBilledExecution(ctx, o) {
   });
 }
 function registerExtraSheetsTools(server) {
+  server.registerTool("gog_sheets_batch_begin", {
+    description: "Open a persisted, revision-locked Sheets request batch. Pass its returned batchId to gog_sheets_batch_request using batch=<id>; no spreadsheet changes are submitted until gog_sheets_batch_end.",
+    annotations: { destructiveHint: false },
+    inputSchema: external_exports.object({ spreadsheetId: external_exports.string().describe("Spreadsheet ID the batch is locked to"), name: external_exports.string().optional().describe("Optional batch label"), account: accountParam })
+  }, async ({ spreadsheetId, name, account }) => {
+    const args = ["batch", "begin", `--service=sheets`, `--spreadsheet=${spreadsheetId}`];
+    if (name) args.push(`--name=${name}`);
+    return runOrDiagnose(args, { account });
+  });
+  server.registerTool("gog_sheets_batch_end", {
+    description: "Submit a persisted Sheets request batch atomically against its locked revision. The queued requests are shown for review and require confirmation before they are applied.",
+    annotations: { destructiveHint: true },
+    inputSchema: external_exports.object({ batchId: external_exports.string().describe("Batch ID returned by gog_sheets_batch_begin"), account: accountParam, confirmToken: confirmTokenParam })
+  }, async ({ batchId, account, confirmToken }, ctx) => {
+    const previewResult = await runOrDiagnose(["batch", "show", pos(batchId)], { account });
+    if (previewResult.isError) return previewResult;
+    const preview = resultText2(previewResult);
+    if (preview === void 0) throw new Error("gog returned no queued batch preview; refusing to submit an unreviewed batch.");
+    if (Buffer.byteLength(preview, "utf8") > 1e5) throw new Error("The queued batch is too large to review safely through this tool; inspect and submit it with gog directly.");
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: "sheets.batch-end",
+      message: "Review and confirm applying the queued Sheets requests:",
+      confirmationLabel: "Confirm applying this atomic Sheets batch.",
+      details: { batchId, queuedBatch: preview },
+      fallback: { tool: "gog_sheets_batch_end", account, confirmToken, subject: () => ({ target: batchId, payload: { queuedBatch: preview }, preview: { batchId, queuedBatch: preview } }) }
+    });
+    if (confirmation) return confirmation;
+    return runOrDiagnose(["batch", "end", pos(batchId), "--force"], { account });
+  });
   server.registerTool("gog_sheets_list_tabs", {
     description: "List tabs (sheets) in a spreadsheet with their titles, sheetIds, and indices. A friendlier view than gog_sheets_metadata when you only need the tab list \u2014 useful for restructuring a workbook over a long agent session without losing track of names.",
     annotations: { readOnlyHint: true },
@@ -37180,6 +37212,54 @@ ${resultText2(result) ?? ""}` }] };
     if (responseDateTimeRender) args.push(`--response-date-time-render=${responseDateTimeRender}`);
     return runOrDiagnose(args, { account });
   });
+  server.registerTool("gog_sheets_batch_request", {
+    description: "Submit a Google Sheets API structural request array atomically (for example addDimension, repeatCell, mergeCells, or updateSheetProperties). requestsJson must be a JSON array of Sheets API Request objects. Requests are previewed and require confirmation before submission. Use batch=<id> to append these requests to a persisted Sheets batch instead of submitting immediately.",
+    annotations: { destructiveHint: true },
+    inputSchema: external_exports.object({
+      spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
+      requestsJson: external_exports.string().describe('JSON array of Google Sheets API Request objects, e.g. [{"addSheet":{"properties":{"title":"Archive"}}}]'),
+      batch: external_exports.string().optional().describe("Persisted Sheets batch ID; append requests without submitting yet"),
+      account: accountParam,
+      confirmToken: confirmTokenParam
+    })
+  }, async ({ spreadsheetId, requestsJson, batch, account, confirmToken }, ctx) => {
+    confineAtFile(requestsJson, "requestsJson");
+    let requests;
+    try {
+      requests = JSON.parse(requestsJson);
+    } catch {
+      throw new Error("requestsJson must be valid JSON");
+    }
+    if (!Array.isArray(requests) || requests.length === 0) throw new Error("requestsJson must be a non-empty JSON array");
+    if (Buffer.byteLength(requestsJson, "utf8") > 1e5) throw new Error("requestsJson exceeds the 100 KB inline limit; split the requests across persisted batches");
+    const args = ["sheets", "batch-request", pos(spreadsheetId), `--requests-json=${requestsJson}`];
+    if (batch) {
+      args.push(`--batch=${batch}`);
+      return runOrDiagnose(args, { account });
+    }
+    const got = await runOrDiagnose(["sheets", "metadata", pos(spreadsheetId), "--select=properties.title"], { account });
+    if (got.isError) return got;
+    const title = spreadsheetTitle(resultText2(got));
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: "sheets.batch-request",
+      message: "Review and confirm these structural changes to the spreadsheet:",
+      confirmationLabel: "Confirm submitting this atomic Sheets request batch.",
+      details: {
+        spreadsheet: { id: spreadsheetId, ...title !== void 0 ? { title } : {} },
+        requestCount: requests.length,
+        requests
+      },
+      fallback: {
+        tool: "gog_sheets_batch_request",
+        account,
+        confirmToken,
+        subject: () => ({ target: spreadsheetId, payload: { requests }, preview: { requestCount: requests.length, requests } })
+      }
+    });
+    if (confirmation) return confirmation;
+    args.push("--force");
+    return runOrDiagnose(args, { account });
+  });
   server.registerTool("gog_sheets_reorder_tab", {
     description: "Move a tab to a specific 0-based position. `tab` is the tab name or numeric sheetId; `to=0` is the leftmost slot.",
     annotations: { destructiveHint: true },

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-sheets",
   "display_name": "gogcli (Sheets)",
-  "version": "4.5.2",
+  "version": "4.6.0",
   "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
   "author": {
     "name": "Chris Hall",
@@ -362,6 +362,18 @@
     {
       "name": "gog_sheets_datasource_delete",
       "description": "Delete a Connected Sheets data source and its linked sheet"
+    },
+    {
+      "name": "gog_sheets_batch_request",
+      "description": "Submit an atomic array of Google Sheets structural requests after confirmation."
+    },
+    {
+      "name": "gog_sheets_batch_begin",
+      "description": "Open a revision-locked Sheets request batch."
+    },
+    {
+      "name": "gog_sheets_batch_end",
+      "description": "Review and atomically submit a Sheets request batch after confirmation."
     }
   ],
   "compatibility": {

package/mint.yaml

@@ -92,7 +92,7 @@ dependencies:
   # bumping these nine pins, and the pin stored on each mcp-host registration.
   - kind: github-release
     repo: openclaw/gogcli
-    tag: v0.41.0
+    tag: v0.43.0
     asset: "gogcli_*_linux_amd64.tar.gz"
     bin: [gog]
 state:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-sheets",
-  "version": "4.5.2",
+  "version": "4.6.0",
   "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>",

package/server.json

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

package/src/tools/sheets-extra.ts

@@ -166,6 +166,37 @@ async function confirmBilledExecution(
 
 export function registerExtraSheetsTools(server: McpServer): void {
 
+  server.registerTool('gog_sheets_batch_begin', {
+    description: 'Open a persisted, revision-locked Sheets request batch. Pass its returned batchId to gog_sheets_batch_request using batch=<id>; no spreadsheet changes are submitted until gog_sheets_batch_end.',
+    annotations: { destructiveHint: false },
+    inputSchema: z.object({ spreadsheetId: z.string().describe('Spreadsheet ID the batch is locked to'), name: z.string().optional().describe('Optional batch label'), account: accountParam }),
+  }, async ({ spreadsheetId, name, account }) => {
+    const args: GogArg[] = ['batch', 'begin', `--service=sheets`, `--spreadsheet=${spreadsheetId}`];
+    if (name) args.push(`--name=${name}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_sheets_batch_end', {
+    description: 'Submit a persisted Sheets request batch atomically against its locked revision. The queued requests are shown for review and require confirmation before they are applied.',
+    annotations: { destructiveHint: true },
+    inputSchema: z.object({ batchId: z.string().describe('Batch ID returned by gog_sheets_batch_begin'), account: accountParam, confirmToken: confirmTokenParam }),
+  }, async ({ batchId, account, confirmToken }, ctx) => {
+    const previewResult = await runOrDiagnose(['batch', 'show', pos(batchId)], { account });
+    if (previewResult.isError) return previewResult;
+    const preview = resultText(previewResult);
+    if (preview === undefined) throw new Error('gog returned no queued batch preview; refusing to submit an unreviewed batch.');
+    if (Buffer.byteLength(preview, 'utf8') > 100_000) throw new Error('The queued batch is too large to review safely through this tool; inspect and submit it with gog directly.');
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: 'sheets.batch-end',
+      message: 'Review and confirm applying the queued Sheets requests:',
+      confirmationLabel: 'Confirm applying this atomic Sheets batch.',
+      details: { batchId, queuedBatch: preview },
+      fallback: { tool: 'gog_sheets_batch_end', account, confirmToken, subject: () => ({ target: batchId, payload: { queuedBatch: preview }, preview: { batchId, queuedBatch: preview } }) },
+    });
+    if (confirmation) return confirmation;
+    return runOrDiagnose(['batch', 'end', pos(batchId), '--force'], { account });
+  });
+
   server.registerTool('gog_sheets_list_tabs', {
     description: 'List tabs (sheets) in a spreadsheet with their titles, sheetIds, and indices. A friendlier view than gog_sheets_metadata when you only need the tab list — useful for restructuring a workbook over a long agent session without losing track of names.',
     annotations: { readOnlyHint: true },
@@ -734,6 +765,49 @@ export function registerExtraSheetsTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
+  server.registerTool('gog_sheets_batch_request', {
+    description: 'Submit a Google Sheets API structural request array atomically (for example addDimension, repeatCell, mergeCells, or updateSheetProperties). requestsJson must be a JSON array of Sheets API Request objects. Requests are previewed and require confirmation before submission. Use batch=<id> to append these requests to a persisted Sheets batch instead of submitting immediately.',
+    annotations: { destructiveHint: true },
+    inputSchema: z.object({
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      requestsJson: z.string().describe('JSON array of Google Sheets API Request objects, e.g. [{"addSheet":{"properties":{"title":"Archive"}}}]'),
+      batch: z.string().optional().describe('Persisted Sheets batch ID; append requests without submitting yet'),
+      account: accountParam,
+      confirmToken: confirmTokenParam,
+    }),
+  }, async ({ spreadsheetId, requestsJson, batch, account, confirmToken }, ctx) => {
+    confineAtFile(requestsJson, 'requestsJson');
+    let requests: unknown;
+    try { requests = JSON.parse(requestsJson); } catch { throw new Error('requestsJson must be valid JSON'); }
+    if (!Array.isArray(requests) || requests.length === 0) throw new Error('requestsJson must be a non-empty JSON array');
+    if (Buffer.byteLength(requestsJson, 'utf8') > 100_000) throw new Error('requestsJson exceeds the 100 KB inline limit; split the requests across persisted batches');
+    const args: GogArg[] = ['sheets', 'batch-request', pos(spreadsheetId), `--requests-json=${requestsJson}`];
+    if (batch) {
+      args.push(`--batch=${batch}`);
+      return runOrDiagnose(args, { account });
+    }
+    const got = await runOrDiagnose(['sheets', 'metadata', pos(spreadsheetId), '--select=properties.title'], { account });
+    if (got.isError) return got;
+    const title = spreadsheetTitle(resultText(got));
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: 'sheets.batch-request',
+      message: 'Review and confirm these structural changes to the spreadsheet:',
+      confirmationLabel: 'Confirm submitting this atomic Sheets request batch.',
+      details: {
+        spreadsheet: { id: spreadsheetId, ...(title !== undefined ? { title } : {}) },
+        requestCount: requests.length,
+        requests,
+      },
+      fallback: {
+        tool: 'gog_sheets_batch_request', account, confirmToken,
+        subject: () => ({ target: spreadsheetId, payload: { requests }, preview: { requestCount: requests.length, requests } }),
+      },
+    });
+    if (confirmation) return confirmation;
+    args.push('--force');
+    return runOrDiagnose(args, { account });
+  });
+
   server.registerTool('gog_sheets_reorder_tab', {
     description: 'Move a tab to a specific 0-based position. `tab` is the tab name or numeric sheetId; `to=0` is the leftmost slot.',
     annotations: { destructiveHint: true },

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

@@ -894,6 +894,121 @@ describe('gog_sheets_batch_update', () => {
   });
 });
 
+describe('gog_sheets_batch_request', () => {
+  it('opens a revision-locked Sheets batch', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_batch_begin', { spreadsheetId: 'sid', name: 'quarterly' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['batch', 'begin', '--service=sheets', '--spreadsheet=sid', '--name=quarterly'], { account: undefined });
+    await harness.callTool('gog_sheets_batch_begin', { spreadsheetId: 'sid' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['batch', 'begin', '--service=sheets', '--spreadsheet=sid'], { account: undefined });
+  });
+
+  it('shows and confirms the queued requests before ending a batch', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{"requests":[{"addSheet":{}}]}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_batch_end', { batchId: 'batch-1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['batch', 'show', pos('batch-1')], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['batch', 'end', pos('batch-1'), '--force'], { account: undefined });
+  });
+
+  it('does not end a batch when the preview fails or is too large', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue({ isError: true, content: [{ type: 'text', text: 'failed' }] });
+    const harness = await setupHandlers();
+    expect((await harness.callTool('gog_sheets_batch_end', { batchId: 'batch-1' })).isError).toBe(true);
+    expect(lib.runOrDiagnose).toHaveBeenCalledTimes(1);
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('x'.repeat(100_001)));
+    expect((await harness.callTool('gog_sheets_batch_end', { batchId: 'batch-1' })).isError).toBe(true);
+    expect(lib.runOrDiagnose).toHaveBeenCalledTimes(2);
+  });
+
+  it('refuses to submit when gog returns no batch preview', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue({ content: [] });
+    const harness = await setupHandlers();
+    expect((await harness.callTool('gog_sheets_batch_end', { batchId: 'batch-1' })).isError).toBe(true);
+    expect(lib.runOrDiagnose).toHaveBeenCalledTimes(1);
+  });
+
+  it('confirms an unprompted client using a one-time token bound to the queued requests', async () => {
+    process.env.MCP_CONFIRM_MODE = 'ask-user';
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{"requests":[{"addSheet":{}}]}'));
+    const harness = await createTestHarness(registerExtraSheetsTools);
+    const preview = await harness.callTool('gog_sheets_batch_end', { batchId: 'batch-1' });
+    const payload = JSON.parse(preview.content[0]!.text!);
+    await harness.callTool('gog_sheets_batch_end', { batchId: 'batch-1', confirmToken: payload.confirmToken });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['batch', 'end', pos('batch-1'), '--force'], { account: undefined });
+    delete process.env.MCP_CONFIRM_MODE;
+  });
+
+  it('confirms and submits a structural request array atomically', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{"properties":{"title":"Plan"}}'));
+    const harness = await setupHandlers();
+    const requestsJson = '[{"addSheet":{"properties":{"title":"Archive"}}}]';
+    await harness.callTool('gog_sheets_batch_request', { spreadsheetId: 'sid', requestsJson });
+    expect(lib.runOrDiagnose).toHaveBeenNthCalledWith(1,
+      ['sheets', 'metadata', pos('sid'), '--select=properties.title'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'batch-request', pos('sid'), `--requests-json=${requestsJson}`, '--force'], { account: undefined });
+  });
+
+  it('appends requests to a persisted batch without submitting or prompting', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    const requestsJson = '[{"addSheet":{"properties":{"title":"Archive"}}}]';
+    await harness.callTool('gog_sheets_batch_request', { spreadsheetId: 'sid', requestsJson, batch: 'batch-1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'batch-request', pos('sid'), `--requests-json=${requestsJson}`, '--batch=batch-1'], { account: undefined });
+  });
+
+  it('rejects malformed or empty request arrays before calling gog', async () => {
+    const harness = await setupHandlers();
+    const malformed = await harness.callTool('gog_sheets_batch_request', { spreadsheetId: 'sid', requestsJson: '{' });
+    expect(malformed.isError).toBe(true);
+    const empty = await harness.callTool('gog_sheets_batch_request', { spreadsheetId: 'sid', requestsJson: '[]' });
+    expect(empty.isError).toBe(true);
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+
+  it('rejects request payloads that exceed the safe argv size', async () => {
+    const harness = await setupHandlers();
+    const result = await harness.callTool('gog_sheets_batch_request', {
+      spreadsheetId: 'sid', requestsJson: JSON.stringify([{ updateCells: { userEnteredValue: { stringValue: 'x'.repeat(100_001) } } }]),
+    });
+    expect(result.isError).toBe(true);
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+
+  it('does not submit if the title lookup fails', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue({ isError: true, content: [{ type: 'text', text: 'failed' }] });
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_batch_request', { spreadsheetId: 'sid', requestsJson: '[{"addSheet":{}}]' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledTimes(1);
+  });
+
+  it('confirms by spreadsheet ID when metadata has no title', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_batch_request', { spreadsheetId: 'sid', requestsJson: '[{"addSheet":{}}]' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'batch-request', pos('sid'), '--requests-json=[{"addSheet":{}}]', '--force'], { account: undefined });
+  });
+
+  it('uses a one-time token when the client cannot prompt', async () => {
+    process.env.MCP_CONFIRM_MODE = 'ask-user';
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{"properties":{"title":"Plan"}}'));
+    const harness = await createTestHarness(registerExtraSheetsTools);
+    const args = { spreadsheetId: 'sid', requestsJson: '[{"addSheet":{"properties":{"title":"Archive"}}}]' };
+    const preview = await harness.callTool('gog_sheets_batch_request', args);
+    const payload = JSON.parse(preview.content[0]!.text!);
+    await harness.callTool('gog_sheets_batch_request', { ...args, confirmToken: payload.confirmToken });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'batch-request', pos('sid'), `--requests-json=${args.requestsJson}`, '--force'], { account: undefined });
+    delete process.env.MCP_CONFIRM_MODE;
+  });
+});
+
 // 24. reorder-tab (gog 0.18.0)
 describe('gog_sheets_reorder_tab', () => {
   it('passes --tab and --to', async () => {