google-tools-mcp 1.0.0

package/dist/tools/sheets/createSpreadsheet.js

@@ -0,0 +1,71 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient, getSheetsClient } from '../../clients.js';
+import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'createSpreadsheet',
+        description: 'Creates a new spreadsheet. Optionally places it in a specific folder and populates it with initial data.',
+        parameters: z.object({
+            title: z.string().min(1).describe('Title for the new spreadsheet.'),
+            parentFolderId: z
+                .string()
+                .optional()
+                .describe('ID of folder where spreadsheet should be created. If not provided, creates in Drive root.'),
+            initialData: z
+                .array(z.array(z.any()))
+                .optional()
+                .describe('Optional initial data to populate in the first sheet. Each inner array represents a row.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            const sheets = await getSheetsClient();
+            log.info(`Creating new spreadsheet "${args.title}"`);
+            try {
+                // Create the spreadsheet file in Drive
+                const spreadsheetMetadata = {
+                    name: args.title,
+                    mimeType: 'application/vnd.google-apps.spreadsheet',
+                };
+                if (args.parentFolderId) {
+                    spreadsheetMetadata.parents = [args.parentFolderId];
+                }
+                const driveResponse = await drive.files.create({
+                    requestBody: spreadsheetMetadata,
+                    fields: 'id,name,webViewLink',
+                    supportsAllDrives: true,
+                });
+                const spreadsheetId = driveResponse.data.id;
+                if (!spreadsheetId) {
+                    throw new UserError('Failed to create spreadsheet - no ID returned.');
+                }
+                let initialDataStatus;
+                // Add initial data if provided
+                if (args.initialData && args.initialData.length > 0) {
+                    try {
+                        await SheetsHelpers.writeRange(sheets, spreadsheetId, 'A1', args.initialData, 'USER_ENTERED');
+                        initialDataStatus = 'added';
+                    }
+                    catch (contentError) {
+                        log.warn(`Spreadsheet created but failed to add initial data: ${contentError.message}`);
+                        initialDataStatus = 'failed';
+                    }
+                }
+                return JSON.stringify({
+                    id: spreadsheetId,
+                    name: driveResponse.data.name,
+                    url: driveResponse.data.webViewLink,
+                    ...(initialDataStatus ? { initialData: initialDataStatus } : {}),
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error creating spreadsheet: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('Parent folder not found. Check the folder ID.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have write access to the destination folder.');
+                throw new UserError(`Failed to create spreadsheet: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/createTable.js

@@ -0,0 +1,120 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+// Column type enum matching Google Sheets API
+const ColumnTypeSchema = z.enum([
+    'TEXT',
+    'NUMBER',
+    'DATE',
+    'DROPDOWN',
+    'CHECKBOX',
+    'PERCENT',
+    'CURRENCY',
+]);
+export function register(server) {
+    server.addTool({
+        name: 'createTable',
+        description: 'Creates a new named table with specific column types. Tables provide structured data with typed columns, automatic formatting, and special features like dropdown validation.',
+        parameters: z
+            .object({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            name: z
+                .string()
+                .min(1)
+                .describe('Unique name for the table within this spreadsheet. Table names must be unique.'),
+            range: z
+                .string()
+                .describe('A1 notation range for the table (e.g., "Sheet1!A1:E10"). Must be within existing sheet boundaries.'),
+            columns: z
+                .array(z.object({
+                columnName: z.string().min(1).describe('Display name for the column header.'),
+                columnType: ColumnTypeSchema.optional().describe('Data type for the column (default: TEXT).'),
+                dropdownValues: z
+                    .array(z.string())
+                    .optional()
+                    .describe('Required for DROPDOWN type: list of dropdown options.'),
+            }))
+                .optional()
+                .describe('Column definitions. If not specified, columns are auto-detected from first row.'),
+            hasHeaderRow: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe('Whether the table has a header row (default: true).'),
+            hasFooterRow: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Whether the table should have a footer row (default: false).'),
+        })
+            .refine((data) => {
+            // Validate dropdown columns have values
+            if (data.columns) {
+                for (const col of data.columns) {
+                    if (col.columnType === 'DROPDOWN' &&
+                        (!col.dropdownValues || col.dropdownValues.length === 0)) {
+                        return false;
+                    }
+                }
+            }
+            return true;
+        }, {
+            message: 'DROPDOWN column type requires dropdownValues to be specified with at least one option.',
+            path: ['columns'],
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Creating table "${args.name}" in spreadsheet: ${args.spreadsheetId}`);
+            try {
+                // Parse the range to get sheet name and grid range
+                const { sheetName, a1Range } = SheetsHelpers.parseRange(args.range);
+                const sheetId = await SheetsHelpers.resolveSheetId(sheets, args.spreadsheetId, sheetName);
+                const gridRange = SheetsHelpers.parseA1ToGridRange(a1Range, sheetId);
+                // Build column properties if provided
+                let columnProperties;
+                if (args.columns && args.columns.length > 0) {
+                    columnProperties = args.columns.map((col, index) => {
+                        const prop = {
+                            columnIndex: index,
+                            columnName: col.columnName,
+                        };
+                        // Add data validation for DROPDOWN type
+                        if (col.columnType === 'DROPDOWN' &&
+                            col.dropdownValues &&
+                            col.dropdownValues.length > 0) {
+                            prop.dataValidationRule = {
+                                condition: {
+                                    type: 'ONE_OF_LIST',
+                                    values: col.dropdownValues.map((v) => ({ userEnteredValue: v })),
+                                },
+                            };
+                        }
+                        return prop;
+                    });
+                }
+                // Create the table
+                const table = await SheetsHelpers.createTableHelper(sheets, args.spreadsheetId, {
+                    name: args.name,
+                    range: gridRange,
+                    columnProperties,
+                });
+                return JSON.stringify({
+                    tableId: table.tableId,
+                    name: table.name,
+                    range: args.range,
+                    columnCount: table.columnProperties?.length || 0,
+                    message: `Table "${args.name}" created successfully.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error creating table: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to create table: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/deleteChart.js

@@ -0,0 +1,41 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'deleteChart',
+        description: 'Deletes a chart from a Google Spreadsheet by chart ID. ' +
+            'The chart ID is returned when a chart is created with insertChart.',
+        parameters: z.object({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            chartId: z.number().int().describe('The numeric chart ID to delete.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Deleting chart ${args.chartId} from spreadsheet ${args.spreadsheetId}`);
+            try {
+                await sheets.spreadsheets.batchUpdate({
+                    spreadsheetId: args.spreadsheetId,
+                    requestBody: {
+                        requests: [
+                            {
+                                deleteEmbeddedObject: {
+                                    objectId: args.chartId,
+                                },
+                            },
+                        ],
+                    },
+                });
+                return `Chart ${args.chartId} deleted successfully.`;
+            }
+            catch (error) {
+                log.error(`Error deleting chart: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to delete chart: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/deleteSheet.js

@@ -0,0 +1,43 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'deleteSheet',
+        description: 'Deletes a sheet (tab) from a spreadsheet. Use getSpreadsheetInfo to find the numeric sheet ID.',
+        parameters: z.object({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            sheetId: z
+                .number()
+                .int()
+                .describe('The numeric sheet ID to delete. Use getSpreadsheetInfo to find sheet IDs.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Deleting sheet ID ${args.sheetId} from spreadsheet ${args.spreadsheetId}`);
+            try {
+                await sheets.spreadsheets.batchUpdate({
+                    spreadsheetId: args.spreadsheetId,
+                    requestBody: {
+                        requests: [
+                            {
+                                deleteSheet: {
+                                    sheetId: args.sheetId,
+                                },
+                            },
+                        ],
+                    },
+                });
+                return `Successfully deleted sheet (ID: ${args.sheetId}) from spreadsheet.`;
+            }
+            catch (error) {
+                log.error(`Error deleting sheet in spreadsheet ${args.spreadsheetId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to delete sheet: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/deleteTable.js

@@ -0,0 +1,56 @@
+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: 'deleteTable',
+        description: 'Deletes a table from a spreadsheet. By default, only removes the table object and formatting while keeping the cell data. Optionally clears the data as well.',
+        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 to delete. Use listTables to see available tables.'),
+            deleteData: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, also clears the cell data in the table range. If false (default), only removes the table object and formatting.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Deleting table "${args.tableIdentifier}" from spreadsheet: ${args.spreadsheetId}`);
+            try {
+                // First resolve the table to get its ID and range
+                const { table, sheetName } = await SheetsHelpers.resolveTableIdentifier(sheets, args.spreadsheetId, args.tableIdentifier);
+                // Delete the table
+                await SheetsHelpers.deleteTableHelper(sheets, args.spreadsheetId, table.tableId || '');
+                // If deleteData is true, clear the range
+                let clearedRange = null;
+                if (args.deleteData && table.range) {
+                    const range = `${sheetName}!${SheetsHelpers.rowColToA1(table.range.startRowIndex || 0, table.range.startColumnIndex || 0)}:${SheetsHelpers.rowColToA1((table.range.endRowIndex || 1) - 1, (table.range.endColumnIndex || 1) - 1)}`;
+                    await SheetsHelpers.clearRange(sheets, args.spreadsheetId, range);
+                    clearedRange = range;
+                }
+                return JSON.stringify({
+                    tableId: table.tableId,
+                    name: table.name,
+                    deleted: true,
+                    dataCleared: args.deleteData,
+                    clearedRange,
+                    message: args.deleteData
+                        ? `Table "${table.name}" deleted and data cleared.`
+                        : `Table "${table.name}" deleted. Data preserved in range.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error deleting table: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to delete table: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/duplicateSheet.js

@@ -0,0 +1,53 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'duplicateSheet',
+        description: 'Duplicates a sheet (tab) within a spreadsheet, copying all values, formulas, formatting, validations, and conditional formatting. Use getSpreadsheetInfo to find the numeric sheet ID.',
+        parameters: z.object({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            sheetId: z
+                .number()
+                .int()
+                .describe('The numeric sheet ID to duplicate. Use getSpreadsheetInfo to find sheet IDs.'),
+            newSheetName: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Name for the duplicated sheet. If omitted, Google auto-names it "Copy of <original>".'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Duplicating sheet ID ${args.sheetId} in spreadsheet ${args.spreadsheetId}${args.newSheetName ? ` as "${args.newSheetName}"` : ''}`);
+            try {
+                const response = await sheets.spreadsheets.batchUpdate({
+                    spreadsheetId: args.spreadsheetId,
+                    requestBody: {
+                        requests: [
+                            {
+                                duplicateSheet: {
+                                    sourceSheetId: args.sheetId,
+                                    newSheetName: args.newSheetName,
+                                },
+                            },
+                        ],
+                    },
+                });
+                const duplicatedSheet = response.data.replies?.[0]?.duplicateSheet?.properties;
+                if (!duplicatedSheet) {
+                    throw new UserError('Failed to duplicate sheet - no sheet properties returned.');
+                }
+                return `Successfully duplicated sheet as "${duplicatedSheet.title}" (Sheet ID: ${duplicatedSheet.sheetId}).`;
+            }
+            catch (error) {
+                log.error(`Error duplicating sheet in spreadsheet ${args.spreadsheetId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to duplicate sheet: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/formatCells.js

@@ -0,0 +1,106 @@
+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: 'formatCells',
+        description: "Applies formatting to a range of cells in a spreadsheet. Supports bold, italic, font size, text color, background color, alignment, and number format. Use range '1:1' to format an entire header row, 'A:A' for an entire column, or 'A1:D1' for specific cells. Use numberFormat to control how values are displayed (e.g. as numbers, text, dates) or to clear a format by setting type to 'TEXT'.",
+        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 format. Examples: "Sheet1!A1:D1", "1:1" (entire row 1), "A:A" (entire column A), "B2:E10".'),
+            bold: z.boolean().optional().describe('Apply bold text formatting.'),
+            italic: z.boolean().optional().describe('Apply italic text formatting.'),
+            fontSize: z.number().min(1).optional().describe('Font size in points.'),
+            foregroundColor: z.string().optional().describe('Text color as hex (e.g., "#FF0000").'),
+            backgroundColor: z
+                .string()
+                .optional()
+                .describe('Cell background color as hex (e.g., "#D9EAD3").'),
+            horizontalAlignment: z
+                .enum(['LEFT', 'CENTER', 'RIGHT'])
+                .optional()
+                .describe('Horizontal text alignment.'),
+            numberFormat: z
+                .object({
+                type: z
+                    .enum([
+                    'TEXT',
+                    'NUMBER',
+                    'PERCENT',
+                    'CURRENCY',
+                    'DATE',
+                    'TIME',
+                    'DATE_TIME',
+                    'SCIENTIFIC',
+                ])
+                    .describe('Number format type. Use "TEXT" to treat cells as plain text (also clears any existing date/number format). Use "NUMBER" for general numeric display.'),
+                pattern: z
+                    .string()
+                    .optional()
+                    .describe('Optional custom format pattern (e.g., "0.00", "#,##0", "yyyy-MM-dd"). If omitted, the default pattern for the type is used.'),
+            })
+                .optional()
+                .describe('Controls how cell values are displayed. Useful for clearing date formatting (set type to "TEXT") or applying a custom number pattern.'),
+        })
+            .refine((data) => data.bold !== undefined ||
+            data.italic !== undefined ||
+            data.fontSize !== undefined ||
+            data.foregroundColor !== undefined ||
+            data.backgroundColor !== undefined ||
+            data.horizontalAlignment !== undefined ||
+            data.numberFormat !== undefined, { message: 'At least one formatting option must be provided.' }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Formatting cells in range "${args.range}" of spreadsheet ${args.spreadsheetId}`);
+            try {
+                // Build the format object expected by the helper
+                const format = {};
+                if (args.backgroundColor) {
+                    const rgb = SheetsHelpers.hexToRgb(args.backgroundColor);
+                    if (!rgb)
+                        throw new UserError(`Invalid background color: "${args.backgroundColor}".`);
+                    format.backgroundColor = rgb;
+                }
+                const hasTextFormat = args.bold !== undefined ||
+                    args.italic !== undefined ||
+                    args.fontSize !== undefined ||
+                    args.foregroundColor !== undefined;
+                if (hasTextFormat) {
+                    format.textFormat = {};
+                    if (args.bold !== undefined)
+                        format.textFormat.bold = args.bold;
+                    if (args.italic !== undefined)
+                        format.textFormat.italic = args.italic;
+                    if (args.fontSize !== undefined)
+                        format.textFormat.fontSize = args.fontSize;
+                    if (args.foregroundColor) {
+                        const rgb = SheetsHelpers.hexToRgb(args.foregroundColor);
+                        if (!rgb)
+                            throw new UserError(`Invalid foreground color: "${args.foregroundColor}".`);
+                        format.textFormat.foregroundColor = rgb;
+                    }
+                }
+                if (args.horizontalAlignment) {
+                    format.horizontalAlignment = args.horizontalAlignment;
+                }
+                if (args.numberFormat) {
+                    format.numberFormat = args.numberFormat;
+                }
+                await SheetsHelpers.formatCells(sheets, args.spreadsheetId, args.range, format);
+                return `Successfully applied formatting to range "${args.range}".`;
+            }
+            catch (error) {
+                log.error(`Error formatting cells: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to format cells: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/freezeRowsAndColumns.js

@@ -0,0 +1,58 @@
+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: 'freezeRowsAndColumns',
+        description: 'Pins rows and/or columns so they stay visible when scrolling. Use frozenRows=1 to freeze a header row. Set a value to 0 to unfreeze.',
+        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.'),
+            frozenRows: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('Number of rows to freeze from the top (e.g., 1 for a header row). Set to 0 to unfreeze rows.'),
+            frozenColumns: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('Number of columns to freeze from the left. Set to 0 to unfreeze columns.'),
+        })
+            .refine((data) => data.frozenRows !== undefined || data.frozenColumns !== undefined, {
+            message: 'At least one of frozenRows or frozenColumns must be provided.',
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Freezing rows=${args.frozenRows ?? 'unchanged'}, cols=${args.frozenColumns ?? 'unchanged'} in spreadsheet ${args.spreadsheetId}`);
+            try {
+                await SheetsHelpers.freezeRowsAndColumns(sheets, args.spreadsheetId, args.sheetName, args.frozenRows, args.frozenColumns);
+                const parts = [];
+                if (args.frozenRows !== undefined) {
+                    parts.push(args.frozenRows === 0 ? 'unfroze rows' : `froze top ${args.frozenRows} row(s)`);
+                }
+                if (args.frozenColumns !== undefined) {
+                    parts.push(args.frozenColumns === 0
+                        ? 'unfroze columns'
+                        : `froze left ${args.frozenColumns} column(s)`);
+                }
+                return `Successfully ${parts.join(' and ')}.`;
+            }
+            catch (error) {
+                log.error(`Error freezing rows/columns: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to freeze rows/columns: ${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.object({
+            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.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'}`);
+            }
+        },
+    });
+}