@triffon/google-docs-mcp 1.11.3-triffon

package/dist/tools/docs/tableRowDataHelpers.js

@@ -0,0 +1,53 @@
+import { UserError } from 'fastmcp';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+export function buildReplaceTableCellContentRequests(cell, nextValue, tabId) {
+    const requests = [];
+    const insertionIndex = cell.contentStartIndex ?? cell.startIndex;
+    if (insertionIndex == null) {
+        throw new UserError(`Cell [row=${cell.rowIndex}, col=${cell.columnIndex}] does not have a writable insertion index.`);
+    }
+    if (cell.text &&
+        cell.contentStartIndex !== null &&
+        cell.contentEndIndex !== null &&
+        cell.contentEndIndex - 1 > cell.contentStartIndex) {
+        const range = {
+            startIndex: cell.contentStartIndex,
+            endIndex: cell.contentEndIndex - 1,
+        };
+        if (tabId)
+            range.tabId = tabId;
+        requests.push({
+            deleteContentRange: { range: range },
+        });
+    }
+    if (nextValue) {
+        const location = { index: insertionIndex };
+        if (tabId)
+            location.tabId = tabId;
+        requests.push({
+            insertText: {
+                location: location,
+                text: nextValue,
+            },
+        });
+    }
+    return requests;
+}
+export function buildReplaceTableRowRequests(table, rowIndex, values, tabId) {
+    if (rowIndex < 0 || rowIndex >= table.rowCount) {
+        throw new UserError(`Row index ${rowIndex} is out of bounds for table ${table.tableId} with ${table.rowCount} rows.`);
+    }
+    if (values.length > table.columnCount) {
+        throw new UserError(`Received ${values.length} values for table ${table.tableId}, but the table only has ${table.columnCount} columns.`);
+    }
+    return table.cells
+        .filter((cell) => cell.rowIndex === rowIndex)
+        .sort((a, b) => b.columnIndex - a.columnIndex)
+        .flatMap((cell) => buildReplaceTableCellContentRequests(cell, values[cell.columnIndex] ?? '', tabId));
+}
+export async function replaceTableRowData(docs, documentId, table, rowIndex, values, tabId) {
+    const requests = buildReplaceTableRowRequests(table, rowIndex, values, tabId);
+    if (requests.length === 0)
+        return;
+    await GDocsHelpers.executeBatchUpdate(docs, documentId, requests);
+}

package/dist/tools/docs/updateSectionStyle.js

