Email MCP Server

Instructions

Implementation Reference

• src/tools/GetMessageTool.ts:11-24 (handler)

  The GetMessageTool object defining the tool's metadata and the execute handler function that fetches and returns the message using ImapController.
  export const GetMessageTool: Tool<any, typeof GetMessageInput> = { name: "getMessage", description: "Returns a message by UID from a given folder for a given IMAP account.", parameters: GetMessageInput, async execute(args, context) { if (!args || typeof args !== 'object' || !('folder' in args) || !('uid' in args)) { throw new Error("Missing required arguments"); } const controller = ImapControllerFactory.getInstance(); await controller.connect(); const message: MailItem = await controller.getMessage(args.folder, args.uid); return JSON.stringify({ message }); } };
• src/tools/GetMessageTool.ts:6-9 (schema)

  Zod schema defining the input parameters for the getMessage tool: folder (string) and uid (number).
  export const GetMessageInput = z.object({ folder: z.string().min(2).max(100), uid: z.number() });
• src/index.ts:52-52 (registration)

  Registration of the GetMessageTool with the FastMCP server.
  server.addTool(GetMessageTool);
• src/controllers/ImapController.ts:108-213 (helper)

  The ImapController.getMessage method that retrieves and parses the full message content from the IMAP server, used by the tool handler.
  getMessage(folder: string, uid: number): Promise<MailItem> { return new Promise((resolve, reject) => { this.imap.openBox(folder, true, (err: Error | null, box: Imap.Box) => { if (err) return reject(err); const fetch = this.imap.fetch(uid, { bodies: ['HEADER', 'TEXT'], struct: true, envelope: true, size:true }); let mail: MailItem = { id: uid }; fetch.on('message', (msg: ImapMessage, seqno: number) => { let headersBuffer = ''; let textBuffer = ''; let htmlBuffer = ''; let attachments: any[] = []; let headers: any = {}; let fullbuffer = ''; msg.on('body', (stream: any, info: any) => { let buffer = ''; stream.on('data', (chunk: Buffer) => { buffer += chunk.toString('utf8'); fullbuffer += buffer; }); stream.on('end', () => { if (info.which && info.which.toUpperCase().startsWith('HEADER')) { headersBuffer += buffer; } else if (info.which && info.which.toUpperCase().includes('TEXT/HTML')) { htmlBuffer += buffer; } else { textBuffer += buffer; } //console.log('=============END============'); simpleParser(fullbuffer, (parserErr, parsedmail) => { if (parserErr) throw parserErr; //console.log('Subject:', parsedmail.subject); //console.log('From:', parsedmail.from); //console.log('To:', parsedmail.to); //console.log('Text Body:', parsedmail.text?.toString().length); //console.log('HTML Body:', parsedmail.html.toString().length); //console.log('Headers:', parsedmail.headers); mail.subject = parsedmail.subject; mail.from = EmailAddressSchema.parse({ address: parsedmail.from?.value[0].address?.toString(), name: parsedmail.from?.value[0].name }); if (typeof parsedmail.to !== 'undefined' && !Array.isArray(parsedmail.to)) { mail.to?.push(EmailAddressSchema.parse({ address: parsedmail.to.value[0].address?.toString(), name: parsedmail.to.value[0].name })); }else{ if(Array.isArray(parsedmail.to)) { parsedmail.to.map((addr: AddressObject) => { mail.to?.push(EmailAddressSchema.parse({ address: addr.value[0].address?.toString(), name: addr.value[0].name })); }); } } if(typeof parsedmail.cc !== 'undefined' && !Array.isArray(parsedmail.cc)) { mail.cc?.push(EmailAddressSchema.parse({ address: parsedmail.cc.value[0].address?.toString(), name: parsedmail.cc.value[0].name })); }else{ if(Array.isArray(parsedmail.cc)) { parsedmail.cc.map((addr: AddressObject) => { mail.cc?.push(EmailAddressSchema.parse({ address: addr.value[0].address?.toString(), name: addr.value[0].name })); }); } } if(typeof parsedmail.bcc !== 'undefined' && !Array.isArray(parsedmail.bcc)) { mail.bcc?.push(EmailAddressSchema.parse({ address: parsedmail.bcc.value[0].address?.toString(), name: parsedmail.bcc.value[0].name })); }else{ if(Array.isArray(parsedmail.bcc)) { parsedmail.bcc.map((addr: AddressObject) => { mail.bcc?.push(EmailAddressSchema.parse({ address: addr.value[0].address?.toString(), name: addr.value[0].name })); }); } } mail.date = parsedmail.date ? new Date(parsedmail.date) : undefined; mail.messageId = parsedmail.messageId; mail.inReplyTo = parsedmail.inReplyTo; if(typeof parsedmail.references !== 'undefined' && !Array.isArray(parsedmail.references)) { mail.references?.push(parsedmail.references); }else{ if(Array.isArray(parsedmail.references)) { parsedmail.references.map((ref: string) => { mail.references?.push(ref); }); } } mail.text = parsedmail.text?.toString(); mail.html = parsedmail.html?.toString(); for(let [key,value] of parsedmail.headers) { mail.headers?.push([key, value]); } mail.attachments = parsedmail.attachments; // Remove undefined/empty arrays if (mail.to && mail.to.length === 0) delete mail.to; if (mail.cc && mail.cc.length === 0) delete mail.cc; if (mail.bcc && mail.bcc.length === 0) delete mail.bcc; if (mail.references && mail.references.length === 0) delete mail.references; if (mail.attachments && mail.attachments.length === 0) delete mail.attachments; resolve(MailItemSchema.parse(mail)); }); //console.log('=============END============'); }); }); msg.once('end', () => { }); }); fetch.once('error', (err: Error | null) => reject(err)); }); }); }
• src/index.ts:12-12 (registration)

  Import of the GetMessageTool in the main index file.
  import { GetMessageTool } from "./tools/GetMessageTool.js";