google-tools-mcp 1.0.0

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/index.js

@@ -0,0 +1,6 @@
+import { register as applyTextStyle } from './applyTextStyle.js';
+import { register as applyParagraphStyle } from './applyParagraphStyle.js';
+export function registerFormattingTools(server) {
+    applyTextStyle(server);
+    applyParagraphStyle(server);
+}

package/dist/tools/docs/index.js

@@ -0,0 +1,38 @@
+// Core read/write
+import { register as readGoogleDoc } from './readGoogleDoc.js';
+import { register as listDocumentTabs } from './listDocumentTabs.js';
+import { register as renameTab } from './renameTab.js';
+import { register as addTab } from './addTab.js';
+import { register as appendToGoogleDoc } from './appendToGoogleDoc.js';
+import { register as insertText } from './insertText.js';
+import { register as deleteRange } from './deleteRange.js';
+import { register as modifyText } from './modifyText.js';
+import { register as findAndReplace } from './findAndReplace.js';
+// Structure
+import { register as insertTable } from './insertTable.js';
+import { register as insertTableWithData } from './insertTableWithData.js';
+import { register as insertPageBreak } from './insertPageBreak.js';
+import { register as insertImage } from './insertImage.js';
+// Sub-domains
+import { registerCommentTools } from './comments/index.js';
+import { registerFormattingTools } from './formatting/index.js';
+export function registerDocsTools(server) {
+    // Core read/write
+    readGoogleDoc(server);
+    listDocumentTabs(server);
+    renameTab(server);
+    addTab(server);
+    appendToGoogleDoc(server);
+    insertText(server);
+    deleteRange(server);
+    modifyText(server);
+    findAndReplace(server);
+    // Structure
+    insertTable(server);
+    insertTableWithData(server);
+    insertPageBreak(server);
+    insertImage(server);
+    // Sub-domains
+    registerFormattingTools(server);
+    registerCommentTools(server);
+}

package/dist/tools/docs/insertImage.js

