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

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

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

@@ -0,0 +1,116 @@
+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_update_event",
+    description: "Update an existing calendar event. Can modify title, time, location, description, attendees, and other event properties. Only specified fields will be updated; unspecified fields remain unchanged.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            calendarId: {
+                type: "string",
+                description: "Calendar identifier (default: 'primary' for user's main calendar)",
+            },
+            eventId: {
+                type: "string",
+                description: "Event identifier to update",
+            },
+            summary: {
+                type: "string",
+                description: "New event title/summary",
+            },
+            startTime: {
+                type: "string",
+                description: "New event start time (ISO 8601 format: '2024-01-15T10:00:00Z' or date only: '2024-01-15' for all-day)",
+            },
+            endTime: {
+                type: "string",
+                description: "New event end time (ISO 8601 format: '2024-01-15T11:00:00Z' or date only: '2024-01-16' for all-day)",
+            },
+            location: {
+                type: "string",
+                description: "New event location",
+            },
+            description: {
+                type: "string",
+                description: "New event description",
+            },
+            attendees: {
+                type: "array",
+                items: {
+                    type: "string",
+                },
+                description: "New list of attendee email addresses (replaces existing attendees)",
+            },
+            sendUpdates: {
+                type: "string",
+                description: "Whether to send event notifications: 'all', 'externalOnly', 'none'. Default: 'all'",
+            },
+        },
+        required: ["eventId"],
+    },
+};
+export async function updateEvent(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { calendarId = "primary", eventId, summary, startTime, endTime, location, description, attendees, sendUpdates = "all", } = args;
+        // First, get the existing event
+        const existingResponse = await calendar.events.get({
+            calendarId,
+            eventId,
+        });
+        const existingEvent = existingResponse.data;
+        if (!existingEvent) {
+            return ResponseFormatter.error(new Error(`Event not found: ${eventId}`));
+        }
+        // Build update resource with only specified fields
+        const eventResource = {
+            ...existingEvent,
+        };
+        if (summary !== undefined) {
+            eventResource.summary = summary;
+        }
+        if (startTime !== undefined && endTime !== undefined) {
+            // Validate time range if both are provided
+            const validation = validateTimeRange(startTime, endTime);
+            if (!validation.valid) {
+                return ResponseFormatter.error(new Error(validation.error));
+            }
+            eventResource.start = parseDateTime(startTime);
+            eventResource.end = parseDateTime(endTime);
+        }
+        else if (startTime !== undefined || endTime !== undefined) {
+            return ResponseFormatter.error(new Error("Both startTime and endTime must be provided together"));
+        }
+        if (location !== undefined) {
+            eventResource.location = location;
+        }
+        if (description !== undefined) {
+            eventResource.description = description;
+        }
+        if (attendees !== undefined) {
+            eventResource.attendees = formatAttendees(attendees);
+        }
+        const response = await calendar.events.update({
+            calendarId,
+            eventId,
+            requestBody: eventResource,
+            sendUpdates,
+        });
+        const event = response.data;
+        if (!event) {
+            return ResponseFormatter.error(new Error("Failed to update event"));
+        }
+        const formattedOutput = formatEvent(event, calendarId);
+        return ResponseFormatter.success({
+            id: event.id,
+            summary: event.summary,
+            start: event.start,
+            end: event.end,
+            htmlLink: event.htmlLink,
+        }, `Event updated successfully:\n\n${formattedOutput}`);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/calendar/calendarlist/calendar_calendarlist_get.js

@@ -0,0 +1,73 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "calendar_calendarlist_get",
+    description: "Get detailed information about a specific calendar from the user's calendar list. Returns calendar metadata including access role, notifications, and display settings.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            calendarId: {
+                type: "string",
+                description: "Calendar identifier. Use 'primary' for the user's primary calendar.",
+            },
+        },
+        required: ["calendarId"],
+    },
+};
+export async function getCalendarListEntry(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { calendarId } = args;
+        const response = await calendar.calendarList.get({
+            calendarId,
+        });
+        const cal = response.data;
+        let message = `📅 Calendar: ${cal.summary}\n\n`;
+        message += `ID: ${cal.id}\n`;
+        message += `Access Role: ${cal.accessRole}\n`;
+        message += `Time Zone: ${cal.timeZone}\n`;
+        if (cal.description) {
+            message += `Description: ${cal.description}\n`;
+        }
+        if (cal.location) {
+            message += `Location: ${cal.location}\n`;
+        }
+        if (cal.primary) {
+            message += `Primary Calendar: Yes\n`;
+        }
+        if (cal.backgroundColor) {
+            message += `\n🎨 Display Colors:\n`;
+            message += `  Background: ${cal.backgroundColor}\n`;
+            message += `  Foreground: ${cal.foregroundColor}\n`;
+        }
+        if (cal.defaultReminders && cal.defaultReminders.length > 0) {
+            message += `\n⏰ Default Reminders:\n`;
+            cal.defaultReminders.forEach((reminder) => {
+                message += `  - ${reminder.method}: ${reminder.minutes} minutes before\n`;
+            });
+        }
+        if (cal.notificationSettings) {
+            message += `\n🔔 Notification Settings:\n`;
+            cal.notificationSettings.notifications?.forEach((notif) => {
+                message += `  - ${notif.type}: ${notif.method}\n`;
+            });
+        }
+        return ResponseFormatter.success({
+            calendar: {
+                id: cal.id,
+                summary: cal.summary,
+                description: cal.description || null,
+                location: cal.location || null,
+                timeZone: cal.timeZone,
+                accessRole: cal.accessRole,
+                primary: cal.primary || false,
+                backgroundColor: cal.backgroundColor,
+                foregroundColor: cal.foregroundColor,
+                defaultReminders: cal.defaultReminders || [],
+            },
+        }, message);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}