@triffon/google-docs-mcp 1.11.3-triffon

package/dist/tools/sheets/getConditionalFormatting.js

@@ -0,0 +1,98 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+function colIndexToLetters(index) {
+    let s = '';
+    let i = index;
+    do {
+        s = String.fromCharCode(65 + (i % 26)) + s;
+        i = Math.floor(i / 26) - 1;
+    } while (i >= 0);
+    return s;
+}
+function rgbToHex(rgb) {
+    if (!rgb)
+        return '#000000';
+    const r = Math.round((rgb.red ?? 0) * 255);
+    const g = Math.round((rgb.green ?? 0) * 255);
+    const b = Math.round((rgb.blue ?? 0) * 255);
+    return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`.toUpperCase();
+}
+export function register(server) {
+    server.addTool({
+        name: 'getConditionalFormatting',
+        description: 'Lists all conditional formatting rules for a sheet as JSON. Each rule includes its index (needed for deleteConditionalFormatting), kind (BOOLEAN or GRADIENT), ranges, condition type/values, and applied formats (colors, bold, italic).',
+        parameters: z.strictObject({
+            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.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Getting conditional formatting rules for spreadsheet ${args.spreadsheetId}`);
+            try {
+                const sheetId = await SheetsHelpers.resolveSheetId(sheets, args.spreadsheetId, args.sheetName);
+                const response = await sheets.spreadsheets.get({
+                    spreadsheetId: args.spreadsheetId,
+                    fields: 'sheets(properties(sheetId,title),conditionalFormats)',
+                });
+                const sheet = response.data.sheets?.find((s) => s.properties?.sheetId === sheetId);
+                const rules = sheet?.conditionalFormats ?? [];
+                const sheetTitle = sheet?.properties?.title ?? null;
+                const ruleSummaries = rules.map((rule, idx) => {
+                    const condition = rule.booleanRule?.condition;
+                    const gradient = rule.gradientRule;
+                    const fmt = rule.booleanRule?.format ?? {};
+                    const ranges = (rule.ranges ?? []).map((r) => {
+                        const startCol = r.startColumnIndex != null ? colIndexToLetters(r.startColumnIndex) : '';
+                        const endCol = r.endColumnIndex != null ? colIndexToLetters(r.endColumnIndex - 1) : '';
+                        const startRow = r.startRowIndex != null ? r.startRowIndex + 1 : '';
+                        const endRow = r.endRowIndex != null ? r.endRowIndex : '';
+                        return `${startCol}${startRow}:${endCol}${endRow}`;
+                    });
+                    const kind = gradient ? 'GRADIENT' : 'BOOLEAN';
+                    const conditionType = condition?.type ?? (gradient ? 'GRADIENT' : null);
+                    const conditionValues = (condition?.values ?? [])
+                        .map((v) => v.userEnteredValue)
+                        .filter((v) => typeof v === 'string');
+                    const bg = fmt.backgroundColor;
+                    const backgroundColor = bg
+                        ? rgbToHex({ red: bg.red ?? 0, green: bg.green ?? 0, blue: bg.blue ?? 0 })
+                        : null;
+                    const fg = fmt.textFormat?.foregroundColor;
+                    const textColor = fg
+                        ? rgbToHex({ red: fg.red ?? 0, green: fg.green ?? 0, blue: fg.blue ?? 0 })
+                        : null;
+                    return {
+                        index: idx,
+                        kind,
+                        ranges,
+                        conditionType,
+                        conditionValues,
+                        backgroundColor,
+                        textColor,
+                        bold: fmt.textFormat?.bold ?? false,
+                        italic: fmt.textFormat?.italic ?? false,
+                    };
+                });
+                return JSON.stringify({
+                    spreadsheetId: args.spreadsheetId,
+                    sheetName: sheetTitle,
+                    count: ruleSummaries.length,
+                    rules: ruleSummaries,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error getting conditional formatting: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to get conditional formatting: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/getSpreadsheetInfo.js

@@ -0,0 +1,44 @@
+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: 'getSpreadsheetInfo',
+        description: 'Gets metadata about a spreadsheet including its title, URL, and a list of all sheets with their dimensions.',
+        parameters: z.strictObject({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Getting info for spreadsheet: ${args.spreadsheetId}`);
+            try {
+                const metadata = await SheetsHelpers.getSpreadsheetMetadata(sheets, args.spreadsheetId);
+                const sheetList = metadata.sheets || [];
+                return JSON.stringify({
+                    title: metadata.properties?.title || 'Untitled',
+                    id: metadata.spreadsheetId,
+                    url: `https://docs.google.com/spreadsheets/d/${metadata.spreadsheetId}`,
+                    sheets: sheetList.map((sheet) => {
+                        const props = sheet.properties;
+                        return {
+                            title: props?.title || 'Untitled',
+                            sheetId: props?.sheetId,
+                            rows: props?.gridProperties?.rowCount || 0,
+                            columns: props?.gridProperties?.columnCount || 0,
+                            hidden: props?.hidden || false,
+                        };
+                    }),
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error getting spreadsheet info ${args.spreadsheetId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to get spreadsheet info: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

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.strictObject({
+            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.strictObject({
+            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.strictObject({
+                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,84 @@
+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';
+import { register as copySheetTo } from './copySheetTo.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 autoResizeRows } from './autoResizeRows.js';
+import { register as setRowHeights } from './setRowHeights.js';
+import { register as setCellBorders } from './setCellBorders.js';
+import { register as protectRange } from './protectRange.js';
+import { register as getConditionalFormatting } from './getConditionalFormatting.js';
+import { register as deleteConditionalFormatting } from './deleteConditionalFormatting.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';
+// Comments
+import { registerSheetsCommentTools } from './comments/index.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);
+    copySheetTo(server);
+    // Formatting & validation
+    formatCells(server);
+    readCellFormat(server);
+    copyFormatting(server);
+    freezeRowsAndColumns(server);
+    setColumnWidths(server);
+    autoResizeColumns(server);
+    autoResizeRows(server);
+    setRowHeights(server);
+    setCellBorders(server);
+    protectRange(server);
+    getConditionalFormatting(server);
+    deleteConditionalFormatting(server);
+    setDropdownValidation(server);
+    addConditionalFormatting(server);
+    groupRows(server);
+    ungroupAllRows(server);
+    // Comments
+    registerSheetsCommentTools(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.strictObject({
+            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,66 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+import { escapeDriveQuery } from '../../driveQueryUtils.js';
+export function register(server) {
+    server.addTool({
+        name: 'listSpreadsheets',
+        description: 'Lists spreadsheets in your Drive, optionally filtered by name or content.',
+        parameters: z.strictObject({
+            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) {
+                    const escapedQuery = escapeDriveQuery(args.query);
+                    queryString += ` and (name contains '${escapedQuery}' or fullText contains '${escapedQuery}')`;
+                }
+                const response = await drive.files.list({
+                    q: queryString,
+                    pageSize: args.maxResults,
+                    // Drive rejects `orderBy` when `q` contains a `fullText` clause
+                    // ("Sorting is not supported for queries with fullText terms").
+                    ...(args.query ? {} : { 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'}`);
+            }
+        },
+    });
+}