google-calendar-workspace-mcp-server 0.0.1

package/shared/tools/query-freebusy.js

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { logError } from '../logging.js';
+export const QueryFreebusySchema = z.object({
+    time_min: z
+        .string()
+        .describe('Start time for the query in RFC3339 format (e.g., "2024-01-01T00:00:00Z").'),
+    time_max: z
+        .string()
+        .describe('End time for the query in RFC3339 format (e.g., "2024-01-01T23:59:59Z").'),
+    calendar_ids: z
+        .array(z.string())
+        .min(1)
+        .describe('List of calendar IDs to check availability for. Use "primary" for the user\'s primary calendar.'),
+    timezone: z
+        .string()
+        .optional()
+        .describe('Time zone for the query (e.g., "America/New_York"). Optional.'),
+});
+export function queryFreebusyTool(server, clientFactory) {
+    return {
+        name: 'gcal_query_freebusy',
+        description: 'Queries free/busy information for one or more calendars within a specified time range. ' +
+            'Returns time periods when calendars are busy (have events scheduled). ' +
+            'Useful for finding available meeting times, checking if someone is free, or scheduling around existing events.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                time_min: {
+                    type: 'string',
+                    description: QueryFreebusySchema.shape.time_min.description,
+                },
+                time_max: {
+                    type: 'string',
+                    description: QueryFreebusySchema.shape.time_max.description,
+                },
+                calendar_ids: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: QueryFreebusySchema.shape.calendar_ids.description,
+                },
+                timezone: {
+                    type: 'string',
+                    description: QueryFreebusySchema.shape.timezone.description,
+                },
+            },
+            required: ['time_min', 'time_max', 'calendar_ids'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = QueryFreebusySchema.parse(args);
+                const client = clientFactory();
+                const request = {
+                    timeMin: parsed.time_min,
+                    timeMax: parsed.time_max,
+                    items: parsed.calendar_ids.map((id) => ({ id })),
+                    timeZone: parsed.timezone,
+                };
+                const result = await client.queryFreebusy(request);
+                let output = `# Free/Busy Information\n\n`;
+                output += `**Time Range:** ${new Date(result.timeMin).toLocaleString()} to ${new Date(result.timeMax).toLocaleString()}\n\n`;
+                for (const calendarId of parsed.calendar_ids) {
+                    const calendarInfo = result.calendars[calendarId];
+                    output += `## Calendar: ${calendarId}\n\n`;
+                    if (calendarInfo.errors && calendarInfo.errors.length > 0) {
+                        output += `**Errors:**\n`;
+                        for (const error of calendarInfo.errors) {
+                            output += `- ${error.domain}: ${error.reason}\n`;
+                        }
+                        output += '\n';
+                        continue;
+                    }
+                    const busyPeriods = calendarInfo.busy || [];
+                    if (busyPeriods.length === 0) {
+                        output += `**Status:** Free for the entire time range\n\n`;
+                    }
+                    else {
+                        output += `**Busy Periods:** ${busyPeriods.length}\n\n`;
+                        for (const period of busyPeriods) {
+                            const start = new Date(period.start).toLocaleString();
+                            const end = new Date(period.end).toLocaleString();
+                            output += `- ${start} to ${end}\n`;
+                        }
+                        output += '\n';
+                    }
+                    output += '---\n\n';
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: output,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                logError('query-freebusy-tool', error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error querying free/busy: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools.d.ts

@@ -0,0 +1,3 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ClientFactory } from './server.js';
+export declare function createRegisterTools(clientFactory: ClientFactory): (server: Server) => void;

package/shared/tools.js

@@ -0,0 +1,41 @@
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { listEventsTool } from './tools/list-events.js';
+import { getEventTool } from './tools/get-event.js';
+import { createEventTool } from './tools/create-event.js';
+import { listCalendarsTool } from './tools/list-calendars.js';
+import { queryFreebusyTool } from './tools/query-freebusy.js';
+const ALL_TOOLS = [
+    listEventsTool,
+    getEventTool,
+    createEventTool,
+    listCalendarsTool,
+    queryFreebusyTool,
+];
+export function createRegisterTools(clientFactory) {
+    return (server) => {
+        const tools = ALL_TOOLS.map((factory) => factory(server, clientFactory));
+        server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: tools.map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+            })),
+        }));
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            const tool = tools.find((t) => t.name === name);
+            if (!tool) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Unknown tool: ${name}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return await tool.handler(args || {});
+        });
+    };
+}

package/shared/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Google Calendar API type definitions
+ */
+export interface CalendarEvent {
+    id: string;
+    status?: string;
+    htmlLink?: string;
+    created?: string;
+    updated?: string;
+    summary?: string;
+    description?: string;
+    location?: string;
+    start?: {
+        dateTime?: string;
+        date?: string;
+        timeZone?: string;
+    };
+    end?: {
+        dateTime?: string;
+        date?: string;
+        timeZone?: string;
+    };
+    attendees?: Array<{
+        email: string;
+        displayName?: string;
+        responseStatus?: string;
+        organizer?: boolean;
+        self?: boolean;
+    }>;
+    organizer?: {
+        email: string;
+        displayName?: string;
+        self?: boolean;
+    };
+    creator?: {
+        email: string;
+        displayName?: string;
+        self?: boolean;
+    };
+    recurrence?: string[];
+    recurringEventId?: string;
+    reminders?: {
+        useDefault: boolean;
+        overrides?: Array<{
+            method: string;
+            minutes: number;
+        }>;
+    };
+    transparency?: string;
+    visibility?: string;
+    colorId?: string;
+    iCalUID?: string;
+    sequence?: number;
+}
+export interface CalendarEventList {
+    kind: string;
+    etag: string;
+    summary: string;
+    updated: string;
+    timeZone: string;
+    accessRole: string;
+    items?: CalendarEvent[];
+    nextPageToken?: string;
+    nextSyncToken?: string;
+}
+export interface Calendar {
+    kind: string;
+    etag: string;
+    id: string;
+    summary: string;
+    description?: string;
+    location?: string;
+    timeZone: string;
+    selected?: boolean;
+    accessRole: string;
+    primary?: boolean;
+    backgroundColor?: string;
+    foregroundColor?: string;
+}
+export interface CalendarList {
+    kind: string;
+    etag: string;
+    items: Calendar[];
+    nextPageToken?: string;
+    nextSyncToken?: string;
+}
+export interface FreeBusyRequest {
+    timeMin: string;
+    timeMax: string;
+    items: Array<{
+        id: string;
+    }>;
+    timeZone?: string;
+}
+export interface FreeBusyResponse {
+    kind: string;
+    timeMin: string;
+    timeMax: string;
+    calendars: {
+        [calendarId: string]: {
+            busy: Array<{
+                start: string;
+                end: string;
+            }>;
+            errors?: Array<{
+                domain: string;
+                reason: string;
+            }>;
+        };
+    };
+}

package/shared/types.js

@@ -0,0 +1,4 @@
+/**
+ * Google Calendar API type definitions
+ */
+export {};