mcp-google-extras 1.0.0

package/dist/tools/extras/readFile.js

@@ -0,0 +1,82 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+import mammoth from 'mammoth';
+
+function isDocx(mimeType, name) {
+    return (
+        mimeType === 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' ||
+        (name && name.endsWith('.docx'))
+    );
+}
+
+function isPdf(mimeType, name) {
+    return mimeType === 'application/pdf' || (name && name.endsWith('.pdf'));
+}
+
+async function downloadBuffer(drive, fileId) {
+    const response = await drive.files.get(
+        { fileId, alt: 'media', supportsAllDrives: true },
+        { responseType: 'arraybuffer' }
+    );
+    return Buffer.from(response.data);
+}
+
+export async function extractText(buffer, mimeType, name) {
+    if (isDocx(mimeType, name)) {
+        const result = await mammoth.extractRawText({ buffer });
+        return result.value;
+    }
+    if (isPdf(mimeType, name)) {
+        const { default: pdfParse } = await import('pdf-parse/lib/pdf-parse.js');
+        const result = await pdfParse(buffer);
+        return result.text;
+    }
+    return null;
+}
+
+export { isDocx, isPdf, downloadBuffer };
+
+export function register(server) {
+    server.addTool({
+        name: 'readFile',
+        description:
+            'Read the full text content of a .docx or .pdf file from Google Drive by file ID. ' +
+            'Use this for Word documents and PDFs that cannot be read with readDocument.',
+        parameters: z.object({
+            fileId: z.string().describe('The Google Drive file ID'),
+        }),
+        execute: async ({ fileId }, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Reading file ${fileId}`);
+
+            try {
+                const meta = await drive.files.get({
+                    fileId,
+                    fields: 'name,mimeType',
+                    supportsAllDrives: true,
+                });
+
+                const { name, mimeType } = meta.data;
+                const buffer = await downloadBuffer(drive, fileId);
+                const text = await extractText(buffer, mimeType, name);
+
+                if (text === null) {
+                    throw new UserError(
+                        `Unsupported file type: ${mimeType} (${name}). Only .docx and .pdf are supported.`
+                    );
+                }
+
+                return `# ${name}\n\n${text}`;
+            } catch (error) {
+                if (error instanceof UserError) throw error;
+                log.error(`Error reading file: ${error.message}`);
+                if (error.code === 404)
+                    throw new UserError(`File not found: ${fileId}`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Check that the file is shared with this account.');
+                throw new UserError(`Failed to read file: ${error.message}`);
+            }
+        },
+    });
+}

package/dist/tools/extras/searchFileContents.js

@@ -0,0 +1,81 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+import { isDocx, isPdf, downloadBuffer, extractText } from './readFile.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'searchFileContents',
+        description:
+            'Search Google Drive for files whose content or name matches a query. ' +
+            'For .docx and .pdf files, extracts and returns matching text snippets. ' +
+            'Use this to find information inside Office documents and PDFs.',
+        parameters: z.object({
+            query: z.string().describe('Text to search for'),
+            maxResults: z
+                .number()
+                .optional()
+                .default(5)
+                .describe('Max number of files to search (default 5)'),
+            folderId: z
+                .string()
+                .optional()
+                .describe('Restrict search to a specific folder ID'),
+        }),
+        execute: async ({ query, maxResults = 5, folderId }, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Searching file contents for: "${query}"`);
+
+            try {
+                const escaped = query.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+                let q = `fullText contains '${escaped}' and trashed = false`;
+                if (folderId) q += ` and '${folderId}' in parents`;
+
+                const response = await drive.files.list({
+                    q,
+                    pageSize: maxResults,
+                    fields: 'files(id,name,mimeType)',
+                    supportsAllDrives: true,
+                    includeItemsFromAllDrives: true,
+                });
+
+                const files = response.data.files || [];
+                if (files.length === 0) return 'No files found matching that query.';
+
+                const results = [];
+
+                for (const file of files) {
+                    const canRead = isDocx(file.mimeType, file.name) || isPdf(file.mimeType, file.name);
+
+                    if (canRead) {
+                        try {
+                            const buffer = await downloadBuffer(drive, file.id);
+                            const text = await extractText(buffer, file.mimeType, file.name);
+
+                            const lowerText = text.toLowerCase();
+                            const lowerQuery = query.toLowerCase();
+                            const idx = lowerText.indexOf(lowerQuery);
+                            const snippet =
+                                idx !== -1
+                                    ? '...' + text.slice(Math.max(0, idx - 150), idx + 300).trim() + '...'
+                                    : text.slice(0, 400).trim() + '...';
+
+                            results.push(`**${file.name}** (ID: \`${file.id}\`)\n\n${snippet}`);
+                        } catch (e) {
+                            results.push(`**${file.name}** (ID: \`${file.id}\`)\n\n[Could not read: ${e.message}]`);
+                        }
+                    } else {
+                        results.push(`**${file.name}** (ID: \`${file.id}\`, type: ${file.mimeType})`);
+                    }
+                }
+
+                return results.join('\n\n---\n\n');
+            } catch (error) {
+                log.error(`Error searching files: ${error.message}`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Check Drive access.');
+                throw new UserError(`Failed to search files: ${error.message}`);
+            }
+        },
+    });
+}

