Google MCP

Instructions

Implementation Reference

• handlers/gmail.ts:50-63 (handler)

  The main handler function for the google_gmail_get_email tool. Validates input using isGetEmailArgs and delegates to GoogleGmail.getEmail method.

  export async function handleGmailGetEmail(
    args: any,
    googleGmailInstance: GoogleGmail
  ) {
    if (!isGetEmailArgs(args)) {
      throw new Error("Invalid arguments for google_gmail_get_email");
    }
    const { messageId, format } = args;
    const result = await googleGmailInstance.getEmail(messageId, format);
    return {
      content: [{ type: "text", text: result }],
      isError: false,
    };
  }

• server-setup.ts:144-148 (registration)

  Registration in the MCP server: switch case that dispatches tool calls to the appropriate handler function.

  case "google_gmail_get_email":
    return await gmailHandlers.handleGmailGetEmail(
      args,
      googleGmailInstance
    );

• tools/gmail/index.ts:35-53 (schema)

  MCP Tool schema definition with input schema specifying required messageId and optional format.

  export const GET_EMAIL_TOOL: Tool = {
    name: "google_gmail_get_email",
    description: "Get detailed information about a specific email",
    inputSchema: {
      type: "object",
      properties: {
        messageId: {
          type: "string",
          description: "ID of the email to retrieve",
        },
        format: {
          type: "string",
          description:
            "Format to return the email in (full, metadata, minimal, raw)",
        },
      },
      required: ["messageId"],
    },
  };

• utils/helper.ts:139-148 (helper)

  Type guard/helper function that validates the tool arguments against the expected schema.

  export function isGetEmailArgs(args: any): args is {
    messageId: string;
    format?: string;
  } {
    return (
      args &&
      typeof args.messageId === "string" &&
      (args.format === undefined || typeof args.format === "string")
    );
  }

• utils/gmail.ts:125-193 (helper)

  Core helper method in GoogleGmail class that implements the Gmail API call to retrieve email details, parse headers, body, attachments, and format the response text.

  async getEmail(messageId: string, format: string = "full") {
    try {
      const response = await this.gmail.users.messages.get({
        userId: "me",
        id: messageId,
        format: format,
      });
  
      const { payload, snippet, labelIds } = response.data;
      const headers = payload.headers;
  
      // Extract common headers
      const subject =
        headers.find((h: any) => h.name === "Subject")?.value || "(No subject)";
      const from = headers.find((h: any) => h.name === "From")?.value || "";
      const to = headers.find((h: any) => h.name === "To")?.value || "";
      const date = headers.find((h: any) => h.name === "Date")?.value || "";
  
      // Extract message body
      let body = "";
      if (payload.parts) {
        // Multipart message
        for (const part of payload.parts) {
          if (part.mimeType === "text/plain" && part.body.data) {
            body = Buffer.from(part.body.data, "base64").toString();
            break;
          } else if (part.mimeType === "text/html" && part.body.data) {
            body = Buffer.from(part.body.data, "base64").toString();
          }
        }
      } else if (payload.body && payload.body.data) {
        // Simple message
        body = Buffer.from(payload.body.data, "base64").toString();
      }
  
      // Get attachment information
      const attachments = await this.getEmailAttachments(messageId);
  
      // Format the result
      let result = `Subject: ${subject}\n`;
      result += `From: ${from}\n`;
      result += `To: ${to}\n`;
      result += `Date: ${date}\n`;
      result += `Labels: ${labelIds.join(", ")}\n\n`;
      result += `Snippet: ${snippet}\n\n`;
  
      if (attachments.length > 0) {
        result += `Attachments (${attachments.length}):\n`;
        attachments.forEach((att, index) => {
          result += `  ${index + 1}. ${att.filename} (${
            att.mimeType
          }, ${FileUtils.formatFileSize(att.size)})\n`;
        });
        result += `\nUse google_gmail_download_attachments to download all attachments.\n\n`;
      }
  
      result += `Body: \n${body.substring(0, 1500)}${
        body.length > 1500 ? "... (truncated)" : ""
      }`;
  
      return result;
    } catch (error) {
      throw new Error(
        `Failed to get email: ${
          error instanceof Error ? error.message : String(error)
        }`
      );
    }
  }