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

package/dist/tools/calendar/events_advanced/calendar_events_quickadd.js

@@ -0,0 +1,52 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { formatEvent } from "../../../lib/calendar-helpers.js";
+export const schema = {
+    name: "calendar_events_quickadd",
+    description: "Create a calendar event from a simple text description using natural language processing. Examples: 'Meeting with John tomorrow at 2pm', 'Lunch at noon on Friday', 'Conference call next Monday 10-11am'. The system automatically parses the text to extract event details.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            calendarId: {
+                type: "string",
+                description: "Calendar identifier (default: 'primary' for user's main calendar)",
+            },
+            text: {
+                type: "string",
+                description: "Natural language text describing the event (e.g., 'Dinner with Sarah tomorrow at 7pm')",
+            },
+            sendUpdates: {
+                type: "string",
+                description: "Whether to send event notifications: 'all', 'externalOnly', 'none'. Default: 'none'",
+            },
+        },
+        required: ["text"],
+    },
+};
+export async function quickAddEvent(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { calendarId = "primary", text, sendUpdates = "none", } = args;
+        const response = await calendar.events.quickAdd({
+            calendarId,
+            text,
+            sendUpdates,
+        });
+        const event = response.data;
+        let message = `✅ Event created via QuickAdd\n\n`;
+        message += `Input Text: "${text}"\n\n`;
+        message += formatEvent(event, calendarId);
+        return ResponseFormatter.success({
+            eventId: event.id,
+            calendarId,
+            summary: event.summary,
+            start: event.start,
+            end: event.end,
+            htmlLink: event.htmlLink,
+            inputText: text,
+        }, message);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/calendar/freebusy/calendar_freebusy_query.js

@@ -0,0 +1,69 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { formatFreeBusyResponse } from "../../../lib/calendar-helpers.js";
+export const schema = {
+    name: "calendar_freebusy_query",
+    description: "Query free/busy information for one or more calendars within a specified time range. Returns busy time periods to help schedule meetings or check availability. Useful for finding meeting slots that work for multiple attendees.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            timeMin: {
+                type: "string",
+                description: "Start of the time range to query (ISO 8601 format, e.g., '2024-01-01T00:00:00Z')",
+            },
+            timeMax: {
+                type: "string",
+                description: "End of the time range to query (ISO 8601 format)",
+            },
+            calendars: {
+                type: "array",
+                items: {
+                    type: "string",
+                },
+                description: "List of calendar IDs to query (default: ['primary'])",
+            },
+            timeZone: {
+                type: "string",
+                description: "Time zone for the query (e.g., 'America/New_York', 'UTC'). Default: UTC",
+            },
+        },
+        required: ["timeMin", "timeMax"],
+    },
+};
+export async function queryFreeBusy(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { timeMin, timeMax, calendars = ["primary"], timeZone = "UTC", } = args;
+        const response = await calendar.freebusy.query({
+            requestBody: {
+                timeMin,
+                timeMax,
+                timeZone,
+                items: calendars.map((id) => ({ id })),
+            },
+        });
+        const freeBusyData = response.data;
+        if (!freeBusyData) {
+            return ResponseFormatter.error(new Error("Failed to query free/busy information"));
+        }
+        const formattedOutput = formatFreeBusyResponse(freeBusyData);
+        // Calculate total busy periods across all calendars
+        let totalBusyPeriods = 0;
+        if (freeBusyData.calendars) {
+            Object.values(freeBusyData.calendars).forEach((cal) => {
+                if (cal.busy) {
+                    totalBusyPeriods += cal.busy.length;
+                }
+            });
+        }
+        return ResponseFormatter.success({
+            timeMin: freeBusyData.timeMin,
+            timeMax: freeBusyData.timeMax,
+            calendars: freeBusyData.calendars,
+            totalBusyPeriods,
+        }, `Free/Busy query results:\n\n${formattedOutput}`);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/calendar/settings/calendar_settings_list.js

@@ -0,0 +1,81 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "calendar_settings_list",
+    description: "List all user settings for the authenticated user's Google Calendar. Returns configuration settings such as timezone, date format, country, language, and other Calendar preferences. Useful for understanding user's Calendar configuration.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            maxResults: {
+                type: "number",
+                description: "Maximum number of settings to return per page (default: 100, max: 250)",
+            },
+            pageToken: {
+                type: "string",
+                description: "Token for accessing subsequent result pages",
+            },
+        },
+        required: [],
+    },
+};
+export async function listSettings(args = {}) {
+    try {
+        const calendar = google.calendar("v3");
+        const { maxResults, pageToken, } = args;
+        const response = await calendar.settings.list({
+            maxResults,
+            pageToken,
+        });
+        const settings = response.data.items || [];
+        const totalSettings = settings.length;
+        if (totalSettings === 0) {
+            return ResponseFormatter.success({ settings: [], count: 0 }, "No settings found.");
+        }
+        let message = `⚙️ Calendar Settings (${totalSettings} setting${totalSettings > 1 ? "s" : ""})\n\n`;
+        // Group settings by category for better readability
+        const categorizedSettings = {
+            "General": [],
+            "Time & Date": [],
+            "Locale": [],
+            "Other": [],
+        };
+        settings.forEach((setting) => {
+            const id = setting.id || "";
+            if (id.includes("timezone") || id.includes("time") || id.includes("date") || id.includes("hour")) {
+                categorizedSettings["Time & Date"].push(setting);
+            }
+            else if (id.includes("locale") || id.includes("language") || id.includes("country")) {
+                categorizedSettings["Locale"].push(setting);
+            }
+            else if (id.includes("format") || id.includes("weekStart") || id.includes("show")) {
+                categorizedSettings["General"].push(setting);
+            }
+            else {
+                categorizedSettings["Other"].push(setting);
+            }
+        });
+        // Display settings by category
+        Object.entries(categorizedSettings).forEach(([category, items]) => {
+            if (items.length > 0) {
+                message += `\n${category}:\n`;
+                items.forEach((setting) => {
+                    message += `  ${setting.id}: ${setting.value}\n`;
+                });
+            }
+        });
+        if (response.data.nextPageToken) {
+            message += `\n\n📄 Next Page Token: ${response.data.nextPageToken}`;
+        }
+        return ResponseFormatter.success({
+            settings: settings.map((s) => ({
+                id: s.id,
+                value: s.value,
+            })),
+            count: totalSettings,
+            nextPageToken: response.data.nextPageToken || null,
+        }, message);
+    }
+    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";
+}

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

