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

package/dist/tools/gmail/basic/gmail_search_messages.js

@@ -0,0 +1,59 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { formatMessageList } from "../../../lib/gmail-helpers.js";
+export const schema = {
+    name: "gmail_search_messages",
+    description: "Search for messages in Gmail using Gmail query syntax. Supports operators like 'from:', 'to:', 'subject:', 'is:unread', 'has:attachment', date ranges, etc. Returns message IDs, thread IDs, and web URLs for each result.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "Gmail search query using standard Gmail operators (e.g., 'from:user@example.com subject:invoice is:unread')",
+            },
+            pageSize: {
+                type: "number",
+                description: "Maximum number of results to return (default: 10, max: 100)",
+            },
+            pageToken: {
+                type: "string",
+                description: "Token for pagination to get the next page of results",
+            },
+        },
+        required: ["query"],
+    },
+};
+export async function searchMessages(args) {
+    try {
+        const gmail = google.gmail("v1");
+        const { query, pageSize = 10, pageToken } = args;
+        const response = await gmail.users.messages.list({
+            userId: "me",
+            q: query,
+            maxResults: Math.min(pageSize, 100),
+            pageToken: pageToken,
+        });
+        const messages = response.data.messages || [];
+        const nextPageToken = response.data.nextPageToken;
+        if (messages.length === 0) {
+            return ResponseFormatter.success({
+                count: 0,
+                messages: [],
+                query,
+            }, `No messages found matching query: "${query}"`);
+        }
+        const formattedOutput = formatMessageList(messages, nextPageToken);
+        return ResponseFormatter.success({
+            count: messages.length,
+            query,
+            messages: messages.map((m) => ({
+                id: m.id,
+                threadId: m.threadId,
+            })),
+            nextPageToken,
+        }, `Search results for: "${query}"\n\n${formattedOutput}`);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/gmail/batch/gmail_batch_modify_labels.js

@@ -0,0 +1,74 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "gmail_batch_modify_labels",
+    description: "Modify labels on multiple Gmail messages in a single batch operation. More efficient than calling gmail_modify_labels multiple times. Can add and/or remove labels from many messages at once.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            messageIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Array of Gmail message IDs to modify (max recommended: 1000)",
+            },
+            addLabelIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Array of label IDs to add to all specified messages (e.g., ['INBOX', 'STARRED'])",
+                optional: true,
+            },
+            removeLabelIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Array of label IDs to remove from all specified messages (e.g., ['UNREAD', 'SPAM'])",
+                optional: true,
+            },
+        },
+        required: ["messageIds"],
+    },
+};
+export async function batchModifyLabels(args) {
+    try {
+        const gmail = google.gmail("v1");
+        const { messageIds, addLabelIds = [], removeLabelIds = [] } = args;
+        if (messageIds.length === 0) {
+            return ResponseFormatter.error(new Error("messageIds array cannot be empty"));
+        }
+        if (messageIds.length > 1000) {
+            return ResponseFormatter.error(new Error("Too many message IDs. Maximum recommended is 1000 per batch request."));
+        }
+        // Validate at least one operation
+        if (addLabelIds.length === 0 && removeLabelIds.length === 0) {
+            return ResponseFormatter.error(new Error("At least one of addLabelIds or removeLabelIds must be provided"));
+        }
+        // Perform batch modify
+        await gmail.users.messages.batchModify({
+            userId: "me",
+            requestBody: {
+                ids: messageIds,
+                addLabelIds: addLabelIds.length > 0 ? addLabelIds : undefined,
+                removeLabelIds: removeLabelIds.length > 0 ? removeLabelIds : undefined,
+            },
+        });
+        let output = `✅ Successfully modified labels on ${messageIds.length} message(s)\n\n`;
+        output += `📊 Operation Summary:\n`;
+        output += `  Messages affected: ${messageIds.length}\n`;
+        if (addLabelIds.length > 0) {
+            output += `  ➕ Added labels: ${addLabelIds.join(", ")}\n`;
+        }
+        if (removeLabelIds.length > 0) {
+            output += `  ➖ Removed labels: ${removeLabelIds.join(", ")}\n`;
+        }
+        output += `\n📝 Note: Changes applied to all specified messages.\n`;
+        output += `Use gmail_get_message to verify individual message labels.`;
+        return ResponseFormatter.success({
+            messageCount: messageIds.length,
+            messageIds,
+            addedLabels: addLabelIds,
+            removedLabels: removeLabelIds,
+        }, output);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/gmail/batch/gmail_get_messages_batch.js

@@ -0,0 +1,120 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { extractMessageBodies, formatBodyContent, getHeader, generateGmailWebUrl, } from "../../../lib/gmail-helpers.js";
+export const schema = {
+    name: "gmail_get_messages_batch",
+    description: "Retrieve multiple Gmail messages in a single batch request. More efficient than calling gmail_get_message multiple times. Returns message metadata and content for each message ID.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            messageIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Array of Gmail message IDs to retrieve (max recommended: 100)",
+            },
+            format: {
+                type: "string",
+                enum: ["full", "metadata"],
+                description: "Response format: 'full' includes body content, 'metadata' only headers (default: metadata)",
+                optional: true,
+            },
+        },
+        required: ["messageIds"],
+    },
+};
+export async function getMessagesBatch(args) {
+    try {
+        const gmail = google.gmail("v1");
+        const { messageIds, format = "metadata" } = args;
+        if (messageIds.length === 0) {
+            return ResponseFormatter.error(new Error("messageIds array cannot be empty"));
+        }
+        if (messageIds.length > 100) {
+            return ResponseFormatter.error(new Error("Too many message IDs. Maximum recommended is 100 per batch request."));
+        }
+        // Fetch all messages
+        const messagePromises = messageIds.map((messageId) => gmail.users.messages
+            .get({
+            userId: "me",
+            id: messageId,
+            format: format,
+        })
+            .catch((error) => ({
+            error: true,
+            messageId,
+            errorMessage: error.message,
+        })));
+        const results = await Promise.all(messagePromises);
+        // Process results
+        const messages = [];
+        const errors = [];
+        let output = `📬 Batch Message Retrieval Results\n`;
+        output += `${"=".repeat(80)}\n\n`;
+        output += `Requested: ${messageIds.length} messages\n`;
+        results.forEach((result, index) => {
+            if (result.error) {
+                errors.push({
+                    messageId: result.messageId,
+                    error: result.errorMessage,
+                });
+            }
+            else {
+                const message = result.data;
+                const headers = message.payload?.headers || [];
+                const messageData = {
+                    messageId: message.id,
+                    threadId: message.threadId,
+                    subject: getHeader(headers, "Subject"),
+                    from: getHeader(headers, "From"),
+                    to: getHeader(headers, "To"),
+                    date: getHeader(headers, "Date"),
+                    snippet: message.snippet,
+                    labelIds: message.labelIds || [],
+                };
+                // Include body if format is 'full'
+                if (format === "full") {
+                    const { textBody, htmlBody } = extractMessageBodies(message.payload || {});
+                    messageData.bodyPreview = formatBodyContent(textBody, htmlBody).substring(0, 500);
+                }
+                messages.push(messageData);
+            }
+        });
+        output += `Successful: ${messages.length}\n`;
+        output += `Failed: ${errors.length}\n\n`;
+        output += `${"=".repeat(80)}\n\n`;
+        // Display successful messages
+        if (messages.length > 0) {
+            output += `✅ Successfully Retrieved Messages:\n\n`;
+            messages.forEach((msg, index) => {
+                output += `${index + 1}. ${msg.subject}\n`;
+                output += `   From: ${msg.from}\n`;
+                output += `   Date: ${msg.date}\n`;
+                output += `   Message ID: ${msg.messageId}\n`;
+                output += `   URL: ${generateGmailWebUrl(msg.messageId)}\n`;
+                if (format === "full" && msg.bodyPreview) {
+                    output += `   Preview: ${msg.bodyPreview.substring(0, 100)}...\n`;
+                }
+                output += `\n`;
+            });
+        }
+        // Display errors
+        if (errors.length > 0) {
+            output += `\n❌ Failed Messages:\n\n`;
+            errors.forEach((err, index) => {
+                output += `${index + 1}. Message ID: ${err.messageId}\n`;
+                output += `   Error: ${err.error}\n\n`;
+            });
+        }
+        return ResponseFormatter.success({
+            totalRequested: messageIds.length,
+            successCount: messages.length,
+            errorCount: errors.length,
+            messages,
+            errors,
+            format,
+        }, output);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/gmail/batch/gmail_get_threads_batch.js

@@ -0,0 +1,102 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "gmail_get_threads_batch",
+    description: "Retrieve multiple Gmail threads (conversations) in a single batch request. More efficient than calling gmail_get_thread multiple times. Returns all messages in each thread.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            threadIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Array of Gmail thread IDs to retrieve (max recommended: 50)",
+            },
+        },
+        required: ["threadIds"],
+    },
+};
+export async function getThreadsBatch(args) {
+    try {
+        const gmail = google.gmail("v1");
+        const { threadIds } = args;
+        if (threadIds.length === 0) {
+            return ResponseFormatter.error(new Error("threadIds array cannot be empty"));
+        }
+        if (threadIds.length > 50) {
+            return ResponseFormatter.error(new Error("Too many thread IDs. Maximum recommended is 50 per batch request."));
+        }
+        // Fetch all threads
+        const threadPromises = threadIds.map((threadId) => gmail.users.threads
+            .get({
+            userId: "me",
+            id: threadId,
+            format: "full",
+        })
+            .catch((error) => ({
+            error: true,
+            threadId,
+            errorMessage: error.message,
+        })));
+        const results = await Promise.all(threadPromises);
+        // Process results
+        const threads = [];
+        const errors = [];
+        let output = `📬 Batch Thread Retrieval Results\n`;
+        output += `${"=".repeat(80)}\n\n`;
+        output += `Requested: ${threadIds.length} threads\n`;
+        results.forEach((result) => {
+            if (result.error) {
+                errors.push({
+                    threadId: result.threadId,
+                    error: result.errorMessage,
+                });
+            }
+            else {
+                const thread = result.data;
+                const messages = thread.messages || [];
+                threads.push({
+                    threadId: thread.id,
+                    messageCount: messages.length,
+                    snippet: thread.snippet || "",
+                    messages: messages.map((m) => ({
+                        messageId: m.id,
+                        snippet: m.snippet,
+                        labelIds: m.labelIds || [],
+                    })),
+                });
+            }
+        });
+        output += `Successful: ${threads.length}\n`;
+        output += `Failed: ${errors.length}\n\n`;
+        output += `${"=".repeat(80)}\n\n`;
+        // Display successful threads
+        if (threads.length > 0) {
+            output += `✅ Successfully Retrieved Threads:\n\n`;
+            threads.forEach((thread, index) => {
+                output += `${index + 1}. Thread ID: ${thread.threadId}\n`;
+                output += `   Messages: ${thread.messageCount}\n`;
+                output += `   Snippet: ${thread.snippet}\n`;
+                output += `   Message IDs: ${thread.messages.map((m) => m.messageId).join(", ")}\n`;
+                output += `\n`;
+            });
+        }
+        // Display errors
+        if (errors.length > 0) {
+            output += `\n❌ Failed Threads:\n\n`;
+            errors.forEach((err, index) => {
+                output += `${index + 1}. Thread ID: ${err.threadId}\n`;
+                output += `   Error: ${err.error}\n\n`;
+            });
+        }
+        return ResponseFormatter.success({
+            totalRequested: threadIds.length,
+            successCount: threads.length,
+            errorCount: errors.length,
+            threads,
+            errors,
+        }, output);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/gmail/labels/gmail_manage_label.js

@@ -0,0 +1,131 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "gmail_manage_label",
+    description: "Create, update, or delete Gmail labels. Supports creating new labels with visibility settings, updating existing label properties, or deleting labels.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: ["create", "update", "delete"],
+                description: "The action to perform on the label",
+            },
+            name: {
+                type: "string",
+                description: "Label name (required for create, optional for update). The display name of the label.",
+                optional: true,
+            },
+            labelId: {
+                type: "string",
+                description: "Label ID (required for update and delete operations). Get this from gmail_list_labels.",
+                optional: true,
+            },
+            labelListVisibility: {
+                type: "string",
+                enum: ["labelShow", "labelHide"],
+                description: "Whether to show the label in the label list (optional for create/update)",
+                optional: true,
+            },
+            messageListVisibility: {
+                type: "string",
+                enum: ["show", "hide"],
+                description: "Whether to show the label in the message list (optional for create/update)",
+                optional: true,
+            },
+        },
+        required: ["action"],
+    },
+};
+export async function manageLabel(args) {
+    try {
+        const gmail = google.gmail("v1");
+        const { action, name, labelId, labelListVisibility, messageListVisibility, } = args;
+        let output = "";
+        let resultData = {};
+        switch (action) {
+            case "create": {
+                if (!name) {
+                    return ResponseFormatter.error(new Error("Label name is required for create action"));
+                }
+                const createResponse = await gmail.users.labels.create({
+                    userId: "me",
+                    requestBody: {
+                        name,
+                        labelListVisibility: labelListVisibility || "labelShow",
+                        messageListVisibility: messageListVisibility || "show",
+                    },
+                });
+                const createdLabel = createResponse.data;
+                output = `✅ Successfully created label\n\n`;
+                output += `Label ID: ${createdLabel.id}\n`;
+                output += `Name: ${createdLabel.name}\n`;
+                output += `Label List Visibility: ${createdLabel.labelListVisibility}\n`;
+                output += `Message List Visibility: ${createdLabel.messageListVisibility}`;
+                resultData = {
+                    action: "create",
+                    labelId: createdLabel.id,
+                    name: createdLabel.name,
+                    labelListVisibility: createdLabel.labelListVisibility,
+                    messageListVisibility: createdLabel.messageListVisibility,
+                };
+                break;
+            }
+            case "update": {
+                if (!labelId) {
+                    return ResponseFormatter.error(new Error("Label ID is required for update action"));
+                }
+                const updateBody = {};
+                if (name)
+                    updateBody.name = name;
+                if (labelListVisibility)
+                    updateBody.labelListVisibility = labelListVisibility;
+                if (messageListVisibility)
+                    updateBody.messageListVisibility = messageListVisibility;
+                if (Object.keys(updateBody).length === 0) {
+                    return ResponseFormatter.error(new Error("At least one property (name, labelListVisibility, or messageListVisibility) must be provided for update"));
+                }
+                const updateResponse = await gmail.users.labels.update({
+                    userId: "me",
+                    id: labelId,
+                    requestBody: updateBody,
+                });
+                const updatedLabel = updateResponse.data;
+                output = `✅ Successfully updated label\n\n`;
+                output += `Label ID: ${updatedLabel.id}\n`;
+                output += `Name: ${updatedLabel.name}\n`;
+                output += `Label List Visibility: ${updatedLabel.labelListVisibility}\n`;
+                output += `Message List Visibility: ${updatedLabel.messageListVisibility}`;
+                resultData = {
+                    action: "update",
+                    labelId: updatedLabel.id,
+                    name: updatedLabel.name,
+                    labelListVisibility: updatedLabel.labelListVisibility,
+                    messageListVisibility: updatedLabel.messageListVisibility,
+                };
+                break;
+            }
+            case "delete": {
+                if (!labelId) {
+                    return ResponseFormatter.error(new Error("Label ID is required for delete action"));
+                }
+                await gmail.users.labels.delete({
+                    userId: "me",
+                    id: labelId,
+                });
+                output = `✅ Successfully deleted label: ${labelId}`;
+                resultData = {
+                    action: "delete",
+                    labelId,
+                };
+                break;
+            }
+            default:
+                return ResponseFormatter.error(new Error(`Invalid action: ${action}. Must be create, update, or delete.`));
+        }
+        return ResponseFormatter.success(resultData, output);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/gmail/labels/gmail_modify_labels.js

@@ -0,0 +1,65 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "gmail_modify_labels",
+    description: "Add or remove labels from a Gmail message. Can add and remove multiple labels in a single operation. Use gmail_list_labels to get available label IDs.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            messageId: {
+                type: "string",
+                description: "The Gmail message ID to modify",
+            },
+            addLabelIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Array of label IDs to add (e.g., ['INBOX', 'STARRED', 'Label_123'])",
+                optional: true,
+            },
+            removeLabelIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Array of label IDs to remove (e.g., ['UNREAD', 'SPAM'])",
+                optional: true,
+            },
+        },
+        required: ["messageId"],
+    },
+};
+export async function modifyLabels(args) {
+    try {
+        const gmail = google.gmail("v1");
+        const { messageId, addLabelIds = [], removeLabelIds = [] } = args;
+        // Validate at least one operation
+        if (addLabelIds.length === 0 && removeLabelIds.length === 0) {
+            return ResponseFormatter.error(new Error("At least one of addLabelIds or removeLabelIds must be provided"));
+        }
+        // Modify labels
+        const response = await gmail.users.messages.modify({
+            userId: "me",
+            id: messageId,
+            requestBody: {
+                addLabelIds: addLabelIds.length > 0 ? addLabelIds : undefined,
+                removeLabelIds: removeLabelIds.length > 0 ? removeLabelIds : undefined,
+            },
+        });
+        const updatedLabels = response.data.labelIds || [];
+        let output = `✅ Successfully modified labels for message: ${messageId}\n\n`;
+        if (addLabelIds.length > 0) {
+            output += `➕ Added labels: ${addLabelIds.join(", ")}\n`;
+        }
+        if (removeLabelIds.length > 0) {
+            output += `➖ Removed labels: ${removeLabelIds.join(", ")}\n`;
+        }
+        output += `\n📋 Current labels: ${updatedLabels.join(", ") || "(none)"}`;
+        return ResponseFormatter.success({
+            messageId,
+            addedLabels: addLabelIds,
+            removedLabels: removeLabelIds,
+            currentLabels: updatedLabels,
+        }, output);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/gmail/send/gmail_draft_message.js

@@ -0,0 +1,117 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { prepareGmailMessage, generateGmailWebUrl, } from "../../../lib/gmail-helpers.js";
+export const schema = {
+    name: "gmail_draft_message",
+    description: "Create a draft email message in Gmail. The draft is saved but not sent, allowing for later editing or sending. Supports plain text or HTML body, CC/BCC recipients, and threading.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            subject: {
+                type: "string",
+                description: "Email subject line",
+            },
+            body: {
+                type: "string",
+                description: "Email body content (plain text or HTML)",
+            },
+            bodyFormat: {
+                type: "string",
+                enum: ["plain", "html"],
+                description: "Body format type (default: plain)",
+                optional: true,
+            },
+            to: {
+                type: "string",
+                description: "Recipient email address(es). Multiple addresses can be comma-separated.",
+                optional: true,
+            },
+            cc: {
+                type: "string",
+                description: "CC recipient(s). Multiple addresses can be comma-separated.",
+                optional: true,
+            },
+            bcc: {
+                type: "string",
+                description: "BCC recipient(s). Multiple addresses can be comma-separated.",
+                optional: true,
+            },
+            threadId: {
+                type: "string",
+                description: "Thread ID to reply to (makes this a reply draft in an existing conversation)",
+                optional: true,
+            },
+            inReplyTo: {
+                type: "string",
+                description: "Message-ID header of the message being replied to (for threading)",
+                optional: true,
+            },
+            references: {
+                type: "string",
+                description: "References header for email threading (space-separated Message-IDs)",
+                optional: true,
+            },
+        },
+        required: ["subject", "body"],
+    },
+};
+export async function draftMessage(args) {
+    try {
+        const gmail = google.gmail("v1");
+        const { subject, body, bodyFormat = "plain", to, cc, bcc, threadId, inReplyTo, references, } = args;
+        // Prepare base64url encoded MIME message
+        const encodedMessage = prepareGmailMessage({
+            to: to || "",
+            subject,
+            body,
+            bodyFormat,
+            cc,
+            bcc,
+            inReplyTo,
+            references,
+        });
+        // Create the draft
+        const response = await gmail.users.drafts.create({
+            userId: "me",
+            requestBody: {
+                message: {
+                    raw: encodedMessage,
+                    threadId: threadId || undefined,
+                },
+            },
+        });
+        const draft = response.data;
+        const draftId = draft.id || "";
+        const messageId = draft.message?.id || "";
+        const draftThreadId = draft.message?.threadId || "";
+        let output = `✅ Draft created successfully!\n\n`;
+        output += `Draft ID: ${draftId}\n`;
+        output += `Message ID: ${messageId}\n`;
+        if (draftThreadId)
+            output += `Thread ID: ${draftThreadId}\n`;
+        output += `Web URL: ${generateGmailWebUrl(messageId)}\n\n`;
+        output += `📧 Details:\n`;
+        if (to)
+            output += `  To: ${to}\n`;
+        if (cc)
+            output += `  CC: ${cc}\n`;
+        if (bcc)
+            output += `  BCC: ${bcc}\n`;
+        output += `  Subject: ${subject}\n`;
+        output += `  Format: ${bodyFormat}\n`;
+        if (threadId)
+            output += `  Reply to thread: ${threadId}\n`;
+        output += `\n💡 The draft is saved in your Gmail Drafts folder and can be edited or sent later.`;
+        return ResponseFormatter.success({
+            draftId,
+            messageId,
+            threadId: draftThreadId,
+            subject,
+            bodyFormat,
+            to: to || null,
+        }, output);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}