package/dist/tools/index.js

@@ -0,0 +1,15 @@
+import { registerDocsTools } from './docs/index.js';
+import { registerDriveTools } from './drive/index.js';
+import { registerSheetsTools } from './sheets/index.js';
+import { registerUtilsTools } from './utils/index.js';
+import { registerExtrasTools } from './extras/index.js';
+/**
+ * Registers all tools with the FastMCP server.
+ */
+export function registerAllTools(server) {
+    registerDocsTools(server);
+    registerDriveTools(server);
+    registerSheetsTools(server);
+    registerUtilsTools(server);
+    registerExtrasTools(server);
+}

package/dist/tools/sheets/addConditionalFormatting.js

@@ -0,0 +1,143 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+const ONE_VALUE_CONDITIONS = [
+    'NUMBER_GREATER',
+    'NUMBER_GREATER_THAN_EQ',
+    'NUMBER_LESS',
+    'NUMBER_LESS_THAN_EQ',
+    'NUMBER_EQ',
+    'NUMBER_NOT_EQ',
+    'CUSTOM_FORMULA',
+];
+const TWO_VALUE_CONDITIONS = ['NUMBER_BETWEEN', 'NUMBER_NOT_BETWEEN'];
+const NO_VALUE_CONDITIONS = ['BLANK', 'NOT_BLANK'];
+const ALL_CONDITION_TYPES = [
+    ...ONE_VALUE_CONDITIONS,
+    ...TWO_VALUE_CONDITIONS,
+    ...NO_VALUE_CONDITIONS,
+];
+export function register(server) {
+    server.addTool({
+        name: 'addConditionalFormatting',
+        description: 'Adds a conditional formatting rule to one or more ranges in a spreadsheet. Applies a format (background color, bold, text color, etc.) when cells meet a specified condition. Use CUSTOM_FORMULA for complex conditions like "=$A1>$B1". Note: each call appends a new rule — use deleteConditionalFormatting to remove existing rules before re-adding.',
+        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.'),
+            ranges: z
+                .array(z.string())
+                .min(1)
+                .describe('One or more A1 notation ranges the rule applies to (e.g., ["B2:S68"] or ["A1:A10", "C1:C10"]).'),
+            conditionType: z
+                .enum(ALL_CONDITION_TYPES)
+                .describe('The condition type. ' +
+                'NUMBER_* types compare cell values numerically. ' +
+                'CUSTOM_FORMULA evaluates a formula (e.g., "=$A1>10"). ' +
+                'BLANK/NOT_BLANK check whether a cell is empty.'),
+            conditionValues: z
+                .array(z.string())
+                .optional()
+                .describe('Values for the condition. ' +
+                'Omit or pass [] for BLANK and NOT_BLANK. ' +
+                'Pass one value for all NUMBER_* single-operand types and CUSTOM_FORMULA. ' +
+                'Pass two values for NUMBER_BETWEEN and NUMBER_NOT_BETWEEN (lower bound first).'),
+            backgroundColor: z
+                .string()
+                .optional()
+                .describe('Cell background color as hex (e.g., "#FF9900").'),
+            bold: z.boolean().optional().describe('Apply bold text formatting.'),
+            italic: z.boolean().optional().describe('Apply italic text formatting.'),
+            strikethrough: z.boolean().optional().describe('Apply strikethrough text formatting.'),
+            underline: z.boolean().optional().describe('Apply underline text formatting.'),
+            foregroundColor: z
+                .string()
+                .optional()
+                .describe('Text (foreground) color as hex (e.g., "#FF0000").'),
+            fontSize: z.number().min(1).optional().describe('Font size in points.'),
+        })
+            .refine((data) => data.backgroundColor !== undefined ||
+            data.bold !== undefined ||
+            data.italic !== undefined ||
+            data.strikethrough !== undefined ||
+            data.underline !== undefined ||
+            data.foregroundColor !== undefined ||
+            data.fontSize !== undefined, { message: 'At least one formatting option must be provided.' })
+            .refine((data) => {
+            const values = data.conditionValues ?? [];
+            if (NO_VALUE_CONDITIONS.includes(data.conditionType)) {
+                return values.length === 0;
+            }
+            if (TWO_VALUE_CONDITIONS.includes(data.conditionType)) {
+                return values.length === 2;
+            }
+            return values.length === 1;
+        }, (data) => {
+            if (NO_VALUE_CONDITIONS.includes(data.conditionType)) {
+                return { message: `${data.conditionType} does not accept condition values.` };
+            }
+            if (TWO_VALUE_CONDITIONS.includes(data.conditionType)) {
+                return { message: `${data.conditionType} requires exactly two condition values.` };
+            }
+            return { message: `${data.conditionType} requires exactly one condition value.` };
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Adding conditional format rule to spreadsheet ${args.spreadsheetId}`);
+            try {
+                const sheetId = await SheetsHelpers.resolveSheetId(sheets, args.spreadsheetId, args.sheetName);
+                const gridRanges = args.ranges.map((r) => SheetsHelpers.parseA1ToGridRange(r, sheetId));
+                const conditionValues = (args.conditionValues ?? []).map((v) => ({
+                    userEnteredValue: v,
+                }));
+                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.strikethrough !== undefined ||
+                    args.underline !== undefined ||
+                    args.fontSize !== undefined ||
+                    args.foregroundColor !== undefined;
+                if (hasTextFormat) {
+                    const textFormat = {};
+                    if (args.bold !== undefined)
+                        textFormat.bold = args.bold;
+                    if (args.italic !== undefined)
+                        textFormat.italic = args.italic;
+                    if (args.strikethrough !== undefined)
+                        textFormat.strikethrough = args.strikethrough;
+                    if (args.underline !== undefined)
+                        textFormat.underline = args.underline;
+                    if (args.fontSize !== undefined)
+                        textFormat.fontSize = args.fontSize;
+                    if (args.foregroundColor) {
+                        const rgb = SheetsHelpers.hexToRgb(args.foregroundColor);
+                        if (!rgb)
+                            throw new UserError(`Invalid foreground color: "${args.foregroundColor}".`);
+                        textFormat.foregroundColor = rgb;
+                    }
+                    format.textFormat = textFormat;
+                }
+                await SheetsHelpers.addConditionalFormatRule(sheets, args.spreadsheetId, gridRanges, args.conditionType, conditionValues, format);
+                return `Successfully added conditional formatting rule to ${args.ranges.join(', ')}.`;
+            }
+            catch (error) {
+                log.error(`Error adding conditional format rule: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to add conditional formatting: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/addSpreadsheetSheet.js

@@ -0,0 +1,34 @@
+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: 'addSheet',
+        description: "Adds a new sheet (tab) to an existing spreadsheet. Returns the new sheet's title and ID.",
+        parameters: z.object({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            sheetTitle: z.string().min(1).describe('Title for the new sheet/tab.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Adding sheet "${args.sheetTitle}" to spreadsheet ${args.spreadsheetId}`);
+            try {
+                const response = await SheetsHelpers.addSheet(sheets, args.spreadsheetId, args.sheetTitle);
+                const addedSheet = response.replies?.[0]?.addSheet?.properties;
+                if (!addedSheet) {
+                    throw new UserError('Failed to add sheet - no sheet properties returned.');
+                }
+                return `Successfully added sheet "${addedSheet.title}" (Sheet ID: ${addedSheet.sheetId}) to spreadsheet.`;
+            }
+            catch (error) {
+                log.error(`Error adding sheet to spreadsheet ${args.spreadsheetId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to add sheet: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/appendSpreadsheetRows.js

@@ -0,0 +1,43 @@
+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: 'appendRows',
+        description: 'Appends rows to the end of a sheet. Data is added after the last row with content in the specified range.',
+        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 indicating where to append (e.g., "A1" or "Sheet1!A1"). Data will be appended starting from this range.'),
+            values: z
+                .array(z.array(z.any()))
+                .describe('2D array of values to append. Each inner array represents a row.'),
+            valueInputOption: z
+                .enum(['RAW', 'USER_ENTERED'])
+                .optional()
+                .default('USER_ENTERED')
+                .describe('How input data should be interpreted. RAW: values are stored as-is. USER_ENTERED: values are parsed as if typed by a user.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Appending rows to spreadsheet ${args.spreadsheetId}, starting at: ${args.range}`);
+            try {
+                const response = await SheetsHelpers.appendValues(sheets, args.spreadsheetId, args.range, args.values, args.valueInputOption);
+                const updatedCells = response.updates?.updatedCells || 0;
+                const updatedRows = response.updates?.updatedRows || 0;
+                const updatedRange = response.updates?.updatedRange || args.range;
+                return `Successfully appended ${updatedRows} row(s) (${updatedCells} cells) to spreadsheet. Updated range: ${updatedRange}`;
+            }
+            catch (error) {
+                log.error(`Error appending to spreadsheet ${args.spreadsheetId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to append to spreadsheet: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/appendTableRows.js

@@ -0,0 +1,50 @@
+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: 'appendTableRows',
+        description: 'Appends rows to the end of a table using table-aware insertion. This method respects footers and automatically inserts rows before the footer if one exists.',
+        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 append rows to. Use listTables to see available tables.'),
+            values: z
+                .array(z.array(z.any()))
+                .min(1)
+                .describe('2D array of values to append. Each inner array represents a row.'),
+            valueInputOption: z
+                .enum(['RAW', 'USER_ENTERED'])
+                .optional()
+                .default('USER_ENTERED')
+                .describe('How input data should be interpreted. RAW: values are stored as-is. USER_ENTERED (default): values are parsed as if typed by a user.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Appending ${args.values.length} rows to table "${args.tableIdentifier}"`);
+            try {
+                // Resolve the table to get its ID
+                const { table } = await SheetsHelpers.resolveTableIdentifier(sheets, args.spreadsheetId, args.tableIdentifier);
+                // Append rows to the table
+                const result = await SheetsHelpers.appendToTableHelper(sheets, args.spreadsheetId, table.tableId || '', args.values);
+                return JSON.stringify({
+                    tableId: table.tableId,
+                    name: table.name,
+                    rowsAppended: result.rowsAppended,
+                    updatedRange: result.updatedRange,
+                    message: `Successfully appended ${result.rowsAppended} row(s) to table "${table.name}".`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error appending table rows: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to append table rows: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/autoResizeColumns.js

@@ -0,0 +1,67 @@
+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: 'autoResizeColumns',
+        description: 'Auto-resizes columns in a spreadsheet to fit their content. Optionally restrict to a column range (e.g., "A:S"); defaults to all columns.',
+        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.'),
+            columns: z
+                .string()
+                .optional()
+                .describe('Column range to resize in A1 notation (e.g., "A:S"). Omit to resize all columns.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Auto-resizing columns in spreadsheet ${args.spreadsheetId}`);
+            try {
+                const sheetId = await SheetsHelpers.resolveSheetId(sheets, args.spreadsheetId, args.sheetName);
+                const dimensionRange = {
+                    sheetId,
+                    dimension: 'COLUMNS',
+                };
+                if (args.columns) {
+                    const colonIdx = args.columns.indexOf(':');
+                    if (colonIdx !== -1) {
+                        dimensionRange.startIndex = SheetsHelpers.colLettersToIndex(args.columns.slice(0, colonIdx).trim());
+                        dimensionRange.endIndex =
+                            SheetsHelpers.colLettersToIndex(args.columns.slice(colonIdx + 1).trim()) + 1;
+                    }
+                    else {
+                        const idx = SheetsHelpers.colLettersToIndex(args.columns.trim());
+                        dimensionRange.startIndex = idx;
+                        dimensionRange.endIndex = idx + 1;
+                    }
+                }
+                await sheets.spreadsheets.batchUpdate({
+                    spreadsheetId: args.spreadsheetId,
+                    requestBody: {
+                        requests: [
+                            {
+                                autoResizeDimensions: {
+                                    dimensions: dimensionRange,
+                                },
+                            },
+                        ],
+                    },
+                });
+                const rangeDesc = args.columns ? `columns ${args.columns}` : 'all columns';
+                return `Successfully auto-resized ${rangeDesc} to fit content.`;
+            }
+            catch (error) {
+                log.error(`Error auto-resizing columns: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to auto-resize columns: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/batchWrite.js

@@ -0,0 +1,59 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'batchWrite',
+        description: 'Writes data to multiple ranges in a single API call. More efficient than multiple separate writeSpreadsheet calls when updating several ranges at once.',
+        parameters: z.object({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            data: z
+                .array(z.object({
+                range: z.string().describe('A1 notation range (e.g., "Sheet1!A1:B2").'),
+                values: z
+                    .array(z.array(z.any()))
+                    .describe('2D array of values to write. Each inner array represents a row.'),
+            }))
+                .min(1)
+                .describe('Array of range+values pairs to write in a single batch.'),
+            valueInputOption: z
+                .enum(['RAW', 'USER_ENTERED'])
+                .optional()
+                .default('USER_ENTERED')
+                .describe('How input data should be interpreted. RAW: values are stored as-is. USER_ENTERED: values are parsed as if typed by a user.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            const rangeNames = args.data.map((d) => d.range).join(', ');
+            log.info(`Batch writing to ${args.data.length} range(s) in spreadsheet ${args.spreadsheetId}: ${rangeNames}`);
+            try {
+                const response = await sheets.spreadsheets.values.batchUpdate({
+                    spreadsheetId: args.spreadsheetId,
+                    requestBody: {
+                        valueInputOption: args.valueInputOption,
+                        data: args.data.map((d) => ({ range: d.range, values: d.values })),
+                    },
+                });
+                const totalCells = response.data.totalUpdatedCells || 0;
+                const totalRows = response.data.totalUpdatedRows || 0;
+                const totalColumns = response.data.totalUpdatedColumns || 0;
+                const totalSheets = response.data.totalUpdatedSheets || 0;
+                return `Successfully batch-wrote ${totalCells} cells (${totalRows} rows, ${totalColumns} columns) across ${totalSheets} sheet(s) in ${args.data.length} range(s).`;
+            }
+            catch (error) {
+                log.error(`Error batch writing to spreadsheet ${args.spreadsheetId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                if (error.code === 404) {
+                    throw new UserError(`Spreadsheet not found (ID: ${args.spreadsheetId}). Check the ID.`);
+                }
+                if (error.code === 403) {
+                    throw new UserError(`Permission denied for spreadsheet (ID: ${args.spreadsheetId}). Ensure you have write access.`);
+                }
+                throw new UserError(`Failed to batch write to spreadsheet: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/clearSpreadsheetRange.js

@@ -0,0 +1,31 @@
+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: 'clearRange',
+        description: 'Clears all cell values in a range without deleting the cells themselves. Formatting is preserved.',
+        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 clear (e.g., "A1:B10" or "Sheet1!A1:B10").'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Clearing range ${args.range} in spreadsheet ${args.spreadsheetId}`);
+            try {
+                const response = await SheetsHelpers.clearRange(sheets, args.spreadsheetId, args.range);
+                const clearedRange = response.clearedRange || args.range;
+                return `Successfully cleared range ${clearedRange}.`;
+            }
+            catch (error) {
+                log.error(`Error clearing range in spreadsheet ${args.spreadsheetId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to clear range: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}