gogcli-mcp-sheets 2.8.0 → 2.18.1

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-sheets",
   "display_name": "gogcli (Sheets)",
-  "version": "2.8.0",
+  "version": "2.18.1",
   "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
   "author": {
     "name": "Chris Hall",
@@ -60,6 +60,18 @@
       "name": "gog_auth_add",
       "description": "Authorize a Google account via browser-based OAuth"
     },
+    {
+      "name": "gog_auth_health",
+      "description": "Live per-account token health: validity, age, and pre-expiry warnings (detects invalid_grant)"
+    },
+    {
+      "name": "gog_auth_add_url",
+      "description": "Begin remote/headless OAuth (step 1): return a sign-in URL to open in any browser"
+    },
+    {
+      "name": "gog_auth_add_complete",
+      "description": "Complete remote/headless OAuth (step 2): exchange the pasted redirect URL and store the token"
+    },
     {
       "name": "gog_auth_list",
       "description": "List all Google accounts stored in gogcli"
@@ -292,13 +304,17 @@
       "name": "gog_sheets_banding_clear",
       "description": "Remove alternating-color banding by ID or for a whole sheet."
     },
+    {
+      "name": "gog_sheets_filter_set",
+      "description": "Set a basic filter on a range; replacing an existing filter requires replace=true."
+    },
     {
       "name": "gog_sheets_conditional_format_list",
       "description": "List conditional formatting rules."
     },
     {
       "name": "gog_sheets_conditional_format_add",
-      "description": "Add a conditional formatting rule to a range."
+      "description": "Add a conditional formatting rule to a range (boolean or gradient)."
     },
     {
       "name": "gog_sheets_conditional_format_clear",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-sheets",
-  "version": "2.8.0",
+  "version": "2.18.1",
   "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>",
@@ -19,11 +19,12 @@
     "build": "tsc --noEmit && npm run bundle",
     "bundle": "node ../../scripts/bundle.js src/index.ts dist/index.js",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "vitest run --coverage",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
+    "@chrischall/mcp-utils": "^0.13.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3"
   },

package/server.json

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

package/src/index.ts

@@ -1,12 +1,10 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createServer, registerAuthTools, registerSheetsTools } from '../../gogcli-mcp/src/lib.js';
+import { runMcp } from '@chrischall/mcp-utils';
+import { VERSION, authToolsFor, registerSheetsTools } from '../../gogcli-mcp/src/lib.js';
 import { registerExtraSheetsTools } from './tools/sheets-extra.js';
 
-const server = createServer({ name: 'gogcli-sheets' });
-registerAuthTools(server);
-registerSheetsTools(server);
-registerExtraSheetsTools(server);
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
+await runMcp({
+  name: 'gogcli-sheets',
+  version: VERSION,
+  tools: [authToolsFor('sheets'), registerSheetsTools, registerExtraSheetsTools],
+});

package/src/tools/sheets-extra.ts

@@ -1,6 +1,15 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose, run, diagnose, toText, toError } from '../../../gogcli-mcp/src/lib.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { rawTextResult } from '@chrischall/mcp-utils';
+import { accountParam, runOrDiagnose, run, diagnose, errorText, payloadArg } from '../../../gogcli-mcp/src/lib.js';
+
+// Pull the text out of a single-text-block tool result; undefined for any
+// other shape (error results are still text blocks, so they parse below).
+function resultText(result: CallToolResult): string | undefined {
+  const first = result.content[0];
+  return first?.type === 'text' ? first.text : undefined;
+}
 
 // Convert a CSS-style hex color ("#FFF5D9", "#FD9", "FFF5D9") to the
 // {red, green, blue} 0-1 float triple that Sheets API CellFormat expects.
@@ -40,7 +49,7 @@ async function checkDateFormatTarget(
   );
   let parsed: { values?: unknown[][] };
   try {
-    parsed = JSON.parse(peek.content[0].text) as { values?: unknown[][] };
+    parsed = JSON.parse(resultText(peek) ?? '') as { values?: unknown[][] };
   } catch {
     return null;
   }