@@ -0,0 +1,122 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient, getDriveClient, getScriptClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'insertImage',
+        description: 'Inserts an inline image into a Google Document. Provide either a publicly accessible URL or a local file path. Local files are automatically uploaded to Google Drive before insertion.',
+        parameters: DocumentIdParameter.extend({
+            imageUrl: z
+                .string()
+                .url()
+                .optional()
+                .describe('Publicly accessible URL to the image (http:// or https://).'),
+            localImagePath: z
+                .string()
+                .optional()
+                .describe('Absolute path to a local image file (supports .jpg, .jpeg, .png, .gif, .bmp, .webp, .svg). The file will be uploaded to Google Drive.'),
+            index: z
+                .number()
+                .int()
+                .min(1)
+                .describe("1-based character index in the document body where the image should be inserted. Use readDocument with format='json' to inspect indices."),
+            width: z.number().min(1).optional().describe('Width of the image in points.'),
+            height: z.number().min(1).optional().describe('Height of the image in points.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to insert into. Use listDocumentTabs to get tab IDs. If not specified, inserts into the first tab.'),
+        })
+            .refine((data) => data.imageUrl || data.localImagePath, {
+            message: 'Either imageUrl or localImagePath must be provided.',
+        })
+            .refine((data) => !(data.imageUrl && data.localImagePath), {
+            message: 'Provide only one of imageUrl or localImagePath, not both.',
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            const appsScriptDeploymentId = process.env.APPS_SCRIPT_DEPLOYMENT_ID;
+            try {
+                if (args.tabId) {
+                    const docInfo = await docs.documents.get({
+                        documentId: args.documentId,
+                        includeTabsContent: true,
+                        fields: 'tabs(tabProperties,documentTab)',
+                    });
+                    const targetTab = GDocsHelpers.findTabById(docInfo.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).`);
+                    }
+                }
+                // --- Apps Script path: local files when APPS_SCRIPT_DEPLOYMENT_ID is set ---
+                if (args.localImagePath && appsScriptDeploymentId) {
+                    const drive = await getDriveClient();
+                    const scriptClient = await getScriptClient();
+                    log.info(`[AppsScript] Uploading ${args.localImagePath} to Drive (no public sharing)`);
+                    let parentFolderId;
+                    try {
+                        const docInfo = await drive.files.get({
+                            fileId: args.documentId,
+                            fields: 'parents',
+                            supportsAllDrives: true,
+                        });
+                        if (docInfo.data.parents && docInfo.data.parents.length > 0) {
+                            parentFolderId = docInfo.data.parents[0];
+                        }
+                    }
+                    catch (folderError) {
+                        log.warn(`Could not determine document's parent folder, using Drive root: ${folderError}`);
+                    }
+                    const driveFileId = await GDocsHelpers.uploadImageToDrive(drive, args.localImagePath, parentFolderId, true // skipPublicSharing
+                    );
+                    log.info(`[AppsScript] Inserting image via marker at index ${args.index} (fileId: ${driveFileId})`);
+                    await GDocsHelpers.insertImageViaAppsScript(docs, scriptClient, appsScriptDeploymentId, args.documentId, driveFileId, args.index, args.tabId);
+                    return `Successfully inserted local image at index ${args.index} via Apps Script${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
+                }
+                // --- Standard path: public URL insertion via Docs API ---
+                let resolvedUrl;
+                if (args.localImagePath) {
+                    const drive = await getDriveClient();
+                    log.info(`Uploading local image ${args.localImagePath} and inserting at index ${args.index} in doc ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+                    let parentFolderId;
+                    try {
+                        const docInfo = await drive.files.get({
+                            fileId: args.documentId,
+                            fields: 'parents',
+                            supportsAllDrives: true,
+                        });
+                        if (docInfo.data.parents && docInfo.data.parents.length > 0) {
+                            parentFolderId = docInfo.data.parents[0];
+                        }
+                    }
+                    catch (folderError) {
+                        log.warn(`Could not determine document's parent folder, using Drive root: ${folderError}`);
+                    }
+                    resolvedUrl = await GDocsHelpers.uploadImageToDrive(drive, args.localImagePath, parentFolderId);
+                    log.info(`Image uploaded successfully, URL: ${resolvedUrl}`);
+                }
+                else {
+                    resolvedUrl = args.imageUrl;
+                    log.info(`Inserting image from URL ${resolvedUrl} at index ${args.index} in doc ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+                }
+                await GDocsHelpers.insertInlineImage(docs, args.documentId, resolvedUrl, args.index, args.width, args.height, args.tabId);
+                let sizeInfo = '';
+                if (args.width && args.height) {
+                    sizeInfo = ` with size ${args.width}x${args.height}pt`;
+                }
+                return `Successfully inserted image at index ${args.index}${sizeInfo}${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
+            }
+            catch (error) {
+                log.error(`Error inserting image in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to insert image: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/insertPageBreak.js

@@ -0,0 +1,58 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'insertPageBreak',
+        description: 'Inserts a page break at a character index in the document.',
+        parameters: DocumentIdParameter.extend({
+            index: z
+                .number()
+                .int()
+                .min(1)
+                .describe("1-based character index within the document body. Use readDocument with format='json' to inspect indices."),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to insert into. Use listDocumentTabs to get tab IDs. If not specified, inserts into the first tab.'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Inserting page break in doc ${args.documentId} at index ${args.index}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+            try {
+                // If tabId is specified, verify the tab exists
+                if (args.tabId) {
+                    const docInfo = await docs.documents.get({
+                        documentId: args.documentId,
+                        includeTabsContent: true,
+                        fields: 'tabs(tabProperties,documentTab)',
+                    });
+                    const targetTab = GDocsHelpers.findTabById(docInfo.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).`);
+                    }
+                }
+                const location = { index: args.index };
+                if (args.tabId) {
+                    location.tabId = args.tabId;
+                }
+                const request = {
+                    insertPageBreak: { location },
+                };
+                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request]);
+                return `Successfully inserted page break at index ${args.index}${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
+            }
+            catch (error) {
+                log.error(`Error inserting page break in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to insert page break: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/insertTable.js

@@ -0,0 +1,53 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'insertTable',
+        description: 'Inserts an empty table with the specified number of rows and columns at a character index in the document.',
+        parameters: DocumentIdParameter.extend({
+            rows: z.number().int().min(1).describe('Number of rows for the new table.'),
+            columns: z.number().int().min(1).describe('Number of columns for the new table.'),
+            index: z
+                .number()
+                .int()
+                .min(1)
+                .describe("1-based character index within the document body. Use readDocument with format='json' to inspect indices."),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to insert into. Use listDocumentTabs to get tab IDs. If not specified, inserts into the first tab.'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Inserting ${args.rows}x${args.columns} table in doc ${args.documentId} at index ${args.index}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+            try {
+                // If tabId is specified, verify the tab exists
+                if (args.tabId) {
+                    const docInfo = await docs.documents.get({
+                        documentId: args.documentId,
+                        includeTabsContent: true,
+                        fields: 'tabs(tabProperties,documentTab)',
+                    });
+                    const targetTab = GDocsHelpers.findTabById(docInfo.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).`);
+                    }
+                }
+                await GDocsHelpers.createTable(docs, args.documentId, args.rows, args.columns, args.index, args.tabId);
+                return `Successfully inserted a ${args.rows}x${args.columns} table at index ${args.index}${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
+            }
+            catch (error) {
+                log.error(`Error inserting table in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to insert table: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/insertTableWithData.js

@@ -0,0 +1,135 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+// --- Table Index Math ---
+// Google Docs API table index layout for an R×C table inserted at T:
+//   cellContentIndex(T, r, c, C) = T + 4 + r * (1 + 2*C) + 2*c
+// (Verified empirically; see markdownToDocs.ts lines 640-658)
+/**
+ * Builds the Google Docs API requests to insert a table and populate its cells.
+ * Exported for testability (same pattern as convertMarkdownToRequests).
+ */
+export function buildInsertTableWithDataRequests(data, index, hasHeaderRow, tabId) {
+    const numRows = data.length;
+    const numCols = data.reduce((max, row) => Math.max(max, row.length), 0);
+    if (numRows === 0 || numCols === 0) {
+        throw new UserError('Table data must contain at least one non-empty row with at least one cell.');
+    }
+    // Pad ragged rows to uniform column count
+    const normalizedData = data.map((row) => {
+        const padded = [...row];
+        while (padded.length < numCols)
+            padded.push('');
+        return padded;
+    });
+    const insertRequests = [];
+    const formatRequests = [];
+    // 1. Insert the empty table structure
+    const location = { index };
+    if (tabId)
+        location.tabId = tabId;
+    insertRequests.push({
+        insertTable: {
+            location: location,
+            rows: numRows,
+            columns: numCols,
+        },
+    });
+    // 2. Insert text into each cell, tracking cumulative offset
+    let cumulativeTextLength = 0;
+    for (let r = 0; r < numRows; r++) {
+        for (let c = 0; c < numCols; c++) {
+            const cellText = normalizedData[r][c];
+            if (!cellText)
+                continue;
+            const baseCellIndex = index + 4 + r * (1 + 2 * numCols) + 2 * c;
+            const adjustedIndex = baseCellIndex + cumulativeTextLength;
+            const cellLocation = { index: adjustedIndex };
+            if (tabId)
+                cellLocation.tabId = tabId;
+            insertRequests.push({
+                insertText: {
+                    location: cellLocation,
+                    text: cellText,
+                },
+            });
+            // 3. Bold header row cells
+            if (hasHeaderRow && r === 0) {
+                const styleReq = GDocsHelpers.buildUpdateTextStyleRequest(adjustedIndex, adjustedIndex + cellText.length, { bold: true }, tabId);
+                if (styleReq)
+                    formatRequests.push(styleReq.request);
+            }
+            cumulativeTextLength += cellText.length;
+        }
+    }
+    return [...insertRequests, ...formatRequests];
+}
+export function register(server) {
+    server.addTool({
+        name: 'insertTableWithData',
+        description: 'Inserts a table pre-populated with data at a specific index in the document. ' +
+            'All cell content is inserted in a single operation. ' +
+            'Optionally bolds the first row as a header. ' +
+            'Ragged rows are padded with empty cells to match the widest row.',
+        parameters: DocumentIdParameter.extend({
+            data: z
+                .array(z.array(z.string()))
+                .min(1)
+                .describe('A 2D array of strings representing the table contents. Each inner array is one row. ' +
+                'Example: [["Name", "Age"], ["Alice", "30"], ["Bob", "25"]]'),
+            index: z
+                .number()
+                .int()
+                .min(1)
+                .describe('1-based character index within the document body where the table should be inserted. ' +
+                "Use readDocument with format='json' to inspect indices."),
+            hasHeaderRow: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, the first row is treated as a header and its text will be bolded.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to insert into. Use listDocumentTabs to get tab IDs. ' +
+                'If not specified, inserts into the first tab.'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            const numRows = args.data.length;
+            const numCols = args.data.reduce((max, row) => Math.max(max, row.length), 0);
+            log.info(`Inserting ${numRows}x${numCols} table with data in doc ${args.documentId} at index ${args.index}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+            try {
+                // Validate tab if specified (same pattern as insertTable.ts)
+                if (args.tabId) {
+                    const docInfo = await docs.documents.get({
+                        documentId: args.documentId,
+                        includeTabsContent: true,
+                        fields: 'tabs(tabProperties,documentTab)',
+                    });
+                    const targetTab = GDocsHelpers.findTabById(docInfo.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).`);
+                    }
+                }
+                const requests = buildInsertTableWithDataRequests(args.data, args.index, args.hasHeaderRow ?? false, args.tabId);
+                const metadata = await GDocsHelpers.executeBatchUpdateWithSplitting(docs, args.documentId, requests, log);
+                return (`Successfully inserted a ${numRows}x${numCols} table with data at index ${args.index}` +
+                    `${args.tabId ? ` in tab ${args.tabId}` : ''}. ` +
+                    `${args.hasHeaderRow ? 'Header row bolded. ' : ''}` +
+                    `(${metadata.totalRequests} requests in ${metadata.totalApiCalls} API calls, ${metadata.totalElapsedMs}ms)`);
+            }
+            catch (error) {
+                log.error(`Error inserting table with data in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to insert table with data: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/insertText.js

@@ -0,0 +1,61 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'insertText',
+        description: "Inserts text at a specific character index within a document. Use readDocument with format='json' to determine the correct index.",
+        parameters: DocumentIdParameter.extend({
+            text: z.string().min(1).describe('The text to insert.'),
+            index: z
+                .number()
+                .int()
+                .min(1)
+                .describe("1-based character index within the document body. Use readDocument with format='json' to inspect indices."),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to insert into. If not specified, inserts into the first tab (or legacy document.body for documents without tabs).'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Inserting text in doc ${args.documentId} at index ${args.index}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+            try {
+                if (args.tabId) {
+                    // For tab-specific inserts, we need to verify the tab exists first
+                    const docInfo = await docs.documents.get({
+                        documentId: args.documentId,
+                        includeTabsContent: true,
+                        fields: 'tabs(tabProperties,documentTab)',
+                    });
+                    const targetTab = GDocsHelpers.findTabById(docInfo.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).`);
+                    }
+                    // Insert with tabId
+                    const location = { index: args.index, tabId: args.tabId };
+                    const request = {
+                        insertText: { location, text: args.text },
+                    };
+                    await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request]);
+                }
+                else {
+                    // Use existing helper for backward compatibility
+                    await GDocsHelpers.insertText(docs, args.documentId, args.text, args.index);
+                }
+                return `Successfully inserted text at index ${args.index}${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
+            }
+            catch (error) {
+                log.error(`Error inserting text in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to insert text: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}