内容
# 电子邮件MCP服务器
MCP服务器封装IMAP/SMTP，具有持久IDLE、DKIM/SPF验证和策略执行。
## 构建
```bash
cd workspace/email-mcp
go mod tidy
go build -o email-mcp .
```
## 配置
复制`config.json.example`到`config.json`并填写密码:
```json
{
"host": "mail.example.net",
"port": 993,
"smtp_port": 465,
"username": "bob@example.com",
"password": "...",
"policy": {
"always_bcc": "owner@example.com",
"trusted_senders": ["owner@example.com"],
"trusted_authserv_ids": ["mail.example.com"],
"dkim_fail_allowlist": ["newsletters.example.com"],
"dkim_enforced_senders": ["owner@example.com"],
"allowed_from_addrs": ["example.com"]
}
}
```
- **发件人信任：** 只有`policy.trusted_senders`中的地址被视为有效。未信任的发件人返回的内容不包含`policy_action`提示。
- **始终抄送：** 每封 outbound邮件自动抄送给`policy.always_bcc`。
- **安全删除：** `mail.expire`、`mail.move`和`mail.trash`使用UID EXPUNGE（RFC 4315）—— 仅目标邮件被删除，文件夹中其他已标记为删除的邮件不会被删除。
- **附件沙盒：** `mail.send`附件读取仅限于`policy.attachment_allow_dirs`（默认为`/tmp`）。允许列表外的符号链接被拒绝。
- **签名验证：** DKIM/SPF/DMARC，带有客户端DKIM备用验证。当`trust_mta_auth: true`时，仅信任来自`trusted_authserv_ids`的`Authentication-Results`头部。**DKIM现在仅对`dkim_enforced_senders`中列出的发件人强制执行**（例如`["owner@example.com"]`）；对于其他发件人，DKIM失败被容忍，但**SPF仍然被验证** —— SPF失败仍然阻止投递。使用完整的地址或裸域名（子域名匹配：`mail.example.com`匹配`example.com`）。
- **发件地址允许列表：** `allowed_from_addrs`限制`mail.send`可以在`From`头部使用的域名/地址。
- **保留：** 邮件在48小时后过期（可按文件夹配置）。`mail.expire`将邮件移动到垃圾箱，而不硬删除，并记录每封邮件。
- **转发邮件：** `mail.fetch_attachments`自动从转发邮件中提取`.eml`附件。
- **头部安全：** 所有outbound头部都是RFC 2047编码的。`From`显示名称通过`net/mail.Address`结构化 —— 防止头部注入伪造。
- **幂等性：** 在60秒窗口内，重复调用`mail.send`且相同的收件人、主题、正文、HTML、发件人和附件会被阻止。
## 集成
- **MCP事件：** `mail.received`、`mail.error` —— 通过MCP套接字/WebSocket/webhook推送
- **IMAP IDLE：** 持久连接，自动重连 —— 替换轮询
- **REST API：** 身份验证的HTTP API（`/api/v1/tools/call`）用于远程访问Sanctum或其他HTTP客户端
- **Webhooks：** 新邮件通知POST到`api.webhook_url`，超时5秒，不会阻塞IDLE
- **电子邮件客户端：** `bob/email-mcp-client`处的CLI包装器 —— `email search`、`email read`、`email send`、`email mailboxes`等
## 传输模式
| 模式 | 标志/配置 | 描述 |
|------|---------------|-------------|
| 标准输入/输出 | （默认） | MCP通过标准输入/输出 —— 用于本地MCP客户端启动 |
| TCP | `-tcp :8080` | MCP JSON-RPC通过原始TCP —— 多个客户端 |
| Unix套接字 | `-unix /path/to/sock` | MCP JSON-RPC通过Unix套接字 |
| WebSocket | `-ws :8081` | MCP JSON-RPC通过WebSocket —— 浏览器/远程客户端， bearer-token身份验证，10秒身份验证截止日期 |
| HTTP渲染 | `-http 127.0.0.1:8025` | HTML邮件渲染器 + 健康检查（仅限本地主机） |
| REST API | `config.api.enabled` | 身份验证的HTTP REST API用于远程访问 |
REST API和WebSocket与其他模式一起运行。HTTP渲染服务器、REST API和WebSocket使用单独的端口。
