MCP Server Boilerplate

Instructions

Implementation Reference

• src/calendar.ts:280-342 (handler)

  The primary handler function that executes the calendar event creation using Google Calendar API. It constructs the event object from parameters, inserts it into the specified calendar, formats the response as Markdown, and handles errors.

  export async function createEvent(
    params: z.infer<ReturnType<typeof createEventSchema>>
  ) {
    try {
      const auth = createCalendarAuth();
      const calendar = google.calendar({ version: "v3", auth });
  
      const event: any = {
        summary: params.summary,
        description: params.description,
        location: params.location,
        start: {
          dateTime: params.startDateTime,
          timeZone: params.timeZone,
        },
        end: {
          dateTime: params.endDateTime,
          timeZone: params.timeZone,
        },
      };
  
      if (params.attendees && params.attendees.length > 0) {
        event.attendees = params.attendees.map((email) => ({ email }));
      }
  
      const response = await calendar.events.insert({
        calendarId: params.calendarId,
        requestBody: event,
        sendUpdates: "all", // Send invitations to attendees
      });
  
      const eventData = {
        id: response.data.id,
        summary: response.data.summary,
        start: response.data.start,
        end: response.data.end,
        location: response.data.location,
        description: response.data.description,
        attendees: response.data.attendees,
        htmlLink: response.data.htmlLink,
      };
  
      return {
        content: [
          {
            type: "text" as const,
            text: `# Event Created Successfully ✅\n\n${formatEventToMarkdown(eventData)}`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error creating event: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  }

• src/calendar.ts:135-164 (schema)

  Zod schema defining the input parameters for creating a calendar event, including summary, dates, attendees, calendar ID, and time zone.

  export const createEventSchema = () =>
    z.object({
      summary: z.string().describe("Event title/summary"),
      description: z.string().optional().describe("Event description"),
      location: z.string().optional().describe("Event location"),
      startDateTime: z
        .string()
        .describe(
          "Start date/time in ISO format (e.g., '2025-01-15T09:00:00-07:00')"
        ),
      endDateTime: z
        .string()
        .describe(
          "End date/time in ISO format (e.g., '2025-01-15T10:00:00-07:00')"
        ),
      attendees: z
        .array(z.string())
        .optional()
        .describe("Array of attendee email addresses"),
      calendarId: z
        .string()
        .default("primary")
        .describe(getCalendarDescription()),
      timeZone: z
        .string()
        .optional()
        .describe(
          `Time zone - defaults to local time (${systemTimezone}). Examples: 'America/New_York', 'Europe/London', 'Asia/Tokyo'`
        ),
    });

• src/index.ts:216-222 (registration)

  Registers the 'calendar-create-event' tool with the MCP server, providing name, description, input schema from createEventSchema, and handler wrapper calling createEvent.

    "calendar-create-event",
    "Create a new calendar event. Current time: " + new Date().toLocaleString(),
    createEventSchema().shape,
    async (params) => {
      return await createEvent(params);
    }
  );

• src/calendar.ts:9-43 (helper)

  Helper function to format a single calendar event details into Markdown for the tool response.

  function formatEventToMarkdown(event: any): string {
    let markdown = `# ${event.summary || 'Untitled Event'}\n\n`;
    
    if (event.description) markdown += `${event.description}\n\n`;
    
    const startDate = event.start?.dateTime ? new Date(event.start.dateTime) : null;
    const endDate = event.end?.dateTime ? new Date(event.end.dateTime) : null;
    
    if (startDate) {
      markdown += `Start: ${startDate.toLocaleString()}  \n`;
    }
    if (endDate) {
      markdown += `End: ${endDate.toLocaleString()}  \n`;
    }
    
    if (event.location) markdown += `Location: ${event.location}  \n`;
    
    if (event.attendees && event.attendees.length > 0) {
      markdown += `Attendees: ${event.attendees.map((a: any) => {
        let attendee = a.email || a;
        if (a.responseStatus) {
          const status = a.responseStatus === 'accepted' ? '✅' : 
                       a.responseStatus === 'declined' ? '❌' : 
                       a.responseStatus === 'tentative' ? '❓' : '⏳';
          attendee += ` ${status}`;
        }
        return attendee;
      }).join(', ')}  \n`;
    }
    
    if (event.htmlLink) markdown += `Calendar Link: [View Event](${event.htmlLink})  \n`;
    if (event.id) markdown += `Event ID: \`${event.id}\`  \n`;
    
    return markdown;
  }

• src/calendar.ts:246-277 (helper)

  Helper function to create OAuth2 authentication client for Google Calendar API using environment variables.

  function createCalendarAuth() {
    const clientId = process.env.GOOGLE_CLIENT_ID;
    const clientSecret = process.env.GOOGLE_CLIENT_SECRET;
    const redirectUri =
      process.env.GOOGLE_REDIRECT_URI || "http://localhost:3000/oauth2callback";
  
    if (!clientId || !clientSecret) {
      throw new Error(
        "GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are required. Run oauth-setup.js to configure."
      );
    }
  
    const oauth2Client = new google.auth.OAuth2(
      clientId,
      clientSecret,
      redirectUri
    );
  
    const accessToken = process.env.GOOGLE_ACCESS_TOKEN;
    const refreshToken = process.env.GOOGLE_REFRESH_TOKEN;
  
    if (!accessToken || !refreshToken) {
      throw new Error("OAuth2 tokens missing. Run oauth-setup.js to get tokens.");
    }
  
    oauth2Client.setCredentials({
      access_token: accessToken,
      refresh_token: refreshToken,
    });
  
    return oauth2Client;
  }