google-tools-mcp 1.0.0

package/dist/tools/sheets/renameSheet.js

@@ -0,0 +1,48 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'renameSheet',
+        description: 'Renames a sheet (tab) in 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 rename. Use getSpreadsheetInfo to find sheet IDs.'),
+            newName: z.string().min(1).describe('The new name for the sheet.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Renaming sheet ID ${args.sheetId} to "${args.newName}" in spreadsheet ${args.spreadsheetId}`);
+            try {
+                await sheets.spreadsheets.batchUpdate({
+                    spreadsheetId: args.spreadsheetId,
+                    requestBody: {
+                        requests: [
+                            {
+                                updateSheetProperties: {
+                                    properties: {
+                                        sheetId: args.sheetId,
+                                        title: args.newName,
+                                    },
+                                    fields: 'title',
+                                },
+                            },
+                        ],
+                    },
+                });
+                return `Successfully renamed sheet (ID: ${args.sheetId}) to "${args.newName}".`;
+            }
+            catch (error) {
+                log.error(`Error renaming sheet in spreadsheet ${args.spreadsheetId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to rename sheet: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/setColumnWidths.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: 'setColumnWidths',
+        description: 'Sets the width (in pixels) of one or more columns in a spreadsheet. Accepts multiple column specs in a single call, each targeting a single column or a contiguous range (e.g., "A", "B:D").',
+        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.'),
+            columnWidths: z
+                .array(z.object({
+                column: z
+                    .string()
+                    .describe('Column or column range in A1 notation (e.g., "A", "B:D").'),
+                width: z.number().int().min(0).describe('Width in pixels. Use 0 to hide the column.'),
+            }))
+                .min(1)
+                .describe('List of column width specifications to apply.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Setting column widths in spreadsheet ${args.spreadsheetId}`);
+            try {
+                await SheetsHelpers.setColumnWidths(sheets, args.spreadsheetId, args.sheetName, args.columnWidths);
+                const summary = args.columnWidths.map((cw) => `${cw.column}=${cw.width}px`).join(', ');
+                return `Successfully set column widths: ${summary}.`;
+            }
+            catch (error) {
+                log.error(`Error setting column widths: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to set column widths: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/setDropdownValidation.js

@@ -0,0 +1,51 @@
+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: 'setDropdownValidation',
+        description: 'Adds or removes a dropdown list on a range of cells. Provide values to create a dropdown restricting input to those options. Omit values to remove dropdown validation from the 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 to apply the dropdown to (e.g., "Sheet1!B2:B100" or "C2:C50").'),
+            values: z
+                .array(z.string())
+                .optional()
+                .describe('The allowed dropdown options (e.g., ["Open", "In Progress", "Done"]). Omit to remove existing dropdown validation from the range.'),
+            strict: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe('If true, reject input that does not match one of the dropdown values.'),
+            inputMessage: z
+                .string()
+                .optional()
+                .describe('Help text shown when a cell with the dropdown is selected.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            const isClearing = !args.values || args.values.length === 0;
+            log.info(isClearing
+                ? `Clearing dropdown validation on "${args.range}" in spreadsheet ${args.spreadsheetId}`
+                : `Setting dropdown validation on "${args.range}" with ${args.values.length} options in spreadsheet ${args.spreadsheetId}`);
+            try {
+                await SheetsHelpers.setDropdownValidation(sheets, args.spreadsheetId, args.range, args.values, args.strict, args.inputMessage);
+                if (isClearing) {
+                    return `Successfully removed dropdown validation from range "${args.range}".`;
+                }
+                return `Successfully added dropdown validation to range "${args.range}" with ${args.values.length} options: ${args.values.join(', ')}.`;
+            }
+            catch (error) {
+                log.error(`Error setting dropdown validation: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to set dropdown validation: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/ungroupAllRows.js

@@ -0,0 +1,66 @@
+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: 'ungroupAllRows',
+        description: 'Removes all row groupings from a sheet by deleting the entire row dimension group. Use before re-running groupRows to prevent duplicate collapse widgets from accumulating across report refreshes.',
+        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.'),
+            totalRows: z
+                .number()
+                .int()
+                .optional()
+                .default(500)
+                .describe('Number of rows to clear groups from (default: 500). Set higher if the sheet has more rows.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Removing all row groups from spreadsheet ${args.spreadsheetId}`);
+            try {
+                const sheetId = await SheetsHelpers.resolveSheetId(sheets, args.spreadsheetId, args.sheetName);
+                const totalRows = args.totalRows ?? 500;
+                const request = {
+                    deleteDimensionGroup: {
+                        range: {
+                            sheetId,
+                            dimension: 'ROWS',
+                            startIndex: 0,
+                            endIndex: totalRows,
+                        },
+                    },
+                };
+                // deleteDimensionGroup removes one level at a time; call repeatedly until no groups remain
+                let removed = 0;
+                // eslint-disable-next-line no-constant-condition
+                while (true) {
+                    try {
+                        await sheets.spreadsheets.batchUpdate({
+                            spreadsheetId: args.spreadsheetId,
+                            requestBody: { requests: [request] },
+                        });
+                        removed++;
+                    }
+                    catch (err) {
+                        // When no groups remain the API returns an error — treat as done
+                        break;
+                    }
+                }
+                return `Successfully removed all row groups (${removed} level(s) cleared).`;
+            }
+            catch (error) {
+                log.error(`Error removing row groups: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to remove row groups: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/updateTableRange.js

@@ -0,0 +1,51 @@
+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: 'updateTableRange',
+        description: "Modifies a table's dimensions (add/remove rows and columns) by updating its range. The new range must include the original table range.",
+        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 update. Use listTables to see available tables.'),
+            range: z
+                .string()
+                .describe('New A1 notation range for the table (e.g., "Sheet1!A1:F15"). Must include the original table range.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Updating table range for "${args.tableIdentifier}": ${args.range}`);
+            try {
+                // Resolve the table to get its current info
+                const { table, sheetName } = await SheetsHelpers.resolveTableIdentifier(sheets, args.spreadsheetId, args.tableIdentifier);
+                // Parse the new range
+                const { a1Range } = SheetsHelpers.parseRange(args.range);
+                const sheetId = await SheetsHelpers.resolveSheetId(sheets, args.spreadsheetId, sheetName || undefined);
+                const newRange = SheetsHelpers.parseA1ToGridRange(a1Range, sheetId);
+                // Update the table range
+                const updatedTable = await SheetsHelpers.updateTableRangeHelper(sheets, args.spreadsheetId, table.tableId || '', newRange);
+                return JSON.stringify({
+                    tableId: updatedTable.tableId,
+                    name: updatedTable.name,
+                    oldRange: table.range
+                        ? `${SheetsHelpers.rowColToA1(table.range.startRowIndex || 0, table.range.startColumnIndex || 0)}:${SheetsHelpers.rowColToA1((table.range.endRowIndex || 1) - 1, (table.range.endColumnIndex || 1) - 1)}`
+                        : 'Unknown',
+                    newRange: args.range,
+                    columnCount: updatedTable.columnProperties?.length || 0,
+                    message: `Table "${updatedTable.name}" range updated successfully.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error updating table range: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to update table range: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/writeSpreadsheet.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: 'writeSpreadsheet',
+        description: 'Writes data to a range in a spreadsheet, overwriting existing values. Use appendRows to add data without overwriting.',
+        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 write to (e.g., "A1:B2" or "Sheet1!A1:B2").'),
+            values: z
+                .array(z.array(z.any()))
+                .describe('2D array of values to write. 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(`Writing to spreadsheet ${args.spreadsheetId}, range: ${args.range}`);
+            try {
+                const response = await SheetsHelpers.writeRange(sheets, args.spreadsheetId, args.range, args.values, args.valueInputOption);
+                const updatedCells = response.updatedCells || 0;
+                const updatedRows = response.updatedRows || 0;
+                const updatedColumns = response.updatedColumns || 0;
+                return `Successfully wrote ${updatedCells} cells (${updatedRows} rows, ${updatedColumns} columns) to range ${args.range}.`;
+            }
+            catch (error) {
+                log.error(`Error writing to spreadsheet ${args.spreadsheetId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to write to spreadsheet: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/utils/appendMarkdownToGoogleDoc.js

@@ -0,0 +1,93 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter, MarkdownConversionError } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { insertMarkdown, formatInsertResult } from '../../markdown-transformer/index.js';
+export function register(server) {
+    server.addTool({
+        name: 'appendMarkdown',
+        description: 'Appends formatted content to the end of a document using markdown syntax. Supports headings, bold, italic, strikethrough, links, and bullet/numbered lists. Use this instead of appendText when you need formatting.',
+        parameters: DocumentIdParameter.extend({
+            markdown: z.string().min(1).describe('The markdown content to append.'),
+            addNewlineIfNeeded: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe('Add spacing before appended content if needed.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to append to. If not specified, appends to the first tab.'),
+            firstHeadingAsTitle: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, the first H1 heading (# ...) in the markdown is styled as a Google Docs TITLE instead of Heading 1. Useful when the markdown represents a full document whose first line is the document title.'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Appending markdown to doc ${args.documentId} (${args.markdown.length} chars)${args.tabId ? ` in tab ${args.tabId}` : ''}`);
+            try {
+                // 1. Get document end index
+                const doc = await docs.documents.get({
+                    documentId: args.documentId,
+                    includeTabsContent: !!args.tabId,
+                    fields: args.tabId ? 'tabs' : 'body(content(endIndex))',
+                });
+                let bodyContent;
+                if (args.tabId) {
+                    const targetTab = GDocsHelpers.findTabById(doc.data, args.tabId);
+                    if (!targetTab) {
+                        throw new UserError(`Tab with ID "${args.tabId}" not found in document.`);
+                    }
+                    if (!targetTab.documentTab) {
+                        throw new UserError(`Tab "${args.tabId}" does not have content (may not be a document tab).`);
+                    }
+                    bodyContent = targetTab.documentTab.body?.content;
+                }
+                else {
+                    bodyContent = doc.data.body?.content;
+                }
+                if (!bodyContent) {
+                    throw new UserError('No content found in document/tab');
+                }
+                let startIndex = bodyContent[bodyContent.length - 1].endIndex - 1;
+                log.info(`Document end index: ${startIndex}`);
+                // 2. Add spacing if needed
+                if (args.addNewlineIfNeeded && startIndex > 1) {
+                    const location = { index: startIndex };
+                    if (args.tabId) {
+                        location.tabId = args.tabId;
+                    }
+                    await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [
+                        {
+                            insertText: {
+                                location,
+                                text: '\n\n',
+                            },
+                        },
+                    ]);
+                    startIndex += 2;
+                    log.info(`Added spacing, new start index: ${startIndex}`);
+                }
+                // 3. Convert and append markdown
+                const result = await insertMarkdown(docs, args.documentId, args.markdown, {
+                    startIndex,
+                    tabId: args.tabId,
+                    firstHeadingAsTitle: args.firstHeadingAsTitle,
+                });
+                const debugSummary = formatInsertResult(result);
+                log.info(debugSummary);
+                return `Successfully appended ${args.markdown.length} characters of markdown.\n\n${debugSummary}`;
+            }
+            catch (error) {
+                log.error(`Error appending markdown: ${error.message}`);
+                if (error instanceof UserError || error instanceof MarkdownConversionError) {
+                    throw error;
+                }
+                throw new UserError(`Failed to append markdown: ${error.message}`);
+            }
+        },
+    });
+}

package/dist/tools/utils/index.js

@@ -0,0 +1,6 @@
+import { register as replaceDocumentWithMarkdown } from './replaceDocumentWithMarkdown.js';
+import { register as appendMarkdownToGoogleDoc } from './appendMarkdownToGoogleDoc.js';
+export function registerUtilsTools(server) {
+    replaceDocumentWithMarkdown(server);
+    appendMarkdownToGoogleDoc(server);
+}

package/dist/tools/utils/replaceDocumentWithMarkdown.js

@@ -0,0 +1,154 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter, MarkdownConversionError } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { insertMarkdown, formatInsertResult } from '../../markdown-transformer/index.js';
+export function register(server) {
+    server.addTool({
+        name: 'replaceDocumentWithMarkdown',
+        description: "Replaces the entire document body with content parsed from markdown. Supports headings, bold, italic, strikethrough, links, and bullet/numbered lists. Use readDocument with format='markdown' first to get the current content, edit it, then call this tool to apply changes.",
+        parameters: DocumentIdParameter.extend({
+            markdown: z.string().min(1).describe('The markdown content to apply to the document.'),
+            preserveTitle: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, preserves the first heading/title and replaces content after it.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to replace content in. If not specified, replaces content in the first tab.'),
+            firstHeadingAsTitle: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe('If true (default), the first H1 heading (# ...) in the markdown is styled as a Google Docs TITLE instead of Heading 1. Useful when the markdown represents a full document whose first line is the document title. Set to false if the first H1 should remain a Heading 1.'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Replacing doc ${args.documentId} with markdown (${args.markdown.length} chars)${args.tabId ? ` in tab ${args.tabId}` : ''}`);
+            try {
+                // 1. Get document structure
+                const doc = await docs.documents.get({
+                    documentId: args.documentId,
+                    includeTabsContent: !!args.tabId,
+                    fields: args.tabId ? 'tabs' : 'body(content(startIndex,endIndex))',
+                });
+                // 2. Calculate replacement range
+                let startIndex = 1;
+                let bodyContent;
+                if (args.tabId) {
+                    const targetTab = GDocsHelpers.findTabById(doc.data, args.tabId);
+                    if (!targetTab) {
+                        throw new UserError(`Tab with ID "${args.tabId}" not found in document.`);
+                    }
+                    if (!targetTab.documentTab) {
+                        throw new UserError(`Tab "${args.tabId}" does not have content (may not be a document tab).`);
+                    }
+                    bodyContent = targetTab.documentTab.body?.content;
+                }
+                else {
+                    bodyContent = doc.data.body?.content;
+                }
+                if (!bodyContent) {
+                    throw new UserError('No content found in document/tab');
+                }
+                let endIndex = bodyContent[bodyContent.length - 1].endIndex - 1;
+                if (args.preserveTitle) {
+                    // Find first content element that's a heading or paragraph
+                    for (const element of bodyContent) {
+                        if (element.paragraph && element.endIndex) {
+                            startIndex = element.endIndex;
+                            break;
+                        }
+                    }
+                }
+                // 3. Delete existing content
+                if (endIndex > startIndex) {
+                    const deleteRange = { startIndex, endIndex };
+                    if (args.tabId) {
+                        deleteRange.tabId = args.tabId;
+                    }
+                    log.info(`Deleting content from index ${startIndex} to ${endIndex}`);
+                    await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [
+                        {
+                            deleteContentRange: { range: deleteRange },
+                        },
+                    ]);
+                    log.info(`Delete complete.`);
+                }
+                // 4. Clean the surviving trailing paragraph.
+                //    deleteContentRange always leaves one trailing paragraph that cannot
+                //    be deleted. If it has bullet list membership or text formatting from
+                //    the old content, all subsequently inserted text inherits those
+                //    properties, corrupting the new document. We strip both bullets and
+                //    text styles from the survivor before inserting.
+                {
+                    // Re-read to get the survivor's endIndex (always a short document now)
+                    const docAfterDelete = await docs.documents.get({
+                        documentId: args.documentId,
+                        includeTabsContent: !!args.tabId,
+                        fields: args.tabId ? 'tabs' : 'body(content(startIndex,endIndex))',
+                    });
+                    let survivorContent;
+                    if (args.tabId) {
+                        const tab = GDocsHelpers.findTabById(docAfterDelete.data, args.tabId);
+                        survivorContent = tab?.documentTab?.body?.content;
+                    }
+                    else {
+                        survivorContent = docAfterDelete.data.body?.content;
+                    }
+                    const survivorEnd = survivorContent
+                        ? survivorContent[survivorContent.length - 1].endIndex
+                        : startIndex + 1;
+                    const survivorRange = { startIndex, endIndex: survivorEnd };
+                    if (args.tabId) {
+                        survivorRange.tabId = args.tabId;
+                    }
+                    const cleanupRequests = [
+                        { deleteParagraphBullets: { range: survivorRange } },
+                        {
+                            updateTextStyle: {
+                                range: survivorRange,
+                                textStyle: {
+                                    underline: false,
+                                    bold: false,
+                                    italic: false,
+                                    strikethrough: false,
+                                    foregroundColor: {},
+                                    backgroundColor: {},
+                                },
+                                fields: 'underline,bold,italic,strikethrough,foregroundColor,backgroundColor',
+                            },
+                        },
+                    ];
+                    try {
+                        await GDocsHelpers.executeBatchUpdate(docs, args.documentId, cleanupRequests);
+                        log.info(`Cleaned surviving paragraph (bullets + text style) at range ${startIndex}-${survivorEnd}`);
+                    }
+                    catch (e) {
+                        log.info(`Survivor cleanup skipped: ${e.message}`);
+                    }
+                }
+                // 5. Convert markdown and insert (indices calculated for empty document)
+                log.info(`Inserting markdown starting at index ${startIndex} (after delete, document should be empty)`);
+                const result = await insertMarkdown(docs, args.documentId, args.markdown, {
+                    startIndex,
+                    tabId: args.tabId,
+                    firstHeadingAsTitle: args.firstHeadingAsTitle,
+                });
+                const debugSummary = formatInsertResult(result);
+                log.info(debugSummary);
+                return `Successfully replaced document content with ${args.markdown.length} characters of markdown.\n\n${debugSummary}`;
+            }
+            catch (error) {
+                log.error(`Error replacing document with markdown: ${error.message}`);
+                if (error instanceof UserError || error instanceof MarkdownConversionError) {
+                    throw error;
+                }
+                throw new UserError(`Failed to apply markdown: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}