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

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

@@ -0,0 +1,95 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { extractMessageBodies, formatBodyContent, extractAttachments, getHeader, generateGmailWebUrl, } from "../../../lib/gmail-helpers.js";
+export const schema = {
+    name: "gmail_get_message",
+    description: "Retrieve full content of a specific Gmail message including subject, sender, recipients, body (text/HTML), and attachments. Returns formatted message with metadata.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            messageId: {
+                type: "string",
+                description: "The Gmail message ID to retrieve",
+            },
+        },
+        required: ["messageId"],
+    },
+};
+export async function getMessage(args) {
+    try {
+        const gmail = google.gmail("v1");
+        const { messageId } = args;
+        // Fetch message with full format
+        const response = await gmail.users.messages.get({
+            userId: "me",
+            id: messageId,
+            format: "full",
+        });
+        const message = response.data;
+        const headers = message.payload?.headers || [];
+        // Extract metadata
+        const subject = getHeader(headers, "Subject");
+        const from = getHeader(headers, "From");
+        const to = getHeader(headers, "To");
+        const cc = getHeader(headers, "Cc");
+        const date = getHeader(headers, "Date");
+        const messageIdHeader = getHeader(headers, "Message-ID");
+        // Extract body
+        const { textBody, htmlBody } = extractMessageBodies(message.payload || {});
+        const bodyContent = formatBodyContent(textBody, htmlBody);
+        // Extract attachments
+        const attachments = extractAttachments(message.payload || {});
+        // Build output
+        let output = `Message ID: ${messageId}\n`;
+        output += `Thread ID: ${message.threadId}\n`;
+        output += `Web URL: ${generateGmailWebUrl(messageId)}\n\n`;
+        output += `Subject: ${subject}\n`;
+        output += `From: ${from}\n`;
+        output += `To: ${to}\n`;
+        if (cc)
+            output += `Cc: ${cc}\n`;
+        output += `Date: ${date}\n`;
+        if (messageIdHeader)
+            output += `Message-ID: ${messageIdHeader}\n`;
+        output += `\n${"=".repeat(80)}\n\n`;
+        // Truncate very long bodies
+        const maxBodyLength = 20000;
+        if (bodyContent.length > maxBodyLength) {
+            output += bodyContent.substring(0, maxBodyLength);
+            output += `\n\n[... truncated ${bodyContent.length - maxBodyLength} characters ...]`;
+        }
+        else {
+            output += bodyContent;
+        }
+        // Add attachments info
+        if (attachments.length > 0) {
+            output += `\n\n${"=".repeat(80)}\n\n`;
+            output += `📎 Attachments (${attachments.length}):\n`;
+            attachments.forEach((att, index) => {
+                output += `  ${index + 1}. ${att.filename} (${att.mimeType}, ${Math.round(att.size / 1024)}KB)\n`;
+                output += `     Attachment ID: ${att.attachmentId}\n`;
+            });
+            output += `\nUse 'gmail_get_attachment' tool to download attachments.\n`;
+        }
+        return ResponseFormatter.success({
+            messageId,
+            threadId: message.threadId,
+            subject,
+            from,
+            to,
+            cc,
+            date,
+            labels: message.labelIds,
+            attachments: attachments.map((a) => ({
+                filename: a.filename,
+                mimeType: a.mimeType,
+                size: a.size,
+                attachmentId: a.attachmentId,
+            })),
+            snippet: message.snippet,
+        }, output);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

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

@@ -0,0 +1,46 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { formatThreadContent } from "../../../lib/gmail-helpers.js";
+export const schema = {
+    name: "gmail_get_thread",
+    description: "Retrieve a complete Gmail thread (conversation) with all messages. Returns all messages in chronological order with full content, metadata, and attachments.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            threadId: {
+                type: "string",
+                description: "The Gmail thread ID to retrieve",
+            },
+        },
+        required: ["threadId"],
+    },
+};
+export async function getThread(args) {
+    try {
+        const gmail = google.gmail("v1");
+        const { threadId } = args;
+        // Fetch thread with full format
+        const response = await gmail.users.threads.get({
+            userId: "me",
+            id: threadId,
+            format: "full",
+        });
+        const thread = response.data;
+        const messages = thread.messages || [];
+        // Format thread content using helper
+        const formattedContent = formatThreadContent(thread);
+        // Build metadata for structured response
+        const messageCount = messages.length;
+        const messageIds = messages.map((m) => m.id);
+        const snippets = messages.map((m) => m.snippet || "");
+        return ResponseFormatter.success({
+            threadId,
+            messageCount,
+            messageIds,
+            snippets,
+        }, formattedContent);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

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

@@ -0,0 +1,54 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "gmail_list_labels",
+    description: "List all labels in the user's Gmail account. Returns both system labels (INBOX, SENT, TRASH, etc.) and user-created labels with their IDs and names.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        required: [],
+    },
+};
+export async function listLabels(args) {
+    try {
+        const gmail = google.gmail("v1");
+        const response = await gmail.users.labels.list({
+            userId: "me",
+        });
+        const labels = response.data.labels || [];
+        if (labels.length === 0) {
+            return ResponseFormatter.success({ count: 0, labels: [] }, "No labels found in Gmail account");
+        }
+        // Separate system and user labels
+        const systemLabels = labels.filter((l) => l.type === "system");
+        const userLabels = labels.filter((l) => l.type === "user");
+        let output = `Total labels: ${labels.length}\n\n`;
+        if (systemLabels.length > 0) {
+            output += `📌 System Labels (${systemLabels.length}):\n`;
+            systemLabels.forEach((label) => {
+                output += `  - ${label.name} (ID: ${label.id})\n`;
+            });
+            output += `\n`;
+        }
+        if (userLabels.length > 0) {
+            output += `🏷️  User Labels (${userLabels.length}):\n`;
+            userLabels.forEach((label) => {
+                output += `  - ${label.name} (ID: ${label.id})\n`;
+            });
+        }
+        return ResponseFormatter.success({
+            count: labels.length,
+            systemLabels: systemLabels.map((l) => ({
+                id: l.id,
+                name: l.name,
+            })),
+            userLabels: userLabels.map((l) => ({
+                id: l.id,
+                name: l.name,
+            })),
+        }, output);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

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);
+    }
+}