MCP Server Boilerplate

Instructions

Implementation Reference

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

  The handler function `listEvents` that executes the tool logic: authenticates to Google Calendar API, lists events with filters, formats output as markdown, handles errors.

  // List events function
  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 input parameters and descriptions for the calendar-list-events tool.

  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)

  MCP server registration of the 'calendar-list-events' tool, linking name, description, schema, and 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 output used by the 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;
  }