@@ -104,7 +113,7 @@ export function registerExtraSheetsTools(server: McpServer): void {
       account: accountParam,
     },
   }, async ({ spreadsheetId, tabName, account }) => {
-    return runOrDiagnose(['sheets', 'delete-tab', spreadsheetId, tabName], { account });
+    return runOrDiagnose(['sheets', 'delete-tab', spreadsheetId, tabName, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_sheets_rename_tab', {
@@ -141,12 +150,14 @@ export function registerExtraSheetsTools(server: McpServer): void {
       spreadsheetId: z.string().describe('Spreadsheet ID'),
       format: z.string().optional().describe('Export format: csv, tsv, pdf (default: csv)'),
       out: z.string().optional().describe('Output file path'),
+      overwrite: z.boolean().optional().describe('Overwrite the output file if it already exists (gog refuses otherwise)'),
       account: accountParam,
     },
-  }, async ({ spreadsheetId, format, out, account }) => {
+  }, async ({ spreadsheetId, format, out, overwrite, account }) => {
     const args = ['sheets', 'export', spreadsheetId];
     if (format) args.push(`--format=${format}`);
     if (out) args.push(`--out=${out}`);
+    if (overwrite) args.push('--overwrite');
     return runOrDiagnose(args, { account });
   });
 
@@ -350,7 +361,7 @@ export function registerExtraSheetsTools(server: McpServer): void {
     if (pattern) args.push(`--pattern=${pattern}`);
     const result = await runOrDiagnose(args, { account });
     if (warning) {
-      return { content: [{ type: 'text' as const, text: `${warning}\n\n${result.content[0].text}` }] };
+      return { ...result, content: [{ type: 'text' as const, text: `${warning}\n\n${resultText(result) ?? ''}` }] };
     }
     return result;
   });
@@ -422,11 +433,18 @@ export function registerExtraSheetsTools(server: McpServer): void {
     inputSchema: {
       spreadsheetId: z.string().describe('Spreadsheet ID'),
       range: z.string().describe('Cell or range to set the note on (e.g. Sheet1!A1)'),
-      note: z.string().describe('Note text (empty string clears the note)'),
+      note: z.string().describe('Note text (empty string clears the note). Large notes are written to a temp file and passed to gog as --note-file automatically.'),
       account: accountParam,
     },
   }, async ({ spreadsheetId, range, note, account }) => {
-    return runOrDiagnose(['sheets', 'update-note', spreadsheetId, range, `--note=${note}`], { account });
+    // payloadArg keeps normal notes on `--note=` and spills a large one to a
+    // temp file passed as `--note-file`, so it can't blow the argv size cap.
+    // The wrapper exposes no noteFile param, so there is no both-flags case to
+    // guard here (gog would accept both anyway, letting the file win).
+    return runOrDiagnose(
+      ['sheets', 'update-note', spreadsheetId, range, payloadArg('note', 'note-file', note)],
+      { account },
+    );
   });
 
   server.registerTool('gog_sheets_links', {
@@ -532,6 +550,7 @@ export function registerExtraSheetsTools(server: McpServer): void {
     const args = ['sheets', 'delete-dimension', spreadsheetId, rangeOrSheet, `--dimension=${dimension}`];
     if (start !== undefined) args.push(`--start=${start}`);
     if (end !== undefined) args.push(`--end=${end}`);
+    args.push('--force'); // gog gates this op; without --force the runner's --no-input makes it refuse
     return runOrDiagnose(args, { account });
   });
 
@@ -706,7 +725,7 @@ export function registerExtraSheetsTools(server: McpServer): void {
       account: accountParam,
     },
   }, async ({ spreadsheetId, chartId, account }) => {
-    return runOrDiagnose(['sheets', 'chart', 'delete', spreadsheetId, chartId], { account });
+    return runOrDiagnose(['sheets', 'chart', 'delete', spreadsheetId, chartId, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   // ---- Tables (gog 0.19.0) ----
@@ -774,7 +793,7 @@ export function registerExtraSheetsTools(server: McpServer): void {
       account: accountParam,
     },
   }, async ({ spreadsheetId, tableId, account }) => {
-    return runOrDiagnose(['sheets', 'table', 'clear', spreadsheetId, tableId], { account });
+    return runOrDiagnose(['sheets', 'table', 'clear', spreadsheetId, tableId, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_sheets_table_delete', {
@@ -833,15 +852,15 @@ export function registerExtraSheetsTools(server: McpServer): void {
         // The table is already gone but the restore write failed. Hand the
         // read-back data straight back so it can be re-applied manually rather
         // than silently lost.
-        return toText(
+        return rawTextResult(
           `Table ${tableId} was deleted, but restoring its data FAILED — re-apply the values below manually.\n\n` +
           `Range: ${range}\nValues: ${JSON.stringify(values)}\n\n` +
-          `${toError(err).content[0].text}`,
+          `${errorText(err)}`,
         );
       }
     }
 
-    return toText(`Deleted table ${tableId} and preserved ${values.length} row(s) of data (values + formulas) in ${range}.`);
+    return rawTextResult(`Deleted table ${tableId} and preserved ${values.length} row(s) of data (values + formulas) in ${range}.`);
   });
 
   // ---- Banding / alternating colors (gog 0.19.0) ----
@@ -891,6 +910,23 @@ export function registerExtraSheetsTools(server: McpServer): void {
     if (id !== undefined) args.push(`--id=${id}`);
     if (all) args.push('--all');
     if (sheet) args.push(`--sheet=${sheet}`);
+    args.push('--force'); // gog gates this op; without --force the runner's --no-input makes it refuse
+    return runOrDiagnose(args, { account });
+  });
+
+  // ---- Basic filters (gog 0.33.0) ----
+
+  server.registerTool('gog_sheets_filter_set', {
+    description: 'Set a basic filter on a range (the filter/sort header Sheets shows on a data range). A sheet can hold one basic filter; replacing an existing one requires replace=true — without it, gog refuses rather than silently overwriting.',
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      range: z.string().describe('Range to filter (A1 notation with sheet name, e.g. Sheet1!A1:C100, or a named range name)'),
+      replace: z.boolean().optional().describe('Replace the sheet\'s existing basic filter if one is set (appends --force)'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, range, replace, account }) => {
+    const args = ['sheets', 'filter', 'set', spreadsheetId, range];
+    if (replace) args.push('--force');
     return runOrDiagnose(args, { account });
   });
 
@@ -911,7 +947,7 @@ export function registerExtraSheetsTools(server: McpServer): void {
   });
 
   server.registerTool('gog_sheets_conditional_format_add', {
-    description: 'Add a conditional formatting rule to a range. type picks the condition; expr is its value/formula (omit for blank/not-blank). formatJson is the CellFormat to apply when the condition matches (inline or @file). Use formatFields to force-send zero/false fields (e.g. backgroundColor,textFormat.bold).',
+    description: 'Add a conditional formatting rule to a range. Boolean rules: type picks the condition, expr is its value/formula (omit for blank/not-blank), formatJson is the CellFormat to apply when the condition matches (inline or @file); use formatFields to force-send zero/false fields (e.g. backgroundColor,textFormat.bold). Gradient rules (color scales): pass gradientRuleJson instead — a GradientRule JSON with minpoint/maxpoint (and optional midpoint), each {"color":{...},"type":"MIN|MAX|NUMBER|PERCENT|PERCENTILE","value":"..."}. The two modes are mutually exclusive.',
     inputSchema: {
       spreadsheetId: z.string().describe('Spreadsheet ID'),
       range: z.string().describe('Range the rule applies to (e.g. Sheet1!A1:A100)'),
@@ -919,16 +955,20 @@ export function registerExtraSheetsTools(server: McpServer): void {
         'text-eq', 'text-contains', 'text-starts-with', 'text-ends-with',
         'number-eq', 'number-gt', 'number-gte', 'number-lt', 'number-lte',
         'blank', 'not-blank', 'custom-formula',
-      ]).describe('Rule type'),
-      formatJson: z.string().describe('CellFormat JSON to apply when the condition matches (inline or @file)'),
+      ]).optional().describe('Boolean rule type (required unless gradientRuleJson is used)'),
+      formatJson: z.string().optional().describe('CellFormat JSON to apply when a boolean rule matches (inline or @file; required with type)'),
       expr: z.string().optional().describe('Expression value or custom formula (omit for blank/not-blank)'),
       formatFields: z.string().optional().describe('Format field mask for force-sending zero/false fields (e.g. backgroundColor,textFormat.bold)'),
+      gradientRuleJson: z.string().optional().describe('GradientRule JSON for gradient conditional formats (inline or @file; must include minpoint and maxpoint)'),
       account: accountParam,
     },
