search_emails

Instructions

Implementation Reference

• src/index.ts:373-448 (handler)

  The handler function that implements the 'search_emails' tool. It uses the Gmail API to search for emails using the provided query, fetches details for each matching message including subject, sender, date, body (extracted from plain text parts), and labels, then returns the results as a JSON string in the MCP response format.

  private async handleSearchEmails(args: any) {
    try {
      const maxResults = args?.maxResults || 10;
      const query = args?.query || "";
  
      const getEmailBody = (payload: any): string => {
        if (!payload) return "";
  
        if (payload.body && payload.body.data) {
          return Buffer.from(payload.body.data, "base64").toString("utf-8");
        }
  
        if (payload.parts && payload.parts.length > 0) {
          for (const part of payload.parts) {
            if (part.mimeType === "text/plain") {
              return Buffer.from(part.body.data, "base64").toString("utf-8");
            }
          }
        }
  
        return "(No body content)";
      };
  
      const response = await this.gmail.users.messages.list({
        userId: "me",
        maxResults,
        q: query,
      });
  
      const messages = response.data.messages || [];
      const emailDetails = await Promise.all(
        messages.map(async (msg) => {
          const detail = await this.gmail.users.messages.get({
            userId: "me",
            id: msg.id!,
          });
  
          const headers = detail.data.payload?.headers;
          const subject =
            headers?.find((h) => h.name === "Subject")?.value || "";
          const from = headers?.find((h) => h.name === "From")?.value || "";
          const date = headers?.find((h) => h.name === "Date")?.value || "";
          const body = getEmailBody(detail.data.payload);
          // Use helper function to extract the email body correctly
  
          return {
            id: msg.id,
            subject,
            from,
            date,
            body,
            labels: detail.data.labelIds || [],
          };
        })
      );
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(emailDetails, null, 2),
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text",
            text: `Error fetching emails: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:83-103 (schema)

  The input schema for the 'search_emails' tool, defining the expected arguments: a required 'query' string for Gmail search and optional 'maxResults' number.

  inputSchema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description:
          'Gmail search query (e.g., "from:example@gmail.com has:attachment"). Examples:\n' +
          '- "from:alice@example.com" (Emails from Alice)\n' +
          '- "to:bob@example.com" (Emails sent to Bob)\n' +
          '- "subject:Meeting Update" (Emails with "Meeting Update" in the subject)\n' +
          '- "has:attachment filename:pdf" (Emails with PDF attachments)\n' +
          '- "after:2024/01/01 before:2024/02/01" (Emails between specific dates)\n' +
          '- "is:unread" (Unread emails)\n' +
          '- "from:@company.com has:attachment" (Emails from a company domain with attachments)',
      },
      maxResults: {
        type: "number",
        description: "Maximum number of emails to return (default: 10)",
      },
    },
    required: ["query"],

• src/index.ts:80-105 (registration)

  Registration of the 'search_emails' tool in the MCP ListToolsRequestSchema handler, including name, description, and input schema.

  {
    name: "search_emails",
    description: "Search emails with advanced query",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description:
            'Gmail search query (e.g., "from:example@gmail.com has:attachment"). Examples:\n' +
            '- "from:alice@example.com" (Emails from Alice)\n' +
            '- "to:bob@example.com" (Emails sent to Bob)\n' +
            '- "subject:Meeting Update" (Emails with "Meeting Update" in the subject)\n' +
            '- "has:attachment filename:pdf" (Emails with PDF attachments)\n' +
            '- "after:2024/01/01 before:2024/02/01" (Emails between specific dates)\n' +
            '- "is:unread" (Unread emails)\n' +
            '- "from:@company.com has:attachment" (Emails from a company domain with attachments)',
        },
        maxResults: {
          type: "number",
          description: "Maximum number of emails to return (default: 10)",
        },
      },
      required: ["query"],
    },
  },

• src/index.ts:276-277 (registration)

  Dispatch case in the CallToolRequestSchema handler that routes 'search_emails' tool calls to the handleSearchEmails method.

  case "search_emails":
    return await this.handleSearchEmails(request.params.arguments);