Email MCP Server

Instructions

Implementation Reference

• src/tools/GetMessageListTool.ts:12-25 (handler)

  Main tool handler: defines name, description, parameters schema, and execute function that validates args, connects via factory, calls controller.getMessageList, returns JSON stringified messages.

  export const GetMessageListTool: Tool<any, typeof GetMessageListInput> = {
    name: "getMessageList",
    description: "Returns a list of messages in a given folder.",
    parameters: GetMessageListInput,
    async execute(args, context) {
      if (!args || typeof args !== 'object' || !('folder' in args)) {
        throw new Error("Missing required arguments");
      }
      const controller = ImapControllerFactory.getInstance();
      await controller.connect();
      const messages: MailItem[] = await controller.getMessageList(args.folder, args.start, args.end);
      return JSON.stringify({ messages });
    }
  };

• src/tools/GetMessageListTool.ts:6-10 (schema)

  Zod input schema defining required folder (string 2-100 chars), optional start number (default 1), optional end string (default '*').

  const GetMessageListInput = z.object({
    folder: z.string().min(2).max(100),
    start: z.number().min(1).optional().default(1),
    end: z.string().min(1).optional().default('*'),
  });

• src/index.ts:51-51 (registration)

  Registers the GetMessageListTool instance with the FastMCP server.

  server.addTool(GetMessageListTool);

• src/controllers/ImapController.ts:75-106 (helper)

  Core helper method in ImapController that opens IMAP box, fetches headers for range start:end, parses subject/from/to/date/uid into MessageListItem objects.

  getMessageList(folder: string, start: number, end: number|string): Promise<MessageListItem[]> {
      return new Promise((resolve, reject) => {
          this.imap.openBox(folder, true, (err: Error | null, box: Imap.Box) => {
              if (err) return reject(err);
              const results: MessageListItem[] = [];
              const fetch = this.imap.seq.fetch(`${start}:${end}`, { bodies: 'HEADER.FIELDS (FROM TO SUBJECT DATE)', struct: true });
              fetch.on('message', (msg: ImapMessage, seqno: number) => {
                  const item: any = { };
                  msg.on('body', (stream: any) => {
                      let buffer = '';
                      stream.on('data', (chunk: Buffer) => buffer += chunk.toString('utf8'));
                      stream.on('end', () => {
                          const headers = Imap.parseHeader(buffer);
                          item.subject = headers.subject?.[0];
                          item.from = parseAddressList(headers.from)[0];
                          item.to = parseAddressList(headers.to);
                          item.date = headers.date?.[0] ? new Date(headers.date[0]) : undefined;
                      });
                  });
                  msg.once('attributes', (attrs: any) => {
                      item.id = attrs.uid;
                  });
                  msg.once('end', () => {
                      //console.log('Parsed MessageListItem:', item);
                      results.push(MessageListItem.parse(item));
                  });
              });
              fetch.once('error', (err:Error|null) => reject(err));
              fetch.once('end', () => resolve(results));
          });
      });
  }