google-calendar-workspace-mcp-server 0.0.1

package/shared/tools/get-event.js

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+import { logError } from '../logging.js';
+export const GetEventSchema = z.object({
+    calendar_id: z
+        .string()
+        .optional()
+        .default('primary')
+        .describe('Calendar ID containing the event. Defaults to "primary".'),
+    event_id: z.string().min(1).describe('The ID of the event to retrieve.'),
+});
+export function getEventTool(server, clientFactory) {
+    return {
+        name: 'gcal_get_event',
+        description: 'Retrieves detailed information about a specific calendar event by ID. ' +
+            'Returns full event details including title, time, location, attendees, description, recurrence rules, and reminders. ' +
+            'Use this when you need complete information about a particular event.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                calendar_id: {
+                    type: 'string',
+                    description: GetEventSchema.shape.calendar_id.description,
+                },
+                event_id: {
+                    type: 'string',
+                    description: GetEventSchema.shape.event_id.description,
+                },
+            },
+            required: ['event_id'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = GetEventSchema.parse(args);
+                const client = clientFactory();
+                const event = await client.getEvent(parsed.calendar_id, parsed.event_id);
+                let output = `# Event Details\n\n`;
+                output += `## ${event.summary || '(No title)'}\n\n`;
+                output += `**Event ID:** ${event.id}\n`;
+                // Status
+                if (event.status) {
+                    output += `**Status:** ${event.status}\n`;
+                }
+                // Start time
+                if (event.start?.dateTime) {
+                    output += `**Start:** ${new Date(event.start.dateTime).toLocaleString()}`;
+                    if (event.start.timeZone) {
+                        output += ` (${event.start.timeZone})`;
+                    }
+                    output += '\n';
+                }
+                else if (event.start?.date) {
+                    output += `**Start:** ${event.start.date} (All day)\n`;
+                }
+                // End time
+                if (event.end?.dateTime) {
+                    output += `**End:** ${new Date(event.end.dateTime).toLocaleString()}`;
+                    if (event.end.timeZone) {
+                        output += ` (${event.end.timeZone})`;
+                    }
+                    output += '\n';
+                }
+                else if (event.end?.date) {
+                    output += `**End:** ${event.end.date} (All day)\n`;
+                }
+                // Location
+                if (event.location) {
+                    output += `**Location:** ${event.location}\n`;
+                }
+                // Creator
+                if (event.creator) {
+                    output += `**Created By:** ${event.creator.displayName || event.creator.email}\n`;
+                }
+                // Organizer
+                if (event.organizer) {
+                    output += `**Organizer:** ${event.organizer.displayName || event.organizer.email}\n`;
+                }
+                // Attendees
+                if (event.attendees && event.attendees.length > 0) {
+                    output += `\n### Attendees (${event.attendees.length})\n\n`;
+                    for (const attendee of event.attendees) {
+                        const name = attendee.displayName || attendee.email;
+                        const status = attendee.responseStatus || 'needsAction';
+                        const optional = attendee.organizer ? ' [Organizer]' : '';
+                        output += `- ${name} - **${status}**${optional}\n`;
+                    }
+                    output += '\n';
+                }
+                // Description
+                if (event.description) {
+                    output += `### Description\n\n${event.description}\n\n`;
+                }
+                // Recurrence
+                if (event.recurrence && event.recurrence.length > 0) {
+                    output += `### Recurrence\n\n`;
+                    for (const rule of event.recurrence) {
+                        output += `- ${rule}\n`;
+                    }
+                    output += '\n';
+                }
+                // Reminders
+                if (event.reminders) {
+                    output += `### Reminders\n\n`;
+                    if (event.reminders.useDefault) {
+                        output += `Using default reminders\n\n`;
+                    }
+                    else if (event.reminders.overrides && event.reminders.overrides.length > 0) {
+                        for (const reminder of event.reminders.overrides) {
+                            output += `- ${reminder.method}: ${reminder.minutes} minutes before\n`;
+                        }
+                        output += '\n';
+                    }
+                }
+                // Visibility and transparency
+                if (event.visibility) {
+                    output += `**Visibility:** ${event.visibility}\n`;
+                }
+                if (event.transparency) {
+                    output += `**Show as:** ${event.transparency}\n`;
+                }
+                // Metadata
+                if (event.created) {
+                    output += `**Created:** ${new Date(event.created).toLocaleString()}\n`;
+                }
+                if (event.updated) {
+                    output += `**Updated:** ${new Date(event.updated).toLocaleString()}\n`;
+                }
+                // Link
+                if (event.htmlLink) {
+                    output += `\n**Event Link:** ${event.htmlLink}\n`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: output,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                logError('get-event-tool', error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error getting event: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/list-calendars.d.ts

@@ -0,0 +1,36 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const ListCalendarsSchema: z.ZodObject<{
+    max_results: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    max_results: number;
+}, {
+    max_results?: number | undefined;
+}>;
+export declare function listCalendarsTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            max_results: {
+                type: string;
+                description: string | undefined;
+            };
+        };
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};

package/shared/tools/list-calendars.js

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import { logError } from '../logging.js';
+export const ListCalendarsSchema = z.object({
+    max_results: z
+        .number()
+        .positive()
+        .max(250)
+        .optional()
+        .default(50)
+        .describe('Maximum number of calendars to return. Defaults to 50, maximum is 250.'),
+});
+export function listCalendarsTool(server, clientFactory) {
+    return {
+        name: 'gcal_list_calendars',
+        description: 'Lists all calendars available to the authenticated user. ' +
+            'Returns calendar details including ID, name, description, time zone, and access role. ' +
+            'Use this to discover available calendars before querying events, or to see which calendars the user has access to.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                max_results: {
+                    type: 'number',
+                    description: ListCalendarsSchema.shape.max_results.description,
+                },
+            },
+        },
+        handler: async (args) => {
+            try {
+                const parsed = ListCalendarsSchema.parse(args);
+                const client = clientFactory();
+                const result = await client.listCalendars({
+                    maxResults: parsed.max_results,
+                });
+                const calendars = result.items || [];
+                if (calendars.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'No calendars found.',
+                            },
+                        ],
+                    };
+                }
+                let output = `# Available Calendars (${calendars.length} found)\n\n`;
+                for (const calendar of calendars) {
+                    output += `## ${calendar.summary}\n\n`;
+                    output += `**Calendar ID:** ${calendar.id}\n`;
+                    if (calendar.description) {
+                        output += `**Description:** ${calendar.description}\n`;
+                    }
+                    output += `**Time Zone:** ${calendar.timeZone}\n`;
+                    output += `**Access Role:** ${calendar.accessRole}\n`;
+                    if (calendar.primary) {
+                        output += `**Primary:** Yes\n`;
+                    }
+                    if (calendar.selected !== undefined) {
+                        output += `**Selected:** ${calendar.selected ? 'Yes' : 'No'}\n`;
+                    }
+                    if (calendar.backgroundColor) {
+                        output += `**Background Color:** ${calendar.backgroundColor}\n`;
+                    }
+                    output += '\n---\n\n';
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: output,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                logError('list-calendars-tool', error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error listing calendars: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/list-events.d.ts

@@ -0,0 +1,79 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const ListEventsSchema: z.ZodObject<{
+    calendar_id: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    time_min: z.ZodOptional<z.ZodString>;
+    time_max: z.ZodOptional<z.ZodString>;
+    max_results: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    query: z.ZodOptional<z.ZodString>;
+    single_events: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    order_by: z.ZodOptional<z.ZodEnum<["startTime", "updated"]>>;
+}, "strip", z.ZodTypeAny, {
+    calendar_id: string;
+    max_results: number;
+    single_events: boolean;
+    time_min?: string | undefined;
+    time_max?: string | undefined;
+    query?: string | undefined;
+    order_by?: "startTime" | "updated" | undefined;
+}, {
+    calendar_id?: string | undefined;
+    time_min?: string | undefined;
+    time_max?: string | undefined;
+    max_results?: number | undefined;
+    query?: string | undefined;
+    single_events?: boolean | undefined;
+    order_by?: "startTime" | "updated" | undefined;
+}>;
+export declare function listEventsTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            calendar_id: {
+                type: string;
+                description: string | undefined;
+            };
+            time_min: {
+                type: string;
+                description: string | undefined;
+            };
+            time_max: {
+                type: string;
+                description: string | undefined;
+            };
+            max_results: {
+                type: string;
+                description: string | undefined;
+            };
+            query: {
+                type: string;
+                description: string | undefined;
+            };
+            single_events: {
+                type: string;
+                description: string | undefined;
+            };
+            order_by: {
+                type: string;
+                enum: string[];
+                description: string | undefined;
+            };
+        };
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};

