google-calendar-workspace-mcp-server 0.0.1

package/shared/calendar-client/lib/query-freebusy.js

@@ -0,0 +1,13 @@
+import { handleApiError } from './api-errors.js';
+export async function queryFreebusy(baseUrl, headers, request) {
+    const url = `${baseUrl}/freeBusy`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(request),
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'querying freebusy information');
+    }
+    return (await response.json());
+}

package/shared/index.d.ts

@@ -0,0 +1,2 @@
+export { createMCPServer, type ICalendarClient } from './server.js';
+export * from './types.js';

package/shared/index.js

@@ -0,0 +1,2 @@
+export { createMCPServer } from './server.js';
+export * from './types.js';

package/shared/logging.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Centralized logging utilities
+ * IMPORTANT: All logging uses console.error() to write to stderr.
+ * The MCP protocol requires stdout to contain only JSON messages.
+ */
+export declare function logServerStart(serverName: string, transport?: string): void;
+export declare function logError(context: string, error: unknown): void;
+export declare function logWarning(context: string, message: string): void;
+export declare function logDebug(context: string, message: string): void;
+export declare function logInfo(context: string, message: string): void;

package/shared/logging.js

@@ -0,0 +1,23 @@
+/**
+ * Centralized logging utilities
+ * IMPORTANT: All logging uses console.error() to write to stderr.
+ * The MCP protocol requires stdout to contain only JSON messages.
+ */
+export function logServerStart(serverName, transport = 'stdio') {
+    console.error(`MCP server ${serverName} running on ${transport}`);
+}
+export function logError(context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[ERROR] ${context}: ${message}`);
+}
+export function logWarning(context, message) {
+    console.error(`[WARN] ${context}: ${message}`);
+}
+export function logDebug(context, message) {
+    if (process.env.NODE_ENV === 'development' || process.env.DEBUG) {
+        console.error(`[DEBUG] ${context}: ${message}`);
+    }
+}
+export function logInfo(context, message) {
+    console.error(`[INFO] ${context}: ${message}`);
+}

package/shared/server.d.ts

@@ -0,0 +1,130 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { CalendarEvent, CalendarEventList, CalendarList, FreeBusyRequest, FreeBusyResponse } from './types.js';
+/**
+ * Google Calendar API client interface
+ * Defines all methods for interacting with the Google Calendar API
+ */
+export interface ICalendarClient {
+    /**
+     * List events from a calendar
+     */
+    listEvents(calendarId: string, options?: {
+        timeMin?: string;
+        timeMax?: string;
+        maxResults?: number;
+        pageToken?: string;
+        q?: string;
+        singleEvents?: boolean;
+        orderBy?: string;
+    }): Promise<CalendarEventList>;
+    /**
+     * Get a specific event by ID
+     */
+    getEvent(calendarId: string, eventId: string): Promise<CalendarEvent>;
+    /**
+     * Create a new event
+     */
+    createEvent(calendarId: string, event: Partial<CalendarEvent>): Promise<CalendarEvent>;
+    /**
+     * List calendars available to the user
+     */
+    listCalendars(options?: {
+        maxResults?: number;
+        pageToken?: string;
+    }): Promise<CalendarList>;
+    /**
+     * Query free/busy information
+     */
+    queryFreebusy(request: FreeBusyRequest): Promise<FreeBusyResponse>;
+}
+/**
+ * Service account credentials structure
+ */
+export interface ServiceAccountCredentials {
+    type: string;
+    project_id: string;
+    private_key_id: string;
+    private_key: string;
+    client_email: string;
+    client_id: string;
+    auth_uri: string;
+    token_uri: string;
+    auth_provider_x509_cert_url: string;
+    client_x509_cert_url: string;
+}
+/**
+ * Google Calendar API client implementation using service account with domain-wide delegation
+ */
+export declare class ServiceAccountCalendarClient implements ICalendarClient {
+    private impersonateEmail;
+    private baseUrl;
+    private jwtClient;
+    private cachedToken;
+    private tokenExpiry;
+    private refreshPromise;
+    constructor(credentials: ServiceAccountCredentials, impersonateEmail: string);
+    private refreshToken;
+    private getHeaders;
+    listEvents(calendarId: string, options?: {
+        timeMin?: string;
+        timeMax?: string;
+        maxResults?: number;
+        pageToken?: string;
+        q?: string;
+        singleEvents?: boolean;
+        orderBy?: string;
+    }): Promise<CalendarEventList>;
+    getEvent(calendarId: string, eventId: string): Promise<CalendarEvent>;
+    createEvent(calendarId: string, event: Partial<CalendarEvent>): Promise<CalendarEvent>;
+    listCalendars(options?: {
+        maxResults?: number;
+        pageToken?: string;
+    }): Promise<CalendarList>;
+    queryFreebusy(request: FreeBusyRequest): Promise<FreeBusyResponse>;
+}
+export type ClientFactory = () => ICalendarClient;
+/**
+ * Creates the default Google Calendar client based on environment variables.
+ * Uses service account with domain-wide delegation:
+ *   - GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL: Service account email address
+ *   - GCAL_SERVICE_ACCOUNT_PRIVATE_KEY: Service account private key (PEM format)
+ *   - GCAL_IMPERSONATE_EMAIL: Email address to impersonate
+ */
+export declare function createDefaultClient(): ICalendarClient;
+export declare function createMCPServer(): {
+    server: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    registerHandlers: (server: Server, clientFactory?: ClientFactory) => Promise<void>;
+};

package/shared/server.js

@@ -0,0 +1,132 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { JWT } from 'google-auth-library';
+import { createRegisterTools } from './tools.js';
+/**
+ * Google Calendar API client implementation using service account with domain-wide delegation
+ */
+export class ServiceAccountCalendarClient {
+    impersonateEmail;
+    baseUrl = 'https://www.googleapis.com/calendar/v3';
+    jwtClient;
+    cachedToken = null;
+    tokenExpiry = 0;
+    refreshPromise = null;
+    constructor(credentials, impersonateEmail) {
+        this.impersonateEmail = impersonateEmail;
+        this.jwtClient = new JWT({
+            email: credentials.client_email,
+            key: credentials.private_key,
+            scopes: ['https://www.googleapis.com/auth/calendar'],
+            subject: impersonateEmail,
+        });
+    }
+    async refreshToken() {
+        const tokenResponse = await this.jwtClient.authorize();
+        if (!tokenResponse.access_token) {
+            throw new Error('Failed to obtain access token from service account');
+        }
+        this.cachedToken = tokenResponse.access_token;
+        // Token typically expires in 1 hour, but use the actual expiry if provided
+        this.tokenExpiry = tokenResponse.expiry_date || Date.now() + 3600000;
+    }
+    async getHeaders() {
+        // Check if we have a valid cached token (with 60 second buffer)
+        if (this.cachedToken && Date.now() < this.tokenExpiry - 60000) {
+            return {
+                Authorization: `Bearer ${this.cachedToken}`,
+                'Content-Type': 'application/json',
+            };
+        }
+        // Use mutex pattern to prevent concurrent token refresh
+        if (!this.refreshPromise) {
+            this.refreshPromise = this.refreshToken().finally(() => {
+                this.refreshPromise = null;
+            });
+        }
+        await this.refreshPromise;
+        return {
+            Authorization: `Bearer ${this.cachedToken}`,
+            'Content-Type': 'application/json',
+        };
+    }
+    async listEvents(calendarId, options) {
+        const headers = await this.getHeaders();
+        const { listEvents } = await import('./calendar-client/lib/list-events.js');
+        return listEvents(this.baseUrl, headers, calendarId, options);
+    }
+    async getEvent(calendarId, eventId) {
+        const headers = await this.getHeaders();
+        const { getEvent } = await import('./calendar-client/lib/get-event.js');
+        return getEvent(this.baseUrl, headers, calendarId, eventId);
+    }
+    async createEvent(calendarId, event) {
+        const headers = await this.getHeaders();
+        const { createEvent } = await import('./calendar-client/lib/create-event.js');
+        return createEvent(this.baseUrl, headers, calendarId, event);
+    }
+    async listCalendars(options) {
+        const headers = await this.getHeaders();
+        const { listCalendars } = await import('./calendar-client/lib/list-calendars.js');
+        return listCalendars(this.baseUrl, headers, options);
+    }
+    async queryFreebusy(request) {
+        const headers = await this.getHeaders();
+        const { queryFreebusy } = await import('./calendar-client/lib/query-freebusy.js');
+        return queryFreebusy(this.baseUrl, headers, request);
+    }
+}
+/**
+ * Creates the default Google Calendar client based on environment variables.
+ * Uses service account with domain-wide delegation:
+ *   - GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL: Service account email address
+ *   - GCAL_SERVICE_ACCOUNT_PRIVATE_KEY: Service account private key (PEM format)
+ *   - GCAL_IMPERSONATE_EMAIL: Email address to impersonate
+ */
+export function createDefaultClient() {
+    const clientEmail = process.env.GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL;
+    // Handle both literal \n in JSON configs and actual newlines
+    const privateKey = process.env.GCAL_SERVICE_ACCOUNT_PRIVATE_KEY?.replace(/\\n/g, '\n');
+    const impersonateEmail = process.env.GCAL_IMPERSONATE_EMAIL;
+    if (!clientEmail) {
+        throw new Error('GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL environment variable must be set. ' +
+            'This is the email address from your Google Cloud service account.');
+    }
+    if (!privateKey) {
+        throw new Error('GCAL_SERVICE_ACCOUNT_PRIVATE_KEY environment variable must be set. ' +
+            'This is the private key from your Google Cloud service account (PEM format).');
+    }
+    if (!impersonateEmail) {
+        throw new Error('GCAL_IMPERSONATE_EMAIL environment variable must be set. ' +
+            'This is the email address of the user to access Google Calendar as.');
+    }
+    const credentials = {
+        type: 'service_account',
+        project_id: '',
+        private_key_id: '',
+        private_key: privateKey,
+        client_email: clientEmail,
+        client_id: '',
+        auth_uri: 'https://accounts.google.com/o/oauth2/auth',
+        token_uri: 'https://oauth2.googleapis.com/token',
+        auth_provider_x509_cert_url: 'https://www.googleapis.com/oauth2/v1/certs',
+        client_x509_cert_url: '',
+    };
+    return new ServiceAccountCalendarClient(credentials, impersonateEmail);
+}
+export function createMCPServer() {
+    const server = new Server({
+        name: 'google-calendar-workspace-mcp-server',
+        version: '0.0.1',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    const registerHandlers = async (server, clientFactory) => {
+        // Use provided factory or create default client
+        const factory = clientFactory || createDefaultClient;
+        const registerTools = createRegisterTools(factory);
+        registerTools(server);
+    };
+    return { server, registerHandlers };
+}

package/shared/tools/create-event.d.ts

@@ -0,0 +1,110 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const CreateEventSchema: z.ZodObject<{
+    calendar_id: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    summary: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    location: z.ZodOptional<z.ZodString>;
+    start_datetime: z.ZodOptional<z.ZodString>;
+    start_date: z.ZodOptional<z.ZodString>;
+    start_timezone: z.ZodOptional<z.ZodString>;
+    end_datetime: z.ZodOptional<z.ZodString>;
+    end_date: z.ZodOptional<z.ZodString>;
+    end_timezone: z.ZodOptional<z.ZodString>;
+    attendees: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    calendar_id: string;
+    summary: string;
+    description?: string | undefined;
+    location?: string | undefined;
+    start_datetime?: string | undefined;
+    start_date?: string | undefined;
+    start_timezone?: string | undefined;
+    end_datetime?: string | undefined;
+    end_date?: string | undefined;
+    end_timezone?: string | undefined;
+    attendees?: string[] | undefined;
+}, {
+    summary: string;
+    calendar_id?: string | undefined;
+    description?: string | undefined;
+    location?: string | undefined;
+    start_datetime?: string | undefined;
+    start_date?: string | undefined;
+    start_timezone?: string | undefined;
+    end_datetime?: string | undefined;
+    end_date?: string | undefined;
+    end_timezone?: string | undefined;
+    attendees?: string[] | undefined;
+}>;
+export declare function createEventTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            calendar_id: {
+                type: string;
+                description: string | undefined;
+            };
+            summary: {
+                type: string;
+                description: string | undefined;
+            };
+            description: {
+                type: string;
+                description: string | undefined;
+            };
+            location: {
+                type: string;
+                description: string | undefined;
+            };
+            start_datetime: {
+                type: string;
+                description: string | undefined;
+            };
+            start_date: {
+                type: string;
+                description: string | undefined;
+            };
+            start_timezone: {
+                type: string;
+                description: string | undefined;
+            };
+            end_datetime: {
+                type: string;
+                description: string | undefined;
+            };
+            end_date: {
+                type: string;
+                description: string | undefined;
+            };
+            end_timezone: {
+                type: string;
+                description: string | undefined;
+            };
+            attendees: {
+                type: string;
+                items: {
+                    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;
+    }>;
+};

package/shared/tools/create-event.js

@@ -0,0 +1,195 @@
+import { z } from 'zod';
+import { logError } from '../logging.js';
+export const CreateEventSchema = z.object({
+    calendar_id: z
+        .string()
+        .optional()
+        .default('primary')
+        .describe('Calendar ID to create the event in. Defaults to "primary".'),
+    summary: z.string().min(1).describe('Event title/summary.'),
+    description: z.string().optional().describe('Event description.'),
+    location: z.string().optional().describe('Event location.'),
+    start_datetime: z
+        .string()
+        .optional()
+        .describe('Start date-time in RFC3339 format (e.g., "2024-01-01T10:00:00-05:00"). Use this for timed events.'),
+    start_date: z
+        .string()
+        .optional()
+        .describe('Start date for all-day events (e.g., "2024-01-01"). Use this for all-day events.'),
+    start_timezone: z
+        .string()
+        .optional()
+        .describe('Time zone for start time (e.g., "America/New_York"). Optional.'),
+    end_datetime: z
+        .string()
+        .optional()
+        .describe('End date-time in RFC3339 format (e.g., "2024-01-01T11:00:00-05:00"). Use this for timed events.'),
+    end_date: z
+        .string()
+        .optional()
+        .describe('End date for all-day events (e.g., "2024-01-02"). Use this for all-day events.'),
+    end_timezone: z
+        .string()
+        .optional()
+        .describe('Time zone for end time (e.g., "America/New_York"). Optional.'),
+    attendees: z.array(z.string()).optional().describe('List of attendee email addresses.'),
+});
+export function createEventTool(server, clientFactory) {
+    return {
+        name: 'gcal_create_event',
+        description: 'Creates a new event in Google Calendar. ' +
+            'Supports both timed events (using start_datetime/end_datetime) and all-day events (using start_date/end_date). ' +
+            'Can include title, description, location, and attendees. ' +
+            'Returns the created event details including the event ID and link.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                calendar_id: {
+                    type: 'string',
+                    description: CreateEventSchema.shape.calendar_id.description,
+                },
+                summary: {
+                    type: 'string',
+                    description: CreateEventSchema.shape.summary.description,
+                },
+                description: {
+                    type: 'string',
+                    description: CreateEventSchema.shape.description.description,
+                },
+                location: {
+                    type: 'string',
+                    description: CreateEventSchema.shape.location.description,
+                },
+                start_datetime: {
+                    type: 'string',
+                    description: CreateEventSchema.shape.start_datetime.description,
+                },
+                start_date: {
+                    type: 'string',
+                    description: CreateEventSchema.shape.start_date.description,
+                },
+                start_timezone: {
+                    type: 'string',
+                    description: CreateEventSchema.shape.start_timezone.description,
+                },
+                end_datetime: {
+                    type: 'string',
+                    description: CreateEventSchema.shape.end_datetime.description,
+                },
+                end_date: {
+                    type: 'string',
+                    description: CreateEventSchema.shape.end_date.description,
+                },
+                end_timezone: {
+                    type: 'string',
+                    description: CreateEventSchema.shape.end_timezone.description,
+                },
+                attendees: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: CreateEventSchema.shape.attendees.description,
+                },
+            },
+            required: ['summary'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = CreateEventSchema.parse(args);
+                const client = clientFactory();
+                // Validate that we have either datetime or date fields
+                if (!parsed.start_datetime && !parsed.start_date) {
+                    throw new Error('Must provide either start_datetime or start_date');
+                }
+                if (!parsed.end_datetime && !parsed.end_date) {
+                    throw new Error('Must provide either end_datetime or end_date');
+                }
+                // Build event object
+                const event = {
+                    summary: parsed.summary,
+                    description: parsed.description,
+                    location: parsed.location,
+                    start: {},
+                    end: {},
+                };
+                // Set start time
+                if (parsed.start_datetime) {
+                    event.start.dateTime = parsed.start_datetime;
+                    if (parsed.start_timezone) {
+                        event.start.timeZone = parsed.start_timezone;
+                    }
+                }
+                else if (parsed.start_date) {
+                    event.start.date = parsed.start_date;
+                }
+                // Set end time
+                if (parsed.end_datetime) {
+                    event.end.dateTime = parsed.end_datetime;
+                    if (parsed.end_timezone) {
+                        event.end.timeZone = parsed.end_timezone;
+                    }
+                }
+                else if (parsed.end_date) {
+                    event.end.date = parsed.end_date;
+                }
+                // Add attendees
+                if (parsed.attendees && parsed.attendees.length > 0) {
+                    event.attendees = parsed.attendees.map((email) => ({ email }));
+                }
+                const result = await client.createEvent(parsed.calendar_id, event);
+                let output = `# Event Created Successfully\n\n`;
+                output += `## ${result.summary || '(No title)'}\n\n`;
+                output += `**Event ID:** ${result.id}\n`;
+                // Start time
+                if (result.start?.dateTime) {
+                    output += `**Start:** ${new Date(result.start.dateTime).toLocaleString()}\n`;
+                }
+                else if (result.start?.date) {
+                    output += `**Start:** ${result.start.date} (All day)\n`;
+                }
+                // End time
+                if (result.end?.dateTime) {
+                    output += `**End:** ${new Date(result.end.dateTime).toLocaleString()}\n`;
+                }
+                else if (result.end?.date) {
+                    output += `**End:** ${result.end.date} (All day)\n`;
+                }
+                // Location
+                if (result.location) {
+                    output += `**Location:** ${result.location}\n`;
+                }
+                // Attendees
+                if (result.attendees && result.attendees.length > 0) {
+                    output += `**Attendees:** ${result.attendees.length}\n`;
+                    for (const attendee of result.attendees) {
+                        output += `  - ${attendee.email}\n`;
+                    }
+                }
+                // Link
+                if (result.htmlLink) {
+                    output += `\n**Event Link:** ${result.htmlLink}\n`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: output,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                logError('create-event-tool', error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error creating event: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/get-event.d.ts

@@ -0,0 +1,44 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const GetEventSchema: z.ZodObject<{
+    calendar_id: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    event_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    calendar_id: string;
+    event_id: string;
+}, {
+    event_id: string;
+    calendar_id?: string | undefined;
+}>;
+export declare function getEventTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            calendar_id: {
+                type: string;
+                description: string | undefined;
+            };
+            event_id: {
+                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;
+    }>;
+};