@alanse/mcp-server-google-workspace 0.2.0 → 1.0.0

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

@@ -0,0 +1,77 @@
+import { google } from "googleapis";
+export const schema = {
+    name: "drive_read_file",
+    description: "Read contents of a file from Google Drive",
+    inputSchema: {
+        type: "object",
+        properties: {
+            fileId: {
+                type: "string",
+                description: "ID of the file to read",
+            },
+        },
+        required: ["fileId"],
+    },
+};
+const drive = google.drive("v3");
+export async function readFile(args) {
+    const result = await readGoogleDriveFile(args.fileId);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Contents of ${result.name}:\n\n${result.contents.text || result.contents.blob}`,
+            },
+        ],
+        isError: false,
+    };
+}
+async function readGoogleDriveFile(fileId) {
+    // First get file metadata to check mime type
+    const file = await drive.files.get({
+        fileId,
+        fields: "mimeType,name",
+    });
+    // For Google Docs/Sheets/etc we need to export
+    if (file.data.mimeType?.startsWith("application/vnd.google-apps")) {
+        let exportMimeType;
+        switch (file.data.mimeType) {
+            case "application/vnd.google-apps.document":
+                exportMimeType = "text/markdown";
+                break;
+            case "application/vnd.google-apps.spreadsheet":
+                exportMimeType = "text/csv";
+                break;
+            case "application/vnd.google-apps.presentation":
+                exportMimeType = "text/plain";
+                break;
+            case "application/vnd.google-apps.drawing":
+                exportMimeType = "image/png";
+                break;
+            default:
+                exportMimeType = "text/plain";
+        }
+        const res = await drive.files.export({ fileId, mimeType: exportMimeType }, { responseType: "text" });
+        return {
+            name: file.data.name || fileId,
+            contents: {
+                mimeType: exportMimeType,
+                text: res.data,
+            },
+        };
+    }
+    // For regular files download content
+    const res = await drive.files.get({ fileId, alt: "media" }, { responseType: "arraybuffer" });
+    const mimeType = file.data.mimeType || "application/octet-stream";
+    const isText = mimeType.startsWith("text/") || mimeType === "application/json";
+    const content = Buffer.from(res.data);
+    return {
+        name: file.data.name || fileId,
+        contents: {
+            mimeType,
+            ...(isText
+                ? { text: content.toString("utf-8") }
+                : { blob: content.toString("base64") }),
+        },
+    };
+}

package/dist/tools/drive/drive_search.js

@@ -0,0 +1,71 @@
+import { google } from "googleapis";
+export const schema = {
+    name: "drive_search",
+    description: "Search for files in Google Drive",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "Search query",
+            },
+            pageToken: {
+                type: "string",
+                description: "Token for the next page of results",
+                optional: true,
+            },
+            pageSize: {
+                type: "number",
+                description: "Number of results per page (max 100)",
+                optional: true,
+            },
+        },
+        required: ["query"],
+    },
+};
+export async function search(args) {
+    const drive = google.drive("v3");
+    const userQuery = args.query.trim();
+    let searchQuery = "";
+    // If query is empty, list all files
+    if (!userQuery) {
+        searchQuery = "trashed = false";
+    }
+    else {
+        // Escape special characters in the query
+        const escapedQuery = userQuery.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+        // Build search query with multiple conditions
+        const conditions = [];
+        // Search in title
+        conditions.push(`name contains '${escapedQuery}'`);
+        // If specific file type is mentioned in query, add mimeType condition
+        if (userQuery.toLowerCase().includes("sheet")) {
+            conditions.push("mimeType = 'application/vnd.google-sheets.spreadsheet'");
+        }
+        searchQuery = `(${conditions.join(" or ")}) and trashed = false`;
+    }
+    const res = await drive.files.list({
+        q: searchQuery,
+        pageSize: args.pageSize || 10,
+        pageToken: args.pageToken,
+        orderBy: "modifiedTime desc",
+        fields: "nextPageToken, files(id, name, mimeType, modifiedTime, size)",
+    });
+    const fileList = res.data.files
+        ?.map((file) => `${file.id} ${file.name} (${file.mimeType})`)
+        .join("\n");
+    let response = `Found ${res.data.files?.length ?? 0} files:\n${fileList}`;
+    // Add pagination info if there are more results
+    if (res.data.nextPageToken) {
+        response += `\n\nMore results available. Use pageToken: ${res.data.nextPageToken}`;
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: response,
+            },
+        ],
+        isError: false,
+    };
+}