google-tools-mcp 1.0.0

package/dist/tools/index.js

@@ -0,0 +1,163 @@
+// Tool discovery and lazy-loading registration.
+//
+// Only the `load_google_tools` discovery tool is registered at startup.
+// When a category is loaded, its tools are dynamically registered and the
+// client is notified via tools/list_changed so it picks them up.
+import { z } from 'zod';
+import * as fs from 'fs/promises';
+import { getTokenPath } from '../auth.js';
+import { resetClients } from '../clients.js';
+import { logger } from '../logger.js';
+
+// --- Category registry ---
+// Maps category names to { loader, description, toolCount }
+const CATEGORIES = {
+    files: {
+        description: 'Google Drive file management — list, search, create, copy, move, rename, delete files/folders, read file contents (pdf, docx), search within files',
+        toolCount: 16,
+        async loader(server) {
+            const { registerDriveTools } = await import('./drive/index.js');
+            const { registerExtrasTools } = await import('./extras/index.js');
+            registerDriveTools(server);
+            registerExtrasTools(server);
+        },
+    },
+    documents: {
+        description: 'Google Docs — read, write, insert text/tables/images, formatting, comments, tabs, markdown conversion',
+        toolCount: 23,
+        async loader(server) {
+            const { registerDocsTools } = await import('./docs/index.js');
+            const { registerUtilsTools } = await import('./utils/index.js');
+            registerDocsTools(server);
+            registerUtilsTools(server);
+        },
+    },
+    spreadsheets: {
+        description: 'Google Sheets — read, write, format cells, charts, tables, conditional formatting, data validation',
+        toolCount: 30,
+        async loader(server) {
+            const { registerSheetsTools } = await import('./sheets/index.js');
+            registerSheetsTools(server);
+        },
+    },
+    email: {
+        description: 'Gmail — send, reply, forward, get, list, delete, trash messages, create/update/send drafts, attachments, batch operations',
+        toolCount: 19,
+        async loader(server) {
+            const { register: registerMessages } = await import('./gmail/messages.js');
+            const { register: registerDrafts } = await import('./gmail/drafts.js');
+            registerMessages(server);
+            registerDrafts(server);
+        },
+    },
+    email_threads: {
+        description: 'Gmail threads — get, list, batch get, modify, delete, trash/untrash conversation threads',
+        toolCount: 7,
+        async loader(server) {
+            const { register } = await import('./gmail/threads.js');
+            register(server);
+        },
+    },
+    email_labels: {
+        description: 'Gmail labels — create, delete, get, list, update labels for organizing email',
+        toolCount: 6,
+        async loader(server) {
+            const { register } = await import('./gmail/labels.js');
+            register(server);
+        },
+    },
+    email_settings: {
+        description: 'Gmail settings — auto-forwarding, IMAP, POP, vacation responder, delegates, filters, forwarding addresses, send-as aliases, S/MIME, profile, mailbox watch',
+        toolCount: 37,
+        async loader(server) {
+            const { register } = await import('./gmail/settings.js');
+            register(server);
+        },
+    },
+};
+
+// Track which categories have been loaded
+const loadedCategories = new Set();
+
+// ---------------------------------------------------------------------------
+// Notify the MCP client that the tool list has changed
+// ---------------------------------------------------------------------------
+function notifyToolsChanged(server) {
+    try {
+        const session = server.sessions?.[0];
+        if (session?.server?.notification) {
+            session.server.notification({ method: 'notifications/tools/list_changed' });
+            logger.debug('Sent tools/list_changed notification.');
+        } else {
+            logger.debug('No session available for tools/list_changed notification.');
+        }
+    } catch (err) {
+        logger.warn('Failed to send tools/list_changed notification:', err.message);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Public: register the discovery tool (and logout)
+// ---------------------------------------------------------------------------
+export function registerAllTools(server) {
+    // --- Discovery tool ---
+    server.addTool({
+        name: 'load_google_tools',
+        description:
+            'Load Google Workspace tools by category. Call this first before using any Google service.\n\n' +
+            'Categories:\n' +
+            Object.entries(CATEGORIES)
+                .map(([name, { description, toolCount }]) => `  • ${name} (${toolCount} tools) — ${description}`)
+                .join('\n') +
+            '\n\nYou can load multiple categories at once by passing an array.',
+        parameters: z.object({
+            categories: z
+                .array(z.enum(Object.keys(CATEGORIES)))
+                .describe('One or more category names to load'),
+        }),
+        execute: async ({ categories }, { log }) => {
+            const results = [];
+            for (const cat of categories) {
+                if (loadedCategories.has(cat)) {
+                    results.push({ category: cat, status: 'already_loaded' });
+                    continue;
+                }
+                log.info(`Loading category: ${cat}`);
+                await CATEGORIES[cat].loader(server);
+                loadedCategories.add(cat);
+                results.push({
+                    category: cat,
+                    status: 'loaded',
+                    toolCount: CATEGORIES[cat].toolCount,
+                });
+            }
+            notifyToolsChanged(server);
+            return JSON.stringify({
+                loaded: results,
+                message: 'Tools are now available. You can call them directly.',
+                all_loaded_categories: [...loadedCategories],
+            });
+        },
+    });
+
+    // --- Logout tool (always available) ---
+    server.addTool({
+        name: 'logout',
+        description:
+            'Log out of the current Google account by deleting the saved OAuth token. The next tool call will require re-authentication.',
+        parameters: z.object({}),
+        execute: async () => {
+            const tokenPath = getTokenPath();
+            try {
+                await fs.unlink(tokenPath);
+            } catch (err) {
+                if (err.code !== 'ENOENT') throw err;
+            }
+            resetClients();
+            return JSON.stringify({
+                success: true,
+                message: 'Logged out. The next tool call will require re-authentication.',
+            });
+        },
+    });
+}

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'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/copyFormatting.js

@@ -0,0 +1,59 @@
+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: 'copyFormatting',
+        description: 'Copies formatting (not values) from a source range to a destination range within the same spreadsheet. Copies bold, colors, borders, number formats, etc.',
+        parameters: z.object({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            sourceSheetName: z.string().min(1).describe('Source sheet/tab name (e.g., "Sheet1").'),
+            sourceRange: z
+                .string()
+                .describe('A1 notation for the source range (e.g., "A1:D10"). Do not include the sheet name — use sourceSheetName instead.'),
+            destinationSheetName: z
+                .string()
+                .min(1)
+                .describe('Destination sheet/tab name (e.g., "Sheet2").'),
+            destinationRange: z
+                .string()
+                .describe('A1 notation for the destination range (e.g., "A1:D10"). Do not include the sheet name — use destinationSheetName instead.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Copying formatting from ${args.sourceSheetName}!${args.sourceRange} to ${args.destinationSheetName}!${args.destinationRange} in spreadsheet ${args.spreadsheetId}`);
+            try {
+                // Resolve sheet names to numeric IDs
+                const sourceSheetId = await SheetsHelpers.resolveSheetId(sheets, args.spreadsheetId, args.sourceSheetName);
+                const destSheetId = await SheetsHelpers.resolveSheetId(sheets, args.spreadsheetId, args.destinationSheetName);
+                // Convert A1 ranges to GridRange objects
+                const sourceGridRange = SheetsHelpers.parseA1ToGridRange(args.sourceRange, sourceSheetId);
+                const destGridRange = SheetsHelpers.parseA1ToGridRange(args.destinationRange, destSheetId);
+                await sheets.spreadsheets.batchUpdate({
+                    spreadsheetId: args.spreadsheetId,
+                    requestBody: {
+                        requests: [
+                            {
+                                copyPaste: {
+                                    source: sourceGridRange,
+                                    destination: destGridRange,
+                                    pasteType: 'PASTE_FORMAT',
+                                },
+                            },
+                        ],
+                    },
+                });
+                return `Successfully copied formatting from ${args.sourceSheetName}!${args.sourceRange} to ${args.destinationSheetName}!${args.destinationRange}.`;
+            }
+            catch (error) {
+                log.error(`Error copying formatting in spreadsheet ${args.spreadsheetId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to copy formatting: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}