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

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

@@ -0,0 +1,87 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "calendar_calendarlist_list",
+    description: "List all calendars in the user's calendar list. Returns information about each calendar including ID, summary, description, and access role. Supports pagination and filtering by access level.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            maxResults: {
+                type: "number",
+                description: "Maximum number of calendars to return per page (default: 100, max: 250)",
+            },
+            minAccessRole: {
+                type: "string",
+                description: "Minimum access role filter: 'freeBusyReader', 'owner', 'reader', or 'writer'",
+            },
+            pageToken: {
+                type: "string",
+                description: "Token for accessing subsequent result pages",
+            },
+            showDeleted: {
+                type: "boolean",
+                description: "Include deleted calendar entries (default: false)",
+            },
+            showHidden: {
+                type: "boolean",
+                description: "Include hidden entries (default: false)",
+            },
+        },
+        required: [],
+    },
+};
+export async function listCalendarList(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { maxResults, minAccessRole, pageToken, showDeleted, showHidden, } = args;
+        const response = await calendar.calendarList.list({
+            maxResults,
+            minAccessRole,
+            pageToken,
+            showDeleted,
+            showHidden,
+        });
+        const calendars = response.data.items || [];
+        const totalCalendars = calendars.length;
+        if (totalCalendars === 0) {
+            return ResponseFormatter.success({ calendars: [], count: 0 }, "No calendars found in the calendar list.");
+        }
+        // Format calendar list
+        const calendarList = calendars.map((cal) => ({
+            id: cal.id,
+            summary: cal.summary,
+            description: cal.description || null,
+            timeZone: cal.timeZone,
+            accessRole: cal.accessRole,
+            primary: cal.primary || false,
+            backgroundColor: cal.backgroundColor,
+            foregroundColor: cal.foregroundColor,
+        }));
+        let message = `📅 Calendar List (${totalCalendars} calendar${totalCalendars > 1 ? "s" : ""})\n\n`;
+        calendars.forEach((cal, index) => {
+            const isPrimary = cal.primary ? " [PRIMARY]" : "";
+            message += `${index + 1}. ${cal.summary}${isPrimary}\n`;
+            message += `   ID: ${cal.id}\n`;
+            message += `   Access Role: ${cal.accessRole}\n`;
+            if (cal.description) {
+                message += `   Description: ${cal.description}\n`;
+            }
+            message += `   Time Zone: ${cal.timeZone}\n`;
+            if (cal.backgroundColor) {
+                message += `   Colors: BG ${cal.backgroundColor}, FG ${cal.foregroundColor}\n`;
+            }
+            message += "\n";
+        });
+        if (response.data.nextPageToken) {
+            message += `\n📄 Next Page Token: ${response.data.nextPageToken}`;
+        }
+        return ResponseFormatter.success({
+            calendars: calendarList,
+            count: totalCalendars,
+            nextPageToken: response.data.nextPageToken || null,
+        }, message);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/calendar/calendars/calendar_calendars_get.js

@@ -0,0 +1,52 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "calendar_calendars_get",
+    description: "Get metadata for a specific calendar. Returns calendar information including title, description, location, and timezone. Use 'primary' to access the currently logged-in user's main calendar, or provide a specific calendar ID.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            calendarId: {
+                type: "string",
+                description: "Calendar identifier. Use 'primary' for the user's primary calendar.",
+            },
+        },
+        required: ["calendarId"],
+    },
+};
+export async function getCalendar(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { calendarId } = args;
+        const response = await calendar.calendars.get({
+            calendarId,
+        });
+        const cal = response.data;
+        let message = `📅 Calendar: ${cal.summary}\n\n`;
+        message += `ID: ${cal.id}\n`;
+        if (cal.description) {
+            message += `Description: ${cal.description}\n`;
+        }
+        if (cal.location) {
+            message += `Location: ${cal.location}\n`;
+        }
+        if (cal.timeZone) {
+            message += `Time Zone: ${cal.timeZone}\n`;
+        }
+        if (cal.conferenceProperties) {
+            message += `\n📞 Conference Properties:\n`;
+            message += `  Allowed Conference Solution Types: ${cal.conferenceProperties.allowedConferenceSolutionTypes?.join(", ") || "None"}\n`;
+        }
+        return ResponseFormatter.success({
+            calendarId: cal.id,
+            summary: cal.summary,
+            description: cal.description || null,
+            location: cal.location || null,
+            timeZone: cal.timeZone || null,
+            etag: cal.etag,
+        }, message);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/calendar/calendars/calendar_calendars_insert.js

@@ -0,0 +1,66 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "calendar_calendars_insert",
+    description: "Create a new secondary calendar. The authenticated user becomes the owner of the new calendar. You can specify the calendar's title, description, location, and timezone. This is different from the primary calendar which is created automatically with the user account.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            summary: {
+                type: "string",
+                description: "Title of the calendar (required)",
+            },
+            description: {
+                type: "string",
+                description: "Description of the calendar",
+            },
+            location: {
+                type: "string",
+                description: "Geographic location as free-form text",
+            },
+            timeZone: {
+                type: "string",
+                description: "IANA Time Zone Database name (e.g., 'America/New_York', 'Europe/London')",
+            },
+        },
+        required: ["summary"],
+    },
+};
+export async function insertCalendar(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { summary, description, location, timeZone, } = args;
+        const response = await calendar.calendars.insert({
+            requestBody: {
+                summary,
+                description,
+                location,
+                timeZone,
+            },
+        });
+        const cal = response.data;
+        let message = `✅ Calendar created successfully\n\n`;
+        message += `📅 ${cal.summary}\n`;
+        message += `ID: ${cal.id}\n`;
+        if (cal.description) {
+            message += `Description: ${cal.description}\n`;
+        }
+        if (cal.location) {
+            message += `Location: ${cal.location}\n`;
+        }
+        if (cal.timeZone) {
+            message += `Time Zone: ${cal.timeZone}\n`;
+        }
+        message += `\n💡 You are now the owner of this calendar.`;
+        return ResponseFormatter.success({
+            calendarId: cal.id,
+            summary: cal.summary,
+            description: cal.description || null,
+            location: cal.location || null,
+            timeZone: cal.timeZone || null,
+        }, message);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/calendar/calendars/calendar_calendars_update.js

@@ -0,0 +1,85 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "calendar_calendars_update",
+    description: "Update metadata for an existing calendar. You can modify the calendar's title, description, location, and timezone. All fields are optional - only provide the fields you want to update. Use 'primary' to update the user's primary calendar.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            calendarId: {
+                type: "string",
+                description: "Calendar identifier. Use 'primary' for the user's primary calendar.",
+            },
+            summary: {
+                type: "string",
+                description: "New title for the calendar",
+            },
+            description: {
+                type: "string",
+                description: "New description for the calendar",
+            },
+            location: {
+                type: "string",
+                description: "New geographic location as free-form text",
+            },
+            timeZone: {
+                type: "string",
+                description: "New IANA Time Zone Database name (e.g., 'America/New_York')",
+            },
+        },
+        required: ["calendarId"],
+    },
+};
+export async function updateCalendar(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { calendarId, summary, description, location, timeZone, } = args;
+        // Get current calendar data
+        const currentCalendar = await calendar.calendars.get({
+            calendarId,
+        });
+        if (!currentCalendar.data) {
+            return ResponseFormatter.error(new Error(`Calendar with ID '${calendarId}' not found.`));
+        }
+        // Prepare update payload with only provided fields
+        const updatePayload = {};
+        if (summary !== undefined)
+            updatePayload.summary = summary;
+        if (description !== undefined)
+            updatePayload.description = description;
+        if (location !== undefined)
+            updatePayload.location = location;
+        if (timeZone !== undefined)
+            updatePayload.timeZone = timeZone;
+        if (Object.keys(updatePayload).length === 0) {
+            return ResponseFormatter.error(new Error("No fields provided to update. Specify at least one field: summary, description, location, or timeZone."));
+        }
+        const response = await calendar.calendars.update({
+            calendarId,
+            requestBody: updatePayload,
+        });
+        const cal = response.data;
+        let message = `✅ Calendar updated successfully\n\n`;
+        message += `📅 ${cal.summary}\n`;
+        message += `ID: ${cal.id}\n`;
+        if (cal.description) {
+            message += `Description: ${cal.description}\n`;
+        }
+        if (cal.location) {
+            message += `Location: ${cal.location}\n`;
+        }
+        if (cal.timeZone) {
+            message += `Time Zone: ${cal.timeZone}\n`;
+        }
+        return ResponseFormatter.success({
+            calendarId: cal.id,
+            summary: cal.summary,
+            description: cal.description || null,
+            location: cal.location || null,
+            timeZone: cal.timeZone || null,
+        }, message);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

package/dist/tools/calendar/colors/calendar_colors_get.js

@@ -0,0 +1,46 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+export const schema = {
+    name: "calendar_colors_get",
+    description: "Get the color definitions available for calendars and events. Returns a palette of colors with their IDs and hex values that can be used when creating or updating calendars and events. Useful for UI display and color selection.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        required: [],
+    },
+};
+export async function getColors() {
+    try {
+        const calendar = google.calendar("v3");
+        const response = await calendar.colors.get();
+        const data = response.data;
+        const calendarColors = data.calendar || {};
+        const eventColors = data.event || {};
+        let message = `🎨 Google Calendar Color Palette\n\n`;
+        // Calendar Colors
+        message += `📅 Calendar Colors:\n`;
+        Object.entries(calendarColors).forEach(([id, colorData]) => {
+            message += `  ${id}: Background ${colorData.background}, Foreground ${colorData.foreground}\n`;
+        });
+        message += `\n📌 Event Colors:\n`;
+        Object.entries(eventColors).forEach(([id, colorData]) => {
+            message += `  ${id}: Background ${colorData.background}, Foreground ${colorData.foreground}\n`;
+        });
+        message += `\n💡 Usage: Use these color IDs when creating or updating calendars and events.`;
+        return ResponseFormatter.success({
+            calendarColors: Object.entries(calendarColors).map(([id, data]) => ({
+                id,
+                background: data.background,
+                foreground: data.foreground,
+            })),
+            eventColors: Object.entries(eventColors).map(([id, data]) => ({
+                id,
+                background: data.background,
+                foreground: data.foreground,
+            })),
+        }, message);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

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

@@ -0,0 +1,81 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { formatEventList } from "../../../lib/calendar-helpers.js";
+export const schema = {
+    name: "calendar_events_instances",
+    description: "Get all instances of a recurring event within a specified time range. Returns individual occurrences of repeating events, allowing you to see each instance's specific date and time. Useful for viewing or managing individual occurrences of a recurring meeting or appointment.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            calendarId: {
+                type: "string",
+                description: "Calendar identifier (default: 'primary' for user's main calendar)",
+            },
+            eventId: {
+                type: "string",
+                description: "Recurring event identifier",
+            },
+            timeMin: {
+                type: "string",
+                description: "Lower bound (inclusive) for instances (RFC3339 format, e.g., '2024-01-15T00:00:00Z')",
+            },
+            timeMax: {
+                type: "string",
+                description: "Upper bound (exclusive) for instances (RFC3339 format, e.g., '2024-01-31T23:59:59Z')",
+            },
+            maxResults: {
+                type: "number",
+                description: "Maximum number of instances to return (default: 250, max: 2500)",
+            },
+            pageToken: {
+                type: "string",
+                description: "Token for accessing subsequent result pages",
+            },
+            showDeleted: {
+                type: "boolean",
+                description: "Include cancelled instances (default: false)",
+            },
+        },
+        required: ["eventId"],
+    },
+};
+export async function listEventInstances(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { calendarId = "primary", eventId, timeMin, timeMax, maxResults, pageToken, showDeleted, } = args;
+        const response = await calendar.events.instances({
+            calendarId,
+            eventId,
+            timeMin,
+            timeMax,
+            maxResults,
+            pageToken,
+            showDeleted,
+        });
+        const instances = response.data.items || [];
+        const totalInstances = instances.length;
+        if (totalInstances === 0) {
+            return ResponseFormatter.success({ instances: [], count: 0 }, "No instances found for this recurring event in the specified time range.");
+        }
+        const message = formatEventList(instances, calendarId);
+        let resultMessage = `🔁 Recurring Event Instances (${totalInstances} instance${totalInstances > 1 ? "s" : ""})\n\n`;
+        resultMessage += message;
+        if (response.data.nextPageToken) {
+            resultMessage += `\n\n📄 Next Page Token: ${response.data.nextPageToken}`;
+        }
+        return ResponseFormatter.success({
+            instances: instances.map((inst) => ({
+                id: inst.id,
+                summary: inst.summary,
+                start: inst.start,
+                end: inst.end,
+                status: inst.status,
+            })),
+            count: totalInstances,
+            nextPageToken: response.data.nextPageToken || null,
+        }, resultMessage);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

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

@@ -0,0 +1,63 @@
+import { google } from "googleapis";
+import { ResponseFormatter } from "../../../lib/response-formatter.js";
+import { formatEvent } from "../../../lib/calendar-helpers.js";
+export const schema = {
+    name: "calendar_events_move",
+    description: "Move an event from one calendar to another. This changes the event's organizer to the destination calendar owner. Only works with default events (not recurring event instances). The event is removed from the source calendar and appears in the destination calendar.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            calendarId: {
+                type: "string",
+                description: "Source calendar identifier where the event currently exists",
+            },
+            eventId: {
+                type: "string",
+                description: "Event identifier to move",
+            },
+            destination: {
+                type: "string",
+                description: "Destination calendar identifier where the event will be moved to",
+            },
+            sendUpdates: {
+                type: "string",
+                description: "Whether to send event notifications: 'all', 'externalOnly', 'none'. Default: 'none'",
+            },
+        },
+        required: ["calendarId", "eventId", "destination"],
+    },
+};
+export async function moveEvent(args) {
+    try {
+        const calendar = google.calendar("v3");
+        const { calendarId, eventId, destination, sendUpdates = "none", } = args;
+        // Get event details before moving
+        const originalEvent = await calendar.events.get({
+            calendarId,
+            eventId,
+        });
+        const response = await calendar.events.move({
+            calendarId,
+            eventId,
+            destination,
+            sendUpdates,
+        });
+        const event = response.data;
+        let message = `✅ Event moved successfully\n\n`;
+        message += `From Calendar: ${calendarId}\n`;
+        message += `To Calendar: ${destination}\n\n`;
+        message += formatEvent(event, destination);
+        return ResponseFormatter.success({
+            eventId: event.id,
+            sourceCalendar: calendarId,
+            destinationCalendar: destination,
+            summary: event.summary,
+            start: event.start,
+            end: event.end,
+            htmlLink: event.htmlLink,
+        }, message);
+    }
+    catch (error) {
+        return ResponseFormatter.error(error);
+    }
+}

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

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

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

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