Mail MCP Tool

Implementation Reference

• src/tools/mail-service.ts:754-881 (handler)

  Core handler function that implements getContacts logic by analyzing recent emails to extract and rank contacts based on communication frequency.
  async getContacts(options: { maxResults?: number; // 最大结果数 includeGroups?: boolean; // 是否包含分组 searchTerm?: string; // 搜索词 } = {}): Promise<{ contacts: { name?: string; email: string; frequency: number; // 联系频率 lastContact?: Date; // 最后联系时间 }[]; }> { const maxResults = options.maxResults || 100; const searchTerm = options.searchTerm?.toLowerCase() || ''; // 从最近的邮件中提取联系人 const contactMap = new Map<string, { name?: string; email: string; frequency: number; lastContact?: Date; }>(); // 从收件箱和已发送邮件中收集联系人 const folders = ['INBOX', 'Sent Messages']; for (const folder of folders) { try { const emails = await this.searchMails({ folder, limit: 200, // 搜索足够多的邮件以收集联系人 }); emails.forEach(email => { // 处理收件箱中的发件人 if (folder === 'INBOX') { email.from.forEach(sender => { if (sender.address === this.config.defaults.fromEmail) return; // 跳过自己 const key = sender.address.toLowerCase(); if (!contactMap.has(key)) { contactMap.set(key, { name: sender.name, email: sender.address, frequency: 1, lastContact: email.date }); } else { const contact = contactMap.get(key)!; contact.frequency += 1; if (!contact.lastContact || email.date > contact.lastContact) { contact.lastContact = email.date; } } }); } // 处理已发送邮件中的收件人 if (folder === 'Sent Messages') { email.to.forEach(recipient => { if (recipient.address === this.config.defaults.fromEmail) return; // 跳过自己 const key = recipient.address.toLowerCase(); if (!contactMap.has(key)) { contactMap.set(key, { name: recipient.name, email: recipient.address, frequency: 1, lastContact: email.date }); } else { const contact = contactMap.get(key)!; contact.frequency += 1; if (!contact.lastContact || email.date > contact.lastContact) { contact.lastContact = email.date; } } }); // 如果有抄送人，也处理 if (email.cc) { email.cc.forEach(cc => { if (cc.address === this.config.defaults.fromEmail) return; // 跳过自己 const key = cc.address.toLowerCase(); if (!contactMap.has(key)) { contactMap.set(key, { name: cc.name, email: cc.address, frequency: 1, lastContact: email.date }); } else { const contact = contactMap.get(key)!; contact.frequency += 1; if (!contact.lastContact || email.date > contact.lastContact) { contact.lastContact = email.date; } } }); } } }); } catch (error) { console.error(`从文件夹 ${folder} 收集联系人时出错:`, error); // 继续处理其他文件夹 } } // 转换为数组并排序（频率优先） let contacts = Array.from(contactMap.values()); // 如果提供了搜索词，进行过滤 if (searchTerm) { contacts = contacts.filter(contact => (contact.name?.toLowerCase() || '').includes(searchTerm) || contact.email.toLowerCase().includes(searchTerm) ); } // 按联系频率排序 contacts.sort((a, b) => b.frequency - a.frequency); // 限制结果数 contacts = contacts.slice(0, maxResults); return { contacts }; }
• src/tools/mail.ts:662-719 (registration)

  Registers the getContacts tool with the MCP server, including input validation schema and wrapper handler that delegates to MailService and formats output.
  this.server.tool( "getContacts", { maxResults: z.number().default(50), searchTerm: z.string().optional() }, async (params) => { try { const result = await this.mailService.getContacts({ maxResults: params.maxResults, searchTerm: params.searchTerm }); const contacts = result.contacts; // 转换为人类可读格式 if (contacts.length === 0) { const message = params.searchTerm ? `没有找到包含"${params.searchTerm}"的联系人。` : `没有找到任何联系人。`; return { content: [ { type: "text", text: message } ] }; } const header = params.searchTerm ? `📋 搜索结果: 包含"${params.searchTerm}"的联系人 (${contacts.length}个):\n\n` : `📋 联系人列表 (${contacts.length}个):\n\n`; let resultText = header; contacts.forEach((contact, index) => { const name = contact.name || '(无名称)'; const frequency = contact.frequency; const lastContact = contact.lastContact ? contact.lastContact.toLocaleDateString() : '未知'; resultText += `${index + 1}. ${name} <${contact.email}>\n`; resultText += ` 邮件频率: ${frequency}次\n`; resultText += ` 最后联系: ${lastContact}\n\n`; }); return { content: [ { type: "text", text: resultText } ] }; } catch (error) { return { content: [ { type: "text", text: `获取联系人时发生错误: ${error instanceof Error ? error.message : String(error)}` } ] }; } } );
• src/tools/mail.ts:665-667 (schema)

  Zod input schema for getContacts tool: maxResults (optional number, default 50), searchTerm (optional string). Used in MCP tool registration for validation.
  maxResults: z.number().default(50), searchTerm: z.string().optional() },