gogcli-mcp-sheets 2.0.9 → 2.0.10

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/dist/index.js

@@ -31219,6 +31219,7 @@ function registerAuthTools(server2) {
 }
 
 // ../gogcli-mcp/src/tools/sheets.ts
+var cellValueParam = external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean(), external_exports.null()]);
 function registerSheetsTools(server2) {
   server2.registerTool("gog_sheets_get", {
     description: 'Read values from a Google Sheets range. Returns a JSON object with a "values" array of rows.',
@@ -31232,12 +31233,12 @@ function registerSheetsTools(server2) {
     return runOrDiagnose(["sheets", "get", spreadsheetId, range], { account });
   });
   server2.registerTool("gog_sheets_update", {
-    description: "Write values to a Google Sheets range, overwriting existing content.",
+    description: 'Write values to a Google Sheets range, overwriting existing content. Values may be strings, numbers, booleans, or null. Strings starting with "=" are interpreted as formulas (e.g. "=SUM(A1:A10)").',
     annotations: { destructiveHint: true },
     inputSchema: {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID (from the URL)"),
       range: external_exports.string().describe("Top-left cell or range in A1 notation, e.g. Sheet1!A1"),
-      values: external_exports.array(external_exports.array(external_exports.string())).describe("2D array of values: outer array is rows, inner is columns"),
+      values: external_exports.array(external_exports.array(cellValueParam)).describe('2D array of values (rows of columns). Cells may be string/number/boolean/null; strings starting with "=" are formulas.'),
       account: accountParam
     }
   }, async ({ spreadsheetId, range, values, account }) => {
@@ -31247,12 +31248,12 @@ function registerSheetsTools(server2) {
     );
   });
   server2.registerTool("gog_sheets_append", {
-    description: "Append rows to a Google Sheet after the last row with data in the given range.",
+    description: 'Append rows to a Google Sheet after the last row with data in the given range. Values may be strings, numbers, booleans, or null. Strings starting with "=" are interpreted as formulas.',
     annotations: { destructiveHint: true },
     inputSchema: {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID (from the URL)"),
       range: external_exports.string().describe("Range indicating which sheet/columns to append to, e.g. Sheet1!A:C"),
-      values: external_exports.array(external_exports.array(external_exports.string())).describe("2D array of rows to append"),
+      values: external_exports.array(external_exports.array(cellValueParam)).describe('2D array of rows to append. Cells may be string/number/boolean/null; strings starting with "=" are formulas.'),
       account: accountParam
     }
   }, async ({ spreadsheetId, range, values, account }) => {
@@ -31308,7 +31309,7 @@ function registerSheetsTools(server2) {
 }
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.0.9" : "0.0.0";
+var VERSION = true ? "2.0.10" : "0.0.0";
 function createServer(options) {
   return new McpServer({
     name: options?.name ?? "gogcli",
@@ -31317,7 +31318,31 @@ function createServer(options) {
 }
 
 // src/tools/sheets-extra.ts
+function hexToRgb(hex3) {
+  let h = hex3.trim().replace(/^#/, "");
+  if (h.length === 3) h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+  if (!/^[0-9a-fA-F]{6}$/.test(h)) return null;
+  const n = parseInt(h, 16);
+  return {
+    red: (n >> 16 & 255) / 255,
+    green: (n >> 8 & 255) / 255,
+    blue: (n & 255) / 255
+  };
+}
 function registerExtraSheetsTools(server2) {
+  server2.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 },
+    inputSchema: {
+      spreadsheetId: external_exports.string().describe("Spreadsheet ID (from the URL)"),
+      account: accountParam
+    }
+  }, async ({ spreadsheetId, account }) => {
+    return runOrDiagnose(
+      ["sheets", "metadata", spreadsheetId, "--select=sheets.properties.sheetId,sheets.properties.title,sheets.properties.index,sheets.properties.gridProperties"],
+      { account }
+    );
+  });
   server2.registerTool("gog_sheets_add_tab", {
     description: "Add a new sheet tab to a spreadsheet.",
     inputSchema: {
@@ -31440,19 +31465,92 @@ function registerExtraSheetsTools(server2) {
     return runOrDiagnose(["sheets", "unmerge", spreadsheetId, range], { account });
   });
   server2.registerTool("gog_sheets_format", {
-    description: "Apply cell formatting (bold, colors, alignment, etc.) to a range. Pass format as a JSON CellFormat object.",
+    description: "Apply cell formatting to a range. The named flags (bold, italic, backgroundColor, etc.) compose into a Sheets API CellFormat \u2014 use them for the 90% case. For full API control, pass formatJson + formatFields (Sheets CellFormat + field mask) directly.",
     annotations: { destructiveHint: true },
     inputSchema: {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
       range: external_exports.string().describe("Range to format (e.g. Sheet1!A1:C3)"),
-      formatJson: external_exports.string().describe('JSON CellFormat object (e.g. {"textFormat":{"bold":true}})'),
-      formatFields: external_exports.string().optional().describe("Comma-separated field mask (e.g. textFormat.bold,backgroundColor)"),
+      bold: external_exports.boolean().optional().describe("Set bold"),
+      italic: external_exports.boolean().optional().describe("Set italic"),
+      underline: external_exports.boolean().optional().describe("Set underline"),
+      strikethrough: external_exports.boolean().optional().describe("Set strikethrough"),
+      fontSize: external_exports.number().optional().describe("Font size in points"),
+      fontFamily: external_exports.string().optional().describe("Font family (e.g. Arial)"),
+      textColor: external_exports.string().optional().describe("Text color as #RRGGBB or #RGB"),
+      backgroundColor: external_exports.string().optional().describe("Cell background color as #RRGGBB or #RGB"),
+      horizontalAlignment: external_exports.enum(["LEFT", "CENTER", "RIGHT"]).optional().describe("Horizontal alignment"),
+      verticalAlignment: external_exports.enum(["TOP", "MIDDLE", "BOTTOM"]).optional().describe("Vertical alignment"),
+      wrapStrategy: external_exports.enum(["OVERFLOW_CELL", "LEGACY_WRAP", "CLIP", "WRAP"]).optional().describe("Text wrap strategy"),
+      formatJson: external_exports.string().optional().describe("Escape hatch: raw CellFormat JSON. When provided, named flags above are ignored and formatJson is sent as-is."),
+      formatFields: external_exports.string().optional().describe("Comma-separated field mask (e.g. textFormat.bold,backgroundColor). Required when using formatJson; auto-computed when using named flags."),
       account: accountParam
     }
-  }, async ({ spreadsheetId, range, formatJson, formatFields, account }) => {
-    const args = ["sheets", "format", spreadsheetId, range, `--format-json=${formatJson}`];
+  }, async (rawArgs) => {
+    const a = rawArgs;
+    let formatJson = a.formatJson;
+    let formatFields = a.formatFields;
+    if (!formatJson) {
+      const cellFormat = {};
+      const textFormat = {};
+      const fields = [];
+      if (a.bold !== void 0) {
+        textFormat.bold = a.bold;
+        fields.push("textFormat.bold");
+      }
+      if (a.italic !== void 0) {
+        textFormat.italic = a.italic;
+        fields.push("textFormat.italic");
+      }
+      if (a.underline !== void 0) {
+        textFormat.underline = a.underline;
+        fields.push("textFormat.underline");
+      }
+      if (a.strikethrough !== void 0) {
+        textFormat.strikethrough = a.strikethrough;
+        fields.push("textFormat.strikethrough");
+      }
+      if (a.fontSize !== void 0) {
+        textFormat.fontSize = a.fontSize;
+        fields.push("textFormat.fontSize");
+      }
+      if (a.fontFamily !== void 0) {
+        textFormat.fontFamily = a.fontFamily;
+        fields.push("textFormat.fontFamily");
+      }
+      if (a.textColor !== void 0) {
+        const rgb = hexToRgb(a.textColor);
+        if (!rgb) throw new Error(`Invalid textColor: ${a.textColor} (expected #RRGGBB or #RGB)`);
+        textFormat.foregroundColor = rgb;
+        fields.push("textFormat.foregroundColor");
+      }
+      if (Object.keys(textFormat).length > 0) cellFormat.textFormat = textFormat;
+      if (a.backgroundColor !== void 0) {
+        const rgb = hexToRgb(a.backgroundColor);
+        if (!rgb) throw new Error(`Invalid backgroundColor: ${a.backgroundColor} (expected #RRGGBB or #RGB)`);
+        cellFormat.backgroundColor = rgb;
+        fields.push("backgroundColor");
+      }
+      if (a.horizontalAlignment !== void 0) {
+        cellFormat.horizontalAlignment = a.horizontalAlignment;
+        fields.push("horizontalAlignment");
+      }
+      if (a.verticalAlignment !== void 0) {
+        cellFormat.verticalAlignment = a.verticalAlignment;
+        fields.push("verticalAlignment");
+      }
+      if (a.wrapStrategy !== void 0) {
+        cellFormat.wrapStrategy = a.wrapStrategy;
+        fields.push("wrapStrategy");
+      }
+      if (Object.keys(cellFormat).length === 0) {
+        throw new Error("gog_sheets_format requires at least one named flag or a formatJson value");
+      }
+      formatJson = JSON.stringify(cellFormat);
+      if (!formatFields) formatFields = fields.join(",");
+    }
+    const args = ["sheets", "format", a.spreadsheetId, a.range, `--format-json=${formatJson}`];
     if (formatFields) args.push(`--format-fields=${formatFields}`);
-    return runOrDiagnose(args, { account });
+    return runOrDiagnose(args, { account: a.account });
   });
   server2.registerTool("gog_sheets_number_format", {
     description: "Set number format on a range (currency, percentage, date, etc.).",

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-sheets",
   "display_name": "gogcli (Sheets)",
-  "version": "2.0.9",
+  "version": "2.0.10",
   "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
   "author": {
     "name": "Chris Hall",
@@ -146,7 +146,7 @@
     },
     {
       "name": "gog_sheets_format",
-      "description": "Apply cell formatting (bold, colors, alignment, etc.) to a range. Pass format as a JSON CellFormat object."
+      "description": "Apply cell formatting to a range. Named flags (bold, italic, backgroundColor, etc.) compose to a Sheets CellFormat; pass formatJson for full control."
     },
     {
       "name": "gog_sheets_number_format",
@@ -195,6 +195,10 @@
     {
       "name": "gog_sheets_named_ranges_delete",
       "description": "Delete a named range."
+    },
+    {
+      "name": "gog_sheets_list_tabs",
+      "description": "List tabs in a spreadsheet (sheetId, title, index, gridProperties)"
     }
   ],
   "compatibility": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-sheets",
-  "version": "2.0.9",
+  "version": "2.0.10",
   "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": "2.0.9",
+  "version": "2.0.10",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp-sheets",
-      "version": "2.0.9",
+      "version": "2.0.10",
       "transport": {
         "type": "stdio"
       },

package/src/tools/sheets-extra.ts

@@ -2,8 +2,39 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { accountParam, runOrDiagnose } from '../../../gogcli-mcp/src/lib.js';
 
+// 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
+// or error.
+export function hexToRgb(hex: string): { red: number; green: number; blue: number } | null {
+  let h = hex.trim().replace(/^#/, '');
+  if (h.length === 3) h = h[0]! + h[0]! + h[1]! + h[1]! + h[2]! + h[2]!;
+  if (!/^[0-9a-fA-F]{6}$/.test(h)) return null;
+  const n = parseInt(h, 16);
+  return {
+    red: ((n >> 16) & 0xff) / 255,
+    green: ((n >> 8) & 0xff) / 255,
+    blue: (n & 0xff) / 255,
+  };
+}
+
 export function registerExtraSheetsTools(server: McpServer): void {
 
+  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 },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID (from the URL)'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, account }) => {
+    // jq projection keeps the response compact: sheetId, title, index, gridProperties only.
+    return runOrDiagnose(
+      ['sheets', 'metadata', spreadsheetId, '--select=sheets.properties.sheetId,sheets.properties.title,sheets.properties.index,sheets.properties.gridProperties'],
+      { account },
+    );
+  });
+
   server.registerTool('gog_sheets_add_tab', {
     description: 'Add a new sheet tab to a spreadsheet.',
     inputSchema: {
@@ -135,19 +166,92 @@ export function registerExtraSheetsTools(server: McpServer): void {
   });
 
   server.registerTool('gog_sheets_format', {
-    description: 'Apply cell formatting (bold, colors, alignment, etc.) to a range. Pass format as a JSON CellFormat object.',
+    description: 'Apply cell formatting to a range. The named flags (bold, italic, backgroundColor, etc.) compose into a Sheets API CellFormat — use them for the 90% case. For full API control, pass formatJson + formatFields (Sheets CellFormat + field mask) directly.',
     annotations: { destructiveHint: true },
     inputSchema: {
       spreadsheetId: z.string().describe('Spreadsheet ID'),
       range: z.string().describe('Range to format (e.g. Sheet1!A1:C3)'),
-      formatJson: z.string().describe('JSON CellFormat object (e.g. {"textFormat":{"bold":true}})'),
-      formatFields: z.string().optional().describe('Comma-separated field mask (e.g. textFormat.bold,backgroundColor)'),
+      bold: z.boolean().optional().describe('Set bold'),
+      italic: z.boolean().optional().describe('Set italic'),
+      underline: z.boolean().optional().describe('Set underline'),
+      strikethrough: z.boolean().optional().describe('Set strikethrough'),
+      fontSize: z.number().optional().describe('Font size in points'),
+      fontFamily: z.string().optional().describe('Font family (e.g. Arial)'),
+      textColor: z.string().optional().describe('Text color as #RRGGBB or #RGB'),
+      backgroundColor: z.string().optional().describe('Cell background color as #RRGGBB or #RGB'),
+      horizontalAlignment: z.enum(['LEFT', 'CENTER', 'RIGHT']).optional().describe('Horizontal alignment'),
+      verticalAlignment: z.enum(['TOP', 'MIDDLE', 'BOTTOM']).optional().describe('Vertical alignment'),
+      wrapStrategy: z.enum(['OVERFLOW_CELL', 'LEGACY_WRAP', 'CLIP', 'WRAP']).optional().describe('Text wrap strategy'),
+      formatJson: z.string().optional().describe('Escape hatch: raw CellFormat JSON. When provided, named flags above are ignored and formatJson is sent as-is.'),
+      formatFields: z.string().optional().describe('Comma-separated field mask (e.g. textFormat.bold,backgroundColor). Required when using formatJson; auto-computed when using named flags.'),
       account: accountParam,
     },
-  }, async ({ spreadsheetId, range, formatJson, formatFields, account }) => {
-    const args = ['sheets', 'format', spreadsheetId, range, `--format-json=${formatJson}`];
+  }, async (rawArgs) => {
+    const a = rawArgs as {
+      spreadsheetId: string;
+      range: string;
+      bold?: boolean;
+      italic?: boolean;
+      underline?: boolean;
+      strikethrough?: boolean;
+      fontSize?: number;
+      fontFamily?: string;
+      textColor?: string;
+      backgroundColor?: string;
+      horizontalAlignment?: string;
+      verticalAlignment?: string;
+      wrapStrategy?: string;
+      formatJson?: string;
+      formatFields?: string;
+      account?: string;
+    };
+    let formatJson = a.formatJson;
+    let formatFields = a.formatFields;
+    // If the caller didn't pass raw JSON, compose it from the named flags.
+    if (!formatJson) {
+      const cellFormat: Record<string, unknown> = {};
+      const textFormat: Record<string, unknown> = {};
+      const fields: string[] = [];
+      if (a.bold !== undefined) { textFormat.bold = a.bold; fields.push('textFormat.bold'); }
+      if (a.italic !== undefined) { textFormat.italic = a.italic; fields.push('textFormat.italic'); }
+      if (a.underline !== undefined) { textFormat.underline = a.underline; fields.push('textFormat.underline'); }
+      if (a.strikethrough !== undefined) { textFormat.strikethrough = a.strikethrough; fields.push('textFormat.strikethrough'); }
+      if (a.fontSize !== undefined) { textFormat.fontSize = a.fontSize; fields.push('textFormat.fontSize'); }
+      if (a.fontFamily !== undefined) { textFormat.fontFamily = a.fontFamily; fields.push('textFormat.fontFamily'); }
+      if (a.textColor !== undefined) {
+        const rgb = hexToRgb(a.textColor);
+        if (!rgb) throw new Error(`Invalid textColor: ${a.textColor} (expected #RRGGBB or #RGB)`);
+        textFormat.foregroundColor = rgb;
+        fields.push('textFormat.foregroundColor');
+      }
+      if (Object.keys(textFormat).length > 0) cellFormat.textFormat = textFormat;
+      if (a.backgroundColor !== undefined) {
+        const rgb = hexToRgb(a.backgroundColor);
+        if (!rgb) throw new Error(`Invalid backgroundColor: ${a.backgroundColor} (expected #RRGGBB or #RGB)`);
+        cellFormat.backgroundColor = rgb;
+        fields.push('backgroundColor');
+      }
+      if (a.horizontalAlignment !== undefined) {
+        cellFormat.horizontalAlignment = a.horizontalAlignment;
+        fields.push('horizontalAlignment');
+      }
+      if (a.verticalAlignment !== undefined) {
+        cellFormat.verticalAlignment = a.verticalAlignment;
+        fields.push('verticalAlignment');
+      }
+      if (a.wrapStrategy !== undefined) {
+        cellFormat.wrapStrategy = a.wrapStrategy;
+        fields.push('wrapStrategy');
+      }
+      if (Object.keys(cellFormat).length === 0) {
+        throw new Error('gog_sheets_format requires at least one named flag or a formatJson value');
+      }
+      formatJson = JSON.stringify(cellFormat);
+      if (!formatFields) formatFields = fields.join(',');
+    }
+    const args = ['sheets', 'format', a.spreadsheetId, a.range, `--format-json=${formatJson}`];
     if (formatFields) args.push(`--format-fields=${formatFields}`);
-    return runOrDiagnose(args, { account });
+    return runOrDiagnose(args, { account: a.account });
   });
 
   server.registerTool('gog_sheets_number_format', {

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

@@ -170,19 +170,132 @@ describe('gog_sheets_unmerge', () => {
 
 // 10. format
 describe('gog_sheets_format', () => {
-  it('calls runOrDiagnose with correct args', async () => {
+  it('passes raw formatJson + formatFields through unchanged (escape hatch)', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
     const handlers = setupHandlers();
     const fj = '{"textFormat":{"bold":true}}';
-    await handlers.get('gog_sheets_format')!({ spreadsheetId: 'sid', range: 'A1:B2', formatJson: fj });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['sheets', 'format', 'sid', 'A1:B2', `--format-json=${fj}`], { account: undefined });
+    await handlers.get('gog_sheets_format')!({ spreadsheetId: 'sid', range: 'A1:B2', formatJson: fj, formatFields: 'textFormat.bold' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'format', 'sid', 'A1:B2', `--format-json=${fj}`, '--format-fields=textFormat.bold'],
+      { account: undefined },
+    );
+  });
+
+  it('passes raw formatJson without formatFields', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_format')!({ spreadsheetId: 'sid', range: 'A1', formatJson: '{}' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'format', 'sid', 'A1', '--format-json={}'],
+      { account: undefined },
+    );
+  });
+
+  it('composes named flags into CellFormat JSON + auto-computed fields', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_format')!({
+      spreadsheetId: 'sid', range: 'A1:C3',
+      bold: true,
+      backgroundColor: '#FFF5D9',
+      wrapStrategy: 'WRAP',
+      verticalAlignment: 'TOP',
+    });
+    const call = vi.mocked(lib.runOrDiagnose).mock.calls[0]!;
+    const argv = call[0];
+    expect(argv[0]).toBe('sheets');
+    expect(argv[1]).toBe('format');
+    expect(argv[2]).toBe('sid');
+    expect(argv[3]).toBe('A1:C3');
+    const fmtArg = (argv[4] as string).replace(/^--format-json=/, '');
+    const parsed = JSON.parse(fmtArg);
+    expect(parsed.textFormat.bold).toBe(true);
+    expect(parsed.backgroundColor.red).toBeCloseTo(1.0);
+    expect(parsed.backgroundColor.green).toBeCloseTo(245 / 255);
+    expect(parsed.backgroundColor.blue).toBeCloseTo(217 / 255);
+    expect(parsed.wrapStrategy).toBe('WRAP');
+    expect(parsed.verticalAlignment).toBe('TOP');
+    const fieldsArg = argv[5] as string;
+    expect(fieldsArg).toMatch(/^--format-fields=/);
+    expect(fieldsArg).toContain('textFormat.bold');
+    expect(fieldsArg).toContain('backgroundColor');
+    expect(fieldsArg).toContain('wrapStrategy');
+    expect(fieldsArg).toContain('verticalAlignment');
+  });
+
+  it('composes all named flags including textColor + alignment', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_format')!({
+      spreadsheetId: 'sid', range: 'A1',
+      italic: true,
+      underline: true,
+      strikethrough: true,
+      fontSize: 14,
+      fontFamily: 'Inter',
+      textColor: '#FFF',
+      horizontalAlignment: 'CENTER',
+    });
+    const call = vi.mocked(lib.runOrDiagnose).mock.calls[0]!;
+    const fmtArg = (call[0][4] as string).replace(/^--format-json=/, '');
+    const parsed = JSON.parse(fmtArg);
+    expect(parsed.textFormat.italic).toBe(true);
+    expect(parsed.textFormat.underline).toBe(true);
+    expect(parsed.textFormat.strikethrough).toBe(true);
+    expect(parsed.textFormat.fontSize).toBe(14);
+    expect(parsed.textFormat.fontFamily).toBe('Inter');
+    expect(parsed.textFormat.foregroundColor.red).toBeCloseTo(1);
+    expect(parsed.textFormat.foregroundColor.green).toBeCloseTo(1);
+    expect(parsed.textFormat.foregroundColor.blue).toBeCloseTo(1);
+    expect(parsed.horizontalAlignment).toBe('CENTER');
+  });
+
+  it('rejects bad hex in textColor', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await expect(
+      handlers.get('gog_sheets_format')!({ spreadsheetId: 'sid', range: 'A1', textColor: 'not-a-hex' }),
+    ).rejects.toThrow(/Invalid textColor/);
+  });
+
+  it('rejects bad hex in backgroundColor', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await expect(
+      handlers.get('gog_sheets_format')!({ spreadsheetId: 'sid', range: 'A1', backgroundColor: 'orange' }),
+    ).rejects.toThrow(/Invalid backgroundColor/);
   });
 
-  it('includes --format-fields when provided', async () => {
+  it('rejects no-op calls with neither flags nor formatJson', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await expect(
+      handlers.get('gog_sheets_format')!({ spreadsheetId: 'sid', range: 'A1' }),
+    ).rejects.toThrow(/requires at least one named flag/);
+  });
+
+  it('honors caller-provided formatFields when also using named flags', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_format')!({
+      spreadsheetId: 'sid', range: 'A1',
+      bold: true,
+      formatFields: 'textFormat.bold,textFormat.italic',
+    });
+    const call = vi.mocked(lib.runOrDiagnose).mock.calls[0]!;
+    expect(call[0][5]).toBe('--format-fields=textFormat.bold,textFormat.italic');
+  });
+});
+
+describe('gog_sheets_list_tabs', () => {
+  it('uses metadata with a --select projection', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
     const handlers = setupHandlers();
-    await handlers.get('gog_sheets_format')!({ spreadsheetId: 'sid', range: 'A1', formatJson: '{}', formatFields: 'textFormat.bold' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['sheets', 'format', 'sid', 'A1', '--format-json={}', '--format-fields=textFormat.bold'], { account: undefined });
+    await handlers.get('gog_sheets_list_tabs')!({ spreadsheetId: 'sid' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'metadata', 'sid', '--select=sheets.properties.sheetId,sheets.properties.title,sheets.properties.index,sheets.properties.gridProperties'],
+      { account: undefined },
+    );
   });
 });