@@ -0,0 +1,148 @@
+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 buildUpdateSectionStyleRequest(params) {
+    const sectionStyle = {};
+    const fields = [];
+    if (params.flipPageOrientation !== undefined) {
+        sectionStyle.flipPageOrientation = params.flipPageOrientation;
+        fields.push('flipPageOrientation');
+    }
+    if (params.sectionType !== undefined) {
+        sectionStyle.sectionType = params.sectionType;
+        fields.push('sectionType');
+    }
+    if (params.marginTop !== undefined) {
+        sectionStyle.marginTop = { magnitude: params.marginTop, unit: 'PT' };
+        fields.push('marginTop');
+    }
+    if (params.marginBottom !== undefined) {
+        sectionStyle.marginBottom = { magnitude: params.marginBottom, unit: 'PT' };
+        fields.push('marginBottom');
+    }
+    if (params.marginLeft !== undefined) {
+        sectionStyle.marginLeft = { magnitude: params.marginLeft, unit: 'PT' };
+        fields.push('marginLeft');
+    }
+    if (params.marginRight !== undefined) {
+        sectionStyle.marginRight = { magnitude: params.marginRight, unit: 'PT' };
+        fields.push('marginRight');
+    }
+    if (params.pageNumberStart !== undefined) {
+        sectionStyle.pageNumberStart = params.pageNumberStart;
+        fields.push('pageNumberStart');
+    }
+    if (fields.length === 0) {
+        return null;
+    }
+    const range = {
+        startIndex: params.startIndex,
+        endIndex: params.endIndex,
+    };
+    if (params.tabId) {
+        range.tabId = params.tabId;
+    }
+    return {
+        request: {
+            updateSectionStyle: {
+                range,
+                sectionStyle,
+                fields: fields.join(','),
+            },
+        },
+        fields,
+    };
+}
+export function register(server) {
+    server.addTool({
+        name: 'updateSectionStyle',
+        description: 'Updates the style of a section identified by a character range. The range must cover the section whose style is changing — typically from the character right after an inserted section break to any index inside that section. Supports flipping page orientation (landscape <-> portrait), setting margins, and changing the section type. Common workflow for a landscape page: call insertSectionBreak with sectionType="NEXT_PAGE" before the landscape content, call insertSectionBreak again after it, then call updateSectionStyle on the range between the two breaks with flipPageOrientation=true.',
+        parameters: DocumentIdParameter.extend({
+            startIndex: z
+                .number()
+                .int()
+                .min(1)
+                .describe('The starting index of the range covering the section to style (inclusive, 1-based). Typically the index immediately after the section break that opened this section.'),
+            endIndex: z
+                .number()
+                .int()
+                .min(1)
+                .describe('The ending index of the range covering the section to style (exclusive). Any index inside the section works — the style applies to the whole section.'),
+            flipPageOrientation: z
+                .boolean()
+                .optional()
+                .describe('If true, swaps the section page width and height (effectively toggling between portrait and landscape). If false, keeps the default document orientation.'),
+            sectionType: z
+                .enum(['SECTION_TYPE_UNSPECIFIED', 'CONTINUOUS', 'NEXT_PAGE'])
+                .optional()
+                .describe('Changes the section type after the break. Usually set at insert time via insertSectionBreak, but can be updated here.'),
+            marginTop: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe('Top margin of the section in points (1 inch = 72 points).'),
+            marginBottom: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe('Bottom margin of the section in points.'),
+            marginLeft: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe('Left margin of the section in points.'),
+            marginRight: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe('Right margin of the section in points.'),
+            pageNumberStart: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('Page number to start the section from. If unset, numbering continues from the previous section.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to update. Use listDocumentTabs to get tab IDs. If not specified, targets the first tab.'),
+        }).refine((data) => data.endIndex > data.startIndex, {
+            message: 'endIndex must be greater than startIndex',
+            path: ['endIndex'],
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Updating section style in doc ${args.documentId} for range ${args.startIndex}-${args.endIndex}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+            try {
+                if (args.tabId) {
+                    const targetTab = await GDocsHelpers.getDocumentTab(docs, args.documentId, args.tabId);
+                }
+                const built = buildUpdateSectionStyleRequest({
+                    startIndex: args.startIndex,
+                    endIndex: args.endIndex,
+                    flipPageOrientation: args.flipPageOrientation,
+                    sectionType: args.sectionType,
+                    marginTop: args.marginTop,
+                    marginBottom: args.marginBottom,
+                    marginLeft: args.marginLeft,
+                    marginRight: args.marginRight,
+                    pageNumberStart: args.pageNumberStart,
+                    tabId: args.tabId,
+                });
+                if (!built) {
+                    throw new UserError('No section style options were provided. Set at least one of: flipPageOrientation, sectionType, marginTop, marginBottom, marginLeft, marginRight, pageNumberStart.');
+                }
+                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [built.request]);
+                return `Successfully updated section style (${built.fields.join(', ')}) for range ${args.startIndex}-${args.endIndex}${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
+            }
+            catch (error) {
+                log.error(`Error updating section style in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to update section style: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/copyFile.js

@@ -0,0 +1,63 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'copyFile',
+        description: "Creates a copy of a file or document in Google Drive. Returns the new copy's ID and URL.",
+        parameters: z.strictObject({
+            fileId: z
+                .string()
+                .describe('The file or folder ID from a Google Drive URL or a previous tool result.'),
+            newName: z
+                .string()
+                .optional()
+                .describe('Name for the copied file. If not provided, will use "Copy of [original name]".'),
+            parentFolderId: z
+                .string()
+                .optional()
+                .describe('ID of folder where copy should be placed. If not provided, places in same location as original.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Copying file ${args.fileId} ${args.newName ? `as "${args.newName}"` : ''}`);
+            try {
+                // Get original file info
+                const originalFile = await drive.files.get({
+                    fileId: args.fileId,
+                    fields: 'name,parents',
+                    supportsAllDrives: true,
+                });
+                const copyMetadata = {
+                    name: args.newName || `Copy of ${originalFile.data.name}`,
+                };
+                if (args.parentFolderId) {
+                    copyMetadata.parents = [args.parentFolderId];
+                }
+                else if (originalFile.data.parents) {
+                    copyMetadata.parents = originalFile.data.parents;
+                }
+                const response = await drive.files.copy({
+                    fileId: args.fileId,
+                    requestBody: copyMetadata,
+                    fields: 'id,name,webViewLink',
+                    supportsAllDrives: true,
+                });
+                const copiedFile = response.data;
+                return JSON.stringify({
+                    id: copiedFile.id,
+                    name: copiedFile.name,
+                    url: copiedFile.webViewLink,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error copying file: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('Original file or destination folder not found. Check the IDs.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have read access to the original file and write access to the destination.');
+                throw new UserError(`Failed to copy file: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/createDocument.js

@@ -0,0 +1,105 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient, getDocsClient } from '../../clients.js';
+import { insertMarkdown, formatInsertResult } from '../../markdown-transformer/index.js';
+export function register(server) {
+    server.addTool({
+        name: 'createDocument',
+        description: 'Creates a new empty Google Document. Optionally places it in a specific folder and adds initial text content.',
+        parameters: z.strictObject({
+            title: z.string().min(1).describe('Title for the new document.'),
+            parentFolderId: z
+                .string()
+                .optional()
+                .describe('ID of folder where document should be created. If not provided, creates in Drive root.'),
+            initialContent: z
+                .string()
+                .optional()
+                .describe('Initial content to add to the document. By default, markdown syntax is converted to formatted Google Docs content (headings, bold, italic, links, lists, etc.).'),
+            contentFormat: z
+                .enum(['markdown', 'raw'])
+                .optional()
+                .default('markdown')
+                .describe("How to interpret initialContent. 'markdown' (default) converts markdown to formatted Google Docs content. 'raw' inserts the text as-is without any conversion."),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Creating new document "${args.title}"`);
+            try {
+                const documentMetadata = {
+                    name: args.title,
+                    mimeType: 'application/vnd.google-apps.document',
+                };
+                if (args.parentFolderId) {
+                    documentMetadata.parents = [args.parentFolderId];
+                }
+                const response = await drive.files.create({
+                    requestBody: documentMetadata,
+                    fields: 'id,name,webViewLink',
+                    supportsAllDrives: true,
+                });
+                const document = response.data;
+                // Add initial content if provided.
+                // NOTE: the Drive file already exists at this point, so the doc is created
+                // *empty* and content is a second API call. If that second call fails we must
+                // NOT report success — doing so silently leaves an empty document. Surface the
+                // failure loudly, including the doc id/url so the caller can append to the
+                // existing doc instead of creating a duplicate.
+                let contentInserted = false;
+                if (args.initialContent) {
+                    try {
+                        const docs = await getDocsClient();
+                        if (args.contentFormat === 'raw') {
+                            await docs.documents.batchUpdate({
+                                documentId: document.id,
+                                requestBody: {
+                                    requests: [
+                                        {
+                                            insertText: {
+                                                location: { index: 1 },
+                                                text: args.initialContent,
+                                            },
+                                        },
+                                    ],
+                                },
+                            });
+                        }
+                        else {
+                            const result = await insertMarkdown(docs, document.id, args.initialContent, {
+                                startIndex: 1,
+                                firstHeadingAsTitle: true,
+                            });
+                            log.info(formatInsertResult(result));
+                        }
+                        contentInserted = true;
+                    }
+                    catch (contentError) {
+                        const detail = contentError?.message || String(contentError);
+                        log.error(`Document created but failed to add initial content: ${detail}`);
+                        throw new UserError(`Document "${document.name}" was created (id: ${document.id}, url: ${document.webViewLink}) ` +
+                            `but inserting the initial content FAILED, so it is currently EMPTY. ` +
+                            `Append the content to this existing document (do not create a new one). ` +
+                            `Underlying error: ${detail}`);
+                    }
+                }
+                return JSON.stringify({
+                    id: document.id,
+                    name: document.name,
+                    url: document.webViewLink,
+                    contentInserted,
+                }, null, 2);
+            }
+            catch (error) {
+                // Pass through UserErrors we raised above (e.g. created-but-empty) unchanged.
+                if (error instanceof UserError)
+                    throw error;
+                log.error(`Error creating document: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('Parent folder not found. Check the folder ID.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have write access to the destination folder.');
+                throw new UserError(`Failed to create document: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/createFolder.js

@@ -0,0 +1,48 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'createFolder',
+        description: 'Creates a new folder in Google Drive. Optionally places it inside an existing parent folder.',
+        parameters: z.strictObject({
+            name: z.string().min(1).describe('Name for the new folder.'),
+            parentFolderId: z
+                .string()
+                .optional()
+                .describe('Parent folder ID. If not provided, creates folder in Drive root.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Creating folder "${args.name}" ${args.parentFolderId ? `in parent ${args.parentFolderId}` : 'in root'}`);
+            try {
+                const folderMetadata = {
+                    name: args.name,
+                    mimeType: 'application/vnd.google-apps.folder',
+                };
+                if (args.parentFolderId) {
+                    folderMetadata.parents = [args.parentFolderId];
+                }
+                const response = await drive.files.create({
+                    requestBody: folderMetadata,
+                    fields: 'id,name,parents,webViewLink',
+                    supportsAllDrives: true,
+                });
+                const folder = response.data;
+                return JSON.stringify({
+                    id: folder.id,
+                    name: folder.name,
+                    url: folder.webViewLink,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error creating folder: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('Parent folder not found. Check the parent folder ID.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have write access to the parent folder.');
+                throw new UserError(`Failed to create folder: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/createFromTemplate.js

@@ -0,0 +1,82 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient, getDocsClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'createDocumentFromTemplate',
+        description: 'Creates a new document by copying an existing template and optionally replacing placeholder text. Provide key-value pairs in the replacements parameter to substitute template variables.',
+        parameters: z.strictObject({
+            templateId: z.string().describe('ID of the template document to copy from.'),
+            newTitle: z.string().min(1).describe('Title for the new document.'),
+            parentFolderId: z
+                .string()
+                .optional()
+                .describe('ID of folder where document should be created. If not provided, creates in Drive root.'),
+            replacements: z
+                .record(z.string())
+                .optional()
+                .describe('Key-value pairs for text replacements in the template (e.g., {"{{NAME}}": "John Doe", "{{DATE}}": "2024-01-01"}).'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Creating document from template ${args.templateId} with title "${args.newTitle}"`);
+            try {
+                // First copy the template
+                const copyMetadata = {
+                    name: args.newTitle,
+                };
+                if (args.parentFolderId) {
+                    copyMetadata.parents = [args.parentFolderId];
+                }
+                const response = await drive.files.copy({
+                    fileId: args.templateId,
+                    requestBody: copyMetadata,
+                    fields: 'id,name,webViewLink',
+                    supportsAllDrives: true,
+                });
+                const document = response.data;
+                let result = `Successfully created document "${document.name}" from template (ID: ${document.id})\nView Link: ${document.webViewLink}`;
+                // Apply text replacements if provided
+                if (args.replacements && Object.keys(args.replacements).length > 0) {
+                    try {
+                        const docs = await getDocsClient();
+                        const requests = [];
+                        // Create replace requests for each replacement
+                        for (const [searchText, replaceText] of Object.entries(args.replacements)) {
+                            requests.push({
+                                replaceAllText: {
+                                    containsText: {
+                                        text: searchText,
+                                        matchCase: false,
+                                    },
+                                    replaceText: replaceText,
+                                },
+                            });
+                        }
+                        if (requests.length > 0) {
+                            await docs.documents.batchUpdate({
+                                documentId: document.id,
+                                requestBody: { requests },
+                            });
+                            const replacementCount = Object.keys(args.replacements).length;
+                            result += `\n\nApplied ${replacementCount} text replacement${replacementCount !== 1 ? 's' : ''} to the document.`;
+                        }
+                    }
+                    catch (replacementError) {
+                        log.warn(`Document created but failed to apply replacements: ${replacementError.message}`);
+                        result += `\n\nDocument created but failed to apply text replacements. You can make changes manually.`;
+                    }
+                }
+                return result;
+            }
+            catch (error) {
+                log.error(`Error creating document from template: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('Template document or parent folder not found. Check the IDs.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have read access to the template and write access to the destination folder.');
+                throw new UserError(`Failed to create document from template: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/deleteFile.js

@@ -0,0 +1,72 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'deleteFile',
+        description: 'Moves a file or folder to the trash, or permanently deletes it. Set permanent=true for irreversible deletion.',
+        parameters: z.strictObject({
+            fileId: z
+                .string()
+                .describe('The file or folder ID from a Google Drive URL or a previous tool result.'),
+            permanent: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, permanently deletes the file instead of moving it to trash.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Deleting file ${args.fileId} ${args.permanent ? '(permanent)' : '(to trash)'}`);
+            try {
+                // Get file info before deletion
+                const fileInfo = await drive.files.get({
+                    fileId: args.fileId,
+                    fields: 'name,mimeType',
+                    supportsAllDrives: true,
+                });
+                const fileName = fileInfo.data.name;
+                const isFolder = fileInfo.data.mimeType === 'application/vnd.google-apps.folder';
+                if (args.permanent) {
+                    await drive.files.delete({
+                        fileId: args.fileId,
+                        supportsAllDrives: true,
+                    });
+                    return JSON.stringify({
+                        success: true,
+                        action: 'permanently_deleted',
+                        fileId: args.fileId,
+                        fileName,
+                        type: isFolder ? 'folder' : 'file',
+                        message: `Permanently deleted ${isFolder ? 'folder' : 'file'} "${fileName}".`,
+                    }, null, 2);
+                }
+                else {
+                    await drive.files.update({
+                        fileId: args.fileId,
+                        requestBody: {
+                            trashed: true,
+                        },
+                        supportsAllDrives: true,
+                    });
+                    return JSON.stringify({
+                        success: true,
+                        action: 'trashed',
+                        fileId: args.fileId,
+                        fileName,
+                        type: isFolder ? 'folder' : 'file',
+                        message: `Moved ${isFolder ? 'folder' : 'file'} "${fileName}" to trash. It can be restored from the trash.`,
+                    }, null, 2);
+                }
+            }
+            catch (error) {
+                log.error(`Error deleting file: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('File not found. Check the file ID.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have delete access to this file.');
+                throw new UserError(`Failed to delete file: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}