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

package/dist/lib/drive-helpers.js

@@ -0,0 +1,263 @@
+/**
+ * Google Drive Helper Functions
+ *
+ * Utilities for Google Drive API operations including:
+ * - File metadata formatting
+ * - Permission formatting
+ * - MIME type conversion
+ * - URL generation
+ * - File upload handling
+ */
+/**
+ * Format file metadata for display
+ */
+export function formatFileMetadata(file, detailed = false) {
+    const id = file.id || "";
+    const name = file.name || "Unnamed";
+    const mimeType = file.mimeType || "unknown";
+    const size = file.size ? formatFileSize(parseInt(file.size)) : "N/A";
+    const modifiedTime = file.modifiedTime
+        ? new Date(file.modifiedTime).toLocaleString()
+        : "Unknown";
+    const webViewLink = file.webViewLink || "";
+    if (!detailed) {
+        return `${name} (${id}) - ${mimeType}`;
+    }
+    let output = `📄 ${name}\n`;
+    output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
+    output += `ID: ${id}\n`;
+    output += `MIME Type: ${mimeType}\n`;
+    output += `Size: ${size}\n`;
+    output += `Modified: ${modifiedTime}\n`;
+    if (webViewLink) {
+        output += `Web Link: ${webViewLink}\n`;
+    }
+    if (file.parents && file.parents.length > 0) {
+        output += `Parent Folder(s): ${file.parents.join(", ")}\n`;
+    }
+    output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
+    return output;
+}
+/**
+ * Format file list for display
+ */
+export function formatFileList(files, nextPageToken) {
+    if (files.length === 0) {
+        return "No files found.";
+    }
+    let output = `Found ${files.length} file(s):\n\n`;
+    files.forEach((file, index) => {
+        const name = file.name || "Unnamed";
+        const id = file.id || "";
+        const mimeType = file.mimeType || "unknown";
+        const size = file.size ? formatFileSize(parseInt(file.size)) : "N/A";
+        output += `${index + 1}. ${name}\n`;
+        output += `   ID: ${id}\n`;
+        output += `   Type: ${mimeType}\n`;
+        output += `   Size: ${size}\n`;
+        if (file.webViewLink) {
+            output += `   Link: ${file.webViewLink}\n`;
+        }
+        output += `\n`;
+    });
+    if (nextPageToken) {
+        output += `\nMore results available. Use pageToken: ${nextPageToken}`;
+    }
+    return output;
+}
+/**
+ * Format permission for display
+ */
+export function formatPermission(permission) {
+    const role = permission.role || "unknown";
+    const type = permission.type || "unknown";
+    const emailAddress = permission.emailAddress || "";
+    const displayName = permission.displayName || "";
+    const id = permission.id || "";
+    let output = `Permission ID: ${id}\n`;
+    output += `  Role: ${role}\n`;
+    output += `  Type: ${type}\n`;
+    if (emailAddress) {
+        output += `  Email: ${emailAddress}\n`;
+    }
+    if (displayName) {
+        output += `  Name: ${displayName}\n`;
+    }
+    return output;
+}
+/**
+ * Format permission list for display
+ */
+export function formatPermissionList(permissions) {
+    if (permissions.length === 0) {
+        return "No permissions found.";
+    }
+    let output = `Total permissions: ${permissions.length}\n\n`;
+    permissions.forEach((permission, index) => {
+        output += `${index + 1}. ${formatPermission(permission)}\n`;
+    });
+    return output;
+}
+/**
+ * Format revision for display
+ */
+export function formatRevision(revision) {
+    const id = revision.id || "";
+    const modifiedTime = revision.modifiedTime
+        ? new Date(revision.modifiedTime).toLocaleString()
+        : "Unknown";
+    const lastModifyingUser = revision.lastModifyingUser?.displayName || "Unknown";
+    const size = revision.size ? formatFileSize(parseInt(revision.size)) : "N/A";
+    let output = `Revision ID: ${id}\n`;
+    output += `  Modified: ${modifiedTime}\n`;
+    output += `  Modified by: ${lastModifyingUser}\n`;
+    output += `  Size: ${size}\n`;
+    return output;
+}
+/**
+ * Format revision list for display
+ */
+export function formatRevisionList(revisions) {
+    if (revisions.length === 0) {
+        return "No revisions found.";
+    }
+    let output = `Total revisions: ${revisions.length}\n\n`;
+    revisions.forEach((revision, index) => {
+        output += `${index + 1}. ${formatRevision(revision)}\n`;
+    });
+    return output;
+}
+/**
+ * Convert MIME type for export
+ */
+export function convertMimeType(sourceMimeType, targetFormat) {
+    // Google Workspace document types
+    const googleMimeTypes = {
+        "application/vnd.google-apps.document": {
+            pdf: "application/pdf",
+            docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+            html: "text/html",
+            txt: "text/plain",
+            odt: "application/vnd.oasis.opendocument.text",
+            rtf: "application/rtf",
+            epub: "application/epub+zip",
+            markdown: "text/markdown",
+        },
+        "application/vnd.google-apps.spreadsheet": {
+            pdf: "application/pdf",
+            xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+            csv: "text/csv",
+            ods: "application/vnd.oasis.opendocument.spreadsheet",
+            tsv: "text/tab-separated-values",
+            html: "text/html",
+        },
+        "application/vnd.google-apps.presentation": {
+            pdf: "application/pdf",
+            pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+            odp: "application/vnd.oasis.opendocument.presentation",
+            txt: "text/plain",
+        },
+        "application/vnd.google-apps.drawing": {
+            pdf: "application/pdf",
+            png: "image/png",
+            jpeg: "image/jpeg",
+            svg: "image/svg+xml",
+        },
+    };
+    if (!targetFormat) {
+        // Default export formats
+        const defaults = {
+            "application/vnd.google-apps.document": "application/pdf",
+            "application/vnd.google-apps.spreadsheet": "text/csv",
+            "application/vnd.google-apps.presentation": "application/pdf",
+            "application/vnd.google-apps.drawing": "image/png",
+        };
+        return defaults[sourceMimeType] || "application/pdf";
+    }
+    const formats = googleMimeTypes[sourceMimeType];
+    if (!formats) {
+        throw new Error(`Unsupported source MIME type: ${sourceMimeType}`);
+    }
+    const targetMimeType = formats[targetFormat.toLowerCase()];
+    if (!targetMimeType) {
+        throw new Error(`Unsupported export format '${targetFormat}' for MIME type '${sourceMimeType}'`);
+    }
+    return targetMimeType;
+}
+/**
+ * Generate Google Drive web URL for a file or folder
+ */
+export function generateDriveWebUrl(fileId) {
+    return `https://drive.google.com/file/d/${fileId}/view`;
+}
+/**
+ * Generate folder web URL
+ */
+export function generateFolderWebUrl(folderId) {
+    return `https://drive.google.com/drive/folders/${folderId}`;
+}
+/**
+ * Format file size to human-readable format
+ */
+function formatFileSize(bytes) {
+    if (bytes === 0)
+        return "0 Bytes";
+    const k = 1024;
+    const sizes = ["Bytes", "KB", "MB", "GB", "TB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return Math.round((bytes / Math.pow(k, i)) * 100) / 100 + " " + sizes[i];
+}
+/**
+ * Get MIME type for folder
+ */
+export const FOLDER_MIME_TYPE = "application/vnd.google-apps.folder";
+/**
+ * Check if MIME type is a Google Workspace document
+ */
+export function isGoogleWorkspaceDocument(mimeType) {
+    return mimeType.startsWith("application/vnd.google-apps.");
+}
+/**
+ * Get icon for MIME type
+ */
+export function getFileIcon(mimeType) {
+    const icons = {
+        "application/vnd.google-apps.folder": "📁",
+        "application/vnd.google-apps.document": "📝",
+        "application/vnd.google-apps.spreadsheet": "📊",
+        "application/vnd.google-apps.presentation": "📊",
+        "application/vnd.google-apps.drawing": "🎨",
+        "application/pdf": "📄",
+        "image/png": "🖼️",
+        "image/jpeg": "🖼️",
+        "text/plain": "📃",
+        "application/zip": "🗜️",
+    };
+    return icons[mimeType] || "📄";
+}
+/**
+ * Format permission role for display
+ */
+export function getRoleLabel(role) {
+    const labels = {
+        owner: "Owner",
+        organizer: "Organizer",
+        fileOrganizer: "File Organizer",
+        writer: "Editor",
+        commenter: "Commenter",
+        reader: "Viewer",
+    };
+    return labels[role] || role;
+}
+/**
+ * Format permission type for display
+ */
+export function getTypeLabel(type) {
+    const labels = {
+        user: "User",
+        group: "Group",
+        domain: "Domain",
+        anyone: "Anyone with link",
+    };
+    return labels[type] || type;
+}

package/dist/lib/gmail-helpers.js

@@ -0,0 +1,204 @@
+/**
+ * Gmail Helper Functions
+ *
+ * Utilities for Gmail API operations including:
+ * - Message body extraction and formatting
+ * - HTML to text conversion
+ * - MIME message preparation
+ * - Attachment handling
+ * - URL generation
+ */
+import nodemailer from "nodemailer";
+import { convert } from "html-to-text";
+/**
+ * Extract text and HTML bodies from Gmail message payload
+ */
+export function extractMessageBodies(payload) {
+    let textBody = "";
+    let htmlBody = "";
+    function extractParts(part) {
+        if (part.mimeType === "text/plain" && part.body?.data) {
+            textBody = Buffer.from(part.body.data, "base64").toString("utf-8");
+        }
+        else if (part.mimeType === "text/html" && part.body?.data) {
+            htmlBody = Buffer.from(part.body.data, "base64").toString("utf-8");
+        }
+        // Recursively process multipart messages
+        if (part.parts) {
+            for (const subPart of part.parts) {
+                extractParts(subPart);
+            }
+        }
+    }
+    extractParts(payload);
+    return { textBody, htmlBody };
+}
+/**
+ * Format body content, preferring plain text but converting HTML if needed
+ */
+export function formatBodyContent(textBody, htmlBody) {
+    if (textBody) {
+        return textBody;
+    }
+    if (htmlBody) {
+        // Convert HTML to readable plain text
+        return convert(htmlBody, {
+            wordwrap: 80,
+            selectors: [
+                { selector: "a", options: { ignoreHref: false } },
+                { selector: "img", format: "skip" },
+            ],
+        });
+    }
+    return "[No text content found]";
+}
+export function extractAttachments(payload) {
+    const attachments = [];
+    function extractParts(part) {
+        if (part.filename && part.body?.attachmentId) {
+            attachments.push({
+                filename: part.filename,
+                mimeType: part.mimeType || "application/octet-stream",
+                size: part.body.size || 0,
+                attachmentId: part.body.attachmentId,
+            });
+        }
+        if (part.parts) {
+            for (const subPart of part.parts) {
+                extractParts(subPart);
+            }
+        }
+    }
+    extractParts(payload);
+    return attachments;
+}
+export function prepareGmailMessage(options) {
+    const { to, subject, body, bodyFormat, from, cc, bcc, inReplyTo, references, } = options;
+    // Build message using nodemailer's createTransport (for MIME creation only)
+    const message = {
+        from: from || "me",
+        to,
+        subject,
+        [bodyFormat === "html" ? "html" : "text"]: body,
+    };
+    if (cc)
+        message.cc = cc;
+    if (bcc)
+        message.bcc = bcc;
+    if (inReplyTo)
+        message.inReplyTo = inReplyTo;
+    if (references)
+        message.references = references;
+    // Create MIME message
+    const transport = nodemailer.createTransport({ jsonTransport: true });
+    // We'll use a synchronous approach here
+    let mimeMessage = "";
+    mimeMessage += `From: ${message.from}\r\n`;
+    mimeMessage += `To: ${message.to}\r\n`;
+    if (message.cc)
+        mimeMessage += `Cc: ${message.cc}\r\n`;
+    if (message.bcc)
+        mimeMessage += `Bcc: ${message.bcc}\r\n`;
+    mimeMessage += `Subject: ${message.subject}\r\n`;
+    if (message.inReplyTo)
+        mimeMessage += `In-Reply-To: ${message.inReplyTo}\r\n`;
+    if (message.references)
+        mimeMessage += `References: ${message.references}\r\n`;
+    mimeMessage += `Content-Type: text/${bodyFormat}; charset=utf-8\r\n`;
+    mimeMessage += `\r\n`;
+    mimeMessage += body;
+    // Base64url encode
+    return Buffer.from(mimeMessage)
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/**
+ * Generate Gmail web URL for a message or thread
+ */
+export function generateGmailWebUrl(messageId, threadId) {
+    if (messageId) {
+        return `https://mail.google.com/mail/u/0/#all/${messageId}`;
+    }
+    if (threadId) {
+        return `https://mail.google.com/mail/u/0/#all/${threadId}`;
+    }
+    return "https://mail.google.com/mail/u/0/";
+}
+/**
+ * Extract header value from message headers
+ */
+export function getHeader(headers, name) {
+    if (!headers)
+        return "";
+    const header = headers.find((h) => h.name?.toLowerCase() === name.toLowerCase());
+    return header?.value || "";
+}
+/**
+ * Format thread content for display
+ */
+export function formatThreadContent(thread) {
+    const messages = thread.messages || [];
+    const threadId = thread.id || "";
+    if (messages.length === 0) {
+        return "No messages in thread";
+    }
+    // Extract thread subject from first message
+    const firstMessage = messages[0];
+    const subject = getHeader(firstMessage.payload?.headers, "Subject");
+    let output = `Thread ID: ${threadId}\n`;
+    output += `Subject: ${subject}\n`;
+    output += `Messages: ${messages.length}\n`;
+    output += `Web URL: ${generateGmailWebUrl(undefined, threadId)}\n\n`;
+    output += "=".repeat(80) + "\n\n";
+    // Format each message
+    messages.forEach((message, index) => {
+        const headers = message.payload?.headers || [];
+        const from = getHeader(headers, "From");
+        const date = getHeader(headers, "Date");
+        const msgSubject = getHeader(headers, "Subject");
+        output += `Message ${index + 1}/${messages.length}\n`;
+        output += `-`.repeat(40) + "\n";
+        output += `From: ${from}\n`;
+        output += `Date: ${date}\n`;
+        // Only show subject if different from thread subject
+        if (msgSubject && msgSubject !== subject) {
+            output += `Subject: ${msgSubject}\n`;
+        }
+        output += `\n`;
+        // Extract and format body
+        if (message.payload) {
+            const { textBody, htmlBody } = extractMessageBodies(message.payload);
+            const bodyContent = formatBodyContent(textBody, htmlBody);
+            // Truncate very long messages
+            const maxLength = 2000;
+            if (bodyContent.length > maxLength) {
+                output += bodyContent.substring(0, maxLength);
+                output += `\n\n[... truncated ${bodyContent.length - maxLength} characters ...]`;
+            }
+            else {
+                output += bodyContent;
+            }
+        }
+        output += "\n\n";
+    });
+    return output;
+}
+/**
+ * Format message list for search results
+ */
+export function formatMessageList(messages, nextPageToken) {
+    let output = `Found ${messages.length} message(s)\n\n`;
+    messages.forEach((msg, index) => {
+        const messageId = msg.id || "";
+        const threadId = msg.threadId || "";
+        output += `${index + 1}. Message ID: ${messageId}\n`;
+        output += `   Thread ID: ${threadId}\n`;
+        output += `   Web URL: ${generateGmailWebUrl(messageId)}\n\n`;
+    });
+    if (nextPageToken) {
+        output += `\nMore results available. Use pageToken: ${nextPageToken}`;
+    }
+    return output;
+}

package/dist/lib/response-formatter.js

@@ -0,0 +1,82 @@
+/**
+ * ResponseFormatter - Consistent response formatting across all tools
+ */
+export class ResponseFormatter {
+    /**
+     * Create a success response
+     */
+    static success(data, message) {
+        let text;
+        if (message) {
+            // If message is provided, combine it with data
+            if (typeof data === "object" && data !== null) {
+                text = `${message}\n\n${JSON.stringify(data, null, 2)}`;
+            }
+            else {
+                text = message;
+            }
+        }
+        else {
+            // Format data only
+            text = typeof data === "object" && data !== null
+                ? JSON.stringify(data, null, 2)
+                : String(data);
+        }
+        return {
+            content: [{ type: "text", text }],
+            isError: false,
+        };
+    }
+    /**
+     * Create an error response
+     */
+    static error(error) {
+        const message = error instanceof Error ? error.message : error;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    /**
+     * Format Google Docs document data
+     */
+    static formatDocumentData(doc) {
+        const formatted = {
+            documentId: doc.documentId,
+            title: doc.title,
+            revisionId: doc.revisionId,
+            suggestionsViewMode: doc.suggestionsViewMode,
+        };
+        return JSON.stringify(formatted, null, 2);
+    }
+    /**
+     * Format metadata
+     */
+    static formatMetadata(metadata) {
+        return JSON.stringify(metadata, null, 2);
+    }
+    /**
+     * Format a simple success message
+     */
+    static simpleSuccess(message) {
+        return {
+            content: [{ type: "text", text: message }],
+            isError: false,
+        };
+    }
+    /**
+     * Format operation result with details
+     */
+    static operationResult(operation, details) {
+        const text = `${operation} completed successfully\n\n${JSON.stringify(details, null, 2)}`;
+        return {
+            content: [{ type: "text", text }],
+            isError: false,
+        };
+    }
+}

package/dist/lib/validation.js

@@ -0,0 +1,112 @@
+/**
+ * Validation - Shared validation logic for tool inputs
+ */
+export class Validator {
+    /**
+     * Validate that required fields exist in an object
+     */
+    static validateRequired(obj, fields) {
+        const missing = fields.filter((field) => obj[field] === undefined);
+        if (missing.length > 0) {
+            throw new Error(`Missing required fields: ${missing.join(", ")}`);
+        }
+    }
+    /**
+     * Validate RGB color values (0-1 range)
+     */
+    static validateColor(color) {
+        const values = [color.red, color.green, color.blue];
+        return values.every((v) => typeof v === "number" && v >= 0 && v <= 1);
+    }
+    /**
+     * Validate dimension type
+     */
+    static validateDimension(dimension) {
+        return dimension === "ROWS" || dimension === "COLUMNS";
+    }
+    /**
+     * Validate text style object
+     */
+    static validateTextStyle(style) {
+        // Check for at least one style property
+        const validProperties = [
+            "bold",
+            "italic",
+            "underline",
+            "fontSize",
+            "fontFamily",
+            "foregroundColor",
+            "backgroundColor",
+        ];
+        const hasValidProperty = validProperties.some((prop) => style[prop] !== undefined);
+        if (!hasValidProperty) {
+            return false;
+        }
+        // Validate color properties if they exist
+        if (style.foregroundColor && !this.validateColor(style.foregroundColor)) {
+            return false;
+        }
+        if (style.backgroundColor && !this.validateColor(style.backgroundColor)) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Validate index is a positive integer
+     */
+    static validateIndex(index, allowZero = false) {
+        if (!Number.isInteger(index)) {
+            return false;
+        }
+        return allowZero ? index >= 0 : index > 0;
+    }
+    /**
+     * Validate range (startIndex < endIndex)
+     */
+    static validateRange(startIndex, endIndex) {
+        return (this.validateIndex(startIndex) &&
+            this.validateIndex(endIndex) &&
+            startIndex < endIndex);
+    }
+    /**
+     * Validate alignment value
+     */
+    static validateAlignment(alignment) {
+        return ["START", "CENTER", "END", "JUSTIFIED"].includes(alignment);
+    }
+    /**
+     * Validate named style type
+     */
+    static validateNamedStyleType(styleType) {
+        const validTypes = [
+            "NORMAL_TEXT",
+            "HEADING_1",
+            "HEADING_2",
+            "HEADING_3",
+            "HEADING_4",
+            "HEADING_5",
+            "HEADING_6",
+            "TITLE",
+            "SUBTITLE",
+        ];
+        return validTypes.includes(styleType);
+    }
+    /**
+     * Validate URL format
+     */
+    static validateUrl(url) {
+        try {
+            new URL(url);
+            return url.startsWith("http://") || url.startsWith("https://");
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Validate positive number
+     */
+    static validatePositiveNumber(value) {
+        return typeof value === "number" && value > 0 && !isNaN(value);
+    }
+}