mcp-google-extras 1.0.0

package/dist/tools/sheets/getTable.js

@@ -0,0 +1,48 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'getTable',
+        description: 'Gets detailed information about a specific table including its columns, range, and properties. Use the table name or ID returned by listTables.',
+        parameters: z.object({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            tableIdentifier: z
+                .string()
+                .describe('The table name or table ID. Names are resolved first, then IDs. Use listTables to see available tables.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Getting table details for: ${args.tableIdentifier}`);
+            try {
+                const { table, sheetName, sheetId } = await SheetsHelpers.resolveTableIdentifier(sheets, args.spreadsheetId, args.tableIdentifier);
+                // Build detailed table information
+                const columns = table.columnProperties?.map((col) => ({
+                    index: col.columnIndex,
+                    name: col.columnName,
+                })) || [];
+                const range = table.range
+                    ? `${sheetName}!${SheetsHelpers.rowColToA1(table.range.startRowIndex || 0, table.range.startColumnIndex || 0)}:${SheetsHelpers.rowColToA1((table.range.endRowIndex || 1) - 1, (table.range.endColumnIndex || 1) - 1)}`
+                    : 'Unknown';
+                return JSON.stringify({
+                    tableId: table.tableId,
+                    name: table.name,
+                    sheetName,
+                    sheetId,
+                    range,
+                    columns,
+                    columnCount: table.columnProperties?.length || 0,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error getting table details: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to get table details: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/groupRows.js

@@ -0,0 +1,62 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'groupRows',
+        description: 'Creates collapsible row groups in a Google Sheet using the Sheets API addDimensionGroup request. Each group specifies a range of rows (1-based, inclusive) to collapse.',
+        parameters: z.object({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            sheetName: z
+                .string()
+                .optional()
+                .describe('Name of the sheet/tab. Defaults to the first sheet if not provided.'),
+            groups: z
+                .array(z.object({
+                startRowIndex: z
+                    .number()
+                    .int()
+                    .describe('1-based row number of the first row in the group (inclusive).'),
+                endRowIndex: z
+                    .number()
+                    .int()
+                    .describe('1-based row number of the last row in the group (inclusive).'),
+            }))
+                .min(1)
+                .describe('Array of row ranges to group. Each entry is {startRowIndex, endRowIndex} using 1-based row numbers.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Grouping rows in spreadsheet ${args.spreadsheetId}`);
+            try {
+                const sheetId = await SheetsHelpers.resolveSheetId(sheets, args.spreadsheetId, args.sheetName);
+                // Convert 1-based inclusive row numbers to 0-based exclusive indices
+                // required by the Sheets API DimensionRange
+                const requests = args.groups.map(({ startRowIndex, endRowIndex }) => ({
+                    addDimensionGroup: {
+                        range: {
+                            sheetId,
+                            dimension: 'ROWS',
+                            startIndex: startRowIndex - 1, // 0-based, inclusive
+                            endIndex: endRowIndex, // 0-based, exclusive (= 1-based inclusive)
+                        },
+                    },
+                }));
+                await sheets.spreadsheets.batchUpdate({
+                    spreadsheetId: args.spreadsheetId,
+                    requestBody: { requests },
+                });
+                return `Successfully created ${args.groups.length} row group(s).`;
+            }
+            catch (error) {
+                log.error(`Error grouping rows: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to group rows: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/index.js

@@ -0,0 +1,66 @@
+import { register as readSpreadsheet } from './readSpreadsheet.js';
+import { register as writeSpreadsheet } from './writeSpreadsheet.js';
+import { register as batchWrite } from './batchWrite.js';
+import { register as appendSpreadsheetRows } from './appendSpreadsheetRows.js';
+import { register as clearSpreadsheetRange } from './clearSpreadsheetRange.js';
+import { register as getSpreadsheetInfo } from './getSpreadsheetInfo.js';
+import { register as addSpreadsheetSheet } from './addSpreadsheetSheet.js';
+import { register as createSpreadsheet } from './createSpreadsheet.js';
+import { register as listGoogleSheets } from './listGoogleSheets.js';
+import { register as deleteSheet } from './deleteSheet.js';
+import { register as renameSheet } from './renameSheet.js';
+import { register as duplicateSheet } from './duplicateSheet.js';
+// Formatting & validation
+import { register as formatCells } from './formatCells.js';
+import { register as readCellFormat } from './readCellFormat.js';
+import { register as copyFormatting } from './copyFormatting.js';
+import { register as freezeRowsAndColumns } from './freezeRowsAndColumns.js';
+import { register as setColumnWidths } from './setColumnWidths.js';
+import { register as autoResizeColumns } from './autoResizeColumns.js';
+import { register as setDropdownValidation } from './setDropdownValidation.js';
+import { register as addConditionalFormatting } from './addConditionalFormatting.js';
+import { register as groupRows } from './groupRows.js';
+import { register as ungroupAllRows } from './ungroupAllRows.js';
+// Tables
+import { register as createTable } from './createTable.js';
+import { register as listTables } from './listTables.js';
+import { register as getTable } from './getTable.js';
+import { register as deleteTable } from './deleteTable.js';
+import { register as updateTableRange } from './updateTableRange.js';
+import { register as appendTableRows } from './appendTableRows.js';
+import { register as insertChart } from './insertChart.js';
+import { register as deleteChart } from './deleteChart.js';
+export function registerSheetsTools(server) {
+    readSpreadsheet(server);
+    writeSpreadsheet(server);
+    batchWrite(server);
+    appendSpreadsheetRows(server);
+    clearSpreadsheetRange(server);
+    getSpreadsheetInfo(server);
+    addSpreadsheetSheet(server);
+    createSpreadsheet(server);
+    listGoogleSheets(server);
+    deleteSheet(server);
+    renameSheet(server);
+    duplicateSheet(server);
+    // Formatting & validation
+    formatCells(server);
+    readCellFormat(server);
+    copyFormatting(server);
+    freezeRowsAndColumns(server);
+    setColumnWidths(server);
+    autoResizeColumns(server);
+    setDropdownValidation(server);
+    addConditionalFormatting(server);
+    groupRows(server);
+    ungroupAllRows(server);
+    // Tables
+    createTable(server);
+    listTables(server);
+    getTable(server);
+    deleteTable(server);
+    updateTableRange(server);
+    appendTableRows(server);
+    insertChart(server);
+    deleteChart(server);
+}

package/dist/tools/sheets/insertChart.js

@@ -0,0 +1,225 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'insertChart',
+        description: 'Inserts a chart into a Google Sheet. Supports bar, column, line, area, scatter, pie, donut, and treemap (hierarchical) chart types. ' +
+            'For treemap charts, the data must have a label column and a parent label column (use empty string for root nodes) plus a numeric size column. ' +
+            'Chart is placed as an overlay at the specified anchor cell.',
+        parameters: z.object({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            sheetName: z
+                .string()
+                .optional()
+                .describe('Name of the sheet/tab containing the data. Defaults to the first sheet.'),
+            chartType: z
+                .enum(['BAR', 'COLUMN', 'LINE', 'AREA', 'SCATTER', 'PIE', 'DONUT', 'TREEMAP'])
+                .describe('Chart type to create.'),
+            stackedType: z
+                .enum(['NOT_STACKED', 'STACKED', 'PERCENT_STACKED'])
+                .default('NOT_STACKED')
+                .describe('For bar/column/area charts: whether to stack series. NOT_STACKED = grouped, STACKED = absolute stacked, PERCENT_STACKED = 100% stacked.'),
+            title: z.string().optional().describe('Chart title.'),
+            dataRange: z
+                .string()
+                .describe('A1 notation range of the data (e.g., "A1:E50"). Include the header row if present.'),
+            headerRow: z
+                .boolean()
+                .default(true)
+                .describe('Whether the first row of the data range is a header row.'),
+            // Column indices for flexible data mapping
+            labelColumnIndex: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('For pie/donut/treemap: 1-based column index for node labels (default: 1). For treemap this is the leaf/child label.'),
+            parentColumnIndex: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('For treemap: 1-based column index for parent node labels. Root nodes should have an empty string in this column.'),
+            valueColumnIndex: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('For pie/donut/treemap: 1-based column index for the numeric size/value (default: 2).'),
+            // Chart position and size
+            anchorRow: z
+                .number()
+                .int()
+                .min(0)
+                .default(0)
+                .describe('Row index (0-based) of the anchor cell for chart placement.'),
+            anchorColumn: z
+                .number()
+                .int()
+                .min(0)
+                .default(6)
+                .describe('Column index (0-based) of the anchor cell for chart placement.'),
+            offsetXPixels: z
+                .number()
+                .int()
+                .default(0)
+                .describe('Horizontal offset in pixels from the anchor cell.'),
+            offsetYPixels: z
+                .number()
+                .int()
+                .default(0)
+                .describe('Vertical offset in pixels from the anchor cell.'),
+            widthPixels: z.number().int().default(600).describe('Chart width in pixels.'),
+            heightPixels: z.number().int().default(400).describe('Chart height in pixels.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Inserting ${args.chartType} chart into spreadsheet ${args.spreadsheetId}`);
+            try {
+                const sheetId = await SheetsHelpers.resolveSheetId(sheets, args.spreadsheetId, args.sheetName);
+                const { a1Range } = SheetsHelpers.parseRange(args.dataRange);
+                const gridRange = SheetsHelpers.parseA1ToGridRange(a1Range, sheetId);
+                const startRow = gridRange.startRowIndex ?? 0;
+                const endRow = gridRange.endRowIndex ?? startRow + 1;
+                const startCol = gridRange.startColumnIndex ?? 0;
+                const endCol = gridRange.endColumnIndex ?? startCol + 1;
+                const dataStartRow = args.headerRow ? startRow + 1 : startRow;
+                const labelCol = startCol + (args.labelColumnIndex ? args.labelColumnIndex - 1 : 0);
+                const valueCol = startCol + (args.valueColumnIndex ? args.valueColumnIndex - 1 : 1);
+                const parentCol = startCol + (args.parentColumnIndex ? args.parentColumnIndex - 1 : 0);
+                const makeSourceRange = (colStart, colEnd, rowStart = dataStartRow) => ({
+                    sources: [
+                        {
+                            sheetId,
+                            startRowIndex: rowStart,
+                            endRowIndex: endRow,
+                            startColumnIndex: colStart,
+                            endColumnIndex: colEnd,
+                        },
+                    ],
+                });
+                let chartSpec = {};
+                if (args.chartType === 'PIE' || args.chartType === 'DONUT') {
+                    chartSpec.pieChart = {
+                        legendPosition: 'LABELED_LEGEND',
+                        pieHole: args.chartType === 'DONUT' ? 0.5 : 0,
+                        domain: {
+                            data: { sourceRange: makeSourceRange(labelCol, labelCol + 1) },
+                        },
+                        series: {
+                            data: { sourceRange: makeSourceRange(valueCol, valueCol + 1) },
+                        },
+                    };
+                }
+                else if (args.chartType === 'TREEMAP') {
+                    chartSpec.treemapChart = {
+                        labels: {
+                            sourceRange: makeSourceRange(labelCol, labelCol + 1),
+                        },
+                        parentLabels: {
+                            sourceRange: makeSourceRange(parentCol, parentCol + 1),
+                        },
+                        sizeData: {
+                            sourceRange: makeSourceRange(valueCol, valueCol + 1),
+                        },
+                        colorData: {
+                            sourceRange: makeSourceRange(valueCol, valueCol + 1),
+                        },
+                    };
+                }
+                else {
+                    // Basic chart types: BAR, COLUMN, LINE, AREA, SCATTER
+                    // Each series must be a separate entry with a single-column source range.
+                    const seriesCount = endCol - startCol - 1;
+                    const series = Array.from({ length: seriesCount }, (_, i) => ({
+                        series: {
+                            sourceRange: {
+                                sources: [
+                                    {
+                                        sheetId,
+                                        startRowIndex: startRow, // include header so Sheets names the series automatically
+                                        endRowIndex: endRow,
+                                        startColumnIndex: startCol + 1 + i,
+                                        endColumnIndex: startCol + 2 + i,
+                                    },
+                                ],
+                            },
+                        },
+                        targetAxis: 'LEFT_AXIS',
+                    }));
+                    chartSpec.basicChart = {
+                        chartType: args.chartType,
+                        stackedType: args.stackedType,
+                        legendPosition: 'BOTTOM_LEGEND',
+                        axis: [
+                            { position: 'BOTTOM_AXIS', title: '' },
+                            { position: 'LEFT_AXIS', title: '' },
+                        ],
+                        domains: [
+                            {
+                                domain: {
+                                    sourceRange: {
+                                        sources: [
+                                            {
+                                                sheetId,
+                                                startRowIndex: startRow,
+                                                endRowIndex: endRow,
+                                                startColumnIndex: startCol,
+                                                endColumnIndex: startCol + 1,
+                                            },
+                                        ],
+                                    },
+                                },
+                                reversed: false,
+                            },
+                        ],
+                        series,
+                        headerCount: args.headerRow ? 1 : 0,
+                    };
+                }
+                if (args.title) {
+                    chartSpec.title = args.title;
+                }
+                const response = await sheets.spreadsheets.batchUpdate({
+                    spreadsheetId: args.spreadsheetId,
+                    requestBody: {
+                        requests: [
+                            {
+                                addChart: {
+                                    chart: {
+                                        spec: chartSpec,
+                                        position: {
+                                            overlayPosition: {
+                                                anchorCell: {
+                                                    sheetId,
+                                                    rowIndex: args.anchorRow,
+                                                    columnIndex: args.anchorColumn,
+                                                },
+                                                offsetXPixels: args.offsetXPixels,
+                                                offsetYPixels: args.offsetYPixels,
+                                                widthPixels: args.widthPixels,
+                                                heightPixels: args.heightPixels,
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        ],
+                    },
+                });
+                const chartId = response.data.replies?.[0]?.addChart?.chart?.chartId;
+                return `Chart created successfully${chartId ? ` (Chart ID: ${chartId})` : ''}.`;
+            }
+            catch (error) {
+                log.error(`Error inserting chart: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to insert chart: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/listGoogleSheets.js

@@ -0,0 +1,62 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'listSpreadsheets',
+        description: 'Lists spreadsheets in your Drive, optionally filtered by name or content.',
+        parameters: z.object({
+            maxResults: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .default(20)
+                .describe('Maximum number of spreadsheets to return (1-100).'),
+            query: z
+                .string()
+                .optional()
+                .describe('Search query to filter spreadsheets by name or content.'),
+            orderBy: z
+                .enum(['name', 'modifiedTime', 'createdTime'])
+                .optional()
+                .default('modifiedTime')
+                .describe('Sort order for results.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Listing Google Sheets. Query: ${args.query || 'none'}, Max: ${args.maxResults}, Order: ${args.orderBy}`);
+            try {
+                // Build the query string for Google Drive API
+                let queryString = "mimeType='application/vnd.google-apps.spreadsheet' and trashed=false";
+                if (args.query) {
+                    queryString += ` and (name contains '${args.query}' or fullText contains '${args.query}')`;
+                }
+                const response = await drive.files.list({
+                    q: queryString,
+                    pageSize: args.maxResults,
+                    orderBy: args.orderBy === 'name' ? 'name' : args.orderBy,
+                    fields: 'files(id,name,modifiedTime,createdTime,size,webViewLink,owners(displayName,emailAddress))',
+                    supportsAllDrives: true,
+                    includeItemsFromAllDrives: true,
+                });
+                const files = response.data.files || [];
+                const spreadsheets = files.map((file) => ({
+                    id: file.id,
+                    name: file.name,
+                    modifiedTime: file.modifiedTime,
+                    owner: file.owners?.[0]?.displayName || null,
+                    url: file.webViewLink,
+                }));
+                return JSON.stringify({ spreadsheets }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing Google Sheets: ${error.message || error}`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have granted Google Drive access to the application.');
+                throw new UserError(`Failed to list spreadsheets: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/listTables.js

@@ -0,0 +1,55 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'listTables',
+        description: 'Lists all tables in a spreadsheet or specific sheet. Use this to discover table names and IDs before performing table operations.',
+        parameters: z.object({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            sheetName: z
+                .string()
+                .optional()
+                .describe('Optional: filter tables to only those on this specific sheet.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Listing tables for spreadsheet: ${args.spreadsheetId}`);
+            try {
+                const tables = await SheetsHelpers.listAllTables(sheets, args.spreadsheetId, args.sheetName);
+                if (tables.length === 0) {
+                    return JSON.stringify({
+                        spreadsheetId: args.spreadsheetId,
+                        sheetFilter: args.sheetName || 'All sheets',
+                        tables: [],
+                        message: 'No tables found. Use createTable to create a table.',
+                    }, null, 2);
+                }
+                const tableList = tables.map((item) => ({
+                    tableId: item.table.tableId,
+                    name: item.table.name,
+                    sheetName: item.sheetName,
+                    columnCount: item.table.columnProperties?.length || 0,
+                    range: item.table.range
+                        ? `${item.sheetName}!${SheetsHelpers.rowColToA1(item.table.range.startRowIndex || 0, item.table.range.startColumnIndex || 0)}:${SheetsHelpers.rowColToA1((item.table.range.endRowIndex || 1) - 1, (item.table.range.endColumnIndex || 1) - 1)}`
+                        : 'Unknown',
+                }));
+                return JSON.stringify({
+                    spreadsheetId: args.spreadsheetId,
+                    sheetFilter: args.sheetName || 'All sheets',
+                    count: tableList.length,
+                    tables: tableList,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing tables: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to list tables: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/readCellFormat.js

@@ -0,0 +1,143 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+import { rowColToA1 } from '../../googleSheetsApiHelpers.js';
+/**
+ * Converts a Google Sheets RGBA color object (0-1 range) to a hex string.
+ * Returns null if the color is undefined or has no meaningful channels.
+ */
+function rgbaToHex(color) {
+    if (!color)
+        return null;
+    const r = Math.round((color.red ?? 0) * 255);
+    const g = Math.round((color.green ?? 0) * 255);
+    const b = Math.round((color.blue ?? 0) * 255);
+    return `#${r.toString(16).padStart(2, '0').toUpperCase()}${g.toString(16).padStart(2, '0').toUpperCase()}${b.toString(16).padStart(2, '0').toUpperCase()}`;
+}
+/**
+ * Extracts a simplified formatting summary from a Google Sheets CellFormat object.
+ * Only includes properties that are explicitly set (non-default).
+ */
+function simplifyFormat(fmt) {
+    if (!fmt)
+        return null;
+    const result = {};
+    // Text formatting
+    if (fmt.textFormat) {
+        const tf = {};
+        if (fmt.textFormat.bold)
+            tf.bold = true;
+        if (fmt.textFormat.italic)
+            tf.italic = true;
+        if (fmt.textFormat.strikethrough)
+            tf.strikethrough = true;
+        if (fmt.textFormat.underline)
+            tf.underline = true;
+        if (fmt.textFormat.fontSize != null)
+            tf.fontSize = fmt.textFormat.fontSize;
+        if (fmt.textFormat.fontFamily)
+            tf.fontFamily = fmt.textFormat.fontFamily;
+        if (fmt.textFormat.foregroundColorStyle?.rgbColor) {
+            tf.foregroundColor = rgbaToHex(fmt.textFormat.foregroundColorStyle.rgbColor);
+        }
+        else if (fmt.textFormat.foregroundColor) {
+            tf.foregroundColor = rgbaToHex(fmt.textFormat.foregroundColor);
+        }
+        if (Object.keys(tf).length > 0)
+            result.textFormat = tf;
+    }
+    // Background color
+    if (fmt.backgroundColorStyle?.rgbColor) {
+        result.backgroundColor = rgbaToHex(fmt.backgroundColorStyle.rgbColor);
+    }
+    else if (fmt.backgroundColor) {
+        result.backgroundColor = rgbaToHex(fmt.backgroundColor);
+    }
+    // Alignment
+    if (fmt.horizontalAlignment)
+        result.horizontalAlignment = fmt.horizontalAlignment;
+    if (fmt.verticalAlignment)
+        result.verticalAlignment = fmt.verticalAlignment;
+    // Number format
+    if (fmt.numberFormat) {
+        result.numberFormat = {
+            type: fmt.numberFormat.type,
+            pattern: fmt.numberFormat.pattern,
+        };
+    }
+    // Borders
+    if (fmt.borders) {
+        const borders = {};
+        for (const side of ['top', 'bottom', 'left', 'right']) {
+            if (fmt.borders[side]) {
+                borders[side] = {
+                    style: fmt.borders[side].style,
+                    ...(fmt.borders[side].colorStyle?.rgbColor
+                        ? { color: rgbaToHex(fmt.borders[side].colorStyle.rgbColor) }
+                        : fmt.borders[side].color
+                            ? { color: rgbaToHex(fmt.borders[side].color) }
+                            : {}),
+                };
+            }
+        }
+        if (Object.keys(borders).length > 0)
+            result.borders = borders;
+    }
+    // Wrap strategy
+    if (fmt.wrapStrategy)
+        result.wrapStrategy = fmt.wrapStrategy;
+    return Object.keys(result).length > 0 ? result : null;
+}
+export function register(server) {
+    server.addTool({
+        name: 'readCellFormat',
+        description: 'Reads the formatting/style of cells in a given range. Returns formatting details like bold, italic, fontSize, fontFamily, colors, alignment, borders, and number format per cell.',
+        parameters: z.object({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            range: z
+                .string()
+                .describe('A1 notation range to read formatting from (e.g., "Sheet1!A1:D5" or "A1:B2").'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Reading cell format for range "${args.range}" in spreadsheet ${args.spreadsheetId}`);
+            try {
+                const response = await sheets.spreadsheets.get({
+                    spreadsheetId: args.spreadsheetId,
+                    ranges: [args.range],
+                    includeGridData: true,
+                    fields: 'sheets.data.rowData.values.userEnteredFormat,sheets.data.startRow,sheets.data.startColumn',
+                });
+                const sheetData = response.data.sheets?.[0]?.data?.[0];
+                if (!sheetData?.rowData) {
+                    return JSON.stringify({ range: args.range, cells: [] }, null, 2);
+                }
+                const startRow = sheetData.startRow ?? 0;
+                const startCol = sheetData.startColumn ?? 0;
+                const cells = [];
+                for (let rowIdx = 0; rowIdx < sheetData.rowData.length; rowIdx++) {
+                    const row = sheetData.rowData[rowIdx];
+                    if (!row.values)
+                        continue;
+                    for (let colIdx = 0; colIdx < row.values.length; colIdx++) {
+                        const cellData = row.values[colIdx];
+                        const fmt = simplifyFormat(cellData?.userEnteredFormat);
+                        if (fmt) {
+                            const cellRef = rowColToA1(startRow + rowIdx, startCol + colIdx);
+                            cells.push({ cell: cellRef, format: fmt });
+                        }
+                    }
+                }
+                return JSON.stringify({ range: args.range, cells }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error reading cell format for spreadsheet ${args.spreadsheetId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to read cell format: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}