@triffon/google-docs-mcp 1.11.3-triffon

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.strictObject({
+            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,44 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+import { SpreadsheetCellValueSchema } from '../../types.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.strictObject({
+            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(SpreadsheetCellValueSchema))
+                .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,51 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+import { SpreadsheetCellValueSchema } from '../../types.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.strictObject({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            tableIdentifier: z
+                .string()
+                .describe('The table name or table ID to append rows to. Use listTables to see available tables.'),
+            values: z
+                .array(z.array(SpreadsheetCellValueSchema))
+                .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.strictObject({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            sheetName: z
+                .string()
+                .optional()
+                .describe('Name of the sheet/tab. Defaults to the first sheet if not provided.'),
+            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/autoResizeRows.js

@@ -0,0 +1,63 @@
+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: 'autoResizeRows',
+        description: 'Auto-resizes rows in a spreadsheet to fit their content. Optionally restrict to a row range (e.g., startRow=2, endRow=50); defaults to all rows.',
+        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.'),
+            startRow: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('1-based start row index (inclusive). Omit to start from row 1.'),
+            endRow: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('1-based end row index (inclusive). Omit to resize to the last row.'),
+        })
+            .refine((d) => d.startRow === undefined || d.endRow === undefined || d.endRow >= d.startRow, {
+            message: 'endRow must be greater than or equal to startRow.',
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Auto-resizing rows in spreadsheet ${args.spreadsheetId}`);
+            try {
+                const sheetId = await SheetsHelpers.resolveSheetId(sheets, args.spreadsheetId, args.sheetName);
+                const dimensionRange = { sheetId, dimension: 'ROWS' };
+                if (args.startRow !== undefined)
+                    dimensionRange.startIndex = args.startRow - 1;
+                if (args.endRow !== undefined)
+                    dimensionRange.endIndex = args.endRow;
+                await sheets.spreadsheets.batchUpdate({
+                    spreadsheetId: args.spreadsheetId,
+                    requestBody: {
+                        requests: [{ autoResizeDimensions: { dimensions: dimensionRange } }],
+                    },
+                });
+                const rangeDesc = args.startRow !== undefined
+                    ? `rows ${args.startRow}–${args.endRow ?? 'end'}`
+                    : 'all rows';
+                return `Successfully auto-resized ${rangeDesc} to fit content.`;
+            }
+            catch (error) {
+                log.error(`Error auto-resizing rows: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to auto-resize rows: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/batchWrite.js

@@ -0,0 +1,61 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+import { SpreadsheetCellValueSchema } from '../../types.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.strictObject({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            data: z
+                .array(z.strictObject({
+                range: z.string().describe('A1 notation range (e.g., "Sheet1!A1:B2").'),
+                values: z
+                    .array(z.array(SpreadsheetCellValueSchema))
+                    .describe('2D array of values to write. Each inner array represents a row.'),
+            }))
+                .min(1)
+                .max(100)
+                .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.strictObject({
+            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/comments/commentAnchor.js

@@ -0,0 +1,95 @@
+/**
+ * Shared helpers for resolving the cell location of a spreadsheet comment.
+ *
+ * A comment can carry its location in two ways:
+ *  1. A real Drive `anchor` field (present on native/human-created comments).
+ *  2. A click-through deep link in the comment body, of the form
+ *     `#gid=<sheetId>&range=<A1>`, which is what `createSheetsComment` writes
+ *     for API-created comments (the Drive API cannot natively anchor
+ *     spreadsheet comments — see createSheetsComment.ts).
+ *
+ * Location-based filtering must understand both, otherwise comments created by
+ * this server are invisible to cell/row/range filters.
+ */
+/**
+ * Resolves a comment's cell location, preferring a real Drive anchor and
+ * falling back to the deep link embedded in the comment body. Returns null when
+ * neither source yields a location.
+ */
+export function extractCommentLocation(comment) {
+    const fromAnchor = comment.anchor ? parseSheetsAnchor(comment.anchor) : null;
+    if (fromAnchor)
+        return fromAnchor;
+    return comment.content ? parseDeepLink(comment.content) : null;
+}
+/**
+ * Parses a Drive Sheets anchor JSON string into a cell location.
+ * Anchor shape: `{ a: [{ sht: { sid, rng: { r, c } } }] }`.
+ */
+export function parseSheetsAnchor(anchorStr) {
+    try {
+        const anchor = JSON.parse(anchorStr);
+        const actions = anchor.a;
+        if (!actions || !Array.isArray(actions))
+            return null;
+        for (const action of actions) {
+            if (action.sht) {
+                const sid = action.sht.sid;
+                const rng = action.sht.rng;
+                if (sid !== undefined && rng) {
+                    return { sheetId: sid, row: rng.r || 0, col: rng.c || 0 };
+                }
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parses a Sheets click-through deep link of the form
+ * `#gid=<sheetId>&range=<A1>` out of free text. When the range spans multiple
+ * cells, the top-left cell is used (matching the single-cell filter logic).
+ */
+function parseDeepLink(content) {
+    const match = content.match(/#gid=(\d+)&range=([^&\s)]+)/);
+    if (!match)
+        return null;
+    const sheetId = Number(match[1]);
+    const decoded = decodeURIComponent(match[2]);
+    // Strip an optional "Sheet!" prefix, then take the top-left cell of any range.
+    const a1Range = decoded.includes('!') ? decoded.slice(decoded.lastIndexOf('!') + 1) : decoded;
+    const topLeft = a1Range.split(':')[0];
+    const cell = a1ToRowCol(topLeft);
+    if (!cell)
+        return null;
+    return { sheetId, row: cell.row, col: cell.col };
+}
+/**
+ * Converts an A1 cell reference (e.g. "B3") to zero-based row/col indices.
+ * Returns null for malformed input.
+ */
+export function a1ToRowCol(a1) {
+    const match = a1.trim().match(/^([A-Za-z]+)(\d+)$/);
+    if (!match)
+        return null;
+    const colStr = match[1].toUpperCase();
+    let col = 0;
+    for (let i = 0; i < colStr.length; i++) {
+        col = col * 26 + (colStr.charCodeAt(i) - 64);
+    }
+    return { row: parseInt(match[2], 10) - 1, col: col - 1 };
+}
+/**
+ * Converts zero-based row/col indices back to an A1 cell reference.
+ */
+export function rowColToA1(row, col) {
+    let colStr = '';
+    let c = col;
+    do {
+        colStr = String.fromCharCode(65 + (c % 26)) + colStr;
+        c = Math.floor(c / 26) - 1;
+    } while (c >= 0);
+    return `${colStr}${row + 1}`;
+}

package/dist/tools/sheets/comments/createSheetsCellNote.js

@@ -0,0 +1,33 @@
+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: 'createSheetsCellNote',
+        description: 'Creates or replaces a native Google Sheets cell note on a cell or range. Use this when the review text must be attached to a specific cell in the Sheets UI. This is a cell note, not a threaded Drive comment.',
+        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 cell or range to attach the note to, e.g. "Sheet1!F94" or "F94".'),
+            content: z.string().min(1).describe('The note content to attach to the target cell/range.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Creating native cell note on ${args.range} in ${args.spreadsheetId}`);
+            try {
+                await SheetsHelpers.setCellNote(sheets, args.spreadsheetId, args.range, args.content);
+                return `Cell note added successfully to range "${args.range}".`;
+            }
+            catch (error) {
+                log.error(`Error creating sheets cell note: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to create cell note: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}