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()
  },