@alanse/mcp-server-google-workspace 0.2.1 → 1.0.2

package/dist/tools/docs/elements/gdocs_insert_image.js

@@ -0,0 +1,96 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { DocumentIdResolver } from "../../../lib/document-id-resolver.js";
+import { Validator } from "../../../lib/validation.js";
+export const schema = {
+    name: "gdocs_insert_image",
+    description: "Insert an image from a URL into a Google Document at a specific position.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            documentId: {
+                type: "string",
+                description: "Document ID or full Google Docs URL",
+            },
+            imageUrl: {
+                type: "string",
+                description: "URL of the image to insert (must be publicly accessible)",
+            },
+            index: {
+                type: "number",
+                description: "Position to insert image (1-based)",
+            },
+            width: {
+                type: "number",
+                description: "Image width in points (optional)",
+            },
+            height: {
+                type: "number",
+                description: "Image height in points (optional)",
+            },
+        },
+        required: ["documentId", "imageUrl", "index"],
+    },
+};
+export async function insertImage(args) {
+    try {
+        // Validate inputs
+        if (!Validator.validateIndex(args.index)) {
+            throw new Error("Index must be a positive integer");
+        }
+        if (!Validator.validateUrl(args.imageUrl)) {
+            throw new Error("Invalid image URL");
+        }
+        if (args.width && !Validator.validatePositiveNumber(args.width)) {
+            throw new Error("Width must be a positive number");
+        }
+        if (args.height && !Validator.validatePositiveNumber(args.height)) {
+            throw new Error("Height must be a positive number");
+        }
+        // Resolve document ID from URL if needed
+        const docRef = DocumentIdResolver.resolve(args.documentId);
+        const documentId = docRef.id;
+        const docs = google.docs("v1");
+        // Build image properties
+        const imageProperties = {
+            contentUri: args.imageUrl,
+        };
+        if (args.width || args.height) {
+            imageProperties.sourceUri = args.imageUrl;
+        }
+        // Build object size if dimensions specified
+        let objectSize;
+        if (args.width || args.height) {
+            objectSize = {
+                width: args.width ? { magnitude: args.width, unit: "PT" } : undefined,
+                height: args.height ? { magnitude: args.height, unit: "PT" } : undefined,
+            };
+        }
+        const response = await docs.documents.batchUpdate({
+            documentId,
+            requestBody: {
+                requests: [
+                    {
+                        insertInlineImage: {
+                            uri: args.imageUrl,
+                            location: {
+                                index: args.index,
+                            },
+                            objectSize,
+                        },
+                    },
+                ],
+            },
+        });
+        return ResponseFormatter.success({
+            documentId,
+            imageUrl: args.imageUrl,
+            insertedAt: args.index,
+            width: args.width,
+            height: args.height,
+        }, "Image inserted successfully");
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/docs/elements/gdocs_insert_link.js

@@ -0,0 +1,77 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { DocumentIdResolver } from "../../../lib/document-id-resolver.js";
+import { Validator } from "../../../lib/validation.js";
+export const schema = {
+    name: "gdocs_insert_link",
+    description: "Insert a hyperlink on a text range in a Google Document.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            documentId: {
+                type: "string",
+                description: "Document ID or full Google Docs URL",
+            },
+            startIndex: {
+                type: "number",
+                description: "Start position of text to link (1-based, inclusive)",
+            },
+            endIndex: {
+                type: "number",
+                description: "End position of text to link (1-based, exclusive)",
+            },
+            url: {
+                type: "string",
+                description: "URL to link to (must start with http:// or https://)",
+            },
+        },
+        required: ["documentId", "startIndex", "endIndex", "url"],
+    },
+};
+export async function insertLink(args) {
+    try {
+        // Validate inputs
+        if (!Validator.validateRange(args.startIndex, args.endIndex)) {
+            throw new Error("Invalid range: startIndex must be less than endIndex and both must be positive");
+        }
+        if (!Validator.validateUrl(args.url)) {
+            throw new Error("Invalid URL: must start with http:// or https://");
+        }
+        // Resolve document ID from URL if needed
+        const docRef = DocumentIdResolver.resolve(args.documentId);
+        const documentId = docRef.id;
+        const docs = google.docs("v1");
+        const response = await docs.documents.batchUpdate({
+            documentId,
+            requestBody: {
+                requests: [
+                    {
+                        updateTextStyle: {
+                            textStyle: {
+                                link: {
+                                    url: args.url,
+                                },
+                            },
+                            fields: "link",
+                            range: {
+                                startIndex: args.startIndex,
+                                endIndex: args.endIndex,
+                            },
+                        },
+                    },
+                ],
+            },
+        });
+        return ResponseFormatter.success({
+            documentId,
+            url: args.url,
+            range: {
+                startIndex: args.startIndex,
+                endIndex: args.endIndex,
+            },
+        }, "Hyperlink inserted successfully");
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/docs/elements/gdocs_insert_page_break.js

@@ -0,0 +1,55 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { DocumentIdResolver } from "../../../lib/document-id-resolver.js";
+import { Validator } from "../../../lib/validation.js";
+export const schema = {
+    name: "gdocs_insert_page_break",
+    description: "Insert a page break at a specific position in a Google Document.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            documentId: {
+                type: "string",
+                description: "Document ID or full Google Docs URL",
+            },
+            index: {
+                type: "number",
+                description: "Position to insert page break (1-based)",
+            },
+        },
+        required: ["documentId", "index"],
+    },
+};
+export async function insertPageBreak(args) {
+    try {
+        // Validate inputs
+        if (!Validator.validateIndex(args.index)) {
+            throw new Error("Index must be a positive integer");
+        }
+        // Resolve document ID from URL if needed
+        const docRef = DocumentIdResolver.resolve(args.documentId);
+        const documentId = docRef.id;
+        const docs = google.docs("v1");
+        const response = await docs.documents.batchUpdate({
+            documentId,
+            requestBody: {
+                requests: [
+                    {
+                        insertPageBreak: {
+                            location: {
+                                index: args.index,
+                            },
+                        },
+                    },
+                ],
+            },
+        });
+        return ResponseFormatter.success({
+            documentId,
+            insertedAt: args.index,
+        }, "Page break inserted successfully");
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/docs/elements/gdocs_insert_toc.js

@@ -0,0 +1,71 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { DocumentIdResolver } from "../../../lib/document-id-resolver.js";
+import { Validator } from "../../../lib/validation.js";
+export const schema = {
+    name: "gdocs_insert_toc",
+    description: "Insert a 'Table of Contents' heading at a specific position. NOTE: The Google Docs API doesn't support auto-generated TOC insertion. To insert an actual auto-updating TOC, use Insert > Table of contents in the Google Docs UI.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            documentId: {
+                type: "string",
+                description: "Document ID or full Google Docs URL",
+            },
+            index: {
+                type: "number",
+                description: "Position to insert TOC heading (1-based)",
+            },
+        },
+        required: ["documentId", "index"],
+    },
+};
+export async function insertToc(args) {
+    try {
+        // Validate inputs
+        if (!Validator.validateIndex(args.index)) {
+            throw new Error("Index must be a positive integer");
+        }
+        // Resolve document ID from URL if needed
+        const docRef = DocumentIdResolver.resolve(args.documentId);
+        const documentId = docRef.id;
+        const docs = google.docs("v1");
+        // NOTE: Google Docs API doesn't support programmatic TOC insertion
+        // This is a workaround that inserts a styled "Table of Contents" heading
+        const response = await docs.documents.batchUpdate({
+            documentId,
+            requestBody: {
+                requests: [
+                    {
+                        insertText: {
+                            location: {
+                                index: args.index,
+                            },
+                            text: "Table of Contents\n",
+                        },
+                    },
+                    {
+                        updateParagraphStyle: {
+                            range: {
+                                startIndex: args.index,
+                                endIndex: args.index + 19, // "Table of Contents\n".length
+                            },
+                            paragraphStyle: {
+                                namedStyleType: "HEADING_1",
+                            },
+                            fields: "namedStyleType",
+                        },
+                    },
+                ],
+            },
+        });
+        return ResponseFormatter.success({
+            documentId,
+            insertedAt: args.index,
+            note: "Inserted 'Table of Contents' heading. To insert an auto-updating TOC, use Insert > Table of contents in the Google Docs UI. The API doesn't support programmatic TOC generation.",
+        }, "Table of Contents heading inserted successfully");
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/docs/elements/gdocs_merge_documents.js

@@ -0,0 +1,104 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { DocumentIdResolver } from "../../../lib/document-id-resolver.js";
+export const schema = {
+    name: "gdocs_merge_documents",
+    description: "Merge multiple Google Documents into one. Creates a new document or appends to an existing target document.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            sourceDocumentIds: {
+                type: "array",
+                description: "Array of source document IDs or URLs to merge (in order)",
+                items: {
+                    type: "string",
+                },
+            },
+            targetDocumentId: {
+                type: "string",
+                description: "Target document ID or URL to merge into. If not provided, creates a new document.",
+            },
+            title: {
+                type: "string",
+                description: "Title for the new merged document (only used if targetDocumentId is not provided)",
+            },
+        },
+        required: ["sourceDocumentIds"],
+    },
+};
+export async function mergeDocuments(args) {
+    try {
+        if (args.sourceDocumentIds.length === 0) {
+            throw new Error("At least one source document is required");
+        }
+        const docs = google.docs("v1");
+        // Resolve source document IDs
+        const sourceIds = args.sourceDocumentIds.map((id) => {
+            const ref = DocumentIdResolver.resolve(id);
+            return ref.id;
+        });
+        // Determine target document
+        let targetDocumentId;
+        if (args.targetDocumentId) {
+            const targetRef = DocumentIdResolver.resolve(args.targetDocumentId);
+            targetDocumentId = targetRef.id;
+        }
+        else {
+            // Create a new document
+            const createResponse = await docs.documents.create({
+                requestBody: {
+                    title: args.title || "Merged Document",
+                },
+            });
+            targetDocumentId = createResponse.data.documentId;
+        }
+        // Read each source document and append to target
+        for (const sourceId of sourceIds) {
+            const sourceDoc = await docs.documents.get({ documentId: sourceId });
+            // Extract text content from source
+            let textContent = "";
+            if (sourceDoc.data.body?.content) {
+                for (const element of sourceDoc.data.body.content) {
+                    if (element.paragraph?.elements) {
+                        for (const textElement of element.paragraph.elements) {
+                            if (textElement.textRun?.content) {
+                                textContent += textElement.textRun.content;
+                            }
+                        }
+                    }
+                }
+            }
+            // Get target document end index
+            const targetDoc = await docs.documents.get({ documentId: targetDocumentId });
+            const endIndex = targetDoc.data.body?.content?.[targetDoc.data.body.content.length - 1]?.endIndex || 1;
+            // Append content to target
+            if (textContent) {
+                await docs.documents.batchUpdate({
+                    documentId: targetDocumentId,
+                    requestBody: {
+                        requests: [
+                            {
+                                insertText: {
+                                    text: "\n" + textContent,
+                                    location: {
+                                        index: endIndex - 1,
+                                    },
+                                },
+                            },
+                        ],
+                    },
+                });
+            }
+        }
+        const targetUrl = `https://docs.google.com/document/d/${targetDocumentId}/edit`;
+        return ResponseFormatter.success({
+            targetDocumentId,
+            targetDocumentUrl: targetUrl,
+            mergedDocuments: sourceIds.length,
+            sourceDocumentIds: sourceIds,
+        }, `Successfully merged ${sourceIds.length} document(s)`);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/docs/elements/gdocs_suggest_mode.js

@@ -0,0 +1,41 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { DocumentIdResolver } from "../../../lib/document-id-resolver.js";
+export const schema = {
+    name: "gdocs_suggest_mode",
+    description: "NOTE: This tool cannot programmatically control suggestion mode. The Google Docs API doesn't support enabling/disabling suggestion mode. To use suggestion mode, open the document in Google Docs UI and use the 'Editing/Suggesting/Viewing' dropdown in the top-right corner.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            documentId: {
+                type: "string",
+                description: "Document ID or full Google Docs URL",
+            },
+            enabled: {
+                type: "boolean",
+                description: "true to enable suggestion mode, false to disable",
+            },
+        },
+        required: ["documentId", "enabled"],
+    },
+};
+export async function suggestMode(args) {
+    try {
+        // Resolve document ID from URL if needed
+        const docRef = DocumentIdResolver.resolve(args.documentId);
+        const documentId = docRef.id;
+        const docs = google.docs("v1");
+        // Verify document exists
+        await docs.documents.get({ documentId });
+        // Return informative error about API limitation
+        return ResponseFormatter.error(new Error(`Suggestion mode cannot be controlled programmatically via the Google Docs API. ` +
+            `To ${args.enabled ? "enable" : "disable"} suggestion mode, please:\n\n` +
+            `1. Open the document at: https://docs.google.com/document/d/${documentId}/edit\n` +
+            `2. Click the 'Editing' dropdown in the top-right corner\n` +
+            `3. Select '${args.enabled ? "Suggesting" : "Editing"}'\n\n` +
+            `This is a limitation of the Google Docs API, not this tool.`));
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/drive/advanced/drive_empty_trash.js

@@ -0,0 +1,56 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "drive_empty_trash",
+    description: "Permanently delete all files in the trash for the authenticated user. This operation cannot be undone.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        required: [],
+    },
+};
+export async function emptyTrash(args) {
+    try {
+        const drive = google.drive("v3");
+        // First, count items in trash for confirmation message
+        let trashedItemsCount = 0;
+        let nextPageToken;
+        try {
+            // Get count of items in trash
+            const countResponse = await drive.files.list({
+                q: "trashed=true",
+                pageSize: 1,
+                fields: "nextPageToken",
+            });
+            // Try to get actual count by iterating through all pages
+            let hasMore = true;
+            nextPageToken = countResponse.data.nextPageToken || undefined;
+            // Estimate count from first response
+            if (countResponse.data.files && countResponse.data.files.length > 0) {
+                trashedItemsCount = countResponse.data.files.length;
+            }
+        }
+        catch {
+            // If count fails, proceed with emptying trash anyway
+            trashedItemsCount = 0;
+        }
+        // Empty the trash
+        await drive.files.emptyTrash({});
+        let output = `🗑️ Trash Emptied Successfully!\n`;
+        output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
+        output += `✅ All files in trash have been permanently deleted.\n`;
+        output += `⚠️ This action cannot be undone.\n`;
+        if (trashedItemsCount > 0) {
+            output += `📊 Estimated items deleted: ${trashedItemsCount}+\n`;
+        }
+        return ResponseFormatter.success({
+            status: "success",
+            message: "Trash emptied successfully",
+            timestamp: new Date().toISOString(),
+            warning: "This action cannot be undone. Deleted files are permanently removed.",
+        }, output);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/drive/advanced/drive_export_file.js

@@ -0,0 +1,158 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { convertMimeType, isGoogleWorkspaceDocument, } from "../../../lib/drive-helpers.js";
+export const schema = {
+    name: "drive_export_file",
+    description: "Export a Google Workspace document (Docs, Sheets, Slides, Drawing) to a different format. Only works with Google Workspace files.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            fileId: {
+                type: "string",
+                description: "ID of the file to export",
+            },
+            mimeType: {
+                type: "string",
+                description: "Target MIME type for export. Optional - uses default if not specified. Examples: application/pdf, text/csv, text/plain, etc.",
+                optional: true,
+            },
+            format: {
+                type: "string",
+                description: "Export format name (shorthand). For Docs: pdf, docx, html, txt, odt, rtf, epub, markdown. For Sheets: csv, xlsx, ods, tsv, html. For Slides: pdf, pptx, odp, txt. For Drawing: png, jpeg, svg, pdf.",
+                optional: true,
+            },
+        },
+        required: ["fileId"],
+    },
+};
+export async function exportFile(args) {
+    try {
+        const drive = google.drive("v3");
+        const { fileId, mimeType: customMimeType, format } = args;
+        // Get file metadata to check type
+        const fileResponse = await drive.files.get({
+            fileId,
+            fields: "id, name, mimeType, size",
+        });
+        const file = fileResponse.data;
+        const sourceMimeType = file.mimeType || "";
+        // Check if it's a Google Workspace document
+        if (!isGoogleWorkspaceDocument(sourceMimeType)) {
+            return ResponseFormatter.error(`File is not a Google Workspace document. MIME type: ${sourceMimeType}. Only Google Docs, Sheets, Slides, and Drawings can be exported.`);
+        }
+        // Determine target MIME type
+        let targetMimeType;
+        if (customMimeType) {
+            targetMimeType = customMimeType;
+        }
+        else if (format) {
+            try {
+                targetMimeType = convertMimeType(sourceMimeType, format);
+            }
+            catch (error) {
+                return ResponseFormatter.error(error.message);
+            }
+        }
+        else {
+            // Use default format
+            try {
+                targetMimeType = convertMimeType(sourceMimeType);
+            }
+            catch (error) {
+                return ResponseFormatter.error(error.message);
+            }
+        }
+        // Get export MIME type label
+        const formatLabel = getFormatLabel(targetMimeType);
+        // Export the file
+        const exportResponse = await drive.files.export({
+            fileId,
+            mimeType: targetMimeType,
+        }, { responseType: "arraybuffer" });
+        const fileBuffer = Buffer.from(exportResponse.data);
+        const base64Content = fileBuffer.toString("base64");
+        const fileName = `${file.name || "export"}.${getFileExtension(targetMimeType)}`;
+        let output = `✅ File exported successfully!\n\n`;
+        output += `📄 File Name: ${file.name}\n`;
+        output += `📊 Source Format: ${getDocumentTypeLabel(sourceMimeType)}\n`;
+        output += `📥 Exported Format: ${formatLabel}\n`;
+        output += `💾 File Size: ${(fileBuffer.length / 1024).toFixed(2)} KB\n`;
+        output += `📁 Export File Name: ${fileName}\n`;
+        return ResponseFormatter.success({
+            fileId,
+            fileName: file.name,
+            exportFileName: fileName,
+            sourceFormat: sourceMimeType,
+            targetFormat: targetMimeType,
+            fileSizeBytes: fileBuffer.length,
+            fileSizeKB: (fileBuffer.length / 1024).toFixed(2),
+            content: base64Content,
+            contentEncoding: "base64",
+        }, output);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}
+/**
+ * Get file extension based on MIME type
+ */
+function getFileExtension(mimeType) {
+    const extensions = {
+        "application/pdf": "pdf",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+        "text/html": "html",
+        "text/plain": "txt",
+        "application/vnd.oasis.opendocument.text": "odt",
+        "application/rtf": "rtf",
+        "application/epub+zip": "epub",
+        "text/markdown": "md",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
+        "text/csv": "csv",
+        "application/vnd.oasis.opendocument.spreadsheet": "ods",
+        "text/tab-separated-values": "tsv",
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
+        "application/vnd.oasis.opendocument.presentation": "odp",
+        "image/png": "png",
+        "image/jpeg": "jpg",
+        "image/svg+xml": "svg",
+    };
+    return extensions[mimeType] || "bin";
+}
+/**
+ * Get format label for display
+ */
+function getFormatLabel(mimeType) {
+    const labels = {
+        "application/pdf": "PDF Document",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "Microsoft Word",
+        "text/html": "HTML",
+        "text/plain": "Plain Text",
+        "application/vnd.oasis.opendocument.text": "OpenDocument Text",
+        "application/rtf": "Rich Text Format",
+        "application/epub+zip": "EPUB eBook",
+        "text/markdown": "Markdown",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "Microsoft Excel",
+        "text/csv": "CSV (Comma Separated Values)",
+        "application/vnd.oasis.opendocument.spreadsheet": "OpenDocument Spreadsheet",
+        "text/tab-separated-values": "TSV (Tab Separated Values)",
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation": "Microsoft PowerPoint",
+        "application/vnd.oasis.opendocument.presentation": "OpenDocument Presentation",
+        "image/png": "PNG Image",
+        "image/jpeg": "JPEG Image",
+        "image/svg+xml": "SVG Image",
+    };
+    return labels[mimeType] || mimeType;
+}
+/**
+ * Get document type label
+ */
+function getDocumentTypeLabel(mimeType) {
+    const labels = {
+        "application/vnd.google-apps.document": "Google Docs",
+        "application/vnd.google-apps.spreadsheet": "Google Sheets",
+        "application/vnd.google-apps.presentation": "Google Slides",
+        "application/vnd.google-apps.drawing": "Google Drawing",
+    };
+    return labels[mimeType] || "Google Workspace Document";
+}