# Mail Notification MCP

一个通过 SMTP 发送工程进展和人工审批邮件的 MCP Server。它使用标准 stdio transport，适合被 Codex、Claude Desktop、Cursor、VS Code 等 MCP 客户端调用。

## 提供的工具

- `send_progress_update`：发送项目进展、完成或阻塞汇报。
- `request_human_approval`：发送需要人工批准/拒绝的事项，并生成审批编号。
- `send_simple_email`：发送普通纯文本或 HTML 邮件。
- `send_custom_email`：发送带 CC/BCC 和附件的自定义邮件。
- `test_smtp_connection`：测试 SMTP 连接和认证。
- `test_imap_connection`：测试 IMAP 连接和认证。
- `read_replies`：读取收件箱中的最新回复，默认不标记为已读。
- `check_approval_status`：按审批编号识别“批准”“拒绝”或“待处理”。
- `wait_for_approval`：轮询等待人工回复直到批准、拒绝或超时。

进展工具的默认收件人来自 `config.json`；审批邮件会明确要求回复“批准”或“拒绝”。其他工程只需调用 MCP 工具，不需要自己实现 SMTP。

## 1. 配置 SMTP 和目标邮箱

编辑项目根目录的 `config.json`（模板见 `config.example.json`）：

```json
{
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "secure": false,
    "username": "你的发件邮箱@gmail.com",
    "password": "",
    "password_env": "MAIL_SMTP_PASSWORD",
    "from_email": "你的发件邮箱@gmail.com"
  },
  "imap": {
    "host": "imap.gmail.com",
    "port": 993,
    "secure": true,
    "username": "你的发件邮箱@gmail.com",
    "password": "",
    "password_env": "MAIL_SMTP_PASSWORD"
  },
  "notification": {
    "to": "目标收件邮箱@example.com",
    "subject_prefix": "[工程通知]",
    "project_name": "我的工程"
  }
}
```

推荐把密码放在环境变量中，而不是直接写入文件：

```powershell
$env:MAIL_SMTP_PASSWORD = "你的邮箱应用专用密码"
```

也可以直接填写 `smtp.password`。`config.json` 已被 `.gitignore` 忽略，不应提交到版本库。

常见 SMTP 设置：

| 邮箱 | host | port | secure |
|---|---|---:|---|
| Gmail | `smtp.gmail.com` | 587 | `false` |
| Outlook | `smtp-mail.outlook.com` | 587 | `false` |
| QQ 邮箱 | `smtp.qq.com` | 587 | `false` |
| 163 邮箱 | `smtp.163.com` | 465 | `true` |

Gmail、QQ 等通常需要开启 SMTP 并使用应用专用密码；不能直接使用网页登录密码时，请按邮箱服务商要求生成授权码/应用密码。

IMAP 用于读取回复。QQ 邮箱通常使用 `imap.qq.com:993` + SSL；如果省略 `imap.password`，程序会复用 SMTP 密码/授权码。环境变量会覆盖 `config.json`，也可以使用 `IMAP_HOST`、`IMAP_PORT`、`IMAP_SECURE`、`IMAP_USER`、`IMAP_PASS` 和 `NOTIFY_TO`。

## 2. 安装和测试

需要 Python 3.11+ 和 [uv](https://docs.astral.sh/uv/)。在 PowerShell 中运行：

```powershell
cd C:\AI_Tools\Mail
uv sync --extra dev
uv run pytest
uv run python -m email_mcp_server.server
```

MCP 的 stdio 模式不要手工输入普通文字；应由 MCP 客户端启动。建议先调用 `test_smtp_connection` 和 `test_imap_connection`。

## 3. 接入其他工程

以支持 `mcpServers` 格式的客户端为例，将以下服务器项合并到客户端配置中。Windows 路径必须使用双反斜杠：

```json
{
  "mcpServers": {
    "mail-notification": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\AI_Tools\\Mail",
        "run",
        "python",
        "-m",
        "email_mcp_server.server"
      ]
    }
  }
}
```

如果 `uv` 不在客户端的 PATH 中，把 `command` 换成 `uv.exe` 的绝对路径。修改 MCP 配置后重启客户端。

## 调用示例

进展汇报：

```text
调用 send_progress_update：
project="订单系统"
status="进行中"
summary="已完成数据库迁移脚本，并通过本地测试"
details="迁移了 12 张表，新增回滚检查"
next_steps="部署到测试环境并等待接口联调"
```

人工审批：

```text
调用 request_human_approval：
project="订单系统"
title="是否允许部署到生产环境"
request="请批准今晚 22:00 执行生产部署"
reason="测试环境已通过，预计需要 15 分钟，期间会短暂重启服务"
options="批准部署 / 延后到明天"
deadline="今天 21:30 前"
```

工具支持可选的 `to` 参数做单次收件人覆盖；省略时使用 `config.json` 中 `notification.to`。

读取回复：

```text
调用 read_replies：
from_address="target@example.com"
subject_contains="Mail Notification MCP 测试邮件"
since_hours=72
```

审批确认：

```text
调用 check_approval_status：
approval_id="APR-ABC1234567"
```

审批工具返回的状态为 `approved`、`rejected`、`pending` 或 `timeout`。默认只读取 `INBOX`，不会自动修改邮件已读状态。

## 安全说明

- 优先使用应用专用密码或授权码，不要使用主邮箱密码。
- 不要把真实密码、真实目标邮箱配置提交到 Git。
- 默认使用本地 stdio；HTTP 模式仅绑定 `127.0.0.1`。