package/shared/tools/list-events.js

@@ -0,0 +1,176 @@
+import { z } from 'zod';
+import { logError } from '../logging.js';
+export const ListEventsSchema = z.object({
+    calendar_id: z
+        .string()
+        .optional()
+        .default('primary')
+        .describe('Calendar ID to list events from. Defaults to "primary" (user\'s primary calendar).'),
+    time_min: z
+        .string()
+        .optional()
+        .describe('Lower bound (inclusive) for event start time in RFC3339 format (e.g., "2024-01-01T00:00:00Z"). Defaults to current time if not specified.'),
+    time_max: z
+        .string()
+        .optional()
+        .describe('Upper bound (exclusive) for event start time in RFC3339 format (e.g., "2024-12-31T23:59:59Z").'),
+    max_results: z
+        .number()
+        .positive()
+        .max(250)
+        .optional()
+        .default(10)
+        .describe('Maximum number of events to return. Defaults to 10, maximum is 250.'),
+    query: z.string().optional().describe('Free text search query to filter events.'),
+    single_events: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Whether to expand recurring events into instances. Defaults to true to show individual occurrences.'),
+    order_by: z
+        .enum(['startTime', 'updated'])
+        .optional()
+        .describe('Order of events. "startTime" orders by start time (requires single_events=true), "updated" orders by last modification time.'),
+});
+export function listEventsTool(server, clientFactory) {
+    return {
+        name: 'gcal_list_events',
+        description: 'Lists events from a Google Calendar within an optional time range. ' +
+            'Returns event details including title, time, location, attendees, and description. ' +
+            'Useful for checking upcoming meetings, finding events by search query, or reviewing a specific time period. ' +
+            'By default, shows the next 10 events from the primary calendar.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                calendar_id: {
+                    type: 'string',
+                    description: ListEventsSchema.shape.calendar_id.description,
+                },
+                time_min: {
+                    type: 'string',
+                    description: ListEventsSchema.shape.time_min.description,
+                },
+                time_max: {
+                    type: 'string',
+                    description: ListEventsSchema.shape.time_max.description,
+                },
+                max_results: {
+                    type: 'number',
+                    description: ListEventsSchema.shape.max_results.description,
+                },
+                query: {
+                    type: 'string',
+                    description: ListEventsSchema.shape.query.description,
+                },
+                single_events: {
+                    type: 'boolean',
+                    description: ListEventsSchema.shape.single_events.description,
+                },
+                order_by: {
+                    type: 'string',
+                    enum: ['startTime', 'updated'],
+                    description: ListEventsSchema.shape.order_by.description,
+                },
+            },
+        },
+        handler: async (args) => {
+            try {
+                const parsed = ListEventsSchema.parse(args);
+                const client = clientFactory();
+                const result = await client.listEvents(parsed.calendar_id, {
+                    timeMin: parsed.time_min,
+                    timeMax: parsed.time_max,
+                    maxResults: parsed.max_results,
+                    q: parsed.query,
+                    singleEvents: parsed.single_events,
+                    orderBy: parsed.order_by,
+                });
+                const events = result.items || [];
+                if (events.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'No events found matching the criteria.',
+                            },
+                        ],
+                    };
+                }
+                let output = `# Calendar Events (${events.length} found)\n\n`;
+                output += `**Calendar:** ${result.summary}\n`;
+                output += `**Time Zone:** ${result.timeZone}\n\n`;
+                for (const event of events) {
+                    output += `## ${event.summary || '(No title)'}\n\n`;
+                    output += `**Event ID:** ${event.id}\n`;
+                    // Start time
+                    if (event.start?.dateTime) {
+                        output += `**Start:** ${new Date(event.start.dateTime).toLocaleString()}\n`;
+                    }
+                    else if (event.start?.date) {
+                        output += `**Start:** ${event.start.date} (All day)\n`;
+                    }
+                    // End time
+                    if (event.end?.dateTime) {
+                        output += `**End:** ${new Date(event.end.dateTime).toLocaleString()}\n`;
+                    }
+                    else if (event.end?.date) {
+                        output += `**End:** ${event.end.date} (All day)\n`;
+                    }
+                    // Location
+                    if (event.location) {
+                        output += `**Location:** ${event.location}\n`;
+                    }
+                    // Status
+                    if (event.status) {
+                        output += `**Status:** ${event.status}\n`;
+                    }
+                    // Organizer
+                    if (event.organizer) {
+                        output += `**Organizer:** ${event.organizer.displayName || event.organizer.email}\n`;
+                    }
+                    // Attendees
+                    if (event.attendees && event.attendees.length > 0) {
+                        output += `**Attendees:** ${event.attendees.length}\n`;
+                        for (const attendee of event.attendees) {
+                            const name = attendee.displayName || attendee.email;
+                            const status = attendee.responseStatus || 'needsAction';
+                            output += `  - ${name} (${status})\n`;
+                        }
+                    }
+                    // Description
+                    if (event.description) {
+                        const truncated = event.description.length > 200
+                            ? event.description.substring(0, 200) + '...'
+                            : event.description;
+                        output += `**Description:** ${truncated}\n`;
+                    }
+                    // Link
+                    if (event.htmlLink) {
+                        output += `**Link:** ${event.htmlLink}\n`;
+                    }
+                    output += '\n---\n\n';
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: output,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                logError('list-events-tool', error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error listing events: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/query-freebusy.d.ts

@@ -0,0 +1,61 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const QueryFreebusySchema: z.ZodObject<{
+    time_min: z.ZodString;
+    time_max: z.ZodString;
+    calendar_ids: z.ZodArray<z.ZodString, "many">;
+    timezone: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    time_min: string;
+    time_max: string;
+    calendar_ids: string[];
+    timezone?: string | undefined;
+}, {
+    time_min: string;
+    time_max: string;
+    calendar_ids: string[];
+    timezone?: string | undefined;
+}>;
+export declare function queryFreebusyTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            time_min: {
+                type: string;
+                description: string | undefined;
+            };
+            time_max: {
+                type: string;
+                description: string | undefined;
+            };
+            calendar_ids: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string | undefined;
+            };
+            timezone: {
+                type: string;
+                description: string | undefined;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};