Email MCP Server

Instructions

Implementation Reference

• src/tools/GetFolderListTool.ts:10-28 (handler)

  The execute handler function of the getFolderList tool, which connects to the IMAP controller and retrieves and formats the folder list.

  export const GetFolderListTool: Tool<any, typeof GetFolderListInput> = {
    name: "getFolderList",
    description: "Returns a list of folders in the imap account.",
    parameters: GetFolderListInput,
    async execute(params) {
      const controller = ImapControllerFactory.getInstance();
      await controller.connect();
      const folders: MailFolder[] = await controller.getFolderList();
      // Return as a JSON string to match the expected return type
      return JSON.stringify({
        folders: folders.map(f => ({
          name: f.name,
          path: f.path,
          flags: f.flags,
          delimiter: f.delimiter
        }))
      });
    }
  };

• src/tools/GetFolderListTool.ts:6-8 (schema)

  Zod input schema for the getFolderList tool (no parameters required).

  const GetFolderListInput = z.object({
    // No input parameters needed for this tool
  });

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

  Registration of the GetFolderListTool with the FastMCP server.

  server.addTool(GetFolderListTool);

• src/controllers/ImapController.ts:50-73 (helper)

  ImapController.getFolderList() helper method that traverses the IMAP box structure to build the folder list.

  getFolderList(): Promise<MailFolder[]> {
      return new Promise((resolve, reject) => {
          this.imap.getBoxes((err: Error | null, boxes: any) => {
              if (err) return reject(err);
              const folders: MailFolder[] = [];
              const traverse = (boxObj: any, path = '') => {
                  for (const name in boxObj) {
                      const box = boxObj[name];
                      const fullPath = path ? path + box.delimiter + name : name;
                      // Validate with schema and push
                      folders.push(MailFolderSchema.parse({
                          name,
                          path: fullPath,
                          flags: box.flags,
                          delimiter: box.delimiter
                      }));
                      if (box.children) traverse(box.children, fullPath);
                  }
              };
              traverse(boxes);
              resolve(folders);
          });
      });
  }