MCP Email Service

MCP 邮件服务

一个安全的模型上下文协议（MCP）服务和客户端应用，用于发送电子邮件，采用后量子密码学（CRYSTALS-Kyber、Falcon、SPHINCS+）、AES-256-GCM 加密，以及基于 spaCy 的自然语言处理（NLP）来处理用户请求。本服务专为 Ubuntu Linux 设计，可确保通信具备抗量子能力，并提供可靠的电子邮件处理功能。

目录

• 功能
• 先决条件
• 环境设置
• 依赖项安装
• 配置
• 安装
• 使用方法
• 使用示例
• 安全性
• 故障排除
• 贡献
• 许可证

功能

• 后量子密码学：使用 CRYSTALS-Kyber 进行密钥交换，使用 Falcon 进行数字签名，并使用 SPHINCS+ 作为备用签名算法。
• 安全加密：采用 AES-256-GCM 对消息进行认证加密。
• 自然语言处理：利用 spaCy（en_core_web_sm）可靠地解析电子邮件请求。
• 发送真实邮件：集成 SMTP 服务（例如 Gmail），实现实际邮件投递。
• 异步通信：基于 asyncio 构建，实现高效的服务端与客户端交互。
• 支持 Ubuntu Linux：针对 Ubuntu 22.04+ 进行了优化，并提供详细的设置说明。

先决条件

• 操作系统：Ubuntu Linux 22.04 或更高版本。
• Python：3.8 或更高版本。
• 互联网连接：发送邮件和安装依赖项时需要。
• Git：用于克隆代码库。
• SMTP 账户：用于发送邮件的有效电子邮件账户（例如，带有应用专用密码的 Gmail）。

环境设置

1. 更新系统：

   sudo apt-get update
   sudo apt-get upgrade -y
   

2. 安装系统依赖项：

   sudo apt-get install -y python3 python3-pip python3-dev build-essential libssl-dev libffi-dev python3-venv git cmake ninja-build
   

3. 克隆代码库：

   git clone https://github.com/<your-username>/mcp-email-service.git
   cd mcp-email-service
   

依赖项安装

此应用依赖 Python 库，并可选地使用编译后的 C 库来实现后量子密码学。所有依赖项均通过提供的 setup.sh 脚本安装。

Python 依赖项

• pqcrypto==0.1.1：后量子密码学（Kyber、Falcon、SPHINCS+）。
• pyyaml==6.0.1：解析 YAML 配置。
• spacy==3.7.2：用于处理用户请求的 NLP。
• cryptography==42.0.5：AES-256-GCM 加密。

可选 C 库

• liboqs：如果你的平台没有可用的 pqcrypto wheel，则需要此库。必要时，设置脚本会自动编译它。

安装步骤

1. 运行设置脚本：

   chmod +x setup.sh
   ./setup.sh
   

   此脚本会：

   • 创建虚拟环境（venv）。
   • 从 requirements.txt 安装 Python 依赖项。
   • 下载 spaCy en_core_web_sm 模型。
   • 如果安装 pqcrypto 失败，则编译 liboqs 和 liboqs-python。
   • 验证 pqcrypto 和 cryptography 是否安装成功。

2. 激活虚拟环境：

   source venv/bin/activate
   

配置

1. 服务端配置：

   • 编辑 server/config.yaml：

     server:
       host: "0.0.0.0"
       port: 8765
     email:
       server: "smtp.gmail.com"
       port: 587
       user: "[email protected]"
       password: "your-app-password"
     

   • 电子邮件设置：
     • user：你的电子邮件地址。
     • password：应用专用密码（对于 Gmail，可在 Google 账户设置中的“安全性”>“两步验证”>“应用专用密码”下生成）。
     • server 和 port：你的 SMTP 服务详情（例如，Gmail 使用 smtp.gmail.com:587）。

2. 客户端配置：

   • 编辑 client/config.yaml：

     server:
       host: "localhost"
       port: 8765
     

   • 设置 host 和 port，使其与服务端配置一致。

3. 保护配置文件：

   • 确保妥善保护 server/config.yaml（例如，执行 chmod 600 server/config.yaml），因为其中包含敏感凭据。

安装

设置好环境和依赖项后：

