Smart Email AI 🚀📧

基于MCP的智能邮件管理系统 - 集邮件接收、分析、发送于一体的完整解决方案

🌟 项目简介

Smart Email AI 是一个专为MCP（Model Context Protocol）环境设计的全功能邮件管理系统。它不仅能解析和分析邮件，还集成了真实邮箱连接、智能缓存、邮件发送等完整功能，为AI驱动的邮件管理提供强大支撑。

🎯 核心功能

📥 邮件接收与解析

🔗 iCloud真实邮箱集成: 直接连接iCloud邮箱，获取真实邮件数据
🔍 智能邮件解析: 支持Outlook HTML邮件的深度解析，包括转发链和嵌套结构
📊 表格数据提取: 智能识别和提取邮件中的数据表格，转换为结构化格式
🧹 内容清理优化: 移除HTML噪声，提取纯净的邮件内容

⚡ 性能优化

🚀 三层缓存架构: L1内存缓存 + L2 SQLite缓存 + L3 iCloud IMAP
📈 毫秒级响应: 将邮件检索时间从3-5秒降低到3-50ms（提升1000倍+）
🔍 全文索引搜索: SQLite FTS5全文索引，支持布尔查询、模糊匹配
⚡ 超快搜索: search_emails_fts() 提供3-50ms响应时间
📅 实时同步: 智能日期同步，解决时区差异问题

📤 邮件发送

📧 多格式发送: 支持HTML、纯文本、带附件邮件
🎨 智能报告: 自动生成美观的邮件分析报告
🔐 安全认证: 支持应用专用密码和多邮件服务商
📊 发送统计: 详细的发送状态和性能监控

🧠 AI分析增强

📊 重要性评分: 基于关键词、附件、长度的智能评分
📅 时间分析: 按日期、时间段的邮件分布分析
👤 发件人画像: 基于历史交互的发件人类型识别
🔄 学习机制: 支持用户反馈驱动的模型改进

💡 设计理念

完整的邮件管理闭环

📥 接收 → 🧠 分析 → 📤 发送
   ↓        ↓        ↓
iCloud   Claude AI  SMTP
邮箱      智能分析   发送

✅ 统一平台: 一个系统解决所有邮件管理需求
✅ AI驱动: 与Claude等AI模型深度集成
✅ 性能优先: 毫秒级响应，支持大量邮件处理
✅ 安全可靠: 企业级安全标准，支持多种认证方式

🏗️ 系统架构

smart_email_ai/
├── src/smart_email_ai/          # 核心源代码
│   ├── main.py                 # MCP服务器主入口
│   ├── core/                   # 核心业务逻辑
│   │   ├── icloud_connector.py # iCloud邮箱连接器
│   │   ├── email_cache.py      # 三层缓存系统
│   │   ├── email_sender.py     # 邮件发送器
│   │   └── parser.py          # 邮件解析器
│   └── interfaces/             # 接口层
│       ├── config_interface.py # 配置管理
│       └── email_interface.py  # 邮件数据接口
├── data/                       # 数据文件
│   ├── config.yaml            # 系统配置
│   ├── demo_emails.json       # 演示邮件数据
│   └── email_cache.db         # SQLite缓存数据库
├── start_mcp_server.py         # MCP服务器启动器
└── main.py                     # 项目主入口

🚀 快速开始

📋 系统要求

Python 3.8+
8GB+ RAM (推荐16GB用于大量邮件处理)
网络连接 (用于iCloud邮箱访问)
支持的操作系统: macOS, Linux, Windows

⚡ 安装

克隆项目

git clone <repository-url>
cd smart_email_ai

安装依赖

# 使用uv（推荐，更快）
uv pip install -r requirements.txt

# 或使用pip
pip install -r requirements.txt

配置iCloud凭据

# 编辑配置文件，添加您的iCloud凭据
# 注意：建议使用应用专用密码

🎮 使用方法

1. 启动MCP服务器（推荐）

# 启动MCP服务器供Claude Desktop使用
python start_mcp_server.py

2. Claude Desktop配置

将以下配置添加到Claude Desktop的MCP设置中：

{
  "mcpServers": {
    "smart-email-ai": {
      "command": "python",
      "args": ["/path/to/smart_email_ai/start_mcp_server.py"],
      "cwd": "/path/to/smart_email_ai"
    }
  }
}

