@triffon/google-docs-mcp 1.11.3-triffon

package/dist/tools/docs/deleteTableRows.js

@@ -0,0 +1,62 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { getTableById } from './structureHelpers.js';
+import { TABLE_CONTENT_BASIC_BODY_FIELDS, buildDocumentGetFields } from './tabFieldMasks.js';
+export function register(server) {
+    server.addTool({
+        name: 'deleteTableRows',
+        description: 'Deletes one or more rows from an existing Google Docs table without replacing the whole document.',
+        parameters: DocumentIdParameter.extend({
+            tableId: z
+                .string()
+                .min(1)
+                .describe('The MCP table ID returned by listDocumentTables, for example "table:body:0".'),
+            rowStart: z.number().int().min(0).describe('Zero-based starting row index to delete.'),
+            rowCount: z.number().int().min(1).describe('Number of rows to delete.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab containing the table. If not specified, uses the first tab or legacy document body.'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Deleting ${args.rowCount} row(s) from ${args.tableId} in doc ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+            try {
+                const res = await docs.documents.get({
+                    documentId: args.documentId,
+                    ...(args.tabId && { includeTabsContent: true }),
+                    fields: buildDocumentGetFields(TABLE_CONTENT_BASIC_BODY_FIELDS, args.tabId),
+                });
+                const table = getTableById(res.data, args.tableId, args.tabId);
+                if (!table) {
+                    throw new UserError(`Table "${args.tableId}" not found in document.`);
+                }
+                if (table.startIndex == null) {
+                    throw new UserError(`Table "${args.tableId}" does not expose a valid table start index.`);
+                }
+                if (args.rowStart + args.rowCount > table.rowCount) {
+                    throw new UserError(`Requested rows ${args.rowStart}-${args.rowStart + args.rowCount - 1} exceed table ${args.tableId} row count ${table.rowCount}.`);
+                }
+                const requests = [];
+                for (let rowIndex = args.rowStart + args.rowCount - 1; rowIndex >= args.rowStart; rowIndex--) {
+                    requests.push(GDocsHelpers.buildDeleteTableRowRequest(table.startIndex, rowIndex, args.tabId));
+                }
+                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, requests);
+                return `Successfully deleted ${args.rowCount} row(s) from table ${args.tableId}.`;
+            }
+            catch (error) {
+                log.error(`Error deleting rows from ${args.tableId} in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                if (error.code === 404)
+                    throw new UserError(`Document not found (ID: ${args.documentId}).`);
+                if (error.code === 403)
+                    throw new UserError(`Permission denied for document (ID: ${args.documentId}).`);
+                throw new UserError(`Failed to delete table rows: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/findAndReplace.js

@@ -0,0 +1,54 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+const FindAndReplaceParameters = DocumentIdParameter.extend({
+    findText: z.string().min(1).describe('The text to search for in the document.'),
+    replaceText: z
+        .string()
+        .describe('The replacement text. Use an empty string to delete all occurrences.'),
+    matchCase: z
+        .boolean()
+        .optional()
+        .describe('Whether the search should be case-sensitive. Defaults to false.'),
+    tabId: z
+        .string()
+        .optional()
+        .describe('Scope replacement to a specific tab. If omitted, replaces across all tabs.'),
+});
+export function register(server) {
+    server.addTool({
+        name: 'findAndReplace',
+        description: 'Replaces all occurrences of a text string throughout the document (or a specific tab). ' +
+            'Returns the number of replacements made. Use an empty replaceText to delete all matches.',
+        parameters: FindAndReplaceParameters,
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`findAndReplace in doc ${args.documentId}: "${args.findText}" → "${args.replaceText}"` +
+                `${args.matchCase ? ' (case-sensitive)' : ''}` +
+                `${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+            try {
+                const request = {
+                    replaceAllText: {
+                        containsText: {
+                            text: args.findText,
+                            matchCase: args.matchCase ?? false,
+                        },
+                        replaceText: args.replaceText,
+                        ...(args.tabId && { tabsCriteria: { tabIds: [args.tabId] } }),
+                    },
+                };
+                const response = await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request]);
+                const changed = response.replies?.[0]?.replaceAllText?.occurrencesChanged ?? 0;
+                return `Replaced ${changed} occurrence(s) of "${args.findText}" with "${args.replaceText}".`;
+            }
+            catch (error) {
+                log.error(`Error in findAndReplace for doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to find and replace: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/findElement.js

@@ -0,0 +1,43 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+const FindElementParameters = DocumentIdParameter.extend({
+    textQuery: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Exact text to locate. Returns one result per occurrence with its document index range.'),
+    elementType: z
+        .enum(['paragraph', 'table', 'list', 'image'])
+        .optional()
+        .describe('List structural elements of this type. Only "paragraph" and "table" are supported; "list" and "image" are rejected.'),
+});
+export function register(server) {
+    server.addTool({
+        name: 'findElement',
+        description: 'Locates elements in a Google Document. With textQuery, returns the document index range (startIndex/endIndex) of every non-overlapping occurrence of the text — use each as a range for deleteRange or the text-styling tools, or its startIndex as an insertText location. With elementType "paragraph" or "table", lists those elements with their ranges and a text preview. Limitations: searches the first tab only (on multi-tab documents, tabs 2+ are not searched); paragraph listing covers top-level body paragraphs only, not paragraphs inside table cells (textQuery does search inside cells, but only one level deep — text in a table nested inside a table cell is not searched). At least one of textQuery or elementType is required.',
+        parameters: FindElementParameters,
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`findElement in doc ${args.documentId}: textQuery=${args.textQuery ?? 'none'}, elementType=${args.elementType ?? 'none'}`);
+            try {
+                const found = await GDocsHelpers.findElements(docs, args.documentId, {
+                    textQuery: args.textQuery,
+                    elementType: args.elementType,
+                });
+                if (found.length === 0) {
+                    return `No matching elements found (textQuery=${args.textQuery ?? 'none'}, elementType=${args.elementType ?? 'none'}).`;
+                }
+                return JSON.stringify({ count: found.length, elements: found }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error in findElement for doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to find elements: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/findSectionsByHeading.js

@@ -0,0 +1,46 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import { findHeadings } from './structureHelpers.js';
+import { HEADING_BODY_FIELDS, buildDocumentGetFields } from './tabFieldMasks.js';
+export function register(server) {
+    server.addTool({
+        name: 'findSectionsByHeading',
+        description: 'Finds heading-based sections in a Google Document and reports heading ranges plus the first table that follows each heading.',
+        parameters: DocumentIdParameter.extend({
+            headings: z
+                .array(z.string().min(1))
+                .min(1)
+                .max(50)
+                .describe('List of exact heading texts to locate in the document.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to inspect. If not specified, inspects the first tab or legacy document body.'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Finding sections by heading in ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}: ${args.headings.join(', ')}`);
+            try {
+                const res = await docs.documents.get({
+                    documentId: args.documentId,
+                    ...(args.tabId && { includeTabsContent: true }),
+                    fields: buildDocumentGetFields(HEADING_BODY_FIELDS, args.tabId),
+                });
+                const sections = findHeadings(res.data, args.headings, args.tabId);
+                return JSON.stringify({ sections }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error finding sections by heading in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                if (error.code === 404)
+                    throw new UserError(`Document not found (ID: ${args.documentId}).`);
+                if (error.code === 403)
+                    throw new UserError(`Permission denied for document (ID: ${args.documentId}).`);
+                throw new UserError(`Failed to find sections by heading: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/formatting/applyParagraphStyle.js

@@ -0,0 +1,83 @@
+import { UserError } from 'fastmcp';
+import { getDocsClient } from '../../../clients.js';
+import { ApplyParagraphStyleToolParameters, NotImplementedError, } from '../../../types.js';
+import * as GDocsHelpers from '../../../googleDocsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'applyParagraphStyle',
+        description: 'Applies paragraph-level formatting (alignment, spacing, heading styles) to paragraphs identified by a character range or by searching for text. Use namedStyleType to set heading levels (HEADING_1 through HEADING_6).',
+        parameters: ApplyParagraphStyleToolParameters,
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            let startIndex;
+            let endIndex;
+            log.info(`Applying paragraph style to document ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+            log.info(`Style options: ${JSON.stringify(args.style)}`);
+            log.info(`Target specification: ${JSON.stringify(args.target)}`);
+            try {
+                // STEP 1: Determine the target paragraph's range based on the targeting method
+                if ('textToFind' in args.target) {
+                    // Find the text first
+                    log.info(`Finding text "${args.target.textToFind}" (instance ${args.target.matchInstance || 1})${args.tabId ? ` in tab ${args.tabId}` : ''}`);
+                    const textRange = await GDocsHelpers.findTextRange(docs, args.documentId, args.target.textToFind, args.target.matchInstance || 1, args.tabId);
+                    if (!textRange) {
+                        throw new UserError(`Could not find "${args.target.textToFind}" in the document${args.tabId ? ` (tab: ${args.tabId})` : ''}.`);
+                    }
+                    log.info(`Found text at range ${textRange.startIndex}-${textRange.endIndex}, now locating containing paragraph`);
+                    // Then find the paragraph containing this text
+                    const paragraphRange = await GDocsHelpers.getParagraphRange(docs, args.documentId, textRange.startIndex, args.tabId);
+                    if (!paragraphRange) {
+                        throw new UserError(`Found the text but could not determine the paragraph boundaries.`);
+                    }
+                    startIndex = paragraphRange.startIndex;
+                    endIndex = paragraphRange.endIndex;
+                    log.info(`Text is contained within paragraph at range ${startIndex}-${endIndex}`);
+                }
+                else if ('indexWithinParagraph' in args.target) {
+                    // Find paragraph containing the specified index
+                    log.info(`Finding paragraph containing index ${args.target.indexWithinParagraph}${args.tabId ? ` in tab ${args.tabId}` : ''}`);
+                    const paragraphRange = await GDocsHelpers.getParagraphRange(docs, args.documentId, args.target.indexWithinParagraph, args.tabId);
+                    if (!paragraphRange) {
+                        throw new UserError(`Could not find paragraph containing index ${args.target.indexWithinParagraph}${args.tabId ? ` in tab ${args.tabId}` : ''}.`);
+                    }
+                    startIndex = paragraphRange.startIndex;
+                    endIndex = paragraphRange.endIndex;
+                    log.info(`Located paragraph at range ${startIndex}-${endIndex}`);
+                }
+                else if ('startIndex' in args.target && 'endIndex' in args.target) {
+                    // Use directly provided range
+                    startIndex = args.target.startIndex;
+                    endIndex = args.target.endIndex;
+                    log.info(`Using provided paragraph range ${startIndex}-${endIndex}`);
+                }
+                // Verify that we have a valid range
+                if (startIndex === undefined || endIndex === undefined) {
+                    throw new UserError('Could not determine target paragraph range from the provided information.');
+                }
+                if (endIndex <= startIndex) {
+                    throw new UserError(`Invalid paragraph range: end index (${endIndex}) must be greater than start index (${startIndex}).`);
+                }
+                // STEP 2: Build and apply the paragraph style request
+                log.info(`Building paragraph style request for range ${startIndex}-${endIndex}`);
+                const requestInfo = GDocsHelpers.buildUpdateParagraphStyleRequest(startIndex, endIndex, args.style, args.tabId);
+                if (!requestInfo) {
+                    return 'No valid paragraph styling options were provided.';
+                }
+                log.info(`Applying styles: ${requestInfo.fields.join(', ')}`);
+                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [requestInfo.request]);
+                return `Successfully applied paragraph styles (${requestInfo.fields.join(', ')}) to the paragraph${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
+            }
+            catch (error) {
+                // Detailed error logging
+                log.error(`Error applying paragraph style in doc ${args.documentId}:`);
+                log.error(error.stack || error.message || error);
+                if (error instanceof UserError)
+                    throw error;
+                if (error instanceof NotImplementedError)
+                    throw error;
+                // Provide a more helpful error message
+                throw new UserError(`Failed to apply paragraph style: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/formatting/applyTextStyle.js

@@ -0,0 +1,49 @@
+import { UserError } from 'fastmcp';
+import { getDocsClient } from '../../../clients.js';
+import { ApplyTextStyleToolParameters, NotImplementedError, } from '../../../types.js';
+import * as GDocsHelpers from '../../../googleDocsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'applyTextStyle',
+        description: 'Applies character-level formatting (bold, italic, color, font, etc.) to text identified by a character range or by searching for a text string. This is the primary tool for styling text in a document.',
+        parameters: ApplyTextStyleToolParameters,
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            let { startIndex, endIndex } = args.target; // Will be updated if target is text
+            log.info(`Applying text style in doc ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}. Target: ${JSON.stringify(args.target)}, Style: ${JSON.stringify(args.style)}`);
+            try {
+                // Determine target range
+                if ('textToFind' in args.target) {
+                    const range = await GDocsHelpers.findTextRange(docs, args.documentId, args.target.textToFind, args.target.matchInstance, args.tabId);
+                    if (!range) {
+                        throw new UserError(`Could not find instance ${args.target.matchInstance} of text "${args.target.textToFind}"${args.tabId ? ` in tab ${args.tabId}` : ''}.`);
+                    }
+                    startIndex = range.startIndex;
+                    endIndex = range.endIndex;
+                    log.info(`Found text "${args.target.textToFind}" (instance ${args.target.matchInstance}) at range ${startIndex}-${endIndex}`);
+                }
+                if (startIndex === undefined || endIndex === undefined) {
+                    throw new UserError('Target range could not be determined.');
+                }
+                if (endIndex <= startIndex) {
+                    throw new UserError('End index must be greater than start index for styling.');
+                }
+                // Build the request
+                const requestInfo = GDocsHelpers.buildUpdateTextStyleRequest(startIndex, endIndex, args.style, args.tabId);
+                if (!requestInfo) {
+                    return 'No valid text styling options were provided.';
+                }
+                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [requestInfo.request]);
+                return `Successfully applied text style (${requestInfo.fields.join(', ')}) to range ${startIndex}-${endIndex}${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
+            }
+            catch (error) {
+                log.error(`Error applying text style in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                if (error instanceof NotImplementedError)
+                    throw error; // Should not happen here
+                throw new UserError(`Failed to apply text style: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/formatting/batchApplyTextStyle.js

@@ -0,0 +1,86 @@
+import { UserError } from 'fastmcp';
+import { getDocsClient } from '../../../clients.js';
+import { BatchApplyTextStyleToolParameters } from '../../../types.js';
+import * as GDocsHelpers from '../../../googleDocsApiHelpers.js';
+// Mirrors MAX_BATCH_UPDATE_REQUESTS in googleDocsApiHelpers.ts — Google's own
+// per-batchUpdate-call request ceiling, not an arbitrary choice.
+const MAX_REQUESTS_PER_CALL = 50;
+export function register(server) {
+    server.addTool({
+        name: 'batchApplyTextStyle',
+        description: 'Applies character-level formatting (bold, italic, color, font, etc.) to MANY ranges in a single tool ' +
+            'call, instead of one applyTextStyle call per range. Built for scripts that colour dozens or hundreds of ' +
+            'cues: do one readDocument (format="json") pass, compute every range from that one read, then pass them ' +
+            "all here as one operations[] array. Internally chunks into batches of up to 50 requests per Docs API " +
+            'call (Google\'s per-request-array limit), so 100+ operations still cost only 2-3 API calls instead of ' +
+            '100+ round trips.',
+        parameters: BatchApplyTextStyleToolParameters,
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Batch-applying text style in doc ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}. Operations: ${args.operations.length}`);
+            const requests = [];
+            const skipped = [];
+            const fieldsSeen = new Set();
+            for (let i = 0; i < args.operations.length; i++) {
+                const op = args.operations[i];
+                let startIndex;
+                let endIndex;
+                try {
+                    if ('textToFind' in op.target) {
+                        const range = await GDocsHelpers.findTextRange(docs, args.documentId, op.target.textToFind, op.target.matchInstance, args.tabId);
+                        if (!range) {
+                            skipped.push({
+                                index: i,
+                                reason: `Could not find instance ${op.target.matchInstance} of text "${op.target.textToFind}".`,
+                            });
+                            continue;
+                        }
+                        startIndex = range.startIndex;
+                        endIndex = range.endIndex;
+                    }
+                    else {
+                        startIndex = op.target.startIndex;
+                        endIndex = op.target.endIndex;
+                    }
+                    if (startIndex === undefined || endIndex === undefined || endIndex <= startIndex) {
+                        skipped.push({ index: i, reason: 'Target range could not be determined.' });
+                        continue;
+                    }
+                    const requestInfo = GDocsHelpers.buildUpdateTextStyleRequest(startIndex, endIndex, op.style, args.tabId);
+                    if (!requestInfo) {
+                        skipped.push({ index: i, reason: 'No valid text styling options were provided.' });
+                        continue;
+                    }
+                    requests.push(requestInfo.request);
+                    requestInfo.fields.forEach((f) => fieldsSeen.add(f));
+                }
+                catch (error) {
+                    skipped.push({ index: i, reason: error.message || 'Unknown error resolving target.' });
+                }
+            }
+            if (requests.length === 0) {
+                throw new UserError(`No operations could be applied. Skipped: ${JSON.stringify(skipped)}`);
+            }
+            let apiCalls = 0;
+            const totalChunks = Math.ceil(requests.length / MAX_REQUESTS_PER_CALL);
+            try {
+                for (let i = 0; i < requests.length; i += MAX_REQUESTS_PER_CALL) {
+                    const chunk = requests.slice(i, i + MAX_REQUESTS_PER_CALL);
+                    await GDocsHelpers.executeBatchUpdate(docs, args.documentId, chunk);
+                    apiCalls++;
+                }
+            }
+            catch (error) {
+                throw new UserError(`Batch failed after ${apiCalls} of ${totalChunks} chunk(s) succeeded ` +
+                    `(${Math.min(apiCalls * MAX_REQUESTS_PER_CALL, requests.length)} of ${requests.length} operations ` +
+                    `applied before the error). Error: ${error.message || error}`);
+            }
+            const summary = `Applied ${requests.length}/${args.operations.length} text style operation(s) ` +
+                `(${Array.from(fieldsSeen).join(', ')}) to doc ${args.documentId} in ${apiCalls} Docs API call(s).`;
+            if (skipped.length > 0) {
+                return `${summary} Skipped ${skipped.length}: ${JSON.stringify(skipped)}`;
+            }
+            return summary;
+        },
+    });
+}

package/dist/tools/docs/formatting/index.js

@@ -0,0 +1,16 @@
+import { register as applyTextStyle } from './applyTextStyle.js';
+import { register as batchApplyTextStyle } from './batchApplyTextStyle.js';
+import { register as applyParagraphStyle } from './applyParagraphStyle.js';
+import { register as updateTableCellStyle } from './updateTableCellStyle.js';
+import { register as updateTableBorders } from './updateTableBorders.js';
+import { register as updateTableColumnWidth } from './updateTableColumnWidth.js';
+import { register as updateTableRowStyle } from './updateTableRowStyle.js';
+export function registerFormattingTools(server) {
+    applyTextStyle(server);
+    batchApplyTextStyle(server);
+    applyParagraphStyle(server);
+    updateTableCellStyle(server);
+    updateTableBorders(server);
+    updateTableColumnWidth(server);
+    updateTableRowStyle(server);
+}

package/dist/tools/docs/formatting/updateTableBorders.js

@@ -0,0 +1,81 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../../clients.js';
+import { DocumentIdParameter, validateHexColor, hexToRgbColor } from '../../../types.js';
+import { getTableById } from '../structureHelpers.js';
+import * as GDocsHelpers from '../../../googleDocsApiHelpers.js';
+import { TABLE_INDEX_BODY_FIELDS, buildDocumentGetFields } from '../tabFieldMasks.js';
+const createBorderSideSchema = () => z.strictObject({
+    color: z
+        .string()
+        .refine(validateHexColor, { message: 'Invalid hex color format (e.g., #000000).' })
+        .optional(),
+    widthPt: z.number().min(0).optional(),
+    dashStyle: z.enum(['SOLID', 'DASHED', 'DOTTED']).optional(),
+});
+export function register(server) {
+    server.addTool({
+        name: 'updateTableBorders',
+        description: 'Applies table border styles to a Google Docs table range. Supports top/bottom/left/right borders across a cell range.',
+        parameters: DocumentIdParameter.extend({
+            tableId: z.string().min(1).describe('The MCP table ID returned by listDocumentTables.'),
+            rowStart: z.number().int().min(0).describe('Zero-based starting row index.'),
+            rowEnd: z.number().int().min(0).describe('Zero-based ending row index (inclusive).'),
+            columnStart: z.number().int().min(0).describe('Zero-based starting column index.'),
+            columnEnd: z.number().int().min(0).describe('Zero-based ending column index (inclusive).'),
+            top: createBorderSideSchema().optional(),
+            bottom: createBorderSideSchema().optional(),
+            left: createBorderSideSchema().optional(),
+            right: createBorderSideSchema().optional(),
+            tabId: z.string().optional().describe('Optional target tab ID.'),
+        })
+            .refine((data) => data.rowEnd >= data.rowStart, {
+            message: 'rowEnd must be greater than or equal to rowStart',
+            path: ['rowEnd'],
+        })
+            .refine((data) => data.columnEnd >= data.columnStart, {
+            message: 'columnEnd must be greater than or equal to columnStart',
+            path: ['columnEnd'],
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Updating table borders in ${args.tableId} for doc ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+            try {
+                const res = await docs.documents.get({
+                    documentId: args.documentId,
+                    ...(args.tabId && { includeTabsContent: true }),
+                    fields: buildDocumentGetFields(TABLE_INDEX_BODY_FIELDS, args.tabId),
+                });
+                const table = getTableById(res.data, args.tableId, args.tabId);
+                if (!table)
+                    throw new UserError(`Table "${args.tableId}" not found in document.`);
+                if (table.startIndex == null) {
+                    throw new UserError(`Table "${args.tableId}" does not expose a valid table start index.`);
+                }
+                const defaultColor = hexToRgbColor('#000000');
+                const makeBorder = (side) => side
+                    ? GDocsHelpers.buildTableBorder(hexToRgbColor(side.color ?? '#000000') ?? defaultColor, side.widthPt ?? 1, side.dashStyle ?? 'SOLID')
+                    : undefined;
+                const requestInfo = GDocsHelpers.buildTableCellStyleRequest(table.startIndex, args.rowStart, args.columnStart, {
+                    rowSpan: args.rowEnd - args.rowStart + 1,
+                    columnSpan: args.columnEnd - args.columnStart + 1,
+                    borderTop: makeBorder(args.top),
+                    borderBottom: makeBorder(args.bottom),
+                    borderLeft: makeBorder(args.left),
+                    borderRight: makeBorder(args.right),
+                }, args.tabId);
+                if (!requestInfo) {
+                    throw new UserError('No border style options were provided.');
+                }
+                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [requestInfo.request]);
+                return `Successfully updated table borders (${requestInfo.fields.join(', ')}) for ${args.tableId}.`;
+            }
+            catch (error) {
+                log.error(`Error updating table borders for ${args.tableId} in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to update table borders: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/formatting/updateTableCellStyle.js

@@ -0,0 +1,85 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../../clients.js';
+import { getTableById } from '../structureHelpers.js';
+import * as GDocsHelpers from '../../../googleDocsApiHelpers.js';
+import { DocumentIdParameter, validateHexColor, hexToRgbColor } from '../../../types.js';
+import { TABLE_INDEX_BODY_FIELDS, buildDocumentGetFields } from '../tabFieldMasks.js';
+const HexColor = z
+    .string()
+    .refine(validateHexColor, { message: 'Invalid hex color format (e.g., #D9E2F3).' });
+const Alignment = z.enum(['TOP', 'MIDDLE', 'BOTTOM']);
+export function register(server) {
+    server.addTool({
+        name: 'updateTableCellStyle',
+        description: 'Applies cell-level formatting to a Google Docs table range, including background color, alignment, padding, and borders.',
+        parameters: DocumentIdParameter.extend({
+            tableId: z.string().min(1).describe('The MCP table ID returned by listDocumentTables.'),
+            rowStart: z.number().int().min(0).describe('Zero-based starting row index.'),
+            rowEnd: z.number().int().min(0).describe('Zero-based ending row index (inclusive).'),
+            columnStart: z.number().int().min(0).describe('Zero-based starting column index.'),
+            columnEnd: z.number().int().min(0).describe('Zero-based ending column index (inclusive).'),
+            backgroundColor: HexColor.optional().describe('Cell background color, e.g. "#D9E2F3".'),
+            contentAlignment: Alignment.optional().describe('Vertical content alignment inside cells.'),
+            paddingTopPt: z.number().min(0).optional().describe('Top padding in points.'),
+            paddingBottomPt: z.number().min(0).optional().describe('Bottom padding in points.'),
+            paddingLeftPt: z.number().min(0).optional().describe('Left padding in points.'),
+            paddingRightPt: z.number().min(0).optional().describe('Right padding in points.'),
+            tabId: z.string().optional().describe('Optional target tab ID.'),
+        })
+            .refine((data) => data.rowEnd >= data.rowStart, {
+            message: 'rowEnd must be greater than or equal to rowStart',
+            path: ['rowEnd'],
+        })
+            .refine((data) => data.columnEnd >= data.columnStart, {
+            message: 'columnEnd must be greater than or equal to columnStart',
+            path: ['columnEnd'],
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Updating table cell style in ${args.tableId} for doc ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+            try {
+                const res = await docs.documents.get({
+                    documentId: args.documentId,
+                    ...(args.tabId && { includeTabsContent: true }),
+                    fields: buildDocumentGetFields(TABLE_INDEX_BODY_FIELDS, args.tabId),
+                });
+                const table = getTableById(res.data, args.tableId, args.tabId);
+                if (!table)
+                    throw new UserError(`Table "${args.tableId}" not found in document.`);
+                if (table.startIndex == null) {
+                    throw new UserError(`Table "${args.tableId}" does not expose a valid table start index.`);
+                }
+                if (args.rowEnd >= table.rowCount) {
+                    throw new UserError(`rowEnd ${args.rowEnd} exceeds table row count ${table.rowCount}.`);
+                }
+                if (args.columnEnd >= table.columnCount) {
+                    throw new UserError(`columnEnd ${args.columnEnd} exceeds table column count ${table.columnCount}.`);
+                }
+                const requestInfo = GDocsHelpers.buildTableCellStyleRequest(table.startIndex, args.rowStart, args.columnStart, {
+                    rowSpan: args.rowEnd - args.rowStart + 1,
+                    columnSpan: args.columnEnd - args.columnStart + 1,
+                    backgroundColor: args.backgroundColor
+                        ? (hexToRgbColor(args.backgroundColor) ?? undefined)
+                        : undefined,
+                    contentAlignment: args.contentAlignment,
+                    paddingTopPt: args.paddingTopPt,
+                    paddingBottomPt: args.paddingBottomPt,
+                    paddingLeftPt: args.paddingLeftPt,
+                    paddingRightPt: args.paddingRightPt,
+                }, args.tabId);
+                if (!requestInfo) {
+                    throw new UserError('No table cell style options were provided.');
+                }
+                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [requestInfo.request]);
+                return `Successfully updated table cell style (${requestInfo.fields.join(', ')}) for ${args.tableId}.`;
+            }
+            catch (error) {
+                log.error(`Error updating table cell style for ${args.tableId} in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to update table cell style: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}