Email-AI-MCP
by FreeNAP
README.md
<p align="center">
<img src="docs/logo.svg" width="108" alt="Email-AI-MCP logo">
</p>
<h1 align="center">Email-AI-MCP</h1>
<p align="center">用邮件遥控 Devin:任务完成发总结邮件,手机直接回信下指令,回信按会话精确投递回原对话</p>
<p align="center">
<a href="https://github.com/FreeNAP/Email-AI-MCP"><img src="https://img.shields.io/github/stars/FreeNAP/Email-AI-MCP?style=flat-square&logo=github" alt="GitHub stars"></a>
<a href="package.json"><img src="https://img.shields.io/badge/version-v0.1.0-2563eb?style=flat-square" alt="Version"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-CC%20BY--NC%204.0-f97316?style=flat-square" alt="License"></a>
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22.5%2B-339933?style=flat-square&logo=nodedotjs" alt="Node.js"></a>
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-6.0-3178c6?style=flat-square&logo=typescript" alt="TypeScript"></a>
<a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Server-111827?style=flat-square" alt="MCP"></a>
</p>
<p align="center">
<a href="#快速开始">快速开始</a> ·
<a href="#页面展示">页面展示</a> ·
<a href="#mcp-工具">MCP 工具</a> ·
<a href="NOTICE.md">署名与使用声明</a> ·
<a href="LICENSE">许可证</a>
</p>