@@ -0,0 +1,80 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { formatRevisionList, } from "../../../lib/drive-helpers.js";
+export const schema = {
+    name: "drive_list_revisions",
+    description: "List all revisions of a file in Google Drive. Shows revision history with timestamps and modification details. Supports pagination.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            fileId: {
+                type: "string",
+                description: "ID of the file to list revisions for",
+            },
+            pageSize: {
+                type: "number",
+                description: "Maximum number of revisions to return per page (default: 10, max: 1000)",
+                optional: true,
+            },
+            pageToken: {
+                type: "string",
+                description: "Token for pagination to get the next page of results",
+                optional: true,
+            },
+        },
+        required: ["fileId"],
+    },
+};
+export async function listRevisions(args) {
+    try {
+        const drive = google.drive("v3");
+        const { fileId, pageSize = 10, pageToken } = args;
+        // Get file metadata
+        const fileResponse = await drive.files.get({
+            fileId,
+            fields: "id, name, mimeType, size, modifiedTime, createdTime",
+        });
+        const file = fileResponse.data;
+        // List revisions
+        const revisionsResponse = await drive.revisions.list({
+            fileId,
+            pageSize: Math.min(pageSize, 1000), // Cap at 1000
+            pageToken: pageToken || undefined,
+            fields: "revisions(id, modifiedTime, lastModifyingUser, size, keepForever, originalFilename, mimeType), nextPageToken",
+        });
+        const revisions = revisionsResponse.data.revisions || [];
+        const nextPageToken = revisionsResponse.data.nextPageToken;
+        // Format output
+        let output = `📄 Revision History for "${file.name}"\n`;
+        output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
+        output += `Total Revisions: ${revisions.length}\n`;
+        if (nextPageToken) {
+            output += `(More revisions available - use nextPageToken for pagination)\n`;
+        }
+        output += `\n${formatRevisionList(revisions)}\n`;
+        // Format detailed output for each revision
+        let detailedRevisions = revisions.map((revision, index) => ({
+            index: index + 1,
+            revisionId: revision.id || "",
+            modifiedTime: revision.modifiedTime || "Unknown",
+            modifiedBy: revision.lastModifyingUser?.displayName || "Unknown",
+            modifiedByEmail: revision.lastModifyingUser?.emailAddress || "Unknown",
+            size: revision.size ? parseInt(revision.size) : 0,
+            mimeType: revision.mimeType || "Unknown",
+            keepForever: revision.keepForever || false,
+            originalFilename: revision.originalFilename || file.name,
+        }));
+        return ResponseFormatter.success({
+            fileId,
+            fileName: file.name,
+            totalRevisions: revisions.length,
+            revisions: detailedRevisions,
+            nextPageToken: nextPageToken || null,
+            hasMoreResults: !!nextPageToken,
+            pageSize,
+        }, output);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/drive/basic/drive_get_metadata.js

@@ -0,0 +1,49 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { formatFileMetadata } from "../../../lib/drive-helpers.js";
+export const schema = {
+    name: "drive_get_metadata",
+    description: "Get detailed metadata for a specific file in Google Drive. Returns file ID, name, MIME type, size, created/modified times, sharing settings, and more.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            fileId: {
+                type: "string",
+                description: "ID of the file to get metadata for",
+            },
+            fields: {
+                type: "string",
+                description: "Comma-separated list of fields to include (default: all common fields)",
+                optional: true,
+            },
+        },
+        required: ["fileId"],
+    },
+};
+export async function getMetadata(args) {
+    try {
+        const drive = google.drive("v3");
+        const { fileId, fields } = args;
+        const defaultFields = "id, name, mimeType, size, createdTime, modifiedTime, modifiedByMe, owners, lastModifyingUser, shared, sharingUser, permissions, parents, webViewLink, webContentLink, iconLink, thumbnailLink, description, starred, trashed, explicitlyTrashed, properties, appProperties, spaces, version, teamDriveId, driveId, hasAugmentedPermissions, hasVersions, headRevisionId, copyRequiresWriterPermission, writersCanShare, folderColorRgb, originalFilename, fullFileExtension, fileExtension, md5Checksum, sha1Checksum, sha256Checksum";
+        const response = await drive.files.get({
+            fileId,
+            fields: fields || defaultFields,
+            supportsAllDrives: true,
+        });
+        const file = response.data;
+        const output = formatFileMetadata(file, true);
+        return ResponseFormatter.success({
+            fileId: file.id,
+            name: file.name,
+            mimeType: file.mimeType,
+            size: file.size,
+            createdTime: file.createdTime,
+            modifiedTime: file.modifiedTime,
+            webViewLink: file.webViewLink,
+            metadata: file,
+        }, output);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/drive/basic/drive_list_files.js

@@ -0,0 +1,76 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { formatFileList } from "../../../lib/drive-helpers.js";
+export const schema = {
+    name: "drive_list_files",
+    description: "List files in Google Drive. Supports filtering by query, folder, pagination, and sorting. Returns file IDs, names, types, and sizes.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "Search query using Google Drive query syntax (e.g., \"name contains 'report'\")",
+                optional: true,
+            },
+            folderId: {
+                type: "string",
+                description: "Folder ID to list files from (limits search to specific folder)",
+                optional: true,
+            },
+            pageSize: {
+                type: "number",
+                description: "Number of files to return per page (max 1000, default 100)",
+                optional: true,
+            },
+            pageToken: {
+                type: "string",
+                description: "Page token for pagination",
+                optional: true,
+            },
+            orderBy: {
+                type: "string",
+                description: "Sort order (e.g., 'name', 'modifiedTime desc', 'createdTime')",
+                optional: true,
+            },
+        },
+        required: [],
+    },
+};
+export async function listFiles(args) {
+    try {
+        const drive = google.drive("v3");
+        const { query, folderId, pageSize = 100, pageToken, orderBy } = args;
+        // Build query
+        let q = "trashed = false";
+        if (query) {
+            q += ` and (${query})`;
+        }
+        if (folderId) {
+            q += ` and '${folderId}' in parents`;
+        }
+        const response = await drive.files.list({
+            q,
+            pageSize: Math.min(pageSize, 1000),
+            pageToken,
+            orderBy: orderBy || "modifiedTime desc",
+            fields: "nextPageToken, files(id, name, mimeType, size, modifiedTime, createdTime, webViewLink, parents, iconLink)",
+        });
+        const files = response.data.files || [];
+        const nextPageToken = response.data.nextPageToken;
+        const output = formatFileList(files, nextPageToken);
+        return ResponseFormatter.success({
+            count: files.length,
+            files: files.map((f) => ({
+                id: f.id,
+                name: f.name,
+                mimeType: f.mimeType,
+                size: f.size,
+                modifiedTime: f.modifiedTime,
+            })),
+            nextPageToken,
+        }, output);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}