MCP Server Boilerplate

Instructions

Implementation Reference

• src/gmail.ts:293-365 (handler)

  Main handler function 'getEmail' that retrieves a specific Gmail message by ID using the Gmail API v1, extracts headers and body (handling multipart), truncates long body, formats to Markdown using helper, and returns structured content or error.

  export async function getEmail(params: z.infer<typeof getEmailSchema>) {
    try {
      const auth = createGmailAuth();
      const gmail = google.gmail({ version: "v1", auth });
  
      const response = await gmail.users.messages.get({
        userId: "me",
        id: params.messageId,
        format: "full",
      });
  
      const message = response.data;
      const headers = message.payload?.headers || [];
      const getHeader = (name: string) =>
        headers.find((h) => h.name?.toLowerCase() === name.toLowerCase())
          ?.value || "";
  
      // Extract body content
      let body = "";
      if (message.payload?.body?.data) {
        body = Buffer.from(message.payload.body.data, "base64").toString();
      } else if (message.payload?.parts) {
        // Handle multipart messages
        for (const part of message.payload.parts) {
          if (part.mimeType === "text/plain" && part.body?.data) {
            body = Buffer.from(part.body.data, "base64").toString();
            break;
          }
        }
      }
  
      // Truncate body if it exceeds 30000 characters
      const truncatedBody =
        body.length > 20000
          ? body.substring(0, 20000) +
            "\n\n[Email body truncated - content too long]"
          : body;
  
      const emailDetail = {
        id: message.id,
        threadId: message.threadId,
        from: getHeader("From"),
        to: getHeader("To"),
        cc: getHeader("Cc"),
        bcc: getHeader("Bcc"),
        subject: getHeader("Subject"),
        date: getHeader("Date"),
        body: truncatedBody,
        snippet: message.snippet,
        labelIds: message.labelIds,
      };
  
      return {
        content: [
          {
            type: "text" as const,
            text: formatEmailToMarkdown(emailDetail),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error getting email: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  }

• src/gmail.ts:32-34 (schema)

  Zod input schema for the tool, requiring a single 'messageId' string parameter.

  export const getEmailSchema = z.object({
    messageId: z.string().describe("Gmail message ID"),
  });

• src/index.ts:200-207 (registration)

  MCP server tool registration for 'gmail-get-email', specifying name, description, input schema from getEmailSchema, and handler calling getEmail.

  server.tool(
    "gmail-get-email",
    "Get a specific email by message ID",
    getEmailSchema.shape,
    async (params) => {
      return await getEmail(params);
    }
  );

• src/gmail.ts:75-94 (helper)

  Helper function to format the retrieved email details into a readable Markdown structure, used in the handler's response.

  function formatEmailToMarkdown(email: any): string {
    const date = new Date(email.date).toLocaleDateString();
    const from = email.from.replace(/[<>]/g, '');
    const to = email.to.replace(/[<>]/g, '');
    const subject = email.subject || '(No Subject)';
    
    let markdown = `# ${subject}\n\n`;
    markdown += `From: ${from}  \n`;
    markdown += `To: ${to}  \n`;
    if (email.cc) markdown += `CC: ${email.cc.replace(/[<>]/g, '')}  \n`;
    if (email.bcc) markdown += `BCC: ${email.bcc.replace(/[<>]/g, '')}  \n`;
    markdown += `Date: ${date}  \n`;
    markdown += `Message ID: \`${email.id}\`\n\n`;
    
    if (email.body) {
      markdown += `---\n\n${email.body}\n`;
    }
    
    return markdown;
  }

• src/gmail.ts:133-165 (helper)

  Shared authentication helper function that creates OAuth2 client for Gmail API using environment variables for credentials and tokens.

  // OAuth2 Authentication helper
  function createGmailAuth() {
    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;
  }