3. 命令行模式

# 快速演示
python main.py --demo

# 分析邮件文件
python main.py --analyze path/to/email.html

# 系统测试
python main.py --test

🎯 使用示例

超快搜索示例

# 毫秒级全文索引搜索（推荐）
search_emails_fts("Apple", 10)
# 响应时间: 3-50ms，支持布尔查询

# 智能混合搜索（完整功能）
search_icloud_emails_smart("重要 AND 附件", 20)
# 响应时间: 1-3秒，包含AI分析

# 轻量级今日邮件
get_today_emails_simple(5)
# 响应时间: 50-100ms，快速查看

高级搜索语法

# 精确匹配
search_emails_fts('"Apple 账户"', 10)

# 布尔操作
search_emails_fts('Apple AND 安全', 10)
search_emails_fts('邮件 NOT 垃圾', 10)

# 模糊匹配
search_emails_fts('Appl*', 10)

# 组合查询
search_emails_fts('(Apple OR Google) AND 重要', 15)

🔧 MCP工具集

📥 邮件接收工具

工具名称	功能描述	响应时间
`connect_to_icloud()`	连接到iCloud邮箱	~2秒
`get_icloud_inbox_summary()`	获取邮箱统计概览	~1秒
`analyze_icloud_recent_emails()`	智能分析最近邮件	50-100ms (缓存)
`get_today_latest_emails()`	获取今日最新邮件	~2秒 (实时)
`get_today_emails_simple()`	轻量级今日邮件	50-100ms

🔍 搜索工具（性能优化）

工具名称	功能描述	响应时间	搜索引擎
`search_emails_fts()`	超快全文索引搜索	3-50ms	SQLite FTS5
`search_icloud_emails_smart()`	智能混合搜索	1-3秒	索引+服务器
`search_cached_emails()`	缓存快速搜索	20-100ms	缓存数据

⚡ 缓存优化工具

工具名称	功能描述	性能提升
`get_cached_recent_emails()`	从缓存快速获取邮件	15-50倍
`sync_email_cache_with_latest()`	同步缓存与最新数据	-
`get_cache_performance_stats()`	缓存性能统计	-
`optimize_email_cache()`	缓存优化建议	-
`clear_email_cache()`	清理缓存数据	-

📤 邮件发送工具

工具名称	功能描述	支持格式
`send_email()`	基本邮件发送	HTML/文本
`send_html_email_with_attachments()`	高级邮件发送	HTML+附件+抄送
`send_email_analysis_report()`	发送分析报告	HTML报告
`test_email_server_connection()`	测试邮件服务器	-
`get_email_sender_status()`	获取发送器状态	-

🔍 邮件解析工具

工具名称	功能描述	特殊功能
`parse_outlook_email()`	解析Outlook邮件	转发链解析
`extract_outlook_tables()`	提取表格数据	Markdown格式
`analyze_outlook_email_structure()`	邮件结构分析	层级关系

📊 性能基准测试

🚀 搜索性能对比

搜索方式	响应时间	数据源	性能提升	适用场景
`search_emails_fts()`	3-50ms	全文索引	1000倍+	🚀 日常快速搜索
`search_icloud_emails_smart()`	1-3秒	索引+服务器	2-5倍	🔍 完整智能搜索
`search_cached_emails()`	20-100ms	缓存数据	50-250倍	⚡ 缓存快速搜索
传统IMAP搜索	5-15秒	邮件服务器	基准	📧 服务器原生搜索

💾 缓存性能对比

操作类型	无缓存	有缓存	性能提升
获取10封邮件	3-5秒	50-100ms	30-100倍
全文搜索	5-15秒	3-50ms	100-5000倍
邮件统计	2-3秒	10-20ms	100-300倍

💾 存储效率

缓存命中率: 50-80%
数据库大小: ~1MB/1000封邮件
内存使用: <100MB
磁盘I/O: 最小化

🔧 配置说明

iCloud连接配置

icloud_settings:
  email: "your@icloud.com"
  password: "your-app-specific-password"  # 使用应用专用密码
  server: "imap.mail.me.com"
  port: 993
  use_ssl: true

缓存优化配置

cache_settings:
  memory_cache:
    max_size: 100
    ttl_seconds: 300
  sqlite_cache:
    db_path: "data/email_cache.db"
    enable_fts: true
  performance:
    batch_size: 50
    max_connections: 5

