@triffon/google-docs-mcp 1.11.3-triffon

package/dist/tools/docs/insertTable.js

@@ -0,0 +1,42 @@
+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 targetTab = await GDocsHelpers.getDocumentTab(docs, args.documentId, args.tabId);
+                }
+                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,125 @@
+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()).max(50))
+                .min(1)
+                .max(200)
+                .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 targetTab = await GDocsHelpers.getDocumentTab(docs, args.documentId, args.tabId);
+                }
+                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,49 @@
+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) {
+                    const targetTab = await GDocsHelpers.getDocumentTab(docs, args.documentId, args.tabId);
+                    // 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'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/listDocumentTables.js

@@ -0,0 +1,47 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import { extractDocumentTables } from './structureHelpers.js';
+import { TABLE_CONTENT_BASIC_BODY_FIELDS, buildDocumentGetFields } from './tabFieldMasks.js';
+export function register(server) {
+    server.addTool({
+        name: 'listDocumentTables',
+        description: 'Lists tables in a Google Document with stable MCP table IDs, ranges, and dimensions. Use this before table-specific editing tools.',
+        parameters: DocumentIdParameter.extend({
+            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(`Listing document tables for ${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 tables = extractDocumentTables(res.data, args.tabId).map((table) => ({
+                    tableId: table.tableId,
+                    startIndex: table.startIndex,
+                    endIndex: table.endIndex,
+                    rowCount: table.rowCount,
+                    columnCount: table.columnCount,
+                }));
+                return JSON.stringify({ tables }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing tables for 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 list document tables: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/listDocumentTabs.js

@@ -0,0 +1,59 @@
+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 { TAB_LIST_FIELDS, TAB_LIST_WITH_CONTENT_FIELDS } from './tabFieldMasks.js';
+export function register(server) {
+    server.addTool({
+        name: 'listTabs',
+        description: "Lists all tabs in a document with their IDs and hierarchy. Use the returned tab IDs with other tools' tabId parameter to target a specific tab.",
+        parameters: DocumentIdParameter.extend({
+            includeContent: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Whether to include a content summary for each tab (character count).'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Listing tabs for document: ${args.documentId}`);
+            try {
+                // Get document with tabs structure
+                const res = await docs.documents.get({
+                    documentId: args.documentId,
+                    includeTabsContent: true,
+                    // Only get essential fields for tab listing
+                    fields: args.includeContent ? TAB_LIST_WITH_CONTENT_FIELDS : TAB_LIST_FIELDS,
+                });
+                const docTitle = res.data.title || 'Untitled Document';
+                // Get all tabs in a flat list with hierarchy info
+                const allTabs = GDocsHelpers.getAllTabs(res.data);
+                const tabs = allTabs.map((tab) => {
+                    const tabProperties = tab.tabProperties || {};
+                    const tabObj = {
+                        id: tabProperties.tabId || null,
+                        title: tabProperties.title || null,
+                        index: tabProperties.index ?? null,
+                    };
+                    if (tabProperties.parentTabId) {
+                        tabObj.parentTabId = tabProperties.parentTabId;
+                    }
+                    if (args.includeContent && tab.documentTab) {
+                        tabObj.characterCount = GDocsHelpers.getTabTextLength(tab.documentTab);
+                    }
+                    return tabObj;
+                });
+                return JSON.stringify({ documentTitle: docTitle, tabs }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing tabs for doc ${args.documentId}: ${error.message || 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 list tabs: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/listSmartChips.js

@@ -0,0 +1,41 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import { extractSmartChips } from './smartChipHelpers.js';
+import { SMART_CHIP_BODY_FIELDS, buildDocumentGetFields } from './tabFieldMasks.js';
+export function register(server) {
+    server.addTool({
+        name: 'listSmartChips',
+        description: 'Lists smart chips in a Google Document, including date elements, person mentions, and rich links.',
+        parameters: DocumentIdParameter.extend({
+            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(`Listing smart chips for ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+            try {
+                const res = await docs.documents.get({
+                    documentId: args.documentId,
+                    ...(args.tabId && { includeTabsContent: true }),
+                    fields: buildDocumentGetFields(SMART_CHIP_BODY_FIELDS, args.tabId),
+                });
+                const chips = extractSmartChips(res.data, args.tabId);
+                return JSON.stringify({ smartChips: chips }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing smart chips for 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 list smart chips: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/modifyText.js

@@ -0,0 +1,147 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter, TextFindParameter, TextStyleParameters } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+const RangeTarget = z
+    .object({
+    startIndex: z.number().int().min(1).describe('Start of range (inclusive, 1-based).'),
+    endIndex: z.number().int().min(1).describe('End of range (exclusive).'),
+})
+    .refine((d) => d.endIndex > d.startIndex, {
+    message: 'endIndex must be greater than startIndex',
+    path: ['endIndex'],
+});
+const InsertionTarget = z.strictObject({
+    insertionIndex: z.number().int().min(1).describe('Index to insert at (1-based).'),
+});
+const ModifyTextParameters = DocumentIdParameter.extend({
+    target: z
+        .union([RangeTarget, TextFindParameter, InsertionTarget])
+        .describe('Target by range indices, text search, or insertion index.'),
+    text: z.string().optional().describe('New text to insert or replace with.'),
+    style: TextStyleParameters.optional().describe('Text formatting to apply.'),
+    tabId: z
+        .string()
+        .optional()
+        .describe('The ID of the specific tab to operate on. If not specified, operates on the first tab.'),
+})
+    .refine((args) => args.text !== undefined || args.style !== undefined, {
+    message: 'At least one of text or style must be provided.',
+})
+    .refine((args) => {
+    if ('insertionIndex' in args.target && args.text === undefined)
+        return false;
+    return true;
+}, { message: 'text is required when using insertionIndex target (no existing range to format).' });
+/**
+ * Pure, sync function that builds the array of Google Docs API requests for a
+ * modifyText operation. Indices must already be resolved (no text-search here).
+ */
+export function buildModifyTextRequests(opts) {
+    const { startIndex, endIndex, text, style, tabId } = opts;
+    const requests = [];
+    if (!text && !style)
+        return requests;
+    // 1. Delete existing content (only when replacing, not insert-only)
+    if (endIndex !== undefined && text !== undefined) {
+        const range = { startIndex, endIndex };
+        if (tabId)
+            range.tabId = tabId;
+        requests.push({ deleteContentRange: { range } });
+    }
+    // 2. Insert new text
+    if (text !== undefined) {
+        const location = { index: startIndex };
+        if (tabId)
+            location.tabId = tabId;
+        requests.push({ insertText: { location, text } });
+    }
+    // 3. Apply formatting
+    if (style) {
+        const formatStart = startIndex;
+        const formatEnd = text !== undefined
+            ? startIndex + text.length
+            : endIndex !== undefined
+                ? endIndex
+                : startIndex;
+        if (formatEnd > formatStart) {
+            const requestInfo = GDocsHelpers.buildUpdateTextStyleRequest(formatStart, formatEnd, style, tabId);
+            if (requestInfo) {
+                requests.push(requestInfo.request);
+            }
+        }
+    }
+    return requests;
+}
+export function register(server) {
+    server.addTool({
+        name: 'modifyText',
+        description: 'Combines text replacement/insertion and formatting in one atomic operation. ' +
+            'Can insert text at a position, replace a range or found text, apply formatting, ' +
+            "or any combination. Use readGoogleDoc with format='json' to determine indices.",
+        parameters: ModifyTextParameters,
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`modifyText on doc ${args.documentId}: target=${JSON.stringify(args.target)}` +
+                `${args.text !== undefined ? `, text="${args.text.substring(0, 50)}"` : ''}` +
+                `${args.style ? `, style=${JSON.stringify(args.style)}` : ''}` +
+                `${args.tabId ? `, tab=${args.tabId}` : ''}`);
+            try {
+                // Verify tab exists if specified
+                if (args.tabId) {
+                    const targetTab = await GDocsHelpers.getDocumentTab(docs, args.documentId, args.tabId);
+                }
+                // Resolve target to numeric indices
+                let startIndex;
+                let endIndex;
+                if ('insertionIndex' in args.target) {
+                    startIndex = args.target.insertionIndex;
+                    endIndex = undefined;
+                }
+                else 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 ?? 1} of text "${args.target.textToFind}"${args.tabId ? ` in tab ${args.tabId}` : ''}.`);
+                    }
+                    startIndex = range.startIndex;
+                    endIndex = range.endIndex;
+                    log.info(`Found text "${args.target.textToFind}" at range ${startIndex}-${endIndex}`);
+                }
+                else {
+                    startIndex = args.target.startIndex;
+                    endIndex = args.target.endIndex;
+                }
+                // Clamp to minimum 1 (index 0 is the document section break)
+                if (startIndex < 1)
+                    startIndex = 1;
+                const requests = buildModifyTextRequests({
+                    startIndex,
+                    endIndex,
+                    text: args.text,
+                    style: args.style,
+                    tabId: args.tabId,
+                });
+                if (requests.length === 0) {
+                    return 'No operations to perform.';
+                }
+                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, requests);
+                // Build descriptive result
+                const actions = [];
+                if (endIndex !== undefined && args.text !== undefined)
+                    actions.push('replaced text');
+                else if (args.text !== undefined)
+                    actions.push('inserted text');
+                if (args.style)
+                    actions.push('applied formatting');
+                return `Successfully ${actions.join(' and ')} at range ${startIndex}-${endIndex ?? startIndex + (args.text?.length ?? 0)}${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
+            }
+            catch (error) {
+                log.error(`Error in modifyText for doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to modify text: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}