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",