邮件发送配置

email_sender:
  smtp_server: "smtp.mail.me.com"
  smtp_port: 587
  use_tls: true
  from_email: "your@icloud.com"
  from_password: "your-app-specific-password"

💻 编程接口示例

基本使用

from src.smart_email_ai.core.icloud_connector import iCloudConnector
from src.smart_email_ai.core.email_sender import email_sender

# 连接iCloud邮箱
connector = iCloudConnector()
if connector.connect():
    # 获取最近邮件
    emails = connector.get_recent_emails(10)
    
    # 发送分析报告
    email_sender.send_analysis_report("recipient@example.com", {
        'emails': emails,
        'total_emails': len(emails)
    })

高级缓存使用

from src.smart_email_ai.core.email_cache import email_cache_manager

# 高性能邮件检索
cached_emails = email_cache_manager.get_recent_emails(20, 'icloud')

# 全文搜索
search_results = email_cache_manager.search_emails("重要", 10)

# 性能统计
stats = email_cache_manager.get_performance_stats()
print(f"缓存命中率: {stats['cache_hit_rate']}")

🔬 开发与测试

运行测试

# 邮件发送测试
python -c "from src.smart_email_ai.core.email_sender import email_sender; print(email_sender.test_connection())"

# iCloud连接测试
python -c "from src.smart_email_ai.core.icloud_connector import iCloudConnector; c=iCloudConnector(); print(c.connect())"

# 缓存性能测试
python -c "from src.smart_email_ai.core.email_cache import email_cache_manager; print(email_cache_manager.get_performance_stats())"

MCP服务器测试

# 启动MCP服务器
python start_mcp_server.py

# 检查服务器状态
ps aux | grep start_mcp_server

🛡️ 安全说明

iCloud应用专用密码

为了安全连接iCloud邮箱，请使用应用专用密码：

访问 Apple ID管理页面
登录您的Apple ID
在"安全"部分，生成应用专用密码
将密码配置到系统中

数据安全

🔐 邮件内容本地加密存储
🚫 不上传敏感信息到外部服务
🔒 支持SSL/TLS加密连接
📝 详细的访问日志记录

📈 性能优化建议

大量邮件处理

# 批量处理优化
connector.get_recent_emails(100, use_cache=False)  # 首次加载
connector.get_recent_emails(100, use_cache=True)   # 后续快速访问

缓存策略

预热缓存: 系统启动时预加载常用邮件
定期清理: 清理过期缓存数据
智能刷新: 根据邮件活跃度智能更新

网络优化

连接池: 复用IMAP连接
压缩传输: 启用邮件内容压缩
超时设置: 合理的网络超时配置

🔄 版本历史

v3.0.0 (当前版本)

✅ 集成iCloud真实邮箱连接
✅ 实现三层缓存架构
✅ 添加邮件发送功能
✅ 性能优化：响应时间提升15-100倍
✅ 解决日期同步问题
✅ 完整的MCP工具集

v2.0.0

✅ 模块化架构重构
✅ 配置文件外部化
✅ MCP工具集成
✅ 增强AI分析能力

v1.0.0 (Legacy)

✅ 基础邮件解析功能
✅ 简单优先级分析
✅ Outlook HTML处理

🤝 贡献指南

Fork 项目
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
创建 Pull Request

📄 许可证

本项目采用 MIT 许可证。详情请参见 LICENSE 文件。

🆘 支持与帮助

常见问题

Q: iCloud连接失败怎么办？ A: 确保使用应用专用密码，检查网络连接和防火墙设置

Q: 缓存性能如何优化？ A: 使用 optimize_email_cache() 工具获取优化建议

Q: 如何处理大量邮件？ A: 启用缓存系统，使用批量处理模式

Q: 邮件发送失败怎么办？ A: 使用 test_email_server_connection() 检查SMTP配置

性能监控

# 实时性能监控
python -c "
from src.smart_email_ai.core.email_cache import email_cache_manager
import time
while True:
    stats = email_cache_manager.get_performance_stats()
    print(f'缓存命中率: {stats["cache_hit_rate"]}')
    time.sleep(10)
"

联系方式

