calendar-list-events

Instructions

Implementation Reference

• src/calendar.ts:345-406 (handler)

  The handler function for listing calendar events. Queries Google Calendar API with provided filters, maps the response, formats as markdown, and returns in MCP format.

  export async function listEvents(
    params: z.infer<ReturnType<typeof listEventsSchema>>
  ) {
    try {
      const auth = createCalendarAuth();
      const calendar = google.calendar({ version: "v3", auth });
  
      const listParams: any = {
        calendarId: params.calendarId,
        maxResults: params.maxResults,
        singleEvents: params.singleEvents,
        orderBy: params.orderBy,
      };
  
      if (params.timeMin) listParams.timeMin = params.timeMin;
      if (params.timeMax) listParams.timeMax = params.timeMax;
  
      // If no timeMin is specified, default to current time
      if (!params.timeMin) {
        listParams.timeMin = new Date().toISOString();
      }
  
      const response = await calendar.events.list(listParams);
  
      const events = response.data.items?.map((event) => ({
        id: event.id,
        summary: event.summary,
        description: event.description,
        location: event.location,
        start: event.start,
        end: event.end,
        attendees: event.attendees?.map((a) => ({
          email: a.email,
          responseStatus: a.responseStatus,
        })),
        htmlLink: event.htmlLink,
        status: event.status,
        created: event.created,
        updated: event.updated,
      }));
  
      return {
        content: [
          {
            type: "text" as const,
            text: formatEventListToMarkdown(events || [], events?.length || 0),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error listing events: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  }

• src/calendar.ts:166-194 (schema)

  Zod schema defining the input parameters for the listEvents tool, including calendarId, time filters, maxResults, etc.

  export const listEventsSchema = () =>
    z.object({
      calendarId: z
        .string()
        .default("primary")
        .describe(getCalendarDescription()),
      timeMin: z
        .string()
        .optional()
        .describe("Lower bound for event start time (ISO format)"),
      timeMax: z
        .string()
        .optional()
        .describe("Upper bound for event start time (ISO format)"),
      maxResults: z
        .number()
        .min(1)
        .max(250)
        .default(10)
        .describe("Maximum number of events to return"),
      singleEvents: z
        .boolean()
        .default(true)
        .describe("Whether to expand recurring events"),
      orderBy: z
        .enum(["startTime", "updated"])
        .default("startTime")
        .describe("Order of events"),
    });

• src/index.ts:224-231 (registration)

  Registers the 'calendar-list-events' tool with the MCP server, using listEventsSchema and listEvents handler.

  server.tool(
    "calendar-list-events",
    "List calendar events with optional filters",
    listEventsSchema().shape,
    async (params) => {
      return await listEvents(params);
    }
  );

• src/calendar.ts:45-77 (helper)

  Helper function to format the list of events into a readable markdown list, used by the listEvents handler.

  function formatEventListToMarkdown(events: any[], totalResults: number): string {
    if (!events.length) return "# No Upcoming Events\n\nNo events found in the specified time range.";
    
    let markdown = `# Upcoming Events (${totalResults})\n\n`;
    
    events.forEach((event, index) => {
      const startDate = event.start?.dateTime ? new Date(event.start.dateTime) : null;
      const endDate = event.end?.dateTime ? new Date(event.end.dateTime) : null;
      
      markdown += `## ${index + 1}. ${event.summary || 'Untitled Event'}\n`;
      
      if (startDate) {
        if (endDate && startDate.toDateString() === endDate.toDateString()) {
          // Same day event
          markdown += `When: ${startDate.toLocaleDateString()} ${startDate.toLocaleTimeString()} - ${endDate.toLocaleTimeString()}  \n`;
        } else {
          markdown += `Start: ${startDate.toLocaleString()}  \n`;
          if (endDate) markdown += `End: ${endDate.toLocaleString()}  \n`;
        }
      }
      
      if (event.location) markdown += `Location: ${event.location}  \n`;
      if (event.description) markdown += `Description: ${event.description}  \n`;
      if (event.attendees && event.attendees.length > 0) {
        markdown += `Attendees: ${event.attendees.length} people  \n`;
      }
      if (event.id) markdown += `ID: \`${event.id}\`  \n`;
      
      markdown += `\n---\n\n`;
    });
    
    return markdown;
  }