search
Find emails in a specified folder using criteria like sender, recipient, subject, date range, and message status to locate specific messages.
Instructions
Searches for messages in the specified folder matching the parameters set in searchOptions. Available search options are: from, to, subject, since, before, unseen, flagged, answered, custom. It returns a list of ids that can then be used to get individual messages based on their id.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| folder | Yes | ||
| from | No | ||
| to | No | ||
| subject | No | ||
| since | No | ||
| before | No |
Implementation Reference
- src/tools/SearchFolderTool.ts:23-32 (handler)The async execute function that implements the core logic of the 'search' tool: validates input, parses search options, connects to IMAP, performs the search via controller, and returns message IDs as JSON.
async execute(args, context) { if (!args || typeof args !== 'object' || !('folder' in args)) { throw new Error("Missing required arguments"); } const searchOptions = MailSearchOptionSchema.parse(args); const controller = ImapControllerFactory.getInstance(); await controller.connect(); const ids = await controller.search(args.folder, searchOptions); return JSON.stringify({ ids }); } - src/tools/SearchFolderTool.ts:6-16 (schema)Zod schema defining the input parameters for the 'search' tool (used as parameters in Tool object). Note: some options are commented out here but handled via internal schema.
export const SearchInput = z.object({ folder: z.string().min(2).max(100), from: z.string().optional(), to: z.string().optional(), subject: z.string().optional(), since: z.coerce.date().optional(), before: z.coerce.date().optional(), // unseen: z.boolean().optional(), // flagged: z.boolean().optional(), // answered: z.boolean().optional(), }); - src/models/MailSearchOption.ts:5-15 (schema)Internal Zod schema used in the handler to parse full search options, including additional flags like unseen, flagged, answered, and custom.
export const MailSearchOptionSchema = z.object({ from: z.string().optional(), to: z.string().optional(), subject: z.string().optional(), since: z.coerce.date().optional(), before: z.coerce.date().optional(), unseen: z.boolean().optional(), flagged: z.boolean().optional(), answered: z.boolean().optional(), custom: z.any().optional(), }); - src/index.ts:54-54 (registration)Registration of the SearchFolderTool (named 'search') with the FastMCP server.
server.addTool(SearchFolderTool); - src/index.ts:14-14 (registration)Import of the SearchFolderTool in the main index file.
import { SearchFolderTool } from "./tools/SearchFolderTool.js";