JMAP MCP Server

Implementation Reference

• index.js:105-226 (handler)

  The handler function for the 'search_emails' tool. It destructures input parameters, constructs a JMAP filter object based on the provided search criteria, performs batched JMAP requests to query thread exemplar email IDs, fetch thread IDs, get emails in threads, and retrieve email details (id, subject, from, receivedAt, preview, mailboxIds), then returns the email details as JSON text content.

    async (inputs) => {
      try {
        const {
          mailboxId,
          limit,
          excludeMailboxIds,
          receivedBefore,
          receivedAfter,
          hasKeyword,
          notKeyword,
          hasAttachment,
          searchText,
          searchFrom,
          searchTo,
          searchCc,
          searchBcc,
          searchSubject,
          searchBody
        } = inputs;
  
        const session = await jam.session;
        const accountId = session.primaryAccounts["urn:ietf:params:jmap:mail"];
  
        // Construct the filter object based on provided inputs
        const filter = { inMailbox: mailboxId };
        if (excludeMailboxIds && excludeMailboxIds.length > 0) {
          filter.inMailboxOtherThan = excludeMailboxIds;
        }
        if (receivedBefore) {
          filter.before = receivedBefore;
        }
        if (receivedAfter) {
          filter.after = receivedAfter;
        }
        if (hasKeyword) {
          filter.hasKeyword = hasKeyword;
        }
        if (notKeyword) {
          filter.notKeyword = notKeyword;
        }
        if (typeof hasAttachment === 'boolean') {
          filter.hasAttachment = hasAttachment;
        }
        if (searchText) {
          filter.text = searchText;
        }
        if (searchFrom) {
          filter.from = searchFrom;
        }
        if (searchTo) {
          filter.to = searchTo;
        }
        if (searchCc) {
          filter.cc = searchCc;
        }
        if (searchBcc) {
          filter.bcc = searchBcc;
        }
        if (searchSubject) {
          filter.subject = searchSubject;
        }
        if (searchBody) {
          filter.body = searchBody;
        }
  
        const [results] = await jam.requestMany(b => {
          // 1. Query for the latest thread exemplar email IDs
          const queryEmailsDraft = b.Email.query({
            accountId,
            filter: filter, // Use the constructed filter object
            sort: [{ property: "receivedAt", isAscending: false }],
            position: 0,
            collapseThreads: true, // Collapse to get thread exemplars
            limit: limit // Limit the number of threads
          });
  
          // 2. Fetch the threadId of each of those exemplar messages
          const getThreadIdsDraft = b.Email.get({
            accountId,
            ids: queryEmailsDraft.$ref('/ids'), // Use $ref on the draft variable
            properties: ["threadId"]
          });
  
          // 3. Get the emailIds of the messages in those threads
          const getThreadEmailsDraft = b.Thread.get({
            accountId,
            ids: getThreadIdsDraft.$ref('/list/*/threadId'), // Use $ref on the draft variable
          });
  
          // 4. Finally we get the data for all those emails
          const getEmailDetailsDraft = b.Email.get({
            accountId,
            ids: getThreadEmailsDraft.$ref('/list/*/emailIds'), // Use $ref on the draft variable
            properties: ["id", "subject", "from", "receivedAt", "preview", "mailboxIds"]
          });
  
          return {
            queryEmails: queryEmailsDraft,
            getThreadIds: getThreadIdsDraft,
            getThreadEmails: getThreadEmailsDraft,
            getEmailDetails: getEmailDetailsDraft
          };
        });
  
        return {
          content: [{
            type: "text",
            text: JSON.stringify(results.getEmailDetails.list, null, 2)
          }]
        };
      } catch (error) {
        console.error("Error in fetch_latest_emails:", error);
        return {
          content: [{
            type: "text",
            text: `Error fetching emails: ${JSON.stringify(error) || 'Unknown error'}`
          }],
          isError: true
        };
      }
    }
  );

• index.js:87-103 (schema)

  Zod input schema defining parameters for searching emails, including required mailboxId and various optional filters like dates, keywords, attachments, and search fields.

  inputSchema: z.object({
    mailboxId: z.string().describe("The mailbox to search in."),
    limit: z.number().default(15).describe("Max number of threads/emails to return."),
    excludeMailboxIds: z.array(z.string()).optional().describe("Mailboxes to exclude."),
    receivedBefore: z.string().datetime().optional().describe("Only emails received before this date (ISO 8601)."),
    receivedAfter: z.string().datetime().optional().describe("Only emails received after this date (ISO 8601)."),
    hasKeyword: z.string().optional().describe("Only emails with this keyword."),
    notKeyword: z.string().optional().describe("Only emails without this keyword."),
    hasAttachment: z.boolean().optional().describe("Only emails with/without attachments."),
    searchText: z.string().optional().describe("Full-text search."),
    searchFrom: z.string().optional().describe("Filter by sender."),
    searchTo: z.string().optional().describe("Filter by recipient (To)."),
    searchCc: z.string().optional().describe("Filter by recipient (Cc)."),
    searchBcc: z.string().optional().describe("Filter by recipient (Bcc)."),
    searchSubject: z.string().optional().describe("Filter by subject."),
    searchBody: z.string().optional().describe("Filter by body content.")
  })

• index.js:83-84 (registration)

  MCP server registration of the 'search_emails' tool, specifying the tool name, description, input schema, and handler function.

  server.tool(
    "search_emails",