🐛 Bug报告: 创建GitHub Issue
💡 功能建议: 创建GitHub Discussion
📧 技术支持: 查看项目Wiki
🚀 性能优化: 查看性能基准测试

🚀 让AI为您的邮件管理注入超能力！

⚡ 毫秒级响应 | 🔗 真实邮箱集成 | 📤 智能发送 | 🧠 AI驱动

Smart Email AI System

🚀 最新更新 - 修复今日邮件读取问题和扩展邮件发送功能

智能邮件AI系统，基于FastMCP框架构建，提供强大的邮件处理、分析和发送功能。

✨ 核心功能

📧 邮件管理

iCloud邮箱集成 - 安全连接和实时邮件同步
今日邮件获取 - 🔧 已修复 支持UTC+8时区的精确日期解析
智能缓存系统 - 三级缓存架构（内存+SQLite+文件）
全文搜索 - 基于SQLite FTS5的高性能搜索

📤 邮件发送 [新增功能]

🆕 send_email_to_anyone() - 支持自定义发件人发送邮件
🆕 send_bulk_email() - 批量邮件发送功能
send_email() - 基础邮件发送（向后兼容）
send_html_email_with_attachments() - 带附件的HTML邮件

🔍 邮件分析

Outlook邮件解析 - 智能提取邮件结构和表格数据
AI内容分析 - 重要性评分和智能分类
邮件报告生成 - 美观的HTML格式分析报告

🔧 最新修复

1. 今日邮件读取问题 ✅

问题: 日期解析不准确，时区处理有误修复:

统一使用UTC+8时区处理
支持多种日期格式解析
改进缓存同步机制

2. 邮件发送功能扩展 ✅

问题: 只能使用默认发件人发送邮件修复:

新增 send_email_to_anyone() 支持自定义发件人
新增 send_bulk_email() 批量邮件发送
保持向后兼容性

🚀 快速开始

安装依赖

pip install -r requirements.txt

启动MCP服务器

python start_mcp_server.py

核心使用方法

📧 邮件发送

# 使用默认发件人发送
send_email_to_anyone("recipient@example.com", "主题", "内容")

# 使用自定义发件人发送
send_email_to_anyone(
    "recipient@example.com", 
    "主题", 
    "内容",
    "custom@sender.com",
    "app_password"
)

# 批量发送
send_bulk_email(
    "user1@example.com,user2@example.com", 
    "批量邮件主题", 
    "邮件内容"
)

📅 今日邮件获取

# 获取今日最新邮件（UTC+8时区）
get_today_latest_emails(force_refresh=True)

# 连接iCloud邮箱
connect_to_icloud()

# 同步缓存
sync_email_cache_with_latest()

📁 项目结构

smart_email_ai/
├── src/smart_email_ai/
│   ├── core/
│   │   ├── email_sender.py      # 📤 邮件发送器（已增强）
│   │   ├── email_cache.py       # 💾 缓存管理器
│   │   ├── icloud_connector.py  # 📧 iCloud连接器
│   │   └── parser.py           # 🔍 邮件解析器
│   ├── interfaces/
│   │   ├── config_interface.py  # ⚙️ 配置管理
│   │   └── email_interface.py   # 📧 邮件接口
│   └── main.py                 # 🚀 MCP服务器主程序
├── data/
│   ├── config.yaml             # ⚙️ 系统配置
│   ├── demo_emails.json        # 📧 演示邮件数据
│   └── email_cache.db          # 💾 邮件缓存数据库
└── start_mcp_server.py         # 🚀 服务器启动脚本

🔧 配置说明

时区设置

默认时区: UTC+8（中国标准时间）
日期解析: 支持多种格式自动识别
缓存同步: 基于UTC+8时区的时间戳

邮件发送配置

默认发件人: jerrywsx@icloud.com
支持服务商: iCloud, Gmail, Outlook
安全连接: SSL/TLS加密传输

📋 MCP工具接口

📧 邮件读取

connect_to_icloud() - 连接iCloud邮箱
get_today_latest_emails() - 获取今日邮件
analyze_icloud_recent_emails() - 分析最近邮件
search_icloud_emails_smart() - 智能邮件搜索

📤 邮件发送

send_email_to_anyone() - 🆕 给任何人发送邮件（支持自定义发件人）
send_bulk_email() - 🆕 批量邮件发送
send_email() - 基础邮件发送
send_html_email_with_attachments() - 带附件HTML邮件

