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

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/tools/calendar/acl/calendar_acl_insert.js

@@ -0,0 +1,80 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "calendar_acl_insert",
+    description: "Add a new access control rule to share a calendar with a user, group, or domain. Specify the access level (owner, writer, reader, freeBusyReader) and the scope (who gets access). Use this to grant calendar permissions to others. The system can optionally send notification emails to inform users about the new sharing.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            calendarId: {
+                type: "string",
+                description: "Calendar identifier. Use 'primary' for the user's primary calendar.",
+            },
+            role: {
+                type: "string",
+                description: "Access level: 'owner', 'writer', 'reader', 'freeBusyReader', or 'none'",
+            },
+            scopeType: {
+                type: "string",
+                description: "Scope type: 'user' (individual), 'group' (Google group), 'domain' (entire domain), or 'default' (public)",
+            },
+            scopeValue: {
+                type: "string",
+                description: "Email address (for user/group) or domain name (for domain). Omit for 'default' scope type.",
+            },
+            sendNotifications: {
+                type: "boolean",
+                description: "Whether to send email notifications about the sharing change (default: true)",
+            },
+        },
+        required: ["calendarId", "role", "scopeType"],
+    },
+};
+export async function insertAcl(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { calendarId, role, scopeType, scopeValue, sendNotifications = true, } = args;
+        // Validate scope
+        if ((scopeType === "user" || scopeType === "group" || scopeType === "domain") && !scopeValue) {
+            return ResponseFormatter.error(new Error(`scopeValue is required for scopeType '${scopeType}'. Provide an email address or domain name.`));
+        }
+        if (scopeType === "default" && scopeValue) {
+            return ResponseFormatter.error(new Error("scopeValue should not be provided for scopeType 'default' (public access)."));
+        }
+        const response = await calendar.acl.insert({
+            calendarId,
+            sendNotifications,
+            requestBody: {
+                role,
+                scope: {
+                    type: scopeType,
+                    value: scopeValue,
+                },
+            },
+        });
+        const rule = response.data;
+        let message = `✅ Access control rule added successfully\n\n`;
+        message += `📅 Calendar: ${calendarId}\n`;
+        message += `Role: ${rule.role?.toUpperCase()}\n`;
+        message += `Scope: ${rule.scope?.type}`;
+        if (rule.scope?.value) {
+            message += ` (${rule.scope.value})`;
+        }
+        message += `\n`;
+        message += `Rule ID: ${rule.id}\n`;
+        if (sendNotifications && rule.scope?.value) {
+            message += `\n📧 Notification email sent to ${rule.scope.value}`;
+        }
+        message += `\n\n💡 The specified user/group now has ${role} access to this calendar.`;
+        return ResponseFormatter.success({
+            ruleId: rule.id,
+            calendarId,
+            role: rule.role,
+            scopeType: rule.scope?.type,
+            scopeValue: rule.scope?.value || null,
+        }, message);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/calendar/acl/calendar_acl_list.js

@@ -0,0 +1,82 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "calendar_acl_list",
+    description: "List all access control rules (sharing settings) for a calendar. Shows who has access to the calendar and their permission levels (owner, writer, reader, freeBusyReader). Use this to view current sharing configuration before adding or removing permissions.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            calendarId: {
+                type: "string",
+                description: "Calendar identifier. Use 'primary' for the user's primary calendar.",
+            },
+            maxResults: {
+                type: "number",
+                description: "Maximum number of ACL entries to return per page (default: 100, max: 250)",
+            },
+            pageToken: {
+                type: "string",
+                description: "Token for accessing subsequent result pages",
+            },
+            showDeleted: {
+                type: "boolean",
+                description: "Include deleted ACL entries (default: false)",
+            },
+        },
+        required: ["calendarId"],
+    },
+};
+export async function listAcl(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { calendarId, maxResults, pageToken, showDeleted, } = args;
+        const response = await calendar.acl.list({
+            calendarId,
+            maxResults,
+            pageToken,
+            showDeleted,
+        });
+        const rules = response.data.items || [];
+        const totalRules = rules.length;
+        if (totalRules === 0) {
+            return ResponseFormatter.success({ rules: [], count: 0 }, "No access control rules found for this calendar.");
+        }
+        let message = `🔐 Calendar Access Control List (${totalRules} rule${totalRules > 1 ? "s" : ""})\n\n`;
+        rules.forEach((rule, index) => {
+            message += `${index + 1}. ${rule.role?.toUpperCase()}\n`;
+            message += `   Scope: ${rule.scope?.type}`;
+            if (rule.scope?.value) {
+                message += ` (${rule.scope.value})`;
+            }
+            message += `\n`;
+            message += `   Rule ID: ${rule.id}\n`;
+            if (rule.scope?.type === "user" || rule.scope?.type === "group") {
+                message += `   Email: ${rule.scope.value}\n`;
+            }
+            else if (rule.scope?.type === "domain") {
+                message += `   Domain: ${rule.scope.value}\n`;
+            }
+            else if (rule.scope?.type === "default") {
+                message += `   Public Access\n`;
+            }
+            message += `\n`;
+        });
+        if (response.data.nextPageToken) {
+            message += `📄 Next Page Token: ${response.data.nextPageToken}\n`;
+        }
+        message += `\n💡 Role levels: owner > writer > reader > freeBusyReader`;
+        return ResponseFormatter.success({
+            rules: rules.map((rule) => ({
+                id: rule.id,
+                role: rule.role,
+                scopeType: rule.scope?.type,
+                scopeValue: rule.scope?.value || null,
+            })),
+            count: totalRules,
+            nextPageToken: response.data.nextPageToken || null,
+        }, message);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/calendar/basic/calendar_create_event.js

@@ -0,0 +1,113 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { formatEvent, parseDateTime, formatAttendees, validateTimeRange } from "../../../lib/calendar-helpers.js";
+export const schema = {
+    name: "calendar_create_event",
+    description: "Create a new event in Google Calendar with specified details. Supports setting title, time, location, description, attendees, and conference data (Google Meet). Can create all-day events or timed events with specific start/end times.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            calendarId: {
+                type: "string",
+                description: "Calendar identifier (default: 'primary' for user's main calendar)",
+            },
+            summary: {
+                type: "string",
+                description: "Event title/summary",
+            },
+            startTime: {
+                type: "string",
+                description: "Event start time (ISO 8601 format: '2024-01-15T10:00:00Z' or date only: '2024-01-15' for all-day)",
+            },
+            endTime: {
+                type: "string",
+                description: "Event end time (ISO 8601 format: '2024-01-15T11:00:00Z' or date only: '2024-01-16' for all-day)",
+            },
+            location: {
+                type: "string",
+                description: "Event location (address or place name)",
+            },
+            description: {
+                type: "string",
+                description: "Event description (supports plain text and HTML)",
+            },
+            attendees: {
+                type: "array",
+                items: {
+                    type: "string",
+                },
+                description: "List of attendee email addresses",
+            },
+            sendUpdates: {
+                type: "string",
+                description: "Whether to send event notifications: 'all' (send to all attendees), 'externalOnly' (external only), 'none' (no notifications). Default: 'none'",
+            },
+            conferenceData: {
+                type: "boolean",
+                description: "Whether to create a Google Meet conference link (default: false)",
+            },
+        },
+        required: ["summary", "startTime", "endTime"],
+    },
+};
+export async function createEvent(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { calendarId = "primary", summary, startTime, endTime, location, description, attendees, sendUpdates = "none", conferenceData = false, } = args;
+        // Validate time range
+        const validation = validateTimeRange(startTime, endTime);
+        if (!validation.valid) {
+            return ResponseFormatter.error(new Error(validation.error));
+        }
+        // Parse start and end times
+        const start = parseDateTime(startTime);
+        const end = parseDateTime(endTime);
+        // Build event resource
+        const eventResource = {
+            summary,
+            start,
+            end,
+        };
+        if (location) {
+            eventResource.location = location;
+        }
+        if (description) {
+            eventResource.description = description;
+        }
+        if (attendees && attendees.length > 0) {
+            eventResource.attendees = formatAttendees(attendees);
+        }
+        if (conferenceData) {
+            eventResource.conferenceData = {
+                createRequest: {
+                    requestId: `meet-${Date.now()}`,
+                    conferenceSolutionKey: {
+                        type: "hangoutsMeet",
+                    },
+                },
+            };
+        }
+        const response = await calendar.events.insert({
+            calendarId,
+            requestBody: eventResource,
+            sendUpdates,
+            conferenceDataVersion: conferenceData ? 1 : undefined,
+        });
+        const event = response.data;
+        if (!event) {
+            return ResponseFormatter.error(new Error("Failed to create event"));
+        }
+        const formattedOutput = formatEvent(event, calendarId);
+        return ResponseFormatter.success({
+            id: event.id,
+            summary: event.summary,
+            start: event.start,
+            end: event.end,
+            htmlLink: event.htmlLink,
+            conferenceData: event.conferenceData,
+        }, `Event created successfully:\n\n${formattedOutput}`);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/calendar/basic/calendar_delete_event.js

@@ -0,0 +1,52 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "calendar_delete_event",
+    description: "Delete a calendar event permanently. This action cannot be undone. Optionally send notifications to attendees about the event cancellation.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            calendarId: {
+                type: "string",
+                description: "Calendar identifier (default: 'primary' for user's main calendar)",
+            },
+            eventId: {
+                type: "string",
+                description: "Event identifier to delete",
+            },
+            sendUpdates: {
+                type: "string",
+                description: "Whether to send event cancellation notifications: 'all', 'externalOnly', 'none'. Default: 'all'",
+            },
+        },
+        required: ["eventId"],
+    },
+};
+export async function deleteEvent(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { calendarId = "primary", eventId, sendUpdates = "all", } = args;
+        // Get event details before deletion for confirmation message
+        const eventResponse = await calendar.events.get({
+            calendarId,
+            eventId,
+        });
+        const event = eventResponse.data;
+        const eventTitle = event.summary || "(No title)";
+        // Delete the event
+        await calendar.events.delete({
+            calendarId,
+            eventId,
+            sendUpdates,
+        });
+        return ResponseFormatter.success({
+            deleted: true,
+            eventId,
+            calendarId,
+            summary: eventTitle,
+        }, `Event "${eventTitle}" (ID: ${eventId}) has been deleted successfully.`);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/calendar/basic/calendar_get_event.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_get_event",
+    description: "Get detailed information about a specific calendar event by its ID. Returns comprehensive event details including title, time, location, description, attendees, recurrence rules, and conference data (Google Meet links).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            calendarId: {
+                type: "string",
+                description: "Calendar identifier (default: 'primary' for user's main calendar)",
+            },
+            eventId: {
+                type: "string",
+                description: "Event identifier to retrieve",
+            },
+        },
+        required: ["eventId"],
+    },
+};
+export async function getEvent(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { calendarId = "primary", eventId } = args;
+        const response = await calendar.events.get({
+            calendarId,
+            eventId,
+        });
+        const event = response.data;
+        if (!event) {
+            return ResponseFormatter.error(new Error(`Event not found: ${eventId}`));
+        }
+        const formattedOutput = formatEvent(event, calendarId);
+        return ResponseFormatter.success({
+            id: event.id,
+            summary: event.summary,
+            start: event.start,
+            end: event.end,
+            location: event.location,
+            description: event.description,
+            attendees: event.attendees,
+            htmlLink: event.htmlLink,
+            conferenceData: event.conferenceData,
+            recurrence: event.recurrence,
+            status: event.status,
+        }, `Event details:\n\n${formattedOutput}`);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/calendar/basic/calendar_list_events.js

@@ -0,0 +1,86 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { formatEventList } from "../../../lib/calendar-helpers.js";
+export const schema = {
+    name: "calendar_list_events",
+    description: "List events from a Google Calendar. Returns upcoming events with details including title, time, location, attendees, and meeting links. Supports filtering by time range, search query, and pagination.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            calendarId: {
+                type: "string",
+                description: "Calendar identifier (default: 'primary' for user's main calendar)",
+            },
+            timeMin: {
+                type: "string",
+                description: "Lower bound (inclusive) for event start time (ISO 8601 format, e.g., '2024-01-01T00:00:00Z')",
+            },
+            timeMax: {
+                type: "string",
+                description: "Upper bound (exclusive) for event end time (ISO 8601 format)",
+            },
+            q: {
+                type: "string",
+                description: "Free text search terms to find events matching title, description, location, attendee emails, etc.",
+            },
+            maxResults: {
+                type: "number",
+                description: "Maximum number of events to return (default: 10, max: 250)",
+            },
+            pageToken: {
+                type: "string",
+                description: "Token for pagination to get the next page of results",
+            },
+            singleEvents: {
+                type: "boolean",
+                description: "Whether to expand recurring events into instances (default: true)",
+            },
+            orderBy: {
+                type: "string",
+                description: "Order of events: 'startTime' (chronological) or 'updated' (modification time). Requires singleEvents=true for 'startTime'",
+            },
+        },
+        required: [],
+    },
+};
+export async function listEvents(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { calendarId = "primary", timeMin, timeMax, q, maxResults = 10, pageToken, singleEvents = true, orderBy = "startTime", } = args;
+        const response = await calendar.events.list({
+            calendarId,
+            timeMin,
+            timeMax,
+            q,
+            maxResults: Math.min(maxResults, 250),
+            pageToken,
+            singleEvents,
+            orderBy: singleEvents ? orderBy : undefined,
+        });
+        const events = response.data.items || [];
+        const nextPageToken = response.data.nextPageToken;
+        if (events.length === 0) {
+            return ResponseFormatter.success({
+                count: 0,
+                events: [],
+                calendarId,
+            }, `No events found in calendar: ${calendarId}`);
+        }
+        const formattedOutput = formatEventList(events, calendarId);
+        return ResponseFormatter.success({
+            count: events.length,
+            calendarId,
+            events: events.map((e) => ({
+                id: e.id,
+                summary: e.summary,
+                start: e.start,
+                end: e.end,
+                htmlLink: e.htmlLink,
+            })),
+            nextPageToken,
+        }, `Events from ${calendarId}:\n\n${formattedOutput}`);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}