-  }, async ({ spreadsheetId, range, type, formatJson, expr, formatFields, account }) => {
-    const args = ['sheets', 'conditional-format', 'add', spreadsheetId, range, `--type=${type}`, `--format-json=${formatJson}`];
+  }, async ({ spreadsheetId, range, type, formatJson, expr, formatFields, gradientRuleJson, account }) => {
+    const args = ['sheets', 'conditional-format', 'add', spreadsheetId, range];
+    if (type) args.push(`--type=${type}`);
+    if (formatJson !== undefined) args.push(`--format-json=${formatJson}`);
     if (expr !== undefined) args.push(`--expr=${expr}`);
     if (formatFields) args.push(`--format-fields=${formatFields}`);
+    if (gradientRuleJson !== undefined) args.push(`--gradient-rule-json=${gradientRuleJson}`);
     return runOrDiagnose(args, { account });
   });
 
@@ -946,6 +986,7 @@ export function registerExtraSheetsTools(server: McpServer): void {
     const args = ['sheets', 'conditional-format', 'clear', spreadsheetId, `--sheet=${sheet}`];
     if (index !== undefined) args.push(`--index=${index}`);
     if (all) args.push('--all');
+    args.push('--force'); // gog gates this op; without --force the runner's --no-input makes it refuse
     return runOrDiagnose(args, { account });
   });