💾 缓存管理

sync_email_cache_with_latest() - 同步缓存
get_cache_performance_stats() - 缓存性能统计
clear_email_cache() - 清空缓存

🔍 邮件解析

parse_outlook_email() - Outlook邮件解析
extract_outlook_tables() - 表格数据提取
analyze_outlook_email_structure() - 邮件结构分析

🛠 技术特性

性能优化

三级缓存: 内存(L1) + SQLite(L2) + 文件(L3)
响应时间: 缓存命中 < 100ms
并发支持: 线程安全的缓存访问

安全特性

SSL/TLS加密: 邮件传输安全保护
应用密码: 支持邮箱应用专用密码
连接管理: 自动连接恢复和错误处理

兼容性

向后兼容: 保留所有原有API接口
多格式支持: HTML、纯文本、带附件邮件
时区感知: 自动处理时区转换

🐛 故障排除

常见问题

今日邮件读取为空

# 强制刷新缓存
sync_email_cache_with_latest()

# 重新获取今日邮件
get_today_latest_emails(force_refresh=True)

邮件发送失败

# 测试邮件服务器连接
test_email_server_connection()

# 检查发件人配置
get_email_sender_status()

缓存性能问题

# 查看缓存统计
get_cache_performance_stats()

# 优化缓存
optimize_email_cache()

📞 技术支持

项目地址: [GitHub Repository]
问题反馈: 通过GitHub Issues
功能建议: 欢迎提交Pull Request

📊 更新日志

v2.1.0 (最新)

🔧 修复今日邮件读取的日期解析问题
🚀 新增自定义发件人发送邮件功能
📬 新增批量邮件发送功能
⏰ 统一时区处理（UTC+8）
🔄 改进缓存同步机制
📝 向后兼容原有接口

v2.0.0

🏗️ 重构为解耦架构
💾 实现三级缓存系统
📧 集成iCloud邮箱功能
🔍 添加智能邮件搜索
📊 邮件分析和报告生成

Smart Email AI - 让邮件处理更智能、更高效！ 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.idea		.idea
data		data
docs		docs
examples		examples
legacy		legacy
src/smart_email_ai		src/smart_email_ai
.gitignore		.gitignore
.python-version		.python-version
README.md		README.md
main.py		main.py
pyproject.toml		pyproject.toml
start_mcp_server.py		start_mcp_server.py
test_fixes.py		test_fixes.py
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Smart Email AI 🚀📧

🌟 项目简介

🎯 核心功能

📥 邮件接收与解析

⚡ 性能优化

📤 邮件发送

🧠 AI分析增强

💡 设计理念

🏗️ 系统架构

🚀 快速开始

📋 系统要求

⚡ 安装

🎮 使用方法

1. 启动MCP服务器（推荐）

2. Claude Desktop配置

3. 命令行模式

🎯 使用示例

超快搜索示例

高级搜索语法

🔧 MCP工具集

📥 邮件接收工具

🔍 搜索工具（性能优化）

⚡ 缓存优化工具

📤 邮件发送工具

🔍 邮件解析工具

📊 性能基准测试

🚀 搜索性能对比

💾 缓存性能对比

💾 存储效率

🔧 配置说明

iCloud连接配置

缓存优化配置

邮件发送配置

💻 编程接口示例

基本使用

高级缓存使用

🔬 开发与测试

运行测试

MCP服务器测试

🛡️ 安全说明

iCloud应用专用密码

数据安全

📈 性能优化建议

大量邮件处理

缓存策略

网络优化

🔄 版本历史

v3.0.0 (当前版本)

v2.0.0

v1.0.0 (Legacy)

🤝 贡献指南

📄 许可证

🆘 支持与帮助

常见问题

性能监控

联系方式

Smart Email AI System

✨ 核心功能

📧 邮件管理

📤 邮件发送 [新增功能]

🔍 邮件分析

🔧 最新修复

1. 今日邮件读取问题 ✅

2. 邮件发送功能扩展 ✅

🚀 快速开始

安装依赖

启动MCP服务器

核心使用方法

📧 邮件发送

📅 今日邮件获取

📁 项目结构

🔧 配置说明

时区设置

邮件发送配置

📋 MCP工具接口

📧 邮件读取

Packages