1. 验证虚拟环境：

   source venv/bin/activate
   python -c "import pqcrypto, spacy, cryptography; print('All dependencies installed')"
   

2. 测试配置：

   • 确保已正确配置 server/config.yaml 和 client/config.yaml。
   • 验证是否可以访问 SMTP 服务。

使用方法

1. 启动应用：

   chmod +x run.sh
   ./run.sh
   

   • 这会在后台启动 MCP 服务，并在前台启动客户端。
   • 也可以分别运行：

     source venv/bin/activate
     python server/mcp_server.py &
     python client/mcp_client.py
     

2. 与客户端交互：

   • 客户端会提示你输入自然语言。
   • 输入类似这样的请求：“向 [email protected] 发送邮件，主题为 Hello，内容为 This is a test。”
   • 输入 quit 退出。

3. 服务日志：

   • 服务会在控制台打印连接和错误消息。
   • 查看日志以排查问题。

使用示例

客户端使用 spaCy 处理自然语言请求。以下是输入示例及其结果：

1. 基本邮件：

   Input: Send an email to [email protected] saying Hello, how are you?
   Output: Server response: {'status': 'success', 'message': 'Email sent'}
   

   • 向 [email protected] 发送邮件，主题为“Default Subject”，正文为“Hello, how are you?”。

2. 带主题的邮件：

   Input: Email [email protected] with subject Meeting Tomorrow and message Let's meet at 10 AM.
   Output: Server response: {'status': 'success', 'message': 'Email sent'}
   

   • 向 [email protected] 发送邮件，主题为“Meeting Tomorrow”，正文为“Let's meet at 10 AM.”。

3. 复杂请求：

   Input: Send a message to [email protected] with title Project Update and content Please review the latest report.
   Output: Server response: {'status': 'success', 'message': 'Email sent'}
   

   • 向 [email protected] 发送邮件，主题为“Project Update”，正文为“Please review the latest report.”。

4. 无效邮箱：

   Input: Send an email to invalid saying Test
   Output: Server response: {'status': 'success', 'message': 'Email sent'}
   

   • 收件人会回退为 [email protected]。

安全

• 后量子密码学：
  • CRYSTALS-Kyber (ML-KEM)：保护密钥交换，实现抗量子加密。
  • Falcon：提供主要的数字签名，用于身份验证。
  • SPHINCS+：用于冗余备份的签名算法。
• 对称加密：
  • AES-256-GCM：使用从 Kyber 派生的密钥，确保消息的机密性、完整性和真实性。
• 配置安全：
  • 保护 server/config.yaml，以保障邮件凭据安全。
• 网络安全：
  • 在可信网络中或防火墙后运行服务。
  • 可考虑对 SMTP 连接使用 TLS（Gmail 已启用）。

故障排查

• 邮件发送失败：
  • 验证 server/config.yaml 中的凭据和 SMTP 设置。
  • 确保邮件提供商允许使用应用专用密码（对于 Gmail，请启用两步验证）。
  • 检查服务日志中的 SMTP 错误。
• pqcrypto 安装失败：
  • 再次运行 setup.sh 以编译 liboqs 和 liboqs-python。
  • 确保已安装 cmake 和 ninja-build。
• spaCy 问题：
  • 验证 en_core_web_sm 模型：python -m spacy download en_core_web_sm。
  • 检查内存是否充足（spaCy 需要约 200MB）。
• 连接错误：
  • 确保 client/config.yaml 和 server/config.yaml 中的主机和端口一致。
  • 检查服务是否正在运行（ps aux | grep mcp_server.py）。
• 常规调试：
  • 分别运行服务和客户端，以隔离问题。
  • 在 mcp_server.py 或 mcp_client.py 中添加 print 语句，以启用详细日志记录。

贡献

欢迎贡献！请按照以下步骤操作：

1. Fork 此仓库。
2. 创建功能分支（git checkout -b feature/your-feature）。
3. 提交更改（git commit -m 'Add your feature'）。
4. 推送到分支（git push origin feature/your-feature）。
5. 创建 Pull Request。

请确保代码遵循 PEP 8，并在适用时包含测试。

许可证

本项目采用 MIT License。详情请参阅 LICENSE 文件。

MIT License

Copyright (c) 2025 <Your Name>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.