Mail MCP Tool

Implementation Reference

• src/tools/mail.ts:497-585 (registration)

  Registration of the 'searchEmails' MCP tool, including Zod input schema and the handler function that performs advanced email search by calling mailService.advancedSearchMails and formats results.
  this.server.tool( "searchEmails", { keywords: z.string().optional(), folders: z.array(z.string()).optional(), startDate: z.union([z.date(), z.string().datetime({ message: "startDate 必须是有效的 ISO 8601 日期时间字符串或 Date 对象" })]).optional(), endDate: z.union([z.date(), z.string().datetime({ message: "endDate 必须是有效的 ISO 8601 日期时间字符串或 Date 对象" })]).optional(), from: z.string().optional(), to: z.string().optional(), subject: z.string().optional(), hasAttachment: z.boolean().optional(), maxResults: z.number().default(50), includeBody: z.boolean().default(false) }, async (params) => { try { console.log(`开始执行高级邮件搜索，关键词: ${params.keywords || '无'}`); // 处理日期字符串 const startDate = typeof params.startDate === 'string' ? new Date(params.startDate) : params.startDate; const endDate = typeof params.endDate === 'string' ? new Date(params.endDate) : params.endDate; const emails = await this.mailService.advancedSearchMails({ folders: params.folders, keywords: params.keywords, startDate: startDate, endDate: endDate, from: params.from, to: params.to, subject: params.subject, hasAttachment: params.hasAttachment, maxResults: params.maxResults, includeBody: params.includeBody }); // 转换为人类可读格式 if (emails.length === 0) { return { content: [ { type: "text", text: `没有找到符合条件的邮件。` } ] }; } const searchTerms = []; if (params.keywords) searchTerms.push(`关键词"${params.keywords}"`); if (params.from) searchTerms.push(`发件人包含"${params.from}"`); if (params.to) searchTerms.push(`收件人包含"${params.to}"`); if (params.subject) searchTerms.push(`主题包含"${params.subject}"`); if (startDate) searchTerms.push(`开始日期${startDate.toLocaleDateString()}`); if (endDate) searchTerms.push(`结束日期${endDate.toLocaleDateString()}`); if (params.hasAttachment) searchTerms.push(`包含附件`); const searchDescription = searchTerms.length > 0 ? `搜索条件: ${searchTerms.join(', ')}` : '所有邮件'; let resultText = `🔍 邮件搜索结果 (${emails.length}封邮件)\n${searchDescription}\n\n`; emails.forEach((email, index) => { const fromStr = email.from.map(f => f.name ? `${f.name} <${f.address}>` : f.address).join(', '); const date = email.date.toLocaleString(); const status = email.isRead ? '已读' : '未读'; const attachmentInfo = email.hasAttachments ? '有' : ''; const folder = email.folder; resultText += `${index + 1}. [${status}] ${attachmentInfo} 来自: ${fromStr}\n`; resultText += ` 主题: ${email.subject}\n`; resultText += ` 时间: ${date}\n`; resultText += ` 文件夹: ${folder}\n`; resultText += ` UID: ${email.uid}\n\n`; }); resultText += `使用 getEmailDetail 工具并提供 UID 和 folder 可以查看邮件详情。`; return { content: [ { type: "text", text: resultText } ] }; } catch (error) { return { content: [ { type: "text", text: `搜索邮件时发生错误: ${error instanceof Error ? error.message : String(error)}` } ] }; } } );
• src/tools/mail.ts:511-585 (handler)

  The handler function for the searchEmails tool, which invokes the mail service's advanced search and returns human-readable results.
  async (params) => { try { console.log(`开始执行高级邮件搜索，关键词: ${params.keywords || '无'}`); // 处理日期字符串 const startDate = typeof params.startDate === 'string' ? new Date(params.startDate) : params.startDate; const endDate = typeof params.endDate === 'string' ? new Date(params.endDate) : params.endDate; const emails = await this.mailService.advancedSearchMails({ folders: params.folders, keywords: params.keywords, startDate: startDate, endDate: endDate, from: params.from, to: params.to, subject: params.subject, hasAttachment: params.hasAttachment, maxResults: params.maxResults, includeBody: params.includeBody }); // 转换为人类可读格式 if (emails.length === 0) { return { content: [ { type: "text", text: `没有找到符合条件的邮件。` } ] }; } const searchTerms = []; if (params.keywords) searchTerms.push(`关键词"${params.keywords}"`); if (params.from) searchTerms.push(`发件人包含"${params.from}"`); if (params.to) searchTerms.push(`收件人包含"${params.to}"`); if (params.subject) searchTerms.push(`主题包含"${params.subject}"`); if (startDate) searchTerms.push(`开始日期${startDate.toLocaleDateString()}`); if (endDate) searchTerms.push(`结束日期${endDate.toLocaleDateString()}`); if (params.hasAttachment) searchTerms.push(`包含附件`); const searchDescription = searchTerms.length > 0 ? `搜索条件: ${searchTerms.join(', ')}` : '所有邮件'; let resultText = `🔍 邮件搜索结果 (${emails.length}封邮件)\n${searchDescription}\n\n`; emails.forEach((email, index) => { const fromStr = email.from.map(f => f.name ? `${f.name} <${f.address}>` : f.address).join(', '); const date = email.date.toLocaleString(); const status = email.isRead ? '已读' : '未读'; const attachmentInfo = email.hasAttachments ? '有' : ''; const folder = email.folder; resultText += `${index + 1}. [${status}] ${attachmentInfo} 来自: ${fromStr}\n`; resultText += ` 主题: ${email.subject}\n`; resultText += ` 时间: ${date}\n`; resultText += ` 文件夹: ${folder}\n`; resultText += ` UID: ${email.uid}\n\n`; }); resultText += `使用 getEmailDetail 工具并提供 UID 和 folder 可以查看邮件详情。`; return { content: [ { type: "text", text: resultText } ] }; } catch (error) { return { content: [ { type: "text", text: `搜索邮件时发生错误: ${error instanceof Error ? error.message : String(error)}` } ] }; } } );
• src/tools/mail.ts:500-510 (schema)

  Zod schema defining input parameters for the searchEmails tool (keywords, folders, dates, from/to/subject filters, etc.).
  keywords: z.string().optional(), folders: z.array(z.string()).optional(), startDate: z.union([z.date(), z.string().datetime({ message: "startDate 必须是有效的 ISO 8601 日期时间字符串或 Date 对象" })]).optional(), endDate: z.union([z.date(), z.string().datetime({ message: "endDate 必须是有效的 ISO 8601 日期时间字符串或 Date 对象" })]).optional(), from: z.string().optional(), to: z.string().optional(), subject: z.string().optional(), hasAttachment: z.boolean().optional(), maxResults: z.number().default(50), includeBody: z.boolean().default(false) },
• src/tools/mail-service.ts:674-749 (helper)

  Helper method advancedSearchMails in MailService class that implements the core IMAP search logic across multiple folders with advanced filtering and keyword matching.
  async advancedSearchMails(options: { folders?: string[]; // 要搜索的文件夹列表，默认为INBOX keywords?: string; // 全文搜索关键词 startDate?: Date; // 开始日期 endDate?: Date; // 结束日期 from?: string; // 发件人 to?: string; // 收件人 subject?: string; // 主题 hasAttachment?: boolean; // 是否有附件 maxResults?: number; // 最大结果数 includeBody?: boolean; // 是否包含邮件正文 }): Promise<MailItem[]> { const allResults: MailItem[] = []; const folders = options.folders || ['INBOX']; const maxResults = options.maxResults || 100; console.log(`执行高级搜索，文件夹: ${folders.join(', ')}, 关键词: ${options.keywords || '无'}`); // 对每个文件夹执行搜索 for (const folder of folders) { if (allResults.length >= maxResults) break; try { const folderResults = await this.searchMails({ folder, readStatus: 'all', fromDate: options.startDate, toDate: options.endDate, from: options.from, to: options.to, subject: options.subject, hasAttachments: options.hasAttachment, limit: maxResults - allResults.length }); // 如果包含关键词，执行全文匹配 if (options.keywords && options.keywords.trim() !== '') { const keywordLower = options.keywords.toLowerCase(); const filteredResults = folderResults.filter(mail => { // 在主题、发件人、收件人中搜索 const subjectMatch = mail.subject.toLowerCase().includes(keywordLower); const fromMatch = mail.from.some(f => (f.name?.toLowerCase() || '').includes(keywordLower) || f.address.toLowerCase().includes(keywordLower) ); const toMatch = mail.to.some(t => (t.name?.toLowerCase() || '').includes(keywordLower) || t.address.toLowerCase().includes(keywordLower) ); // 如果需要在正文中搜索，可能需要额外获取邮件详情 let bodyMatch = false; if (options.includeBody) { bodyMatch = (mail.textBody?.toLowerCase() || '').includes(keywordLower) || (mail.htmlBody?.toLowerCase() || '').includes(keywordLower); } return subjectMatch || fromMatch || toMatch || bodyMatch; }); allResults.push(...filteredResults); } else { allResults.push(...folderResults); } } catch (error) { console.error(`搜索文件夹 ${folder} 时出错:`, error); // 继续搜索其他文件夹 } } // 按日期降序排序（最新的邮件优先） allResults.sort((a, b) => b.date.getTime() - a.date.getTime()); // 限制结果数量 return allResults.slice(0, maxResults); }