Email-AI-MCP 是一个 MCP Server。Devin(或其他支持 MCP 的 AI 编码代理)完成任务后,通过它把**完整的任务总结**发到你的 QQ 邮箱;你在手机上直接回复这封邮件,回信会被自动识别出属于哪个对话,并**投递回原来那个 Devin 对话**继续执行。配套的 Web 控制台可以查看所有会话的历史记录、把回信改派给别的会话、直接下达指令,通过 Cloudflare 隧道在手机上也能访问。
> 截图中的会话、邮箱、路径均为演示数据。
## 核心功能
- **完整总结邮件**:任务总结、详情、下一步建议全部按 Markdown 渲染(标题、列表、表格、代码块、引用),不截断、不限高;正文统一 15px,手机宽度自适应;跟随系统自动切换白天/黑夜;内置 5 套版式可选。
- **回信按会话投递**:通知邮件自动绑定发出它的 Devin 会话——直接只读 Devin 本地会话库,找到发起这次调用的那条消息所属的会话,多个会话同时运行也不会绑错;回信按 `In-Reply-To` / 主题标记路由回该会话。
- **桌面端精确注入**:注入器自动切换到目标对话标签(支持未加载标签、历史对话列表、标签被改名)再粘贴发送;会话正在运行时用 Ctrl+Enter 排队,不打断也不卡住;输入框有你的草稿时暂缓投递,投递后恢复你的剪贴板。
- **投递状态机**:每条回信/指令都有 `待投递 → 投递中 → 已投递 / 已挂起 / 失败 / 已忽略` 状态;找不到会话时挂起并每 2 分钟自动重试,也可在网页随时改派。
- **Web 控制台**:会话列表、聊天记录式时间线(通知靠左、回信靠右)、全局搜索与筛选、待处理队列、改派并发送、直接下达指令、预览原邮件;白天/黑夜/跟随系统三态主题;手机端抽屉布局。
- **手机访问**:守护进程托管 Cloudflare 隧道,自动获得 https 地址;邮件里的"在网页查看"链接自带 7 天有效的签名登录票据,点开即进,邮件里不出现固定令牌。
- **稳定运行**:后台服务通过 WMI 启动,不随 IDE 重启被连带杀掉;MCP 每 30 秒自检、自动拉起;多进程共用跨进程文件锁读写状态,IMAP 按 UID 水位增量收信不漏信。
## 许可证与使用
本项目采用 [CC BY-NC 4.0](LICENSE)(署名-非商业性使用 4.0 国际)发布,详细说明见 [NOTICE.md](NOTICE.md)。
| 场景 | 是否允许 |
| --- | :---: |
| 个人学习、研究、自用 | ✅ |
| 修改代码、二次开发(需注明来源并说明改动) | ✅ |
| 非商业转载、分享(需注明来源) | ✅ |
| 出售源码或安装包、作为付费服务 / SaaS 提供 | ❌ |
| 集成到收费产品、商业接单交付 | ❌ |
| 去掉署名后以自己名义发布 | ❌ |
魔改或转载时请显著标注:`本项目基于 Email-AI-MCP(https://github.com/FreeNAP/Email-AI-MCP)修改`。商业使用请先通过 Issues 联系取得书面授权。
## 项目功能流程
所有流程图默认折叠,点击标题展开。
<details>
<summary><strong>01|通知与回信闭环</strong></summary>
```mermaid
flowchart LR
DEVIN["Devin 完成任务"] --> NOTIFY["调用 notify_devin_event<br/>标题 + 完整总结 + 详情"]
NOTIFY --> BIND["识别发信会话<br/>只读 Devin 会话库"]
BIND --> SMTP["渲染邮件并经 SMTP 发出<br/>主题带 [AI-CONV:会话ID]"]
SMTP --> PHONE["手机收到邮件<br/>阅读完整总结"]
PHONE --> REPLY["直接回复邮件"]
REPLY --> IMAP["守护进程 IMAP 收信<br/>按 UID 增量拉取"]
IMAP --> ROUTE["按 In-Reply-To / 主题标记<br/>路由到原会话"]
ROUTE --> INJECT["注入器切到对应对话标签<br/>粘贴并发送"]
INJECT --> DEVIN
```
</details>
<details>
<summary><strong>02|会话识别优先级</strong></summary>
```mermaid
flowchart TB
START["发送通知"] --> E{"调用方显式传了<br/>sessionId / conversationId?"}
E -->|是| EXPLICIT["直接使用(explicit)"]
E -->|否| DB["在 Devin 会话库最近消息里<br/>找标题和总结一致的那次调用"]
DB -->|找到| DEVINDB["绑定该会话(devin-db)"]
DB -->|会话库不可用| RECENT["取最近 180 秒内有活动的会话<br/>(recent-activity)"]
RECENT -->|没有| NONE["不绑定,回信按 unboundPolicy 处理"]
```
</details>
<details>
<summary><strong>03|回信投递状态机</strong></summary>
```mermaid
stateDiagram-v2
[*] --> 待投递: 收到回信 / 网页下达指令
待投递 --> 投递中: 注入器领取
投递中 --> 已投递: 发送成功(运行中则排队)
投递中 --> 待投递: 输入框有草稿,稍后再试
投递中 --> 已挂起: 桌面端找不到会话
投递中 --> 失败: 窗口/输入框异常
已挂起 --> 投递中: 每 2 分钟自动重试
失败 --> 投递中: 退避重试(最多 5 次)
已挂起 --> 待投递: 网页改派
失败 --> 待投递: 网页改派
待投递 --> 已忽略: 网页忽略
已投递 --> [*]
```
</details>
<details>
<summary><strong>04|进程架构</strong></summary>
```mermaid
flowchart TB
IDE["Devin Desktop / MCP 客户端"] --> MCP["MCP Server(dist/index.js)<br/>工具调用、发信、每 30 秒自检"]
MCP -->|WMI 启动,脱离 IDE 进程树| DAEMON["守护进程(dist/daemon.js)<br/>单例锁"]
DAEMON --> POLL["IMAP 收信"]
DAEMON --> WEB["Web 控制台 127.0.0.1:8765"]
DAEMON --> INJ["注入器 scripts/mail_injector.py<br/>子进程,异常退避重启"]
DAEMON --> CF["cloudflared 隧道<br/>子进程,异常退避重启"]
CF --> PHONE["手机浏览器 https"]
MCP & DAEMON & INJ --> STATE[("data/state.json<br/>跨进程文件锁 + 原子写")]
```
</details>
## 运行环境
| 依赖 | 版本 | 说明 |
| --- | --- | --- |
| Windows | 10 / 11 | 桌面注入依赖 Windows UI 自动化;其他系统可用 `cli` 目标 |
| Node.js | 22.5+ | 需要内置 `node:sqlite` 读取 Devin 会话库 |
| Python | 3.9+ | 注入器,`pip install uiautomation pyperclip` |
| QQ 邮箱 | 开启 SMTP/IMAP | 使用**授权码**,不是 QQ 登录密码 |
| cloudflared | 可选 | 手机访问控制台;[官方发布页](https://github.com/cloudflare/cloudflared/releases) 下载 `cloudflared-windows-amd64.exe` |
## 快速开始
```bash
git clone https://github.com/FreeNAP/Email-AI-MCP.git
cd Email-AI-MCP
npm install
npm run build
pip install uiautomation pyperclip
cp config.example.yml config.yml # 首次运行也会自动生成
```
编辑 `config.yml`,至少填写:
```yaml
mail:
recipients: ["你的收件邮箱@qq.com"]
allowedReplyFrom: ["你的收件邮箱@qq.com"] # 只有白名单发来的回信才会被当作指令
smtp:
enabled: true
user: "发信邮箱@qq.com"
pass: "SMTP 授权码"
imap:
enabled: true
user: "发信邮箱@qq.com"
pass: "IMAP 授权码"
```
在 MCP 客户端中注册(路径换成你的项目目录):
```json
{
"mcpServers": {
"email-ai-mcp": {
"command": "node",
"args": ["D:/path/to/Email-AI-MCP/dist/index.js"],
"env": { "EMAIL_AI_MCP_CONFIG": "D:/path/to/Email-AI-MCP/config.yml" }
}
}
}
```
重启客户端后,MCP Server 会自动拉起守护进程、注入器和 Cloudflare 隧道。控制台地址 `http://127.0.0.1:8765/`,访问令牌见 `config.yml` 的 `web.token`(留空则自动生成到 `data/web-token.txt`)。
建议在 AI 代理的规则里加上一句:*完成任务后调用 `notify_devin_event` 发送完整任务总结*,或使用 `injector.systemReminder` 自动附加。
## 首次配置顺序
1. QQ 邮箱 → 设置 → 账户 → 开启 IMAP/SMTP 服务,生成授权码;
2. 填写 `config.yml` 的 `mail` / `smtp` / `imap`,调用 `verify_mail_connection` 工具校验连通;
3. 让 Devin 发一封测试通知,确认邮件排版与"在网页查看"链接;
4. 直接回复这封邮件,在控制台看它从"待投递"变为"已投递";
5. 需要固定域名时,在 Cloudflare 后台创建 tunnel,把 token 填到 `web.tunnel.tunnelToken`、`mode: named`,域名填到 `web.publicUrl`。
## 主要配置项
| 配置 | 说明 |
| --- | --- |
| `mail.design` | 邮件版式:`classic` 简洁卡片 / `minimal` 极简文档 / `banner` 彩色横幅 / `terminal` 开发者终端 / `stacked` 分块卡片 |
| `mail.theme` | 邮件配色:`auto` 跟随系统 / `light` / `dark` |
| `injector.targets` | 投递目标:`cascade`(Devin Desktop 窗口)或 `cli`(`devin -r <会话> -p`) |
| `injector.unboundPolicy` | 未绑定会话的回信:`foreground` 投到当前对话 / `hold` 挂起等网页指派 |
| `injector.systemReminder` | 投递时附加在指令末尾的提醒 |
| `web.token` / `web.loginLinkDays` | 控制台固定令牌 / 邮件自动登录票据有效天数(0 为不带) |
| `web.tunnel.*` | Cloudflare 隧道:`quick` 临时域名或 `named` 固定域名,`protocol` 默认 `http2` |
| `sessions.*` | 会话自动识别、Devin 会话库路径、活动时间窗 |
## MCP 工具
| 工具 | 用途 |
| --- | --- |
| `notify_devin_event` | Devin 任务完成/失败/启动/暂停时发送通知邮件,自动绑定会话 |
| `notify_task_event` | 通用任务事件通知(todo 完成、卡住、token 不足等) |
| `send_email` | 发送自定义邮件 |
| `get_devin_instructions` | 查看邮件指令队列(注入器运行时只返回概况,避免被其他会话误领) |
| `poll_replies` / `ack_reply` | 手动拉取回信、标记已消费 |
| `get_mail_runtime_status` / `verify_mail_connection` | 运行状态与 SMTP/IMAP 连通性校验 |
## 目录与文件用途
| 路径 | 内容 |
| --- | --- |
| `src/index.ts` | MCP Server 入口:注册工具、WMI 拉起守护进程、30 秒自检 |
| `src/daemon.ts` / `src/supervisor.ts` | 守护进程:IMAP 收信、Web 控制台、注入器与隧道的进程监护 |
| `src/email/` | SMTP 发信、IMAP 收信(UID 水位)、Markdown 邮件模板与 5 套版式 |
| `src/sessions/` | Devin 会话列表与会话库只读查询、历史通知回填 |
| `src/store/` | `state.json` 状态存储、跨进程文件锁、单例锁 |
| `src/web/` | 控制台 HTTP API、登录票据、公网地址、视图模型 |
| `src/tools/` | MCP 工具实现 |
| `web/index.html` | 单文件控制台前端(原生 JS,零依赖) |
| `scripts/mail_injector.py` | 桌面注入器:切换对话标签、草稿检测、投递状态机 |
| `scripts/launch-detached.ps1` | 通过 WMI 启动脱离 IDE 进程树的后台进程 |
| `test/` | Node `node:test` 与 Python `unittest` 自动化测试 |
| `config.example.yml` | 配置模板(含每一项的中文注释) |
## 页面展示
<table>
<tr>
<td width="50%"><img src="docs/screenshots/01-desktop-light.png" alt="桌面端白天模式:会话时间线"></td>
<td width="50%"><img src="docs/screenshots/02-desktop-dark-queue.png" alt="桌面端黑夜模式:待处理队列与改派"></td>
</tr>
<tr>
<td align="center">桌面端 · 会话时间线(白天)</td>
<td align="center">待处理队列 · 改派并发送(黑夜)</td>
</tr>
</table>
<table>
<tr>
<td width="33%"><img src="docs/screenshots/03-mobile-light.png" alt="手机端白天模式"></td>
<td width="33%"><img src="docs/screenshots/04-mobile-dark.png" alt="手机端黑夜模式"></td>
<td width="33%"><img src="docs/screenshots/05-mobile-drawer.png" alt="手机端会话抽屉"></td>
</tr>
<tr>
<td align="center">手机 · 回信待投递</td>
<td align="center">手机 · 黑夜模式</td>
<td align="center">手机 · 会话抽屉</td>
</tr>
</table>
**5 套通知邮件版式**(`mail.design`):

## 数据与安全
- 控制台只监听 `127.0.0.1`,公网访问必须经 Cloudflare 隧道;所有接口需登录,写操作校验同源,登录失败按 IP 限流;
- 邮件里的自动登录链接是带有效期的 HMAC 签名票据,不包含固定令牌;更换令牌后旧票据全部失效;
- 只接受 `allowedReplyFrom` 白名单发来的回信;渲染邮件与网页时所有文本先转义,链接只放行 `http/https/mailto`;
- 读取 Devin 会话库只用只读模式,不写入;`config.yml`、`data/` 已在 `.gitignore` 中,切勿提交授权码。
## 验证
```bash
npm run typecheck
npm test # 构建后运行 Node 与 Python 全部测试
```
测试覆盖:5 套邮件版式 × 3 种主题的字号规格、不截断与防注入;多进程并发写状态文件;Web 接口鉴权、改派、翻页与登录票据;Devin 会话库识别;注入器状态机、标签匹配与草稿检测。
## 致谢
- [Model Context Protocol](https://modelcontextprotocol.io/) · [ImapFlow](https://imapflow.com/) · [Nodemailer](https://nodemailer.com/) · [Zod](https://zod.dev/)
- [uiautomation](https://github.com/yinkaisheng/Python-UIAutomation-for-Windows) · [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)
---
<p align="center">本项目基于 <a href="LICENSE">CC BY-NC 4.0</a> 发布 · 禁止商用 · 修改与转载